Creating Posts

The Posts Create endpoints let you asynchronously schedule, draft, or immediately publish content across one or more social networks. Submit a batch request, receive a job ID, then poll for completion.

Requirements

Authentication: Bearer API token
Scopes: posts, media
Headers:
- Authorization: Bearer-API YOUR_API_KEY
- Publer-Workspace-Id: YOUR_WORKSPACE_ID

Core Concepts

Asynchronous Workflow

Submit Request  →  Receive Job ID  →  Poll Job Status  →  Processing Complete

Submit Request to /posts/schedule or /posts/schedule/publish
Receive { "job_id": "…" }
Poll /job_status/{job_id} until status: "completed"
Handle results or errors

Common Request Structure

All create requests share this shape:

{
  "bulk": {
    "state": "[publishing_method]",
    "posts": [
      {
        "networks": {
          "[network_provider]": {
            "type": "[content_type]",
            "text": "Post content",
            // other network-specific fields
          }
        },
        "accounts": [
          { 
            "id": "ACCOUNT_ID"
            // Additional parameters based on publishing method
            }
        ],
        // optional: recycling, recurring, labels, etc.
      }
    ]
  }
}

bulk: batch container
state: how to handle content (see Publishing Methods)
posts: array of post definitions
networks: per-network content config
accounts: target profiles with scheduling overrides

Endpoints

Endpoint

Purpose

Result

/api/v1/posts/schedule

Schedule posts for future publication including drafts

Scheduled post or draft

/api/v1/posts/schedule/publish

Publish content immediately

Published post

/api/v1/job_status/{job_id}

Check status of submitted job

Job status

Publishing Methods

The state parameter determines how your content will be handled:

State

Description

Additional Parameters

scheduled

Schedule for specific date/time

scheduled_at (ISO timestamp)

draft, draft_private, draft_public

Save as draft

None required

scheduled + auto: true

Use AI-powered auto-scheduling

range.start_date, range.end_date

scheduled + recycling

Reuse content multiple times

recycling.gap, recycling.expire_count

recurring

Create repeating posts

recurring.repeat, recurring.days_of_week

Content Types

The type parameter specifies the content format:

Type

Description

Required Properties

status

Text-only post

text

photo

Image post

text, media array

video

Video post

text, media array

link

Link post with preview

text, url

carousel

Multi-image post

text, media array

pdf

PDF document (LinkedIn)

text, media array

Network Providers

Supported platforms and their keys under networks: facebook, instagram, twitter, linkedin, pinterest, youtube, tiktok, google, wordpress_basic (self-hosted wordpress), wordpress_oauth (hosted on wordpress), telegram, mastodon, threads, bluesky.

Job Status

Poll your job with:

GET /api/v1/job_status/{job_id}

Response:

{
  "status": "working|completed|failed",
  "payload": { /* results or errors */ }
}

Common Patterns

Network-Specific Content

To customize content for specific platforms:

{
"networks": {
  "facebook": {
    "type": "status",
    "text": "Facebook simple status update"
  },
  "twitter": {
    "type": "status", 
    "text": "Twitter/X specific content with #hashtags"
  },
  "linkedin": {
    "type": "status",
    "text": "Longer, more professional content for LinkedIn audience"
  }
},
"accounts": [
  {
    "id": "66db83154e299efa19a2d8eb",
    "scheduled_at": "2025-05-15T14:30:00Z"
  },
  {
    "id": "66e973ac4e299e531f5dc034",
    "scheduled_at": "2025-05-15T15:00:00Z"
  },
  {
    "id": "66e973ac4e299e531f4hc034",
    "scheduled_at": "2025-05-15T15:00:00Z"
  }
]
}

Media References

Media files must be pre-uploaded and referenced by ID, see Media Handling:

"media": [
  {
    "id": "66fba4234e299e531f5dc100",
    "type": "image",
    "alt_text": "Optional accessibility description"
  }
]

Schedule posts

post

Schedule one or more posts for publishing. Supports immediate publishing, scheduled publishing, auto-scheduling, recurring posts, and more.

Authorizations

AuthorizationstringRequired

API key authentication. Format: "Bearer-API YOUR_API_KEY"

Header parameters

Publer-Workspace-IdstringRequired

ID of the workspace to schedule posts in

Body

Responses

200

Posts scheduled successfully

application/json

400

Invalid scheduling parameters

application/json

401

Unauthorized

application/json

403

Permission denied or missing required scope

application/json

post

/posts/schedule

POST /api/v1/posts/schedule HTTP/1.1
Host: app.publer.com
Authorization: YOUR_API_KEY
Publer-Workspace-Id: text
Content-Type: application/json
Accept: */*
Content-Length: 1029

{
  "bulk": {
    "state": "scheduled",
    "posts": [
      {
        "networks": {
          "facebook": {
            "type": "status",
            "text": "Check out our new product launch!"
          }
        },
        "accounts": [
          {
            "id": "63c675b54e299e9cf2b667ea",
            "scheduled_at": "2025-05-17T16:19+02:00",
            "labels": [],
            "previewed_media": true,
            "share": {
              "text": "text",
              "account_ids": [
                "text"
              ],
              "after": {
                "duration": 1,
                "unit": "Minute"
              },
              "delay": {
                "duration": 1,
                "unit": "Minute"
              }
            },
            "comments": [
              {
                "text": "text",
                "language": "text",
                "delay": {
                  "duration": 1,
                  "unit": "Minute"
                },
                "media": {
                  "type": "photo",
                  "path": "text",
                  "caption": "text",
                  "thumbnail": "text",
                  "thumbnails": {
                    "real": "text",
                    "small": "text"
                  }
                }
              }
            ],
            "delete": {
              "hide": true,
              "delay": {
                "duration": 1,
                "unit": "Minute"
              }
            }
          }
        ],
        "recycling": {
          "solo": true,
          "gap": 2,
          "gap_freq": "Week",
          "start_date": "2025-05-24",
          "expire_count": "1",
          "expire_date": "2025-06-14"
        },
        "recurring": {
          "start_date": "2025-05-05T13:29+02:00",
          "end_date": "2025-06-21T13:29+02:00",
          "repeat": "weekly",
          "days_of_week": [
            1,
            4,
            6
          ],
          "repeat_rate": 1
        },
        "share_next": false,
        "range": {
          "start_date": "2025-05-31T08:43:00.000Z",
          "end_date": "2025-06-08T08:43:00.000Z"
        },
        "auto": true
      }
    ]
  }
}

{
  "success": true,
  "data": {
    "job_id": "6810dec617eae6d55d7a5e5b"
  }
}

Create post

post

Creates a new social media post. Can be scheduled for immediate publishing, future publishing, or saved as a draft.

Authorizations

AuthorizationstringRequired

API key authentication. Format: "Bearer-API YOUR_API_KEY"

Header parameters

Publer-Workspace-IdstringRequired

ID of the workspace to create post in

Body

Responses

200

Post creation job initiated

application/json

400

Invalid post data

application/json

401

Unauthorized

application/json

403

Permission denied or missing required scope

application/json

post

/posts/schedule/publish

POST /api/v1/posts/schedule/publish HTTP/1.1
Host: app.publer.com
Authorization: YOUR_API_KEY
Publer-Workspace-Id: text
Content-Type: application/json
Accept: */*
Content-Length: 1029

{
  "bulk": {
    "state": "scheduled",
    "posts": [
      {
        "networks": {
          "facebook": {
            "type": "status",
            "text": "Check out our new product launch!"
          }
        },
        "accounts": [
          {
            "id": "63c675b54e299e9cf2b667ea",
            "scheduled_at": "2025-05-17T16:19+02:00",
            "labels": [],
            "previewed_media": true,
            "share": {
              "text": "text",
              "account_ids": [
                "text"
              ],
              "after": {
                "duration": 1,
                "unit": "Minute"
              },
              "delay": {
                "duration": 1,
                "unit": "Minute"
              }
            },
            "comments": [
              {
                "text": "text",
                "language": "text",
                "delay": {
                  "duration": 1,
                  "unit": "Minute"
                },
                "media": {
                  "type": "photo",
                  "path": "text",
                  "caption": "text",
                  "thumbnail": "text",
                  "thumbnails": {
                    "real": "text",
                    "small": "text"
                  }
                }
              }
            ],
            "delete": {
              "hide": true,
              "delay": {
                "duration": 1,
                "unit": "Minute"
              }
            }
          }
        ],
        "recycling": {
          "solo": true,
          "gap": 2,
          "gap_freq": "Week",
          "start_date": "2025-05-24",
          "expire_count": "1",
          "expire_date": "2025-06-14"
        },
        "recurring": {
          "start_date": "2025-05-05T13:29+02:00",
          "end_date": "2025-06-21T13:29+02:00",
          "repeat": "weekly",
          "days_of_week": [
            1,
            4,
            6
          ],
          "repeat_rate": 1
        },
        "share_next": false,
        "range": {
          "start_date": "2025-05-31T08:43:00.000Z",
          "end_date": "2025-06-08T08:43:00.000Z"
        },
        "auto": true
      }
    ]
  }
}

{
  "success": true,
  "data": {
    "job_id": "6810dec617eae6d55d7a5e5b"
  }
}

Get job status

get

Check the status of an asynchronous job, including URL media uploads

Authorizations

AuthorizationstringRequired

API key authentication. Format: "Bearer-API YOUR_API_KEY"

Path parameters

job_idstringRequired

ID of the job to check

Header parameters

Publer-Workspace-IdstringRequired

ID of the workspace to retrieve posts from

Responses

200

Job status retrieved successfully

application/json

401

Unauthorized

application/json

403

Permission denied or missing required scope

application/json

get

/job_status/{job_id}

GET /api/v1/job_status/{job_id} HTTP/1.1
Host: app.publer.com
Authorization: YOUR_API_KEY
Publer-Workspace-Id: text
Accept: */*

{
  "success": true,
  "data": {
    "status": "complete",
    "result": {
      "status": "working",
      "payload": {
        "failures": {
          "error": "Failed to upload media",
          "code": 500
        }
      },
      "plan": {
        "rate": "business",
        "locked": false
      }
    }
  }
}

Next Steps

This overview covers the essential concepts for creating posts with the Publer API. For detailed information about specific features, refer to:

Publishing Methods: Complete documentation of all publishing options
Content Types: Detailed guide to content formats and requirements
Media Handling: Information about uploading and managing media
Network Reference: Platform-specific capabilities and limitations

PreviousMedia NextPublishing Methods

Last updated 3 months ago

Was this helpful?

Good morning

hashtagRequirements

hashtagCore Concepts

hashtagAsynchronous Workflow

hashtagCommon Request Structure

hashtagEndpoints

hashtagPublishing Methods

hashtagContent Types

hashtagNetwork Providers

hashtagJob Status

hashtagCommon Patterns

hashtagNetwork-Specific Content

hashtagMedia References

hashtagSchedule posts

hashtagCreate post

hashtagGet job status

hashtagNext Steps

Requirements

Core Concepts

Asynchronous Workflow

Common Request Structure

Endpoints

Publishing Methods

Content Types

Network Providers

Job Status

Common Patterns

Network-Specific Content

Media References

Schedule posts

Create post

Get job status

Next Steps