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

# Idempotency

> Retry supported write operations safely with Idempotency-Key.

A request can succeed even when your server times out before receiving the response. If you retry with a new idempotency key, Brightalk could create the same call, batch, or Automation run twice. Reuse the same `Idempotency-Key` and Brightalk can return the original result instead.

## Three rules

1. **One logical action, one key.** Generate a unique, nonsecret value before the first request.
2. **Same action, same key.** Within 24 hours, if the request times out, the connection fails, or a response explicitly tells you to retry (for example, with `Retry-After`), resend the same method, path, API version, semantically identical body, and key.
3. **Changed action, new key.** Use a new key when the API version or body changes, or when you intentionally want another call, batch, or Automation run.

The following header-only excerpt intentionally omits the required JSON body and `Content-Type` header.

```bash theme={null}
curl --request POST 'https://api.brightalk.ai/calls' \
  --header "Authorization: Bearer $BRIGHTALK_API_KEY" \
  --header "Brightalk-Version: 2026-07-16" \
  --header "Idempotency-Key: order-8f4c2-call-1"
```

Keep `order-8f4c2-call-1` with the business action. It is not an authentication secret, but it must not contain a phone number, contact data, or another secret.

After 24 hours, do not assume the old idempotency claim prevents duplication. Confirm whether the original action occurred before submitting it again.

## Where the header is required

The header is required on exactly these four operations:

| Operation             | Path                             |
| --------------------- | -------------------------------- |
| Create Call           | `POST /calls`                    |
| Create Batch          | `POST /batches`                  |
| Start Batch           | `POST /batches/{batch_id}/start` |
| Create Automation run | `POST /automation-runs`          |

Omitting it returns `400 idempotency_key_required`.

## Where the header is optional

The header is optional on state-machine controls. Adding it makes a completed result replayable:

| Operation             | Path                                    |
| --------------------- | --------------------------------------- |
| Cancel Call           | `POST /calls/{call_id}/cancel`          |
| Pause Batch           | `POST /batches/{batch_id}/pause`        |
| Resume Batch          | `POST /batches/{batch_id}/resume`       |
| Cancel Batch          | `POST /batches/{batch_id}/cancel`       |
| Cancel Automation run | `POST /automation-runs/{run_id}/cancel` |

## What Brightalk returns

| Situation                                        | Result                                                                               |
| ------------------------------------------------ | ------------------------------------------------------------------------------------ |
| Same key and semantically identical body         | Original status and response; completed replays include `Idempotency-Replayed: true` |
| Same key and different body                      | `409 idempotency_conflict`                                                           |
| Same key while the original is still in progress | `409 idempotency_in_progress` with numeric `Retry-After` delta-seconds               |

Wait for the `Retry-After` interval before retrying an in-progress request. Validation failures are not stored as completed idempotent results.

## Advanced details

Claims are retained for 24 hours and scoped by organization, API key class, API version, HTTP method, and normalized path. Rotating one `bt_live_` key to another does not reset a claim for the same key class; reuse the original idempotency key when retrying the same logical request after rotation.