PostifyPostify Docs
Public API

API documentation

Everything to build on the Postify REST API — 5-minute quickstart, API-key auth, RFC 9457 errors, cursor pagination, idempotency keys, rate limits, and all 17 operations with examples.

REST API v1 for programmatic scheduling and publishing. Base URL https://app.usepostify.com/v1.

5-minute quickstart

  1. Mint an organization API key at Settings → API keys (org owners and admins only). Keys start with postify_live_ and are shown once — store the secret immediately.
  2. Make your first call — list the channels you can publish to:
curl https://app.usepostify.com/v1/channels \
  -H "Authorization: Bearer postify_live_XXXXXXXXXXXXXXXX"
200 OK · application/json
{
  "data": [
    {
      "id": "cmc1x2y3z0001abcd",
      "platform": "linkedin",
      "handle": "Acme Co",
      "avatar_url": null,
      "followers": 4210,
      "status": "live",
      "last_sync_at": "2026-10-01T09:30:00Z",
      "last_error": null,
      "created_at": "2026-08-14T15:02:11Z"
    },
    {
      "id": "cmc9x2y3z0001abcd",
      "platform": "bluesky",
      "handle": "acme.bsky.social",
      "avatar_url": null,
      "followers": 980,
      "status": "live",
      "last_sync_at": "2026-10-01T09:30:00Z",
      "last_error": null,
      "created_at": "2026-09-02T18:45:40Z"
    }
  ]
}
  1. Use a channel's id to create your first post — as a draft, scheduled, or published now.

Authentication

Send your key on every request, either way:

  • Authorization: Bearer postify_live_…
  • x-api-key: postify_live_…

Keys are organization-scoped: they see exactly the workspace they were minted in. Each key carries the scopes chosen at mint — every operation page lists the scope it requires.

Scopes

ScopeGrants
posts:readView your posts and drafts
posts:writeCreate and edit posts
posts:publishPublish posts to your social accounts right away
posts:deleteDelete posts and media
channels:readSee your connected social channels
channels:writeManage channel connections
inbox:readRead your inbox — mentions, comments and direct messages from your connected accounts
inbox:replySend replies to comments and mentions from your accounts
analytics:readView analytics
webhooks:readView webhooks
webhooks:writeManage webhooks
ai:generateUse AI generation (consumes your AI credits)
workspace:readSee workspace settings (name, timezone, brand voice)
workspace:writeChange workspace settings
account:readSee your profile and notification settings
account:writeChange your profile and notifications, export or delete your account
team:readSee workspace members and invites
team:writeInvite, remove and change members; create or delete workspaces
billing:readSee your plan, usage and renewal
billing:writeStart a purchase, change or cancel your subscription
support:readSee your support requests
support:writeSend support requests
keys:readSee API keys, connected AI apps and API logs
keys:writeCreate, rotate and revoke API keys and connected AI apps

Errors

Every error is RFC 9457 application/problem+json. Branch on the stable code; the type URI resolves to a docs page for that exact code. Validation errors add an errors array; each entry has a JSON Pointer (pointer) to the offending field, a field-level code and a message.

400 Bad Request · application/problem+json
{
  "type": "https://usepostify.com/docs/api/problems/validation-failed",
  "title": "Request validation failed",
  "status": 400,
  "code": "validation_failed",
  "detail": "One or more channel_ids are not connected to this organization — see GET /v1/channels.",
  "errors": [
    {
      "pointer": "/variants/0/channel_id",
      "code": "unknown_channel",
      "message": "Channel cmc0unknown0000abcd is not connected to this organization."
    }
  ],
  "request_id": "req_6f1f8a2b40d34cd2a6f1e2c9b8d7a601"
}

All 14 codes: error-code index.

Pagination

List endpoints return { data, has_more, next_cursor }. Pass limit (1–100) and after — a previous page's next_cursor — to walk the collection. Cursors are opaque; never parse them.

Idempotency

POST /v1/posts accepts an Idempotency-Key header (1–255 printable ASCII characters — use a UUID). The ledger keeps keys for 24 hours:

  • Same key + same body → the recorded response replays verbatim, with Idempotency-Replayed: true.
  • Same key + different body → 422 idempotency_key_reused.
  • Same key while the first attempt still runs → 409 idempotency_in_progress — wait and retry the same key.

Uploading media

Media is a three-step flow, and the upload URL is signed for what you declare in step 1:

  1. Start the upload with the filename, the content_type and the exact size_bytes of the file. Only image, video and audio types are accepted (image/svg+xml is not), plus PDF, PPT, PPTX, DOC and DOCX documents, judged by the filename extension (XLSX and other Office types are refused). A refused type or a size over your plan's per-file limit answers 400 validation_failed with the field in errors. (Earlier versions signed any content_type, including text/html and SVG. Those are now refused because the bucket serves them back as active content.)
  2. PUT the raw bytes to the returned upload_url. Send the same Content-Type you declared, and exactly size_bytes bytes when you sent it: the URL is signed for that header and length, so storage answers 403 to a different or missing Content-Type, and refuses a body of any other length.
  3. Complete the upload, then, once the asset is ready, use its url as media[].url on a post. An image is ready in the response. A video or audio file is probed after the response, which can take a few minutes, so it comes back pending: call complete again (it is idempotent and returns the current asset) or poll List media until its status is ready, or failed with a failure_reason, before you attach it.

What completing does, and what that changes for you:

  • The PUT to upload_url stores your file as a staging object. Completing checks it (size against your plan, type against the one you declared), copies it to the asset's own key and deletes the staging object. The asset's url reads nothing until then: it answers 404 for an upload that is not completed.
  • A second PUT to upload_url after you complete does not replace the file. The ready asset keeps the bytes that were checked; to change the file, request a new upload.
  • A post that holds a failed or still-processing video is refused (validation_failed) when you schedule or publish it, so wait for ready first. Completing a video that is already being probed returns it as it is. A file over your plan, or stored as another type than you declared, is refused in the completing response itself.
  • Completing before the file is in storage answers 409 resource_conflict and the asset stays pending: PUT the file and complete again. (A video that is not there yet used to be marked failed; it now stays pending, so a retry can succeed.)

Always send size_bytes

size_bytes is strongly recommended and will be required in a future major version of the API. When sent it is checked against your plan's per-file limit and signed into the URL, so storage refuses a body of any other length. A request without it still works, for callers built on earlier SDK versions, and is answered with a Deprecation header (an RFC 9745 date) and a Link with rel="deprecation". That path is weaker, and you should not rely on it:

  • the URL is not length-bound, so the plan limit is enforced when you complete the upload, which measures the object. Completing before the file is in storage answers 409 resource_conflict and leaves the asset pending: PUT the file, then complete again;
  • a presigned URL stays valid for its whole life (5 minutes without size_bytes, 15 with it). Completing copies the checked object to the asset's own key, so a body PUT to the URL after you complete is never served and never changes the ready asset;
  • an upload you never complete, or PUT again after completing, leaves an object of unbounded size until it is swept.
curl -X PUT "$UPLOAD_URL"   -H "Content-Type: video/mp4"   --data-binary @launch-teaser.mp4

Rate limits & plan quotas

Two independent limits, with distinct 429 codes so your retry logic can be correct: rate_limited (per-key burst — honor Retry-After) and quota_exhausted (monthly plan allowance — retrying is pointless until the period resets).

PlanAPI requests / monthPer-key burst / minute
Free1,00030
Starter10,00060
Team50,000120
Agency250,000300

Every API-key response carries IETF draft-11 rate-limit headers plus the X-RateLimit compatibility trio:

RateLimit-Policy: "per-key-minute";q=120;w=60
RateLimit: "per-key-minute";r=73;t=38
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 73
X-RateLimit-Reset: 1800000038

Dangerous operations

DELETE /v1/posts/{id} and POST /v1/posts/{id}/publish can destroy content or publish publicly to real accounts, so each needs its own scope: posts:delete and posts:publish. Both sit in the "Delete, publish or send" permission you tick when you create a key in Settings → API keys; a key without them gets 403 insufficient_scope. Drafts and scheduled posts need only posts:write, with one exception: a scheduled_at less than 60 seconds ahead is sent by the next publish sweep, so it needs posts:publish as well.

All operations

Analytics

OperationEndpointSummary
getAnalyticsGET /v1/analyticsGet workspace analytics

Channels

OperationEndpointSummary
listChannelsGET /v1/channelsList channels

Media

OperationEndpointSummary
listMediaGET /v1/mediaList media assets
createMediaUploadPOST /v1/media/uploadsStart a media upload
completeMediaUploadPOST /v1/media/uploads/{id}/completeComplete a media upload

Posts

OperationEndpointSummary
listPostsGET /v1/postsList posts
createPostPOST /v1/postsCreate a post
getPostGET /v1/posts/{id}Get a post
reschedulePostPATCH /v1/posts/{id}Reschedule a post
deletePostDELETE /v1/posts/{id}Delete a post
publishPostPOST /v1/posts/{id}/publishPublish a post now

Usage

OperationEndpointSummary
getUsageGET /v1/usageGet plan usage

Webhooks

OperationEndpointSummary
listWebhookEndpointsGET /v1/webhook-endpointsList webhook endpoints
createWebhookEndpointPOST /v1/webhook-endpointsCreate a webhook endpoint
updateWebhookEndpointPATCH /v1/webhook-endpoints/{id}Update a webhook endpoint
deleteWebhookEndpointDELETE /v1/webhook-endpoints/{id}Delete a webhook endpoint
testWebhookEndpointPOST /v1/webhook-endpoints/{id}/testSend a test delivery

More

On this page