API
Idempotency
Use the Idempotency-Key header to safely retry write operations.
Every POST and PATCH request on the v1 API accepts an Idempotency-Key
header. The first successful response is cached for 24 hours and replayed
verbatim for any retry that sends the same key.
curl https://www.clientcasa.com/api/v1/clients \
-X POST \
-H "x-api-key: sk_live_xxx" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
-d '{ "name": "Acme Inc." }'Rules
| Retry condition | Result |
|---|---|
| Same key + same body | Original response replayed. No new write. |
| Same key + different body | 409 conflict (request hash mismatch). |
| New key | Treated as a fresh request. |
| Key older than 24h | Eligible for cleanup; behaves like a new key after expiry. |
Keys are organization-scoped — the same key value in two different orgs is unrelated.
Method support
| Method | Accepted | Notes |
|---|---|---|
POST | ✅ | All endpoints. |
PATCH | ✅ | All PATCH endpoints. Useful for status transitions that fire webhooks. |
GET | — | Read-only; safe to retry without a key. |
DELETE | — | Idempotent by definition; duplicate deletes are no-ops. |
Want patterns, not just the spec?
See the Idempotent writes tutorial for retry strategy, key persistence advice, and worked payment/refund examples.