Concepts
Idempotency
How the Idempotency-Key header and the MCP server's derived keys turn retries into replays instead of duplicate posts.
An agent that times out will try again, often with the same arguments. Idempotency makes the second call return the first result instead of creating a second post.
The rules§
- Same key, same body
- The stored response is replayed with
Idempotent-Replayed: true. - Same key, different body
422 idempotency_key_reuse. Nothing is created.- New key
- A new request.
- After 24 hours
- The key expires and may be used again.
POST /v1/posts requires the header when called with an API key. Every other POST accepts it. Posts made in the dashboard do not need one.
Over MCP§
create_post takes an optional idempotency_key. Without one, the server derives a key from the caller, the text, the media, the accounts, the time and the draft flag, and returns it with replayed so the agent can see what happened.
Choosing keys§
- Name the thing, not the attempt:
voicemsg-launch-2026-10-12, not a random value per try. - Keep the key stable across retries of the same intent, and change it when the content changes.
- Store it next to whatever triggered the post (a queue row, a commit), so a rerun reuses it.