> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truedy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Idempotency

> Safely retry create requests with X-Idempotency-Key

# 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.

## Header

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

| Method | Endpoint       | Idempotency |
| ------ | -------------- | ----------- |
| POST   | `/agents`      | Yes         |
| POST   | `/calls`       | Yes         |
| POST   | `/batch-calls` | Yes         |
| POST   | `/tools`       | Yes         |

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

```bash theme={null}
# 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.