# Postify API documentation

REST API v1 for Postify, the AI social media scheduler. Base URL: `https://app.usepostify.com/v1`.

## Quickstart

1. Mint an organization API key at [Settings → API keys](https://app.usepostify.com/settings/api-keys) (org owner/admin only). Keys start with `postify_live_` and are shown once.
2. Call the API: `curl https://app.usepostify.com/v1/channels -H "Authorization: Bearer postify_live_…"`
3. Use a channel's `id` to create your first post via [createPost](https://usepostify.com/docs/api/createPost.md).

## Authentication

Send the key as `Authorization: Bearer postify_live_…` or in an `x-api-key` header. Keys are organization-scoped and carry the scopes chosen at mint.

## Scopes

- `posts:read` — View your posts and drafts
- `posts:write` — Create and edit posts
- `channels:read` — See your connected social channels
- `channels:write` — Manage channel connections
- `analytics:read` — View analytics
- `webhooks:read` — View webhooks
- `webhooks:write` — Manage webhooks
- `ai:generate` — Use AI generation (consumes your AI credits)

## Errors

RFC 9457 `application/problem+json`: `{ type, title, status, code, detail, request_id }`. Branch on `code`; `type` resolves to a docs page. [All 14 error codes](https://usepostify.com/docs/api/problems.md).

## Pagination

List endpoints return `{ data, has_more, next_cursor }`. Pass `limit` (1–100) and `after` (a previous page's `next_cursor`).

## Idempotency

POST /v1/posts accepts an `Idempotency-Key` header (24h ledger). Replays return the recorded response with `Idempotency-Replayed: true`; the same key with a different body is a 422 `idempotency_key_reused`.

## Rate limits

Responses carry IETF draft-11 `RateLimit`/`RateLimit-Policy` headers plus the `X-RateLimit-*` trio. Two distinct 429s: `rate_limited` (per-key burst — honor `Retry-After`) and `quota_exhausted` (monthly plan allowance — retrying is pointless until reset).

| Plan | API requests / month | Per-key burst / minute |
| --- | --- | --- |
| Free | 1,000 | 30 |
| Starter | 10,000 | 60 |
| Team | 50,000 | 120 |
| Agency | 250,000 | 300 |

## Dangerous operations

`DELETE /v1/posts/{id}` and `POST /v1/posts/{id}/publish` return 403 `dangerous_ops_disabled` until an org owner enables "Dangerous AI operations" in [Settings → API keys](https://app.usepostify.com/settings/api-keys). Drafts and scheduled posts need no toggle.

## Operations

### Analytics

- [getAnalytics](https://usepostify.com/docs/api/getAnalytics.md) — `GET /v1/analytics` — Get workspace analytics

### Channels

- [listChannels](https://usepostify.com/docs/api/listChannels.md) — `GET /v1/channels` — List channels

### Media

- [listMedia](https://usepostify.com/docs/api/listMedia.md) — `GET /v1/media` — List media assets
- [createMediaUpload](https://usepostify.com/docs/api/createMediaUpload.md) — `POST /v1/media/uploads` — Start a media upload
- [completeMediaUpload](https://usepostify.com/docs/api/completeMediaUpload.md) — `POST /v1/media/uploads/{id}/complete` — Complete a media upload

### Posts

- [listPosts](https://usepostify.com/docs/api/listPosts.md) — `GET /v1/posts` — List posts
- [createPost](https://usepostify.com/docs/api/createPost.md) — `POST /v1/posts` — Create a post
- [getPost](https://usepostify.com/docs/api/getPost.md) — `GET /v1/posts/{id}` — Get a post
- [reschedulePost](https://usepostify.com/docs/api/reschedulePost.md) — `PATCH /v1/posts/{id}` — Reschedule a post
- [deletePost](https://usepostify.com/docs/api/deletePost.md) — `DELETE /v1/posts/{id}` — Delete a post
- [publishPost](https://usepostify.com/docs/api/publishPost.md) — `POST /v1/posts/{id}/publish` — Publish a post now

### Usage

- [getUsage](https://usepostify.com/docs/api/getUsage.md) — `GET /v1/usage` — Get plan usage

### Webhooks

- [listWebhookEndpoints](https://usepostify.com/docs/api/listWebhookEndpoints.md) — `GET /v1/webhook-endpoints` — List webhook endpoints
- [createWebhookEndpoint](https://usepostify.com/docs/api/createWebhookEndpoint.md) — `POST /v1/webhook-endpoints` — Create a webhook endpoint
- [updateWebhookEndpoint](https://usepostify.com/docs/api/updateWebhookEndpoint.md) — `PATCH /v1/webhook-endpoints/{id}` — Update a webhook endpoint
- [deleteWebhookEndpoint](https://usepostify.com/docs/api/deleteWebhookEndpoint.md) — `DELETE /v1/webhook-endpoints/{id}` — Delete a webhook endpoint
- [testWebhookEndpoint](https://usepostify.com/docs/api/testWebhookEndpoint.md) — `POST /v1/webhook-endpoints/{id}/test` — Send a test delivery

## More

- [Webhooks event catalog & verification](https://usepostify.com/docs/api/webhooks.md)
- [Interactive reference (Scalar)](https://app.usepostify.com/docs/api-reference)
- [OpenAPI 3.1 spec](https://app.usepostify.com/v1/openapi.json)
- [Developer overview](https://usepostify.com/developers.md)
- [For AI agents](https://usepostify.com/docs/ai.md) · [llms.txt](https://usepostify.com/llms.txt)
- [Changelog](https://usepostify.com/changelog.md)