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

# Idempotency

> Safely retry create requests with the Idempotency-Key header

Two operations accept an `Idempotency-Key` request header:

* `POST /v1/sandbox` — create a sandbox.
* `POST /v1/sandbox/{sandbox_id}/previews` — create a preview.

**Idempotency-Key** `string`

Optional. Maximum length **255 characters**.

## What it does — and doesn't do

Per the API contract, an absent `Idempotency-Key` means the server generates one on your behalf — and a server-generated key **provides no deduplication**. Only a client-supplied key actually dedupes retries.

> [!WARNING]
>
> If you don't send `Idempotency-Key` yourself, retrying a create request (for example, after a timeout where you're not sure the first request landed) can create a second sandbox or a second preview. The server generating its own key internally does not protect you from this — that internal key isn't shared across separate requests you make.

## How to use it

Generate a unique key (a UUID works well) per logical create attempt, and send the same key again on retries of that same attempt:

```shell theme={null}
curl -s -X POST https://api.bonya.ai/v1/sandbox \
  -H "Authorization: Bearer $BONYA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"template_id": "bonya-dev"}'
```

If that request needs to be retried — a network timeout, a client crash before the response was read — reuse the exact same `Idempotency-Key` value on the retry rather than generating a new one. A new key on retry is indistinguishable from a genuinely new create request.

> [!NOTE]
>
> `Idempotency-Key` is only accepted on the two create endpoints listed above. Other operations, including delete and resume, don't take this header — resume in particular already returns `already_running: true` as a no-op signal instead of needing idempotency-key support.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.