POST/v1/posts

createPost

Create a post. Creates a post with one variant per target channel. Exactly one mode is required: `draft: true` (save only), `scheduled_at` (future publish), or `publish_now: true` (immediate — requires the workspace's dangerous-operations toggle for API callers). Send an `Idempotency-Key` header to make retries safe.

Required scope:posts:write

Idempotent by design

Send an Idempotency-Key header (a UUID) so retries can never double-post. Replays of the same key + body return the recorded response with Idempotency-Replayed: true; the same key with a different body is rejected with 422 idempotency_key_reused. Ledger window: 24 hours. Details: idempotency docs.

Headers

Idempotency-Keystringoptional

Client-chosen key (1–255 printable ASCII chars, e.g. a UUID) making this POST safely retryable: within 24h, the same key + same body replays the original response with `Idempotency-Replayed: true`; the same key with a DIFFERENT body is rejected with 422 `idempotency_key_reused`.

Request body

variantsarray of objectrequired

One variant per target channel.

channel_idstringrequired

A connected channel's `id` (see /v1/channels).

bodystringrequired

The text to publish to this channel.

mediaarray of PostMediaItemoptional

Media attachments for this channel.

titlestring | nulloptional

Internal title (not published).

bodystring | nulloptional

Optional channel-agnostic base text.

draftbooleanoptional

Save as a draft (no scheduling, no publishing).

scheduled_atstring (ISO-8601)optional

Future publish time (ISO-8601). Mutually exclusive with `draft` and `publish_now`.

publish_nowbooleanoptional

Publish immediately. Requires the workspace's dangerous-operations toggle for API callers.

Depth-limited view — the interactive reference has every nested schema.

Responses

201Post

The created post.

400invalid_requestvalidation_failed
401authentication_requiredinvalid_api_key
403insufficient_scopefeature_not_enableddangerous_ops_disabled
409idempotency_in_progress
422idempotency_key_reused
429rate_limitedquota_exhausted
500internal_error

Errors are RFC 9457 problem+json with a stable code and a request_id — each code above links to its own page.

Example

curl -X POST https://app.usepostify.com/v1/posts \
  -H "Authorization: Bearer postify_live_XXXXXXXXXXXXXXXX" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "variants": [
    {
      "channel_id": "ch_9x2y3z0001",
      "body": "Shipping day 🚀 Our new analytics dashboard is live — see what actually lands with your audience."
    }
  ],
  "scheduled_at": "2026-08-01T09:00:00Z"
}'