← All docs

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

/capabilities
/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

Availability

Call GET /capabilities with your bearer token before showing account connection or billing actions. account_connections lists each provider's method, available flag, and an optional reason. billing reports free_beta or paid mode, Checkout and portal availability, and available_plans. A provider adapter does not imply that its account connection is enabled on this server.

Billing

A workspace owner or administrator signed in through Clerk can use POST /billing/checkout-sessions with {"workspace_id":"wrk_...","plan":"payg"}. The optional plan is payg, pro, or scale, defaults to payg, and must be listed in billing.available_plans. API keys cannot create billing sessions.

The response is {"session":{"id":"...","url":"https://..."}}. Existing subscribers receive a billing portal session to manage their subscription. POST /billing/portal-sessions accepts the workspace ID and has the same owner or administrator requirement. Prices and redirect destinations are controlled by the server. Clients cannot supply arbitrary Stripe price IDs.

Stripe webhooks and reconciliation update verified subscription and payment method state. Returning from Checkout alone does not authorize paid usage. When paid usage is not eligible, the API returns HTTP 402 with PAYMENT_METHOD_REQUIRED; a workspace owner or administrator must complete billing setup. Free beta keeps unavailable billing actions hidden.

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. If scanning cannot complete, the upload is rejected before storage; retry after service recovery. Production uploads require an available scanner. 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.

Operational Admin API

Production maintenance uses a separate POSTMCP_ADMIN_TOKEN bearer credential. User API keys and Clerk sessions do not authorize these endpoints: