Publish & Schedule

Publish a draft post immediately, schedule it for later, cancel a scheduled publish, or set platform-specific options (TikTok privacy, YouTube visibility, Threads who can reply).

Publish Post

POST /api/v1/posts/{id}/publish

Publish a draft post to connected social platforms. Each item is published to its target platform independently — if one fails, the others still go through.

Prerequisites

Before publishing, ensure:

1. Platforms are connected — Connect your social accounts in Settings → Connections
2. Post is publishable — A post can be published only when its status is draft. After first publish starts, the post moves to sent and each item owns its own lifecycle. Retry failed items with POST /api/v1/post-items/{id}/retry.
3. Sufficient credits — Publishing costs vary by platform (premium platforms like X cost more)

Path Parameters

Body Parameters

If items is omitted entirely (or sent without settings), all items publish with the documented defaults.

Example

curl -X POST https://powerpost.ai/api/v1/posts/post-550e8400-e29b-41d4-a716-446655440000/publish \
  -H "x-api-key: pp_live_sk_YOUR_KEY" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "item_id": "item-yt-002-cccc-dddd",
        "settings": {
          "privacy_status": "public",
          "self_declared_made_for_kids": false,
          "embeddable": true
        }
      }
    ]
  }'

Response

{
  "post_id": "post-550e8400-e29b-41d4-a716-446655440000",
  "status": "draft",
  "skipped": ["x"],
  "status_url": "/api/v1/posts/post-550e8400-e29b-41d4-a716-446655440000"
}

Publishing is asynchronous. A 200 means the publish was accepted and enqueued; the post stays draft until the background job claims it and moves it to sent. Poll the Get Post endpoint or use webhooks to know when publishing completes.

If only some target platforms are connected, the connected ones publish and the rest come back in skipped. The whole request is rejected with a 422 only when none of the target platforms are connected.

Publishing Costs

Publishing costs vary by platform. Premium platforms (X) cost more due to higher API costs. Credits are charged per successful item in the background — the publish response itself does not include a cost figure since nothing has been charged yet. Check your balance via Get Credits after publishing. When charges apply: Credits. Rates: pricing.

Schedule Post

POST /api/v1/posts/{id}/schedule

Schedule a draft post to publish automatically at a future time. The post is held in scheduled status until then, when it publishes exactly as Publish Post would.

Prerequisites

Same as publishing — platforms connected and content ready. The post must be in draft status. Credits aren't checked when you schedule; they're charged per successful item when the post publishes, so make sure the balance is funded before the scheduled time.

A workspace can hold up to 100 scheduled posts at once; scheduling more returns a 400.

Path Parameters

Request Body

Example

curl -X POST https://powerpost.ai/api/v1/posts/post-550e8400-e29b-41d4-a716-446655440000/schedule \
  -H "x-api-key: pp_live_sk_YOUR_KEY" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduled_at": "2026-02-01T15:00:00Z",
    "items": [
      {
        "item_id": "item-yt-002-cccc-dddd",
        "settings": {
          "privacy_status": "public",
          "self_declared_made_for_kids": false,
          "embeddable": true
        }
      }
    ]
  }'

Response

{
  "post_id": "post-550e8400-e29b-41d4-a716-446655440000",
  "status": "scheduled",
  "scheduled_at": "2026-02-01T15:00:00Z",
  "skipped": ["x"],
  "status_url": "/api/v1/posts/post-550e8400-e29b-41d4-a716-446655440000"
}

Publish Settings Reference

Some post types accept extra publish-time settings via the optional items[].settings field on Publish Post and Schedule Post.

TikTok Video (tiktok-video)

TikTok Photos (tiktok-photos)

Same as TikTok Video minus disable_duet and disable_stitch.

YouTube Video & Short (youtube-video, youtube-short)

Threads (threads-post)

Other Platforms

Instagram, Facebook, X, and LinkedIn have no publish-time settings. Sending settings for one of those items returns 400.

Cancel Scheduled Post

POST /api/v1/posts/{id}/cancel-publish

Cancel a scheduled (or in-progress) publish and revert the post to a draft. Only works while nothing has gone out yet — once any item has started posting, the publish can no longer be cancelled.

Path Parameters

Example

curl -X POST https://powerpost.ai/api/v1/posts/post-550e8400-e29b-41d4-a716-446655440000/cancel-publish \
  -H "x-api-key: pp_live_sk_YOUR_KEY" \
  -H "X-Workspace-Id: YOUR_WORKSPACE_ID"

Response

{
  "post_id": "post-550e8400-e29b-41d4-a716-446655440000",
  "status": "draft",
  "reverted": true
}

Errors

Related

• Posts — Create and get posts
• Post items — List and retry
• Post types — Media and caption limits
• Credits — How publishing is charged
• Webhooks — post_item.published / post_item.failed