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

# Idempotency

> Replay-safe POST requests using Idempotency-Key

# Idempotency

For **`POST`** requests that create resources or perform billable actions, you can send an `Idempotency-Key` header so retries return the **same HTTP status and JSON body** as the first successful response for that key.

```bash theme={null}
curl -X POST https://api.kallglot.com/v1/sessions \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{"mode": "bidirectional_translation"}'
```

## Behavior

* **Scope**: Idempotency keys are scoped to your **organization** (derived from the API key).
* **Body matching**: Reusing the same key with a **different JSON body** returns `invalid_request_error` / `idempotency_mismatch` (`400`).
* **Concurrent retries**: While the original request is still running, duplicates may receive `409` / `idempotency_conflict`.
* **TTL**: Cached responses expire after roughly **24 hours**, after which keys behave like fresh requests again.

## Supported routes

Include `Idempotency-Key` on these endpoints when you need safe retries:

| Method | Endpoint                     |
| ------ | ---------------------------- |
| `POST` | `/v1/sessions`               |
| `POST` | `/v1/sessions/{id}/end`      |
| `POST` | `/v1/sessions/{id}/dial`     |
| `POST` | `/v1/sessions/{id}/analysis` |
| `POST` | `/v1/agents`                 |

Hang-up and similar `POST`s do **not** honor `Idempotency-Key`—ensure your caller treats duplicates safely when you retry.