API reference
Every endpoint of the Postel API v1, with its full reference and the guide that covers it.
Base URL https://www.postel.app/api. Every request needs an API key. Request and response bodies are JSON. Each path below opens its full reference: parameters, request and response schemas, examples and code samples.
The machine-readable description is an OpenAPI 3.1 spec at https://www.postel.app/api/v1/openapi.json. Load it into Postman, Insomnia or a client generator.
Account
| Method | Path | What it does |
|---|---|---|
| GET | /v1/me | The person and workspace the key acts for, and whether the plan can publish. Authentication |
Channels
| Method | Path | What it does |
|---|---|---|
| GET | /v1/channels | The networks Postel posts to and whether each is connected. Quickstart |
Posts
| Method | Path | What it does |
|---|---|---|
| GET | /v1/posts | List posts, newest first. Pagination |
| GET | /v1/posts/{id} | Get one post. Read posts |
| POST | /v1/posts | Create a draft, or schedule or publish it right away. Create a post |
| POST | /v1/posts/{id}/schedule | Schedule a draft. Schedule a draft |
| POST | /v1/posts/{id}/publish | Publish a draft within a minute. Publish now |
Writing
| Method | Path | What it does |
|---|---|---|
| POST | /v1/posts/generate | Write a post in your voice from a prompt and save it as a draft. Write in your voice |
| POST | /v1/viral/takes | Write your take on a viral post or format, one draft per network. Write your take |
Viral posts
| Method | Path | What it does |
|---|---|---|
| GET | /v1/viral/posts | Search posts and videos that took off. Find viral posts |
| GET | /v1/viral/posts/{id} | Get one viral post or video. Find viral posts |
| GET | /v1/viral/formats | List the formats viral posts keep using. Formats |
Events
| Method | Path | What it does |
|---|---|---|
| GET | /v1/events | Poll for published posts, failed posts, ready drafts and new viral posts. Polling events |
Headers
| Header | Direction | What it does |
|---|---|---|
Authorization | Request | Bearer pstl_.... Required. Authentication |
Idempotency-Key | Request | Makes POST /v1/posts, POST /v1/posts/generate and POST /v1/viral/takes safe to retry. Idempotency |
X-Postel-Client | Request | Optional. Your app's name and version. Authentication |
X-Request-Id | Both | Names the request. Quote it when you contact support. Request IDs |
Retry-After | Response | Seconds to wait after a 429. Rate limits |
Idempotent-Replayed | Response | true when the response is a replay of an earlier request. Idempotency |
MCP server
Connect Claude, ChatGPT, Cursor and other MCP clients to Postel so they can research, draft and schedule posts for you.
Get the key's account
The person and workspace the API key acts for, and whether the plan can schedule and publish. Integrations call this to test a connection and use label as its name. Free on every plan.