Create, schedule, or draft a post
POST/posts
Omit scheduled_for to publish immediately; provide it (ISO 8601,
assumed UTC when no offset given) to schedule. Set draft: true to
save a native draft instead (no destinations are created and nothing
publishes until POST /posts/{id}/schedule).
Attach media by id (see media requirements per platform),
and use platform_content for per-platform overrides — the
Platform Guides document every option.
Field-name handling: camelCase aliases (accountIds, mediaIds,
scheduledFor, platformContent) and the deprecated scheduled_at
alias are accepted. Fields whose names imply a different shape
(media, media_id, mediaId, attachments) are rejected with
400 invalid_field_name.
Content rules: content may be omitted only when platform_content
provides at least one per-platform caption or media is attached.
Max 10,000 characters. Max 50 account_ids. Instagram captions with
more than 30 hashtags are rejected
(instagram_hashtag_limit_exceeded).
Media referenced by media_ids must exist in the workspace and be
ready (media_not_found / media_not_ready otherwise; media stuck
in uploading is auto-finalized via the /complete flow when the
file was actually uploaded). Platform media requirements are
validated pre-flight (platform_requirement_violation, e.g. video to
Pinterest).
A circuit breaker refuses a request body that has already failed
5+ times in 6 hours for the same key with
422 permanent_failure_circuit_breaker — change any field to reset.
Error codes: invalid_json, wrong_content_type_for_endpoint,
invalid_field_name, validation_error, content_too_long,
account_ids_required, too_many_accounts, invalid_timezone,
invalid_accounts, instagram_hashtag_limit_exceeded,
invalid_datetime, past_schedule_time, media_not_found,
media_not_ready, platform_requirement_violation,
post_creation_failed, rate_limit_exceeded,
permanent_failure_circuit_breaker.
Request
Responses
- 201
- 400
- 401
- 402
- 403
- 422
- 429
- 500
Post created. Regular creates return the full publishing topology
(destinations); draft: true returns the smaller draft shape
with next_steps.
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)
Circuit breaker open for this exact request body
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.