API Reference

The endpoint reference in this section is generated from openapi.json.

Base URL

All endpoints are served from:

https://api.postzen.dev

Authentication

Use a bearer API key with every API request:

Authorization: Bearer POSTZEN_API_KEY

Create and manage API keys on the API keys page in the dashboard.

Permission — read-only keys can call read endpoints. Create, update, delete, connect, media upload, and post creation endpoints require a read-write key.
Profile access — a key has access to all profiles or a selected set. Requests that touch a profile outside the key's scope return 403.

Rate limits

Requests are rate limited per user across all API keys. Your plan sets the shared limit:

Plan	Requests per minute
Free	60
Starter	120
Pro	600
Scale	2,000

Exceeding the limit returns 429 with the body {"error":"rate_limited"} and a Retry-After header giving the number of seconds to wait before retrying.

Errors return a JSON body with an error message and a conventional status code: 400 for invalid input, 401 for a missing or invalid key, 402 when an account-connection or monthly post limit blocks a request, 403 for insufficient permission or profile access, 404 when a resource does not exist, 429 when the rate limit is exceeded, and 500 for unexpected server errors.

Idempotency

POST /v1/posts accepts an optional x-request-id header. Repeating a request with the same value returns the original post (status 200) instead of creating a duplicate.

Webhooks

Use webhooks to receive terminal post outcomes and account connection changes without polling. Start with the webhook setup and signature guide, then use the generated Webhooks API reference to manage endpoints, send tests, inspect delivery logs, and redeliver retained events.

Analytics

Analytics is live for all accounts. Metric availability varies by platform — each platform guide notes what that platform reports.

Endpoint	Purpose
`GET /v1/analytics`	Aggregate performance across a profile's posts and connected accounts.
`GET /v1/analytics/post-timeline`	Per-post metrics over time for a single post.
`GET /v1/analytics/daily-metrics`	Daily metric totals for a profile or connected account.
`GET /v1/analytics/best-time`	Suggested posting times derived from a connected account's past performance.
`GET /v1/accounts/follower-stats`	Follower counts, and their change over time, per connected account.
`POST /v1/posts/sync-external`	Pull in posts published outside PostZen so they appear alongside PostZen posts.

Analytics endpoints are reads, so a read-only API key is enough — except POST /v1/posts/sync-external, which requires a read-write key.

Two things to expect:

Empty is not an error. An account returns empty metric collections rather than a 4xx when its platform's analytics review is still pending (currently LinkedIn), or when it was connected before analytics launched and has not been reconnected to grant the new read permissions.
Not every metric exists everywhere. Metrics a platform does not report come back as 0 or are omitted rather than estimated.