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. Enough credits — Publishing uses credits. The amount depends on the platform.

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 uses credits. You are charged for each item that publishes successfully, after it goes out. The amount depends on the platform. The publish response does not include a cost, because nothing has been charged yet. Check your balance with Get Credits after publishing. See Credits.

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)

YouTube may restrict uploads to private viewing for unverified API projects, regardless of the requested visibility. See YouTube's upload restrictions.

Threads (threads-post)

Instagram (instagram-feed, instagram-reel, instagram-story)

Set this to true when you want Instagram's AI info label on the post. The label goes on the container that gets published. Carousel slides are not labeled on their own. PowerPost does not turn this on based on how the media was made.

Other Platforms

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