Posts

Update a post

Edits an existing post. Works on drafts, scheduled posts, and posts that previously failed or were cancelled — basically anything that hasn’t been published yet. Posts that are currently publishing, already published, or partially published can’t be edited and will return a 400.

The body is the same shape as POST /posts.

The list of accounts and the list of media are replaced wholesale by what you send. Anything that was attached before is swapped out for the new lists. The history of past publish attempts is kept around for the audit log, but the per-account rows themselves are rebuilt from scratch.

If the post was scheduled, editing it cancels the pending publish and Postbreeze re-queues it with the new content and time. We do this so you can change a scheduled post without having to cancel and recreate it.

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

PATCH

posts

{postId}

Update a post

curl --request PATCH \
  --url http://localhost:4100/api/v1/posts/{postId} \
  --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

Path Parameters

postId

string

required

Prefixed cuid of the post to update.

Example:

"post_01HZX5T2K9Q3RB6N6JZP3RYV0M"

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 updated 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

Delete a postDeletes a post. The row stays in our database for audit purposes, but it's hidden from every listing and from `GET /posts/{postId}` — for your purposes it's gone. Important: delete does **not** stop a scheduled post from publishing. If the post is scheduled and you want to make sure it doesn't go out, call `POST /posts/{postId}/cancel` first, then delete it. Only workspace **owners**, **admins**, and **editors** can delete posts.

Update a post

curl --request PATCH \
  --url http://localhost:4100/api/v1/posts/{postId} \
  --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>"
    }
  ]
}