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
- 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. - Make your first call — list the channels you can publish to:
curl https://app.usepostify.com/v1/channels \
-H "Authorization: Bearer postify_live_XXXXXXXXXXXXXXXX"{
"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"
}
]
}- Use a channel's
idto 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
| Scope | Grants |
|---|---|
posts:read | View your posts and drafts |
posts:write | Create and edit posts |
posts:publish | Publish posts to your social accounts right away |
posts:delete | Delete posts and media |
channels:read | See your connected social channels |
channels:write | Manage channel connections |
inbox:read | Read your inbox — mentions, comments and direct messages from your connected accounts |
inbox:reply | Send replies to comments and mentions from your accounts |
analytics:read | View analytics |
webhooks:read | View webhooks |
webhooks:write | Manage webhooks |
ai:generate | Use AI generation (consumes your AI credits) |
workspace:read | See workspace settings (name, timezone, brand voice) |
workspace:write | Change workspace settings |
account:read | See your profile and notification settings |
account:write | Change your profile and notifications, export or delete your account |
team:read | See workspace members and invites |
team:write | Invite, remove and change members; create or delete workspaces |
billing:read | See your plan, usage and renewal |
billing:write | Start a purchase, change or cancel your subscription |
support:read | See your support requests |
support:write | Send support requests |
keys:read | See API keys, connected AI apps and API logs |
keys:write | Create, 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.
{
"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:
- Start the upload with
the
filename, thecontent_typeand the exactsize_bytesof the file. Only image, video and audio types are accepted (image/svg+xmlis 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 400validation_failedwith the field inerrors. (Earlier versions signed anycontent_type, includingtext/htmland SVG. Those are now refused because the bucket serves them back as active content.) PUTthe raw bytes to the returnedupload_url. Send the sameContent-Typeyou declared, and exactlysize_bytesbytes when you sent it: the URL is signed for that header and length, so storage answers 403 to a different or missingContent-Type, and refuses a body of any other length.- Complete the upload,
then, once the asset is
ready, use itsurlasmedia[].urlon a post. An image isreadyin the response. A video or audio file is probed after the response, which can take a few minutes, so it comes backpending: call complete again (it is idempotent and returns the current asset) or poll List media until itsstatusisready, orfailedwith afailure_reason, before you attach it.
What completing does, and what that changes for you:
- The
PUTtoupload_urlstores 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'surlreads nothing until then: it answers 404 for an upload that is not completed. - A second
PUTtoupload_urlafter you complete does not replace the file. Thereadyasset keeps the bytes that were checked; to change the file, request a new upload. - A post that holds a
failedor still-processing video is refused (validation_failed) when you schedule or publish it, so wait forreadyfirst. 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_conflictand the asset stayspending:PUTthe file and complete again. (A video that is not there yet used to be markedfailed; it now stayspending, 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_conflictand leaves the assetpending:PUTthe 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 bodyPUTto the URL after you complete is never served and never changes thereadyasset; - an upload you never complete, or
PUTagain 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.mp4Rate 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).
| Plan | API requests / month | Per-key burst / minute |
|---|---|---|
| Free | 1,000 | 30 |
| Starter | 10,000 | 60 |
| Team | 50,000 | 120 |
| Agency | 250,000 | 300 |
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: 1800000038Dangerous 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
| Operation | Endpoint | Summary |
|---|---|---|
getAnalytics | GET /v1/analytics | Get workspace analytics |
Channels
| Operation | Endpoint | Summary |
|---|---|---|
listChannels | GET /v1/channels | List channels |
Media
| Operation | Endpoint | Summary |
|---|---|---|
listMedia | GET /v1/media | List media assets |
createMediaUpload | POST /v1/media/uploads | Start a media upload |
completeMediaUpload | POST /v1/media/uploads/{id}/complete | Complete a media upload |
Posts
| Operation | Endpoint | Summary |
|---|---|---|
listPosts | GET /v1/posts | List posts |
createPost | POST /v1/posts | Create a post |
getPost | GET /v1/posts/{id} | Get a post |
reschedulePost | PATCH /v1/posts/{id} | Reschedule a post |
deletePost | DELETE /v1/posts/{id} | Delete a post |
publishPost | POST /v1/posts/{id}/publish | Publish a post now |
Usage
| Operation | Endpoint | Summary |
|---|---|---|
getUsage | GET /v1/usage | Get plan usage |
Webhooks
| Operation | Endpoint | Summary |
|---|---|---|
listWebhookEndpoints | GET /v1/webhook-endpoints | List webhook endpoints |
createWebhookEndpoint | POST /v1/webhook-endpoints | Create a webhook endpoint |
updateWebhookEndpoint | PATCH /v1/webhook-endpoints/{id} | Update a webhook endpoint |
deleteWebhookEndpoint | DELETE /v1/webhook-endpoints/{id} | Delete a webhook endpoint |
testWebhookEndpoint | POST /v1/webhook-endpoints/{id}/test | Send a test delivery |
More
- Webhooks — event catalog, Standard Webhooks verification, retry schedule.
- Post from Python — working
requestscode with idempotency keys,Retry-Afterand problem+json handling. - API reference — one page per operation: every schema, try-it-out included.
- OpenAPI 3.1 spec — feed it to your generator of choice.
- Developer overview · For AI agents · llms.txt
Connecting AI assistants (MCP)
Connect Claude, ChatGPT, Cursor, VS Code, Gemini or any MCP-capable client to your Postify workspace with the Postify MCP server.
Post to social media from Python
Automate social media posting from Python with one REST call instead of a script per network. Working requests code with Idempotency-Key, Retry-After and RFC 9457 errors.