Skip to main content

​
Idempotency

For create operations that have side effects (e.g. creating a call or an agent), you can send an idempotency key so that duplicate requests are detected and the same response is returned instead of creating a second resource. Send the header on the request: 
X-Idempotency-Key: <key>
  • Key format: Any unique string. We recommend a UUID (e.g. 550e8400-e29b-41d4-a716-446655440000) or a string that is unique per logical operation in your system.
  • Scope: Keys are scoped per organization (per API key). The same key can be used for only one create operation per endpoint; duplicate requests with the same key and same endpoint/body return the cached response.

​
Supported endpoints

MethodEndpointIdempotency
POST/agentsYes
POST/callsYes
POST/batch-callsYes
POST/toolsYes
Other create endpoints (e.g. POST /knowledge-bases, POST /voices) do not currently support X-Idempotency-Key. Send the header only on the endpoints listed above.

​
Behavior

  1. First request with a given key: The request is processed normally. The response (status code and body) is stored and associated with that key. You receive 201 Created and the new resource in data.
  2. Duplicate request (same key, same endpoint, same request body): The server returns the same response as the first request (201 and the same data), without creating a second resource. Use this to safely retry after timeouts or network errors.
  3. Same key, different body: Treated as a new request; if the key was already used, behavior may vary. Always use a new key for each distinct create operation.

​
TTL and cleanup

Stored idempotency responses are cleaned up periodically. Do not rely on a key being valid indefinitely. For retries, use the same key within a short window (e.g. minutes to hours).

​
Example

# First request
curl -X POST https://api.truedy.ai/api/public/v1/calls \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{"agent_id":"...","phone_number":"+15551234567","direction":"outbound"}'

# Retry with same key and body -> same 201 response, no second call created
curl -X POST https://api.truedy.ai/api/public/v1/calls \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{"agent_id":"...","phone_number":"+15551234567","direction":"outbound"}'

​
Best practices

  1. Generate a new idempotency key for each distinct create (e.g. one per call, one per agent).
  2. Use the same key when retrying the same logical request (e.g. after a timeout).
  3. Do not reuse keys across different request bodies or endpoints.