Idempotent creation and publication
POST /posts and POST /posts/POST_ID/publish accept an optional Idempotency-Key header. Use 1–128 letters, digits, underscores, periods, or hyphens.
Reuse the same key and payload for the same logical operation for up to 24 hours. A replay returns the original data and HTTP status. Reusing a key with different input returns 409; a concurrent request can return idempotency_in_progress with Retry-After: 1.
CLI can generate a key, but an explicit key is easier to persist across job retries. MCP create, schedule, and publish tools require one.
Rate limits
Limits are shared by all keys in the project. The default configuration is 120 total requests and 30 writes per minute; deployments can configure different limits. ReadX-RateLimit-Limit and X-RateLimit-Remaining when provided. On 429, wait for the Retry-After duration before retrying.
Error responses
JSON bodies are limited to 100 KB. Rejections before the controller may not use the public error envelope.
Uncertain outcomes
An interrupted request can have succeeded. Reuse the original key for supported idempotent operations. For media creation, editing, or deletion, inspect the resource before retrying. Uploading the same file again creates a new media reservation. The CLI’sdoctor checks runtime, connectivity, authentication, and effective permissions. Include the request ID when reporting an API issue.