Create posts

The create-post request contains one publishing entry for every connected social account. A single request can create posts for multiple destinations.

Destinations

Call GET /public/v1/workspaces/{workspaceId}/integrations first and use the returned id as posts[].integration.id. Do not use the provider name or profile URL as an identifier.

Publishing modes

The type field controls how PostlyBee handles the request:

Value	Behavior
`draft`	Saves editable content without publishing it.
`schedule`	Queues content for the UTC time in `date`.
`now`	Queues content for immediate publication.

Set autoSchedule to true to select the next available time from each account’s posting schedule. When auto-scheduling, date is not required. Optional autoScheduleOptions can constrain the search window. With "type": "draft", auto-scheduling only sets the draft’s date and does not queue it for publishing. autoScheduleOptions.topOfQueue reorders scheduled posts, so it cannot be used with drafts.

Threads

Each item in posts[].value represents one content segment. For thread-based platforms such as X, Threads, and Bluesky, multiple items form a thread. On platforms without native threads, provider behavior may differ.

{
  "integration": { "id": "CONNECTED_ACCOUNT_ID" },
  "value": [
    { "content": "First post in the thread", "image": [] },
    { "content": "Second post in the thread", "image": [] }
  ],
  "settings": {}
}

Media

Upload media before creating the post. Use the returned id and path in the content segment:

{
  "content": "A post with an image",
  "image": [
    {
      "id": "4cb8c6af-7111-4e5d-a7cd-846c9293d4c1",
      "path": "https://postlybee.com/uploads/2026/08/launch-image.png",
      "alt": "Product launch graphic"
    }
  ]
}

The destination platform ultimately determines supported formats, file sizes, aspect ratios, and attachment counts.

Provider settings

posts[].settings contains destination-specific options. PostlyBee automatically adds the provider discriminator after resolving the connected account. Only include settings supported by that provider.

Repeat and recycle modes are mutually exclusive. A request enabling both is rejected with 400 Bad Request.

Repeating and recycling

Use repeat to create a fixed number of future copies. Use recycle to republish on an interval until an optional maximum cycle count is reached. Intervals support DAY, WEEK, and MONTH.

External IDs and safe retries

Set posts[].externalId to your own reference for a destination (up to 128 characters: letters, digits, _ . : -). It is stored on that destination’s root post, must be unique among the workspace’s live posts, and is returned in post lookups and webhook events. Reusing an external ID that belongs to another live post returns 409 external_id_conflict with the existing postId. Send an Idempotency-Key header to make POST /posts safe to retry. For 24 hours, a repeat with the same key and body returns the original response without creating posts again; a repeat with a different body returns 409 idempotency_key_reused.

curl -X POST "https://api.postlybee.com/public/v1/workspaces/$WORKSPACE_ID/posts" \
  -H "Authorization: Bearer $POSTLYBEE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: launch-2026-10-03-1" \
  -d '{"type":"schedule","date":"2026-10-04T09:00:00.000Z","shortLink":false,"tags":[],
       "posts":[{"integration":{"id":"ACCOUNT_ID"},"externalId":"order-123",
                 "value":[{"content":"Hello","image":[]}],"settings":{}}]}'

Use GET /posts/lookup?externalIds=order-123 (up to 100 IDs) to read status, releaseURL, and errors without listing a date range.

Get started

Essentials

MCP

CLI

SDKs

API reference

Destinations

Publishing modes

Threads

Media

Provider settings

Repeating and recycling

External IDs and safe retries

​Destinations

​Publishing modes

​Threads

​Media

​Provider settings

​Repeating and recycling

​External IDs and safe retries

Destinations

Publishing modes

Threads

Media

Provider settings

Repeating and recycling

External IDs and safe retries