Posts

Create a post

Creates a new post — either a draft you’ll schedule later or one that’s already scheduled to go out at a specific time — and queues it up for every account you list.

Send content (the caption shared across every platform) and a platforms array of one entry per account you want to post to. Each entry can override the caption or attach platform-specific settings via platformOptions.

If you include scheduledFor, the post is created as scheduled and Postbreeze queues it up to publish at that time. Leave it out and the post is saved as a draft instead.

Postbreeze figures out which workspace the post belongs to from the first account you list, so you don’t need to pass a workspaceId.

Only workspace owners, admins, and editors can create posts.

POST

posts

Create a post

curl --request POST \
  --url http://localhost:4100/api/v1/posts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "platforms": [
    {
      "accountId": "soc_01HZW2K9R5T8V3N7M4P0J1Q6BD",
      "platformOptions": {
        "platform": "INSTAGRAM",
        "kind": "FEED"
      }
    }
  ],
  "content": "Just shipped a new feature 🚀",
  "scheduledFor": "2026-06-15T09:00:00.000Z",
  "draftScheduledFor": "<string>",
  "timezone": "<string>",
  "mediaItems": [
    {
      "url": "https://cdn.example.com/launch-hero.jpg",
      "altText": "<string>"
    }
  ],
  "mediaIds": [
    "<string>"
  ],
  "mediaAltText": {}
}
'

{
  "id": "<string>",
  "workspaceId": "<string>",
  "createdByUserId": "<string>",
  "caption": "<string>",
  "scheduledAt": "2023-11-07T05:31:56Z",
  "timezone": "<string>",
  "workflowId": "<string>",
  "pendingWorkflowId": "<string>",
  "approvedByUserId": "<string>",
  "approvedAt": "2023-11-07T05:31:56Z",
  "createdViaApi": true,
  "createdViaFlatShape": true,
  "deletedAt": "2023-11-07T05:31:56Z",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "targets": [
    {
      "id": "<string>",
      "postId": "<string>",
      "socialAccountId": "<string>",
      "captionOverride": "<string>",
      "firstComment": "<string>",
      "firstCommentError": "<string>",
      "firstCommentAttempt": 123,
      "platformOptions": {},
      "mediaIds": [
        "<string>"
      ],
      "scheduledFor": "2023-11-07T05:31:56Z",
      "publishedAt": "2023-11-07T05:31:56Z",
      "externalPostId": "<string>",
      "externalUrl": "<string>",
      "errorCode": "<string>",
      "errorMessage": "<string>",
      "attemptCount": 123,
      "lastAttemptAt": "2023-11-07T05:31:56Z",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "media": [
    {
      "postId": "<string>",
      "mediaAssetId": "<string>",
      "order": 123,
      "altText": "<string>"
    }
  ]
}

Authorizations

Authorization

string

header

required

Your Postbreeze API key

Body

application/json

platforms

object[]

required

One entry per platform to publish to. Order is preserved in the UI.

Show child attributes

Example:

[
  {
    "accountId": "soc_01HZW2K9R5T8V3N7M4P0J1Q6BD",
    "platformOptions": { "platform": "INSTAGRAM", "kind": "FEED" }
  }
]

content

string

Default caption applied to every platform unless overridden via platforms[].captionOverride.

Maximum string length: 10000

Example:

"Just shipped a new feature 🚀"

scheduledFor

string

ISO-8601 publish time. Post is created as SCHEDULED and a Temporal workflow is started. Omit for a draft.

Example:

"2026-06-15T09:00:00.000Z"

draftScheduledFor

string

ISO-8601 time to pin the post on the calendar without actually scheduling it (status stays DRAFT). Ignored when scheduledFor is set.

timezone

string

IANA timezone the user composed in (e.g. Europe/Stockholm). Used to render scheduledFor correctly in the UI; not used by the publisher.

mediaItems

object[]

Media to ingest by URL. The server fetches each URL (SSRF-guarded) and stores it in your media library. Resulting MediaAsset ids are prepended to mediaIds.

Show child attributes

mediaIds

string[]

IDs of media already in your library (returned from POST /media/presign or POST /media/from-url).

mediaAltText

object

Per-asset alt-text overrides keyed by MediaAsset.id. Falls back to MediaAsset.altText when an entry is absent.

Response

The newly created post.

string

Prefixed cuid identifier.

workspaceId

string

Workspace this post belongs to.

createdByUserId

string

User id of the author.

status

enum<string>

Aggregate publish state. Derived from per-target statuses (PARTIALLY_PUBLISHED when some succeed and some fail).

Available options:

DRAFT,

NEEDS_APPROVAL,

SCHEDULED,

PUBLISHING,

PARTIALLY_PUBLISHED,

PUBLISHED,

FAILED,

CANCELED

caption

string | null

Default caption applied to every target unless overridden via targets[].captionOverride.

scheduledAt

string<date-time> | null

ISO-8601 publish time. Doubles as the calendar pin for drafts (set via draftScheduledAt).

timezone

string | null

IANA timezone the post was composed in. Cosmetic — used by the UI.

workflowId

string | null

Temporal workflow id driving this post's publish, when scheduled. Null on drafts and after cancellation.

pendingWorkflowId

string | null

Workflow id staged during the schedule transaction. Visible while a Temporal start is in flight; cleared on commit.

approvedByUserId

string | null

User id of the approver. Set when an NEEDS_APPROVAL post is approved.

approvedAt

string<date-time> | null

When the post was approved, if applicable.

createdViaApi

boolean

True when the post was authored by an API-key or OAuth request. Cookie-session dashboard posts are false.

createdViaFlatShape

boolean

True when the request used the flat platforms[] body shape. False for the nested targets[] shape and dashboard posts.

deletedAt

string<date-time> | null

Soft-delete timestamp. Listings and GET /posts/:id exclude rows where this is non-null.

createdAt

string<date-time>

When the post was created.

updatedAt

string<date-time>

When the post was last modified.

targets

object[]

One fan-out target per connected account this post publishes to.

Show child attributes

media

object[]

Library media attached to the post, ordered by order. Per-target overrides on targets[].mediaIds win over this list.

Show child attributes

Get a postReturns a single post by id, with its per-account targets and attached media included in the response. You don't need to tell us which workspace the post belongs to — Postbreeze figures that out from the post itself and checks that your API key can reach that workspace. Deleted posts return `null`.

Create a post

curl --request POST \
  --url http://localhost:4100/api/v1/posts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "platforms": [
    {
      "accountId": "soc_01HZW2K9R5T8V3N7M4P0J1Q6BD",
      "platformOptions": {
        "platform": "INSTAGRAM",
        "kind": "FEED"
      }
    }
  ],
  "content": "Just shipped a new feature 🚀",
  "scheduledFor": "2026-06-15T09:00:00.000Z",
  "draftScheduledFor": "<string>",
  "timezone": "<string>",
  "mediaItems": [
    {
      "url": "https://cdn.example.com/launch-hero.jpg",
      "altText": "<string>"
    }
  ],
  "mediaIds": [
    "<string>"
  ],
  "mediaAltText": {}
}
'

{
  "id": "<string>",
  "workspaceId": "<string>",
  "createdByUserId": "<string>",
  "caption": "<string>",
  "scheduledAt": "2023-11-07T05:31:56Z",
  "timezone": "<string>",
  "workflowId": "<string>",
  "pendingWorkflowId": "<string>",
  "approvedByUserId": "<string>",
  "approvedAt": "2023-11-07T05:31:56Z",
  "createdViaApi": true,
  "createdViaFlatShape": true,
  "deletedAt": "2023-11-07T05:31:56Z",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "targets": [
    {
      "id": "<string>",
      "postId": "<string>",
      "socialAccountId": "<string>",
      "captionOverride": "<string>",
      "firstComment": "<string>",
      "firstCommentError": "<string>",
      "firstCommentAttempt": 123,
      "platformOptions": {},
      "mediaIds": [
        "<string>"
      ],
      "scheduledFor": "2023-11-07T05:31:56Z",
      "publishedAt": "2023-11-07T05:31:56Z",
      "externalPostId": "<string>",
      "externalUrl": "<string>",
      "errorCode": "<string>",
      "errorMessage": "<string>",
      "attemptCount": 123,
      "lastAttemptAt": "2023-11-07T05:31:56Z",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "media": [
    {
      "postId": "<string>",
      "mediaAssetId": "<string>",
      "order": 123,
      "altText": "<string>"
    }
  ]
}