Skip to main content
POST
/
posts
/
{postId}
/
schedule
Schedule a draft post
curl --request POST \
  --url http://localhost:4100/api/v1/posts/{postId}/schedule \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "scheduledAt": "2026-06-10T14:00:00.000Z"
}
'
{
  "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

Path Parameters

​
postId
string
required

Prefixed cuid of the post to schedule.

Example:

"post_01HZX5T2K9Q3RB6N6JZP3RYV0M"

Body

application/json
​
scheduledAt
string
required

ISO-8601 publish time. Must be in the future.

Example:

"2026-06-10T14:00:00.000Z"

Response

The scheduled post.

​
id
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.

​
media
object[]

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