Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.revdesk.com/llms.txt

Use this file to discover all available pages before exploring further.

The RevDesk v1 API supports idempotency keys on every POST, PUT, PATCH, and DELETE endpoint. Set the Idempotency-Key header to a unique value (a UUID is recommended) on your first request; retry the same request with the same header and we’ll return the original response.

​
How it works

curl -X POST https://api.revdesk.com/v1/calls \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: 9b8cfa7a-1c2d-4a88-b3c0-1d2e3f4a5b6c" \
  -H "Content-Type: application/json" \
  -d '{"caller_id": "+14155551234", "destination": "+14155556789"}'
  • First request with a key: we run the handler and persist the response under the key.
  • Repeat with the same key and same body: we replay the saved response verbatim, including status code. The replay carries an Idempotency-Replay: true response header so you can tell.
  • Repeat with the same key but a different body: we return 409 idempotency_conflict with the original key’s request id in fields.conflicts_with.

​
TTL

Idempotency records live for 24 hours after the first successful response. After the window, reusing the key is a fresh request.

​
Semantics

  • Do use a new key for each new logical operation — reusing keys across different calls is an easy way to accidentally drop traffic.
  • Do not rely on idempotency across key rotations — the key is scoped to the API key it was submitted under.
  • Do not assume idempotency for cross-process transactions (e.g. a call + a Stripe charge). Idempotency only protects the RevDesk side.

​
When to set one

  • Retrying a request after a network timeout — critical.
  • Background jobs that might re-run after a worker crash — critical.
  • Interactive UIs with a double-click-vulnerable button — nice to have.
Client SDKs automatically generate idempotency keys on mutations; set yours manually only if you need to correlate retries across a longer window than the SDK’s in-memory dedupe.