How to do it
- Get a key Mint an agent key for automation, or use the owner key for admin tasks. Send it as Authorization: Bearer.
- Read the spec Fetch /openapi.json from your API origin and generate a client, or use the TypeScript SDK.
- Create a draft POST /v1/posts with the body and target networks. Add an idempotencyKey so a retry returns the same post.
- Preview it POST /v1/posts/dry-run shows exactly what each network would get. Nothing is queued.
- Approve with the owner key POST /v1/posts/:id/approve with schedule or publishNow. Agent keys cannot approve their own drafts.
Useful routes
| Method and path | Purpose |
|---|---|
GET /v1/whoami | Which key you are using |
GET, POST /v1/posts | List or create posts |
POST /v1/posts/dry-run | Preview without queuing |
POST /v1/posts/:id/approve | Approve now or for a time (owner) |
POST /v1/posts/:id/reject | Reject with a reason |
POST /v1/posts/:id/undo | Undo inside the window |
POST /v1/media | Upload an image |
GET /v1/analytics?days=7 | Metrics |
POST /v1/workspace/pause | Kill switch (owner) |
GET /v1/mcp-config | MCP snippets for the calling key |
Error codes you will see
- 403 an agent tried to approve its own draft.
- 409 undo after the post started publishing.
- 422 banned topic, over length, or over the daily limit.
- 423 the workspace is paused.
CLI
The CLI wraps common tasks, for example pnpm socialhandoff policy apply for the policy file and pnpm socialhandoff import postiz for migration.
Automation tools
n8n, Zapier, Make, LangChain, CrewAI, and the OpenAI Agents SDK connect over the REST API or MCP. See n8n, Make, and LangChain.
The API key and rate limit glossary entries cover the basics.
Frequently asked questions
Is there an OpenAPI spec?
Yes. Every server serves it at /openapi.json, so you can generate a client in any language.
What is /llms.txt?
A plain-text description of the API written for AI agents, so an agent can learn the endpoints without reading the whole spec.
How do I avoid duplicate posts when my script retries?
Send an idempotencyKey when creating a post. A repeat request with the same key returns the original post instead of creating a new one.