Skip to main content
Two operations accept an Idempotency-Key request header:
  • POST /v1/sandbox — create a sandbox.
  • POST /v1/sandbox/{sandbox_id}/previews — create a preview.
​
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.
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:
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.
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.