Authentication

All API requests require a Bearer token in the Authorization header. Postlark supports two authentication methods.

API Key (recommended for MCP, CLI, automation)

Authorization: Bearer pk_live_xxxxxxxxxxxx

Generate keys in Dashboard → Settings → API Keys. Each key is bound to a specific blog.

JWT Session (Dashboard only)

The Dashboard uses Supabase JWT tokens for session-based authentication:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

When using JWT auth, Postlark auto-selects your first blog. To target a specific blog, include the X-Blog-Id header:

X-Blog-Id: blog-uuid-here

Note

JWT auth is used internally by the Dashboard. For external integrations, always use API keys.

Scopes

API keys support scoped permissions. Each scope controls access to a specific set of operations.

Scope	Description
*	Full access (all scopes)
posts:read	Read posts (list, get)
posts:write	Create, update, delete, publish, schedule posts
blogs:read	Read blog settings
blogs:write	Update blog settings, manage API keys
analytics:read	Read analytics data
search:read	Search posts
account:read	Read profile
account:write	Delete account, manage tokens
packs:read	Read post pack balance
packs:write	Purchase post packs
domains:read	Read custom domain status
domains:write	Register/remove custom domains
media:read	Read uploaded images
media:write	Upload images

Use {resource}:* for all actions on a resource (e.g. posts:* = posts:read + posts:write).

When you create a new key, the default scope is ["*"] (full access). You can restrict scopes when generating a key in the Dashboard or via the API.

Tip

For automation scripts that only publish posts, use ["posts:write"] scope to follow the principle of least privilege.

Token Expiration

Blog API keys do not expire by default. You can revoke a key at any time from Dashboard → Settings → API Keys or via DELETE /blogs/:id/api-keys/:keyId.

Scoped access tokens support optional expiration (30 days, 90 days, 1 year, or no expiration). Create them in Dashboard → Access Tokens or via POST /account/tokens. Expired or revoked tokens return 401 Unauthorized.

JWT session tokens expire according to Supabase Auth settings (default: 1 hour). The Dashboard handles token refresh automatically.

Rate Limits

Plan	Requests/hour
Free	60
Starter	300
Creator	1,000
Scale	10,000
Enterprise	10,000+

Every response includes rate limit headers:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
X-RateLimit-Reset: 1711324800

When exceeded, you’ll receive a 429 response with retry_after seconds.

See the full Rate Limits reference for Post Packs and plan details.

Error Format

All errors follow a consistent JSON format:

{
  "error": "not_found",
  "message": "Post not found"
}

Status	Description	Example
400	Invalid input	"title is required"
401	Missing or invalid token	"Invalid API key"
403	Plan upgrade required	"Post limit exceeded. Free plan allows 10 total posts."
404	Resource not found	"Post not found"
409	Duplicate resource	"slug \"my-post\" is already taken"
429	Rate limit exceeded	"Rate limit exceeded. Limit: 60 requests/hour."
500	Server error	"Internal server error"

Base URL

https://api.postlark.ai/v1

Try the interactive API explorer: api.postlark.ai/docs

Try it live

Interactive API explorer | API llms.txt | OpenAPI JSON | Docs llms.txt | Full spec