Posts

Change post status

Pause a scheduled post, resume/schedule a paused/paused_due_to_token/draft/failed post, or move a scheduled/failed/paused post back to draft. Published, publishing, and processing posts cannot be changed through this endpoint. A paused_due_to_token post (paused because its account token died) resumes only once the account is reconnected: 409 account_needs_reconnect while the account still needs a reconnect, and 409 needs_reschedule (with original_scheduled_at) when its time has passed and no future scheduled_at is supplied. The API never publishes a missed post immediately. X posts in paused_due_to_token cannot be resumed through this endpoint (409 status_transition_not_allowed); resume them from the dashboard. Reconnecting an account resumes its future token-paused posts automatically, and publishes ones that missed their time by less than 24 hours.

put/api/v1/posts/{id}/status

Request

  • Base URL: https://www.poster.ly
  • URL: https://www.poster.ly/api/v1/posts/{id}/status
  • Auth: HTTP bearer

Path parameters

idinteger required

Post ID

Request body

status'scheduled' | 'paused' | 'draft' required

paused pauses a scheduled post. scheduled resumes/schedules a paused, paused_due_to_token, draft, or failed post. draft moves a scheduled, failed, or paused post back to drafts.

scheduled_atstring date-time nullable

Required when scheduling a draft. Optional when resuming a paused or paused_due_to_token post whose original scheduled time is still in the future; required (and must be in the future) when that time has passed.

Example request

{
  "status": "paused"
}

Response

Post status updated successfully

Example response

{
  "post": {
    "id": 971,
    "content": "Searching for the best teeth whitening device?",
    "scheduled_at": "2026-03-11T09:45:00.000Z",
    "social_account_id": 123,
    "status": "paused",
    "created_at": "2026-03-10T09:45:00.000Z",
    "updated_at": "2026-03-10T10:10:00.000Z"
  },
  "transition": {
    "old_status": "scheduled",
    "new_status": "paused",
    "removed_queued_jobs": 1,
    "queued": false
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.