Posts

get/v1/postsList posts
post/v1/postsCreate post
get/v1/posts/{id}Get post
patch/v1/posts/{id}Update post
del/v1/posts/{id}Delete post
patch/v1/posts/{id}/content/{channelId}Update post content
del/v1/posts/{id}/content/{channelId}Delete post content
put/v1/posts/{id}/content/{channelId}/mediaReplace post content media
post/v1/posts/{id}/actionsAct on post
get/v1/posts/{id}/historyGet post history
get/v1/calendarList calendar posts
get/v1/backlogList backlog posts
get/v1/backlog/countCount backlog posts
put/v1/posts/{id}/approval-modeSet post approval mode
post/v1/posts/{id}/revisionsCreate post revision
post/v1/posts/{id}/cancel-deliveryCancel post delivery
post/v1/post-schedulesBulk schedule posts
get/v1/posts/{id}/review-requestsList post review requests
post/v1/posts/{id}/review-requests/{requestId}/cancelCancel post review request
get/v1/review-requestsList pending review requests
get/v1/review-batches/{id}Get review batch
del/v1/review-batches/{id}/posts/{postId}Remove post from review batch

List posts

get/v1/posts

List visible Posty posts in the selected workspace with optional status, channel, creation-date and scheduled-date filters and cursor pagination. Returns post summaries, statuses, schedules and platform names. Use get_post for expanded channel content, media attachments and delivery details.

Query parameters

limitinteger
Default 20 · Min 1 · Max 100
starting_afterstring
ending_beforestring
statusstring
channelIdstring
scheduledAt_gtestring (date-time)
scheduledAt_ltestring (date-time)
createdAt_gtestring (date-time)
createdAt_ltestring (date-time)

Response 200

List of posts

objectstringrequired
One oflist
dataarray of Postrequired
has_morebooleanrequired
next_cursorstringrequirednullable

Errors

401: Unauthenticated
403: Missing scope

Request

curl "https://api.posty.social/v1/posts" \
  -H "Authorization: Bearer $POSTY_API_KEY"

Response 200

{
  "object": "list",
  "data": [
    {
      "createdBy": "string",
      "id": "string",
      "approvalMode": "none",
      "scheduledAt": "2026-01-15T09:30:00.000Z",
      "status": "draft",
      "workspaceId": "string",
      "createdAt": "2026-01-15T09:30:00.000Z",
      "updatedAt": "2026-01-15T09:30:00.000Z",
      "body": "string",
      "content": [
        {
          "id": "string",
          "postId": "string",
          "channelId": "string",
          "platform": "bluesky",
          "body": "string",
          "firstComment": "string",
          "firstCommentExternalId": "string",
          "firstCommentError": "string",
          "contentType": "image",
          "thumbnailUrl": "string",
          "permalink": "string",
          "hashtags": "string",
          "updatedBy": "string",
          "deliveryStatus": "pending",
          "deliveryAttempts": 1,
          "deliveryError": "string",
          "deliveryErrorCategory": "transform",
          "externalPostId": "string",
          "consecutiveMissingFetches": 1,
          "metadata": {
            "key": null
          },
          "media": [
            null
          ],
          "deliveredAt": "2026-01-15T09:30:00.000Z",
          "nextRetryAt": "2026-01-15T09:30:00.000Z",
          "updatedAt": "2026-01-15T09:30:00.000Z",
          "historyBackfilledAt": "2026-01-15T09:30:00.000Z",
          "deletedOnPlatformAt": "2026-01-15T09:30:00.000Z",
          "firstCommentPostedAt": "2026-01-15T09:30:00.000Z"
        }
      ]
    }
  ],
  "has_more": true,
  "next_cursor": "string"
}

Create post

post/v1/posts

Create a draft Posty post with channel-specific text, metadata, optional firstComment and ready media IDs in the selected workspace. First comments require the workspace entitlement and publish after the post on supported platforms. An optional future scheduledAt records the intended publication time. Returns the created post and content. Creation does not publish the draft; use act_on_post for review and publication.

Request body

scheduledAtstring (date-time)
approvalModestring
One ofnoneoptionalrequiredmulti_level
contentarray of objectrequired
Min items 1
Child attributes
- channelIdstringrequired
- bodystringnullable
- firstCommentstringnullable
  First comment or reply to publish after the post on supported platforms. At most 10,000 Unicode codepoints after trimming whitespace. Non-empty text requires the workspace first-comment entitlement. Null or blank text means no comment.
- metadatamap of string or number or boolean or array of string or null
- mediaIdsarray of string

Response 201

Post created

createdBystringrequirednullable
idstringrequired
approvalModestringrequirednullable
One ofnoneoptionalrequiredmulti_level
scheduledAtstring (date-time)requirednullable
statusstringrequired
One ofdraftpending_approvalpending_client_approvalapprovedscheduleddeliveredpartially_delivereddelivery_failed
workspaceIdstringrequired
createdAtstring (date-time)required
updatedAtstring (date-time)required
bodystring
contentarray of PostContent

Errors

400: Validation error
401: Unauthenticated
402: Monthly post limit reached
403: Missing scope
404: Channel or media not found
409: Conflict - inactive channel or non-ready media

Request

curl -X POST "https://api.posty.social/v1/posts" \
  -H "Authorization: Bearer $POSTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "scheduledAt": "2026-01-15T09:30:00.000Z",
  "approvalMode": "none",
  "content": [
    {
      "channelId": "string",
      "body": "string",
      "firstComment": "string",
      "metadata": {
        "key": "string"
      },
      "mediaIds": [
        "string"
      ]
    }
  ]
}'

Response 201

{
  "createdBy": "string",
  "id": "string",
  "approvalMode": "none",
  "scheduledAt": "2026-01-15T09:30:00.000Z",
  "status": "draft",
  "workspaceId": "string",
  "createdAt": "2026-01-15T09:30:00.000Z",
  "updatedAt": "2026-01-15T09:30:00.000Z",
  "body": "string",
  "content": [
    {
      "id": "string",
      "postId": "string",
      "channelId": "string",
      "platform": "bluesky",
      "body": "string",
      "firstComment": "string",
      "firstCommentExternalId": "string",
      "firstCommentError": "string",
      "contentType": "image",
      "thumbnailUrl": "string",
      "permalink": "string",
      "hashtags": "string",
      "updatedBy": "string",
      "deliveryStatus": "pending",
      "deliveryAttempts": 1,
      "deliveryError": "string",
      "deliveryErrorCategory": "transform",
      "externalPostId": "string",
      "consecutiveMissingFetches": 1,
      "metadata": {
        "key": "string"
      },
      "media": [
        {
          "id": "string",
          "title": "string",
          "url": "string",
          "thumbnailUrl": "string"
        }
      ],
      "deliveredAt": "2026-01-15T09:30:00.000Z",
      "nextRetryAt": "2026-01-15T09:30:00.000Z",
      "updatedAt": "2026-01-15T09:30:00.000Z",
      "historyBackfilledAt": "2026-01-15T09:30:00.000Z",
      "deletedOnPlatformAt": "2026-01-15T09:30:00.000Z",
      "firstCommentPostedAt": "2026-01-15T09:30:00.000Z"
    }
  ]
}

Get post

get/v1/posts/{id}

Retrieve a visible Posty post by ID in the selected workspace. Returns its status, schedule and expanded channel content, including media attachments and delivery details. Use this to inspect a post before editing or taking a lifecycle action.

Path parameters

idstringrequired

Response 200

Post with expanded content

createdBystringrequirednullable
idstringrequired
approvalModestringrequirednullable
One ofnoneoptionalrequiredmulti_level
scheduledAtstring (date-time)requirednullable
statusstringrequired
One ofdraftpending_approvalpending_client_approvalapprovedscheduleddeliveredpartially_delivereddelivery_failed
workspaceIdstringrequired
createdAtstring (date-time)required
updatedAtstring (date-time)required
bodystring
contentarray of PostContent

Errors

401: Unauthenticated
403: Missing scope or status not visible
404: Not found

Request

curl "https://api.posty.social/v1/posts/$ID" \
  -H "Authorization: Bearer $POSTY_API_KEY"

Response 200

{
  "createdBy": "string",
  "id": "string",
  "approvalMode": "none",
  "scheduledAt": "2026-01-15T09:30:00.000Z",
  "status": "draft",
  "workspaceId": "string",
  "createdAt": "2026-01-15T09:30:00.000Z",
  "updatedAt": "2026-01-15T09:30:00.000Z",
  "body": "string",
  "content": [
    {
      "id": "string",
      "postId": "string",
      "channelId": "string",
      "platform": "bluesky",
      "body": "string",
      "firstComment": "string",
      "firstCommentExternalId": "string",
      "firstCommentError": "string",
      "contentType": "image",
      "thumbnailUrl": "string",
      "permalink": "string",
      "hashtags": "string",
      "updatedBy": "string",
      "deliveryStatus": "pending",
      "deliveryAttempts": 1,
      "deliveryError": "string",
      "deliveryErrorCategory": "transform",
      "externalPostId": "string",
      "consecutiveMissingFetches": 1,
      "metadata": {
        "key": "string"
      },
      "media": [
        {
          "id": "string",
          "title": "string",
          "url": "string",
          "thumbnailUrl": "string"
        }
      ],
      "deliveredAt": "2026-01-15T09:30:00.000Z",
      "nextRetryAt": "2026-01-15T09:30:00.000Z",
      "updatedAt": "2026-01-15T09:30:00.000Z",
      "historyBackfilledAt": "2026-01-15T09:30:00.000Z",
      "deletedOnPlatformAt": "2026-01-15T09:30:00.000Z",
      "firstCommentPostedAt": "2026-01-15T09:30:00.000Z"
    }
  ]
}

Update post

patch/v1/posts/{id}

Update supplied status, scheduledAt or approvalMode fields on a Posty post by ID. Permissions, transitions and review rules apply. Returns the updated post. Scheduling can cause publication to connected social platforms when due; returning a post to draft resets existing approvals.

Path parameters

idstringrequired

Request body

statusstring
One ofdraftpending_approvalpending_client_approvalapprovedscheduleddeliveredpartially_delivereddelivery_failed
scheduledAtstring (date-time)nullable
approvalModestring
One ofnoneoptionalrequiredmulti_level

Response 200

Updated post

createdBystringrequirednullable
idstringrequired
approvalModestringrequirednullable
One ofnoneoptionalrequiredmulti_level
scheduledAtstring (date-time)requirednullable
statusstringrequired
One ofdraftpending_approvalpending_client_approvalapprovedscheduleddeliveredpartially_delivereddelivery_failed
workspaceIdstringrequired
createdAtstring (date-time)required
updatedAtstring (date-time)required
bodystring
contentarray of PostContent

Errors

400: Invalid schedule
401: Unauthenticated
403: Missing scope
404: Not found
409: Invalid transition or approval required

Request

curl -X PATCH "https://api.posty.social/v1/posts/$ID" \
  -H "Authorization: Bearer $POSTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "status": "draft",
  "scheduledAt": "2026-01-15T09:30:00.000Z",
  "approvalMode": "none"
}'

Response 200

{
  "createdBy": "string",
  "id": "string",
  "approvalMode": "none",
  "scheduledAt": "2026-01-15T09:30:00.000Z",
  "status": "draft",
  "workspaceId": "string",
  "createdAt": "2026-01-15T09:30:00.000Z",
  "updatedAt": "2026-01-15T09:30:00.000Z",
  "body": "string",
  "content": [
    {
      "id": "string",
      "postId": "string",
      "channelId": "string",
      "platform": "bluesky",
      "body": "string",
      "firstComment": "string",
      "firstCommentExternalId": "string",
      "firstCommentError": "string",
      "contentType": "image",
      "thumbnailUrl": "string",
      "permalink": "string",
      "hashtags": "string",
      "updatedBy": "string",
      "deliveryStatus": "pending",
      "deliveryAttempts": 1,
      "deliveryError": "string",
      "deliveryErrorCategory": "transform",
      "externalPostId": "string",
      "consecutiveMissingFetches": 1,
      "metadata": {
        "key": "string"
      },
      "media": [
        {
          "id": "string",
          "title": "string",
          "url": "string",
          "thumbnailUrl": "string"
        }
      ],
      "deliveredAt": "2026-01-15T09:30:00.000Z",
      "nextRetryAt": "2026-01-15T09:30:00.000Z",
      "updatedAt": "2026-01-15T09:30:00.000Z",
      "historyBackfilledAt": "2026-01-15T09:30:00.000Z",
      "deletedOnPlatformAt": "2026-01-15T09:30:00.000Z",
      "firstCommentPostedAt": "2026-01-15T09:30:00.000Z"
    }
  ]
}

Delete post

del/v1/posts/{id}

Permanently delete a Posty post and associated content and collaboration records by ID in the selected workspace. Requires deletion permission and is rejected during active delivery. Returns a deletion confirmation. Already published social-platform copies remain online.

Path parameters

idstringrequired

Response 204

Deleted

Errors

401: Unauthenticated
403: Missing scope
404: Not found

Request

curl -X DELETE "https://api.posty.social/v1/posts/$ID" \
  -H "Authorization: Bearer $POSTY_API_KEY"

Response 204

No content

Update post content

patch/v1/posts/{id}/content/{channelId}

Update supplied text body, platform metadata or firstComment for one channel of an editable Posty post using post and channel IDs. Omit firstComment to preserve it; null or blank text clears it. Non-empty first comments require the workspace entitlement. Returns updated channel content. Edits apply to the Posty copy without updating an already published social-platform copy.

Path parameters

idstringrequired
channelIdstringrequired

Request body

bodystringnullable
firstCommentstringnullable
First comment or reply on supported platforms. At most 10,000 Unicode codepoints after trimming whitespace. Omit to preserve the saved value; null or blank text clears it. Non-empty text requires the workspace first-comment entitlement.
metadatamap of string or number or boolean or array of string or null

Response 200

Updated content

idstringrequired
postIdstringrequired
channelIdstringrequirednullable
platformstringrequired
One ofblueskydiscordfacebookinstagramlinkedinpinterestthreadstiktokwordpressyoutube
bodystringrequirednullable
firstCommentstringrequirednullable
firstCommentExternalIdstringrequirednullable
firstCommentErrorstringrequirednullable
contentTypestringrequirednullable
One ofimagevideoreelstorycarouseltext
thumbnailUrlstringrequirednullable
permalinkstringrequirednullable
hashtagsstringrequirednullable
updatedBystringrequirednullable
deliveryStatusstringrequired
One ofpendingin_progressdeliveredfailedpermanently_failedcancelledexternal
deliveryAttemptsintegerrequired
deliveryErrorstringrequirednullable
deliveryErrorCategorystringrequirednullable
One oftransformplatformauthmedia_proxyvalidationunknown
externalPostIdstringrequirednullable
consecutiveMissingFetchesintegerrequired
metadatamap of string or number or boolean or array of string or nullrequirednullable
mediaarray of objectrequired
Child attributes
- idstringrequired
- titlestringrequired
- urlstringrequirednullable
- thumbnailUrlstringrequirednullable
deliveredAtstring (date-time)requirednullable
nextRetryAtstring (date-time)requirednullable
updatedAtstring (date-time)required
historyBackfilledAtstring (date-time)requirednullable
deletedOnPlatformAtstring (date-time)requirednullable
firstCommentPostedAtstring (date-time)requirednullable

Errors

400: Validation error or first comments unavailable on this plan
401: Unauthenticated
403: Missing scope
404: Not found
409: Post is not editable or delivery is in progress

Request

curl -X PATCH "https://api.posty.social/v1/posts/$ID/content/$CHANNEL_ID" \
  -H "Authorization: Bearer $POSTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "body": "string",
  "firstComment": "string",
  "metadata": {
    "key": "string"
  }
}'

Response 200

{
  "id": "string",
  "postId": "string",
  "channelId": "string",
  "platform": "bluesky",
  "body": "string",
  "firstComment": "string",
  "firstCommentExternalId": "string",
  "firstCommentError": "string",
  "contentType": "image",
  "thumbnailUrl": "string",
  "permalink": "string",
  "hashtags": "string",
  "updatedBy": "string",
  "deliveryStatus": "pending",
  "deliveryAttempts": 1,
  "deliveryError": "string",
  "deliveryErrorCategory": "transform",
  "externalPostId": "string",
  "consecutiveMissingFetches": 1,
  "metadata": {
    "key": "string"
  },
  "media": [
    {
      "id": "string",
      "title": "string",
      "url": "string",
      "thumbnailUrl": "string"
    }
  ],
  "deliveredAt": "2026-01-15T09:30:00.000Z",
  "nextRetryAt": "2026-01-15T09:30:00.000Z",
  "updatedAt": "2026-01-15T09:30:00.000Z",
  "historyBackfilledAt": "2026-01-15T09:30:00.000Z",
  "deletedOnPlatformAt": "2026-01-15T09:30:00.000Z",
  "firstCommentPostedAt": "2026-01-15T09:30:00.000Z"
}

Delete post content

del/v1/posts/{id}/content/{channelId}

Delete one channel-specific content entry and its attachments from an editable Posty post using post and channel IDs. Returns a deletion confirmation. Library media and already published social-platform copies are retained.

Path parameters

idstringrequired
Min length 1
channelIdstringrequired
Min length 1

Response 204

Channel content removed from post

Request

curl -X DELETE "https://api.posty.social/v1/posts/$ID/content/$CHANNEL_ID" \
  -H "Authorization: Bearer $POSTY_API_KEY"

Response 204

No content

Replace post content media

put/v1/posts/{id}/content/{channelId}/media

Replace the complete ordered media attachment list for one channel of an editable Posty post. Provide post and channel IDs and the full ordered list of ready media IDs. Omitted attachments are detached; an empty list clears attachments. Returns updated channel content while retaining library assets.

Path parameters

idstringrequired
channelIdstringrequired

Request body

mediaIdsarray of stringrequired

Response 200

Media replaced

idstringrequired
postIdstringrequired
channelIdstringrequirednullable
platformstringrequired
One ofblueskydiscordfacebookinstagramlinkedinpinterestthreadstiktokwordpressyoutube
bodystringrequirednullable
firstCommentstringrequirednullable
firstCommentExternalIdstringrequirednullable
firstCommentErrorstringrequirednullable
contentTypestringrequirednullable
One ofimagevideoreelstorycarouseltext
thumbnailUrlstringrequirednullable
permalinkstringrequirednullable
hashtagsstringrequirednullable
updatedBystringrequirednullable
deliveryStatusstringrequired
One ofpendingin_progressdeliveredfailedpermanently_failedcancelledexternal
deliveryAttemptsintegerrequired
deliveryErrorstringrequirednullable
deliveryErrorCategorystringrequirednullable
One oftransformplatformauthmedia_proxyvalidationunknown
externalPostIdstringrequirednullable
consecutiveMissingFetchesintegerrequired
metadatamap of string or number or boolean or array of string or nullrequirednullable
mediaarray of objectrequired
Child attributes
- idstringrequired
- titlestringrequired
- urlstringrequirednullable
- thumbnailUrlstringrequirednullable
deliveredAtstring (date-time)requirednullable
nextRetryAtstring (date-time)requirednullable
updatedAtstring (date-time)required
historyBackfilledAtstring (date-time)requirednullable
deletedOnPlatformAtstring (date-time)requirednullable
firstCommentPostedAtstring (date-time)requirednullable

Errors

401: Unauthenticated
403: Missing scope
404: Not found (post, channel, or media)
409: Media not ready

Request

curl -X PUT "https://api.posty.social/v1/posts/$ID/content/$CHANNEL_ID/media" \
  -H "Authorization: Bearer $POSTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "mediaIds": [
    "string"
  ]
}'

Response 200

{
  "id": "string",
  "postId": "string",
  "channelId": "string",
  "platform": "bluesky",
  "body": "string",
  "firstComment": "string",
  "firstCommentExternalId": "string",
  "firstCommentError": "string",
  "contentType": "image",
  "thumbnailUrl": "string",
  "permalink": "string",
  "hashtags": "string",
  "updatedBy": "string",
  "deliveryStatus": "pending",
  "deliveryAttempts": 1,
  "deliveryError": "string",
  "deliveryErrorCategory": "transform",
  "externalPostId": "string",
  "consecutiveMissingFetches": 1,
  "metadata": {
    "key": "string"
  },
  "media": [
    {
      "id": "string",
      "title": "string",
      "url": "string",
      "thumbnailUrl": "string"
    }
  ],
  "deliveredAt": "2026-01-15T09:30:00.000Z",
  "nextRetryAt": "2026-01-15T09:30:00.000Z",
  "updatedAt": "2026-01-15T09:30:00.000Z",
  "historyBackfilledAt": "2026-01-15T09:30:00.000Z",
  "deletedOnPlatformAt": "2026-01-15T09:30:00.000Z",
  "firstCommentPostedAt": "2026-01-15T09:30:00.000Z"
}

Act on post

post/v1/posts/{id}/actions

Apply a lifecycle action to a Posty post and return its resulting status. Use submit to follow its configured approval flow, approve to record approval, request_changes with a comment body to request edits, or retry to requeue failed deliveries. For an approved or scheduled post, publish with at=now (the default) queues immediate delivery; at=scheduled retains its saved publication time. Submission or approval may also schedule publication according to workspace settings. Publishing and retrying can expose content and media on external social platforms. Permissions, review stages and readiness checks apply.

Path parameters

idstringrequired
Min length 1

Response 200

Resulting post status

idstringrequired
statusstringrequired
One ofdraftpending_approvalpending_client_approvalapprovedscheduleddeliveredpartially_delivereddelivery_failed

Errors

403: Permission denied

Request

curl -X POST "https://api.posty.social/v1/posts/$ID/actions" \
  -H "Authorization: Bearer $POSTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "skipApproval": false,
  "action": "submit"
}'

Response 200

{
  "id": "string",
  "status": "draft"
}

Get post history

get/v1/posts/{id}/history

Retrieve revision history, approval decisions and recorded events for a visible Posty post by ID in the selected workspace. Requires permission to view post history. Returns revisions, approvals and events without modifying the post.

Path parameters

idstringrequired
Min length 1

Response 200

Post revisions, review decisions, and events

revisionsarray of objectrequired
Child attributes
- idstringrequired
approvalsarray of objectrequired
Child attributes
- idstringrequired
eventsarray of objectrequired
Child attributes
- idstringrequired

Request

curl "https://api.posty.social/v1/posts/$ID/history" \
  -H "Authorization: Bearer $POSTY_API_KEY"

Response 200

{
  "revisions": [
    {
      "id": "string"
    }
  ],
  "approvals": [
    {
      "id": "string"
    }
  ],
  "events": [
    {
      "id": "string"
    }
  ]
}

List calendar posts

get/v1/calendar

List posts scheduled between from and to (ISO timestamps) as calendar cards with per-channel delivery counts. Needs posts:view; client reviewers never see drafts or team review.

Query parameters

fromstring (date-time)required
tostring (date-time)required
limitinteger
Default 500 · Min 1 · Max 1000

Response 200

Calendar posts in the range

dataarray of CalendarPostrequired

Errors

400: Invalid request
403: Missing permission
404: Post, request or group not found
409: The post changed or is not in a state that allows this

Request

curl "https://api.posty.social/v1/calendar?from=$FROM&to=$TO" \
  -H "Authorization: Bearer $POSTY_API_KEY"

Response 200

{
  "data": [
    {
      "id": "string",
      "status": "draft",
      "body": "string",
      "campaignId": "string",
      "channelIds": [
        "string"
      ],
      "platforms": [
        "bluesky"
      ],
      "thumbnail": "string",
      "scheduledAt": "2026-01-15T09:30:00.000Z",
      "deliveryCounts": {
        "delivered": 1,
        "failed": 1,
        "pending": 1,
        "permanentlyFailed": 1,
        "total": 1
      },
      "deliveryErrorCategory": "string"
    }
  ]
}

List backlog posts

get/v1/backlog

List unscheduled posts that are not yet delivered, most recently updated first. Needs posts:view; client reviewers never see drafts or team review.

Query parameters

limitinteger
Default 100 · Min 1 · Max 500

Response 200

Backlog posts

dataarray of BacklogPostrequired

Errors

400: Invalid request
403: Missing permission
404: Post, request or group not found
409: The post changed or is not in a state that allows this

Request

curl "https://api.posty.social/v1/backlog" \
  -H "Authorization: Bearer $POSTY_API_KEY"

Response 200

{
  "data": [
    {
      "id": "string",
      "status": "draft",
      "body": "string",
      "campaignId": "string",
      "channelIds": [
        "string"
      ],
      "platforms": [
        "bluesky"
      ],
      "thumbnail": "string",
      "updatedAt": "2026-01-15T09:30:00.000Z"
    }
  ]
}

Count backlog posts

get/v1/backlog/count

Count the unscheduled posts the caller can see in the backlog. Needs posts:view.

Response 200

Backlog size

countintegerrequired

Errors

400: Invalid request
403: Missing permission
404: Post, request or group not found
409: The post changed or is not in a state that allows this

Request

curl "https://api.posty.social/v1/backlog/count" \
  -H "Authorization: Bearer $POSTY_API_KEY"

Response 200

{
  "count": 1
}

Set post approval mode

put/v1/posts/{id}/approval-mode

Pin a draft post's approval flow (none, optional, required or multi_level), or pass null to inherit the workspace default. Needs posts:update_approval_mode; the mode must be included in the workspace plan.

Path parameters

idstringrequired
Min length 1

Request body

approvalModestringrequirednullable
One ofnoneoptionalrequiredmulti_level

Response 200

The post with its new approval mode

idstringrequired
statusstringrequired
One ofdraftpending_approvalpending_client_approvalapprovedscheduleddeliveredpartially_delivereddelivery_failed
approvalModestringrequirednullable
One ofnoneoptionalrequiredmulti_level
scheduledAtstring (date-time)requirednullable
updatedAtstring (date-time)required

Errors

400: Invalid request
403: Missing permission
404: Post, request or group not found
409: The post changed or is not in a state that allows this

Request

curl -X PUT "https://api.posty.social/v1/posts/$ID/approval-mode" \
  -H "Authorization: Bearer $POSTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "approvalMode": "none"
}'

Response 200

{
  "id": "string",
  "status": "draft",
  "approvalMode": "none",
  "scheduledAt": "2026-01-15T09:30:00.000Z",
  "updatedAt": "2026-01-15T09:30:00.000Z"
}

Create post revision

post/v1/posts/{id}/revisions

Snapshot the post's current per-channel content and media as a new numbered revision. Needs posts:update. Read revisions with get_post_history.

Path parameters

idstringrequired
Min length 1

Response 201

Revision created

idstringrequired
postIdstringrequired
versionintegerrequired
statusstringrequired
One ofdraftpending_approvalpending_client_approvalapprovedscheduleddeliveredpartially_delivereddelivery_failed
scheduledAtstring (date-time)requirednullable
createdBystringrequirednullable
createdAtstring (date-time)required

Errors

400: Invalid request
403: Missing permission
404: Post, request or group not found
409: The post changed or is not in a state that allows this

Request

curl -X POST "https://api.posty.social/v1/posts/$ID/revisions" \
  -H "Authorization: Bearer $POSTY_API_KEY"

Response 201

{
  "id": "string",
  "postId": "string",
  "version": 1,
  "status": "draft",
  "scheduledAt": "2026-01-15T09:30:00.000Z",
  "createdBy": "string",
  "createdAt": "2026-01-15T09:30:00.000Z"
}

Cancel post delivery

post/v1/posts/{id}/cancel-delivery

Stop retrying one channel's failed delivery, or dismiss one that failed permanently, so the post no longer counts as needing attention. Obtain postContentId from content[].id in get_post for the post. Requires posts:publish. Returns the content ID and resulting delivery status. Fails with 409 if a retry already started; it does not delete a published platform post.

Path parameters

idstringrequired
Min length 1

Request body

postContentIdstringrequired
Min length 1

Response 200

Delivery cancelled

postContentIdstringrequired
deliveryStatusstringrequired
One ofpendingin_progressdeliveredfailedpermanently_failedcancelledexternal

Errors

400: Invalid request
403: Missing permission
404: Post, request or group not found
409: The post changed or is not in a state that allows this

Request

curl -X POST "https://api.posty.social/v1/posts/$ID/cancel-delivery" \
  -H "Authorization: Bearer $POSTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "postContentId": "string"
}'

Response 200

{
  "postContentId": "string",
  "deliveryStatus": "pending"
}

Bulk schedule posts

post/v1/post-schedules

Move up to 50 posts to new future times in one all or nothing change. Each item carries the post's current updatedAt as expectedUpdatedAt; a stale value answers 409. Needs posts:update; approval states are unchanged.

Request body

postsarray of objectrequired
Min items 1 · Max items 50
Child attributes
- postIdstringrequired
  Min length 1
- expectedUpdatedAtstring (date-time)required
- scheduledAtstring (date-time)required

Response 200

Posts whose schedule changed

dataarray of PostStaterequired

Errors

400: Invalid request
403: Missing permission
404: Post, request or group not found
409: The post changed or is not in a state that allows this

Request

curl -X POST "https://api.posty.social/v1/post-schedules" \
  -H "Authorization: Bearer $POSTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "posts": [
    {
      "postId": "string",
      "expectedUpdatedAt": "2026-01-15T09:30:00.000Z",
      "scheduledAt": "2026-01-15T09:30:00.000Z"
    }
  ]
}'

Response 200

{
  "data": [
    {
      "id": "string",
      "status": "draft",
      "approvalMode": "none",
      "scheduledAt": "2026-01-15T09:30:00.000Z",
      "updatedAt": "2026-01-15T09:30:00.000Z"
    }
  ]
}

List post review requests

get/v1/posts/{id}/review-requests

List who has been asked to approve a post and how each ask ended (pending, approved, changes_requested, superseded, cancelled). Needs posts:view; client reviewers see only client stage asks.

Path parameters

idstringrequired
Min length 1

Response 200

Review requests for the post

dataarray of ReviewRequestrequired

Errors

400: Invalid request
403: Missing permission
404: Post, request or group not found
409: The post changed or is not in a state that allows this

Request

curl "https://api.posty.social/v1/posts/$ID/review-requests" \
  -H "Authorization: Bearer $POSTY_API_KEY"

Response 200

{
  "data": [
    {
      "id": "string",
      "postId": "string",
      "audience": "team",
      "requestedBy": "string",
      "email": "string",
      "userId": "string",
      "invitationId": "string",
      "batchId": "string",
      "message": "string",
      "status": "pending",
      "respondedAt": "2026-01-15T09:30:00.000Z",
      "lastNotifiedAt": "2026-01-15T09:30:00.000Z",
      "createdAt": "2026-01-15T09:30:00.000Z",
      "updatedAt": "2026-01-15T09:30:00.000Z",
      "reviewerName": "string",
      "reviewerImage": "string",
      "requesterName": "string"
    }
  ]
}

Cancel post review request

post/v1/posts/{id}/review-requests/{requestId}/cancel

Withdraw a pending ask for one reviewer; the post stays in review and nobody is emailed. Needs posts:submit_for_approval. Asks inside a review group cannot be withdrawn here.

Path parameters

idstringrequired
Min length 1
requestIdstringrequired
Min length 1

Response 200

The withdrawn request

idstringrequired
postIdstringrequired
audiencestringrequired
One ofteamclient
requestedBystringrequirednullable
emailstringrequired
userIdstringrequirednullable
invitationIdstringrequirednullable
batchIdstringrequirednullable
messagestringrequirednullable
statusstringrequired
One ofpendingapprovedchanges_requestedsupersededcancelled
respondedAtstring (date-time)requirednullable
lastNotifiedAtstring (date-time)requirednullable
createdAtstring (date-time)required
updatedAtstring (date-time)required

Errors

400: Invalid request
403: Missing permission
404: Post, request or group not found
409: The post changed or is not in a state that allows this

Request

curl -X POST "https://api.posty.social/v1/posts/$ID/review-requests/$REQUEST_ID/cancel" \
  -H "Authorization: Bearer $POSTY_API_KEY"

Response 200

{
  "id": "string",
  "postId": "string",
  "audience": "team",
  "requestedBy": "string",
  "email": "string",
  "userId": "string",
  "invitationId": "string",
  "batchId": "string",
  "message": "string",
  "status": "pending",
  "respondedAt": "2026-01-15T09:30:00.000Z",
  "lastNotifiedAt": "2026-01-15T09:30:00.000Z",
  "createdAt": "2026-01-15T09:30:00.000Z",
  "updatedAt": "2026-01-15T09:30:00.000Z"
}

List pending review requests

get/v1/review-requests

List review requests still waiting at their post's current stage, newest first, cursor paginated. Needs posts:view. Grouped requests appear only to their requester and recipients over OAuth; API keys see ungrouped requests.

Query parameters

limitinteger
Default 20 · Min 1 · Max 100
starting_afterstring

Response 200

Pending review requests

objectstringrequired
One oflist
dataarray of PendingReviewRequestrequired
has_morebooleanrequired
next_cursorstringrequirednullable

Errors

400: Invalid request
403: Missing permission
404: Post, request or group not found
409: The post changed or is not in a state that allows this

Request

curl "https://api.posty.social/v1/review-requests" \
  -H "Authorization: Bearer $POSTY_API_KEY"

Response 200

{
  "object": "list",
  "data": [
    {
      "id": "string",
      "postId": "string",
      "audience": "team",
      "requestedBy": "string",
      "email": "string",
      "userId": "string",
      "invitationId": "string",
      "batchId": "string",
      "message": "string",
      "status": "pending",
      "respondedAt": "2026-01-15T09:30:00.000Z",
      "lastNotifiedAt": "2026-01-15T09:30:00.000Z",
      "createdAt": "2026-01-15T09:30:00.000Z",
      "updatedAt": "2026-01-15T09:30:00.000Z",
      "reviewerName": "string",
      "reviewerImage": "string",
      "postTitle": "string",
      "postUpdatedAt": "2026-01-15T09:30:00.000Z"
    }
  ],
  "has_more": true,
  "next_cursor": "string"
}

Get review batch

get/v1/review-batches/{id}

Read a grouped approval request: its shared note and how many visible posts are still waiting. Needs posts:view and an OAuth connection for the requester or a recipient; API keys are refused.

Path parameters

idstringrequired
Min length 1

Response 200

The review group

idstringrequired
messagestringrequirednullable
totalintegerrequired
pendingintegerrequired

Errors

400: Invalid request
403: Missing permission
404: Post, request or group not found
409: The post changed or is not in a state that allows this

Request

curl "https://api.posty.social/v1/review-batches/$ID" \
  -H "Authorization: Bearer $POSTY_API_KEY"

Response 200

{
  "id": "string",
  "message": "string",
  "total": 1,
  "pending": 1
}

Remove post from review batch

del/v1/review-batches/{id}/posts/{postId}

Detach one post from a grouped approval request. Its individual asks and decisions stay; repeating is a no-op. Needs posts:submit_for_approval and an OAuth connection for the person who sent the group.

Path parameters

idstringrequired
Min length 1
postIdstringrequired
Min length 1

Response 204

Post detached from the group

Errors

400: Invalid request
403: Missing permission
404: Post, request or group not found
409: The post changed or is not in a state that allows this

Request

curl -X DELETE "https://api.posty.social/v1/review-batches/$ID/posts/$POST_ID" \
  -H "Authorization: Bearer $POSTY_API_KEY"

Response 204

No content

Models

Objects referenced by the endpoints above.

BacklogPost

idstringrequired
statusstringrequired
One ofdraftpending_approvalpending_client_approvalapprovedscheduleddeliveredpartially_delivereddelivery_failed
bodystringrequired
Display label: platform title or first caption, or a media fallback.
campaignIdstringrequirednullable
channelIdsarray of stringrequired
platformsarray of stringrequired
One ofblueskydiscordfacebookinstagramlinkedinpinterestthreadstiktokwordpressyoutube
thumbnailstringrequirednullable
Short-lived signed preview URL, when the post has one.
updatedAtstring (date-time)required

CalendarPost

idstringrequired
statusstringrequired
One ofdraftpending_approvalpending_client_approvalapprovedscheduleddeliveredpartially_delivereddelivery_failed
bodystringrequired
Display label: platform title or first caption, or a media fallback.
campaignIdstringrequirednullable
channelIdsarray of stringrequired
platformsarray of stringrequired
One ofblueskydiscordfacebookinstagramlinkedinpinterestthreadstiktokwordpressyoutube
thumbnailstringrequirednullable
Short-lived signed preview URL, when the post has one.
scheduledAtstring (date-time)requirednullable
deliveryCountsobjectrequired
Child attributes
- deliveredintegerrequired
- failedintegerrequired
- pendingintegerrequired
- permanentlyFailedintegerrequired
- totalintegerrequired
deliveryErrorCategorystringrequirednullable

PendingReviewRequest

idstringrequired
postIdstringrequired
audiencestringrequired
One ofteamclient
requestedBystringrequirednullable
emailstringrequired
userIdstringrequirednullable
invitationIdstringrequirednullable
batchIdstringrequirednullable
messagestringrequirednullable
statusstringrequired
One ofpendingapprovedchanges_requestedsupersededcancelled
respondedAtstring (date-time)requirednullable
lastNotifiedAtstring (date-time)requirednullable
createdAtstring (date-time)required
updatedAtstring (date-time)required
reviewerNamestringrequirednullable
reviewerImagestringrequirednullable
postTitlestringrequired
postUpdatedAtstring (date-time)required
Pass as expectedUpdatedAt when rescheduling this post.

Post

createdBystringrequirednullable
idstringrequired
approvalModestringrequirednullable
One ofnoneoptionalrequiredmulti_level
scheduledAtstring (date-time)requirednullable
statusstringrequired
One ofdraftpending_approvalpending_client_approvalapprovedscheduleddeliveredpartially_delivereddelivery_failed
workspaceIdstringrequired
createdAtstring (date-time)required
updatedAtstring (date-time)required
bodystring
contentarray of PostContent

PostContent

idstringrequired
postIdstringrequired
channelIdstringrequirednullable
platformstringrequired
One ofblueskydiscordfacebookinstagramlinkedinpinterestthreadstiktokwordpressyoutube
bodystringrequirednullable
firstCommentstringrequirednullable
firstCommentExternalIdstringrequirednullable
firstCommentErrorstringrequirednullable
contentTypestringrequirednullable
One ofimagevideoreelstorycarouseltext
thumbnailUrlstringrequirednullable
permalinkstringrequirednullable
hashtagsstringrequirednullable
updatedBystringrequirednullable
deliveryStatusstringrequired
One ofpendingin_progressdeliveredfailedpermanently_failedcancelledexternal
deliveryAttemptsintegerrequired
deliveryErrorstringrequirednullable
deliveryErrorCategorystringrequirednullable
One oftransformplatformauthmedia_proxyvalidationunknown
externalPostIdstringrequirednullable
consecutiveMissingFetchesintegerrequired
metadatamap of string or number or boolean or array of string or nullrequirednullable
mediaarray of objectrequired
Child attributes
- idstringrequired
- titlestringrequired
- urlstringrequirednullable
- thumbnailUrlstringrequirednullable
deliveredAtstring (date-time)requirednullable
nextRetryAtstring (date-time)requirednullable
updatedAtstring (date-time)required
historyBackfilledAtstring (date-time)requirednullable
deletedOnPlatformAtstring (date-time)requirednullable
firstCommentPostedAtstring (date-time)requirednullable

PostState

idstringrequired
statusstringrequired
One ofdraftpending_approvalpending_client_approvalapprovedscheduleddeliveredpartially_delivereddelivery_failed
approvalModestringrequirednullable
One ofnoneoptionalrequiredmulti_level
scheduledAtstring (date-time)requirednullable
updatedAtstring (date-time)required

ReviewRequest

idstringrequired
postIdstringrequired
audiencestringrequired
One ofteamclient
requestedBystringrequirednullable
emailstringrequired
userIdstringrequirednullable
invitationIdstringrequirednullable
batchIdstringrequirednullable
messagestringrequirednullable
statusstringrequired
One ofpendingapprovedchanges_requestedsupersededcancelled
respondedAtstring (date-time)requirednullable
lastNotifiedAtstring (date-time)requirednullable
createdAtstring (date-time)required
updatedAtstring (date-time)required
reviewerNamestringrequirednullable
reviewerImagestringrequirednullable
requesterNamestringrequirednullable