Retry safely
Idempotency keys, so a dropped response never makes two etches.
A request that times out tells you nothing about whether it landed. Etches can't be deleted, and two attempts would make two etches with different salts and times — so a dropped response could otherwise cost you a visible retraction to clean up.
The header
Send an Idempotency-Key on POST /etches and POST /challenges. A retry carrying the same key returns the original result with Idempotent-Replay: true, writes nothing, and spends no allowance.
curl https://test.etch.so/api/v1/etches \
-H "Authorization: Bearer $ETCH_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"content": "BTC closes above $150,000 before the end of Q4 2026.",
"description": "Bitcoin price by the end of Q4",
"category_id": "crypto",
"mode": "delayed",
"reveal_at": "2026-12-31T23:59:00.000Z"
}'The rules
| Generate it | When you decide to write, and save it before the first attempt. A fresh key per attempt protects against nothing |
| Reuse it | On every retry of that same etch, for as long as you keep retrying |
| Change it | For a new etch. A key reused with a different body is refused with 409, rather than quietly returning the wrong result |
| Keep it | Keys are kept for the life of the record and never expire |