---
title: "Change post status"
method: PUT
path: "/api/v1/posts/{id}/status"
tags: ["Posts"]
---

# Change post status

`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

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.

## Path parameters

- `id` integer, required

## Request body

- PostStatusUpdateRequest
  - `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_at` string, 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.

## Response `200`

Post status updated successfully

- PostStatusUpdateResponse
  - `post` Post, required
    - `id` integer, required
    - `content` string, nullable
    - `scheduled_at` string, date-time, required
    - `social_account_id` integer, required
    - `media_url` string, nullable
    - `media_urls` string[], nullable
    - `status` string, required
    - `post_type` string, nullable
    - `platform_post_url` string, nullable
    - `published_at` string, date-time, nullable
    - `metadata` object, nullable
    - `reel_cover_url` string, nullable
    - `reel_cover_method` string, nullable
    - `reel_thumb_offset` number, nullable
    - `created_at` string, date-time, required: When the post was created (ISO 8601 with time zone). Read-only.
    - `updated_at` string, date-time, required
    - `created_by` object: Who or what created the post. Read-only. Any field is null when it was never recorded: posts created before the creation channel was tracked have a null source.
      - `user_id` string, uuid, nullable, required: The posterly account the post was created under.
      - `name` string, nullable, required: That account's full name, falling back to its username, then its email address. Filled in by GET /api/v1/posts, GET /api/v1/posts/{id}, and PATCH /api/v1/posts/{id}; null elsewhere or when unknown.
      - `source` string, nullable, required: How the post was created, for example dashboard, api_v1, mcp_http, mcp_stdio, bulk_upload, autopublisher, weekly_pack.
      - `source_label` string, nullable, required: A readable label for source, for example Dashboard, REST API, MCP.
    - `brand_id` string, uuid, nullable: The assigned brand/client, matching the id from GET /api/v1/brands. Read-only.
    - `content_plan_id` string, uuid, nullable: Read-only.
    - `workspace_id` string, uuid, nullable: The workspace this post belongs to. Read-only; null only for legacy posts created before workspaces.
    - `approval` object: Client review status. Cannot be set through POST or PATCH. Change it with POST /api/v1/posts/{id}/approval (workspace owner or admin only).
      - `status` 'none' | 'pending_client' | 'approved' | 'changes_requested' | 'rejected', required
      - `asset_status` 'none' | 'pending_client' | 'approved' | 'changes_requested' | 'rejected', required
      - `caption_status` 'none' | 'pending_client' | 'approved' | 'changes_requested' | 'rejected', required
      - `waiting_on` 'client' | 'team', nullable, required: 'client' when status is pending_client, 'team' when changes_requested or rejected, null otherwise.
      - `pending_client_approval` boolean, required: True only when status is pending_client.
      - `requested_at` string, date-time, nullable, required
      - `completed_at` string, date-time, nullable, required
  - `transition` object, required
    - `old_status` string, required
    - `new_status` string, required
    - `removed_queued_jobs` integer, required
    - `queued` boolean, required

## Other responses

- `400`: Validation error
- `401`: Invalid or missing API key
- `404`: Resource not found
- `409`: Validation error
- `429`: Too many requests

---

[API](https://skmtc.dev/poster/apis/posterly-api.md) · [All operations](https://skmtc.dev/poster/apis/posterly-api/llms.txt) · [OpenAPI document](https://skmtc.dev/poster/apis/posterly-api/revisions/60be02a61f95?raw)