Idempotency
Tools that create a resource or queue work accept an optional idempotency_key argument. It is sent to the endpoint as the X-Idempotency-Key header the REST API already honours.
{ "name": "inboxes_create",
"arguments": { "label": "Support — Triage", "idempotency_key": "7c4a8d09-ca37-4f21-b1f0-3d2f2b8c9a11" } }
| Format | Opaque string, 8 to 255 characters. A UUID is the usual choice. |
| Window | 24 hours. |
| Replay, same body | Returns the original response, unchanged. |
| Replay, different body | 409 conflict. |
Send one whenever an agent may retry: a client that times out and calls again would otherwise create a second inbox, a second agent or a second webhook. Read tools, updates and deletes are naturally idempotent and take no key.
Tools that accept it
| Resource | Tools |
|---|---|
| Workspaces | workspaces_create, workspaces_upsert |
| Inboxes | inboxes_create, inboxes_upsert |
| E-mails | emails_reprocess |
| Agents | agents_create, agents_upsert |
| Webhooks | webhooks_create, webhooks_upsert, webhooks_test, webhooks_regenerate_secret, webhooks_deliveries_replay |
caution
webhooks_regenerate_secret rotates a secret that is returned exactly once. An unintended second call is not recoverable from the response — always send an idempotency_key with it.