API

Use /openapi.json for the full OpenAPI 3.1 contract. Core resources include agents, API keys, accounts, media, posts, usage, billing, logs, and webhook delivery replay.

Production API base URL

https://api.postmcp.dev

Agent, CLI, MCP, and OpenClaw production setup should set POSTMCP_API_BASE_URL=https://api.postmcp.dev. Override it only for local development or staging.

Auth

Send scoped API keys as bearer tokens:

Authorization: Bearer pmcp_key_...

Use the narrowest scopes possible. Common scopes are posts.read, posts.draft, posts.schedule, posts.publish, media.upload, accounts.read, accounts.write, usage.read, logs.read, and api_keys.write.

Idempotency

Write requests that can create duplicate work accept an idempotency-key header:

idempotency-key: idem_123

Post idempotency keys are valid for 24 hours. Reusing a key within that window returns the original post group instead of billing or scheduling twice.

Post Writes

Use /posts/validate before creating posts when an agent is composing or repairing content. Use /posts for create, draft, schedule, dry-run, sandbox, and publish-like requests.

Important request fields:

{
  "dry_run": true,
  "sandbox": true,
  "wait": true,
  "webhook_url": "https://example.com/postmcp",
  "targets": [{ "platform": "bluesky", "connected_account_id": "acct_123" }]
}

Core Resources

/posts
/posts/batch
/posts/{post_group_id}
/workspaces/{workspace_id}/export
/accounts
/accounts/{account_id}/status
/accounts/{account_id}/capabilities
/media
/usage
/billing
/billing/checkout-sessions
/billing/portal-sessions
/logs
/auth/api-keys
/agents

Billing

Use POST /billing/checkout-sessions to create a Stripe Checkout session for a workspace customer and POST /billing/portal-sessions to create a billing portal session. Both routes require a bearer token authorized for the requested workspace_id and return a session ID plus hosted Stripe URL.

Media Uploads

Uploads are validated server-side for file size, MIME type, and per-platform media constraints. Files flagged as malicious are rejected before storage and return MEDIA_MALWARE_DETECTED to the caller. Validate uploads with a sandbox post before scheduling or publishing on platforms with strict media policies.

Workspace and Account Data

Use GET /workspaces/{workspace_id}/export to retrieve workspace metadata for data access requests. Use DELETE /workspaces/{workspace_id} to soft-delete a workspace; deleted workspaces are hidden from owner workspace lists and retained according to the retention policy.

Use GET /users/{user_id}/export to retrieve user account metadata and active owned workspaces. Use DELETE /users/{user_id} to anonymize the user record and soft-delete active workspaces owned by that user.

Errors

Every REST error returns PostMCPError:

{
  "code": "SPEND_CAP_EXCEEDED",
  "message": "Monthly spend cap exceeded.",
  "suggested_action": "Raise the workspace spend cap or wait.",
  "auto_fixable": false,
  "trace_id": "trace_123"
}

Agents should branch on code, show suggested_action, and preserve trace_id in logs or support messages.