Publish and Schedule
Create a draft post, publish immediately or schedule for later, retry failures, and cancel a schedule.
End-to-end path from captions (and optional media) to live social posts.
Prerequisites
- Connected accounts — Settings → Connections for each platform you target
- API key scopes —
posts:writeto create,posts:publishto publish/schedule/cancel/retry,posts:readto inspect - Workspace ID header on every call
- Content ready — captions (from a generation or your own text) and media that meet post type limits
Flow overview
Create post (draft) → Publish now OR Schedule for later
↓
Poll get post / webhooks
↓
Retry failed items if needed1. Create a draft post
From a completed caption generation:
curl -X POST https://powerpost.ai/api/v1/posts \
-H "x-api-key: pp_live_sk_YOUR_KEY" \
-H "X-Workspace-Id: YOUR_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{
"generation_id": "550e8400-e29b-41d4-a716-446655440000",
"items": [
{
"post_type": "instagram-reel",
"media_ids": ["img-001-abcd-efgh"]
},
{
"post_type": "tiktok-video",
"media_ids": ["img-001-abcd-efgh"]
}
]
}'Or pass custom content / title per item without a generation. Full options: Create post.
Save the post_id and each item's item_id.
2a. Publish now
curl -X POST https://powerpost.ai/api/v1/posts/POST_ID/publish \
-H "x-api-key: pp_live_sk_YOUR_KEY" \
-H "X-Workspace-Id: YOUR_WORKSPACE_ID" \
-H "Content-Type: application/json" \
-d '{}'Optional per-item settings (TikTok privacy, YouTube visibility, Threads who can reply) go in items[]. TikTok and YouTube default to private; Threads reply_control defaults to everyone. See Publish settings.
A 200 means the job was enqueued. The post stays draft until the worker claims it, then moves to sent while items resolve to posted or failed.
2b. Schedule for later
curl -X POST https://powerpost.ai/api/v1/posts/POST_ID/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"
}'scheduled_at must be at least a minute ahead and within 60 days. Max 100 scheduled posts per workspace.
3. Track status
curl https://powerpost.ai/api/v1/posts/POST_ID \
-H "x-api-key: pp_live_sk_YOUR_KEY" \
-H "X-Workspace-Id: YOUR_WORKSPACE_ID"Or listen for post_item.published / post_item.failed webhooks.
| Post status | Meaning |
|---|---|
draft | Not published yet |
scheduled | Waiting for scheduled_at |
sent | Publish started; check each item |
4. Retry a failed item
curl -X POST https://powerpost.ai/api/v1/post-items/ITEM_ID/retry \
-H "x-api-key: pp_live_sk_YOUR_KEY" \
-H "X-Workspace-Id: YOUR_WORKSPACE_ID"5. Cancel a schedule
Only while nothing has gone out yet:
curl -X POST https://powerpost.ai/api/v1/posts/POST_ID/cancel-publish \
-H "x-api-key: pp_live_sk_YOUR_KEY" \
-H "X-Workspace-Id: YOUR_WORKSPACE_ID"Credits and connections
- Credits charge per successful item after publish runs, not when you call publish/schedule. See Credits.
- If some platforms aren't connected, connected ones still publish and others appear in
skipped. If none are connected, you get422.