API · Conventions
Idempotency
Safe retries via Idempotency-Key. 24-hour retention. Scoped per token — a Matter-specific guarantee.
Last updated
TL;DR. Every POST accepts Idempotency-Key: <up-to-255-chars>. Same key + same
body returns the original response. 24-hour retention. Token-scoped (not
account-scoped) — prevents cross-token key collisions in multi-agent deployments.
Every POST in the Matter API accepts an Idempotency-Key header. Same key + same body →
the original response is returned. Same key + different body → 409 idempotency_key_reused_with_different_body.
Key format
- Up to 255 characters.
- V4 UUIDs recommended (sufficient entropy, collision-resistant).
- Any random string is acceptable. Do not use sensitive data as a key — emails, personal identifiers, or anything that could leak identity on logs.
curl -X POST https://api.mattermode.com/v1/entities \
-H "Idempotency-Key: 7a0c3b8e-4f52-4d91-b7f2-c0b0b4a3d1e9" \
-H "Authorization: Bearer $MATTER_KEY" \
-H "Matter-Version: 2026-05-01" \
-d '{...}'Retention
Keys are remembered for 24 hours from the first response. After 24 hours a key with the same value is treated as a new request. Retention is per-key — do not depend on keys colliding if they fall outside the window.
Replay semantics
| Scenario | Behavior |
|---|---|
| Same key, same body | Original response returned (including original X-Request-Id). |
| Same key, different body | 409 idempotency_key_reused_with_different_body. |
| Same key, original in flight | Server delays and returns the original once it completes. |
| Same key, original failed transiently | Retry is treated as a new request (failed responses are not memoized). |
Only successful-or-permanent-failure responses are memoized. Transient 5xx errors are never memoized, so retrying on 500s is safe even with the same key.
Scoped per token — not per account
Matter's idempotency keys are scoped to the authenticating token, not to the account as a whole. This closes a real security hole:
Two agents on the same account share an account. Agent A (tier 2, prep only) generates key
kand runs a dry-run. Agent B (tier 3, execute) later uses the same keykfor a real mutation. Without per-token scoping, the API could collapse the tier-3 request into the cached tier-2 response — or vice versa — silently changing the effective authority.
Per-token scoping eliminates this class of bug. Each token has its own idempotency namespace.
Which methods?
- POST: required on every POST that mutates state. Omitting it is allowed but a retry may produce a duplicate resource.
- GET / DELETE:
Idempotency-Keyis silently ignored. dry_run: true: the key is still honored — dry-runs are memoized too, which matters for agent runtimes that retry by default.
Combining with webhooks
The event emitted by an idempotent POST carries the idempotency key in request.idempotency_key.
Consumers can de-duplicate events by the pair (idempotency key, event type) without
depending on event id uniqueness.