Idempotency

Mutating requests (POST, PATCH, DELETE) can be made safe to retry by sending an Idempotency-Key header. The platform guarantees exactly one side-effecting execution per key, and replays the stored response for any retry.

curl -X POST https://your-app.example.com/api/v1/customers \
  -H "Authorization: Bearer sk_live_PUBLICID.SECRET" \
  -H "X-Company-Id: 0190abcd-1234-7000-8000-000000000000" \
  -H "Idempotency-Key: 6f9619ff-8b86-d011-b42d-00c04fc964ff" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Co" }'

How it behaves

Retry of the same key + same request returns the stored response, with the header Idempotent-Replayed: true set so you can tell a replay from a fresh execution.
Same key, different request body (or different effective company — see Company scoping) returns 409 with the idempotency_conflict code — the key was already used for a different request.
A request with the same key still in flight returns 409 with idempotency_in_progress — retry shortly.

The request is fingerprinted over the method, path, query, effective company, and body, so a replay is only served when the request genuinely matches.

Use a fresh key per logical operation

Generate a new unique Idempotency-Key (a UUID works well) for each distinct operation you want to be exactly-once. Stored keys are retained for about 24 hours, after which the key may be reused for a new operation.