Schedule (publish) a draft
POST/posts/:id/schedule
Turns a draft into a live scheduled/publishing post: flips the post to
scheduled, clears draft data, and creates one queued destination per
account. Provide either scheduled_for (at least 1 minute in the
future) or publish_now: true (queued to fire within ~1 scheduler
cycle). account_ids overrides the draft's saved targets; required if
the draft has none. Non-drafts return 409 not_a_draft — use
PATCH /posts/{id} to move an already-scheduled post.
Plan post limits are enforced here
(429 post_limit_reached / daily_limit_reached).
Request
Responses
- 200
- 400
- 401
- 402
- 403
- 404
- 409
- 429
- 500
Draft scheduled
Validation error — see error.code and error.details
Missing/invalid/revoked/expired API key (codes invalid_api_key, api_key_revoked, api_key_expired, api_key_required, auth_failed). Auth-layer 401s omit error.retryable and meta.request_id.
No active subscription (code subscription_required — the error object also carries subscription_status), or insufficient AI credits (insufficient_credits) / paid plan required (upgrade_required).
API key missing the required scope (insufficient_scope), storage quota exceeded (storage_quota_exceeded), or account limit reached (account_limit_reached)
Resource not found in your organization/workspace (not_found)
Post is not a draft
Rate limit exceeded (rate_limit_exceeded, or plan budgets post_limit_reached / daily_limit_reached on schedulePost). All 429s carry Retry-After. The API-key limiter additionally sets the X-RateLimit-* headers and error.details {limit, remaining, reset_at}.
Response Headers
Seconds to wait before retrying
Requests allowed in the window (API-key limiter only)
Requests remaining (API-key limiter only)
Unix seconds when the window resets (API-key limiter only)
Internal error (internal_error and endpoint-specific 5xx codes). Retryable.