Posts

Cancel a scheduled post

Stops a scheduled post from publishing. Postbreeze cancels the pending publish so the post doesn’t go out, and marks both the post and every account on it as cancelled.

If some accounts on the post already published (a partial publish), those are left alone — we don’t try to retract what’s already live. Cancel doesn’t delete the post; the row is still around and you can reschedule it later. To get rid of it, call DELETE /posts/{postId} afterwards.

Postbreeze fires a post.cancelled webhook to any webhook endpoints you’ve set up for the workspace.

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

POST

posts

{postId}

cancel

Cancel a scheduled post

curl --request POST \
  --url http://localhost:4100/api/v1/posts/{postId}/cancel \
  --header 'Authorization: Bearer <token>'

{
  "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 cancel.

Example:

"post_01HZX5T2K9Q3RB6N6JZP3RYV0M"

Response

The canceled 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

Retry first-comment for a published targetHas another go at posting the auto-first-comment for one account on the post. Use this when the main post landed fine but the follow-up first comment failed on its own — usually because of a rate limit, a missing permission, or because comments were turned off on the post at the moment we tried. Postbreeze re-runs just the first-comment step against the post that already went out, so we don't double-publish the main post. For this to work, all of the following need to be true: 1. The account on the post has to be in the published state — the main post landed. 2. Postbreeze has a record of the platform's id for that published post, so it knows what to comment on. 3. You saved first-comment text on the post when you created it. 4. There's a recorded error from the previous first-comment attempt — if it already succeeded, there's nothing to retry. There's a 30-second cooldown between retries on the same account, so a quick double-click doesn't keep hammering an already-throttled platform. Only workspace **owners**, **admins**, and **editors** can retry first comments.

Cancel a scheduled post

curl --request POST \
  --url http://localhost:4100/api/v1/posts/{postId}/cancel \
  --header 'Authorization: Bearer <token>'

{
  "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>"
    }
  ]
}