Idempotency
- OpenAPI 3.1.0 document: https://api.rollstack.com/public/v1/openapi.json
- The whole reference in Markdown: https://docs.rollstack.com/llms-full.txt
- An index of the reference: https://docs.rollstack.com/llms.txt
A request that times out may have run or not. To retry a write safely, send an Idempotency-Key header with a unique value, such as a UUID, on any POST, PUT, PATCH or DELETE, and send the same value when you retry it. MCP write tools take the same value as their idempotencyKey argument.
curl -X POST https://api.rollstack.com/public/v1/reports \
-H "Authorization: Bearer rsk_..." \
-H "Idempotency-Key: 6f1c2a4e-9b7d-4e2f-8a3c-1d5e7f9b0a2c" \
-H "Content-Type: application/json" \
-d '{"name": "Weekly sales"}'
- The first request with a key runs, and its response is kept for 24 hours. A retry with the same key and the same request answers that response, with its status, and runs nothing.
- Keys belong to the API key and the endpoint, so another key or endpoint never sees them. A tool call and a REST request to the same endpoint share them.
- A retry with the same key but a different body, path or query answers 422
idempotency-key-reused. Use a new key for a new request. - A retry while the first request is still running answers 409
idempotency-key-in-progress: retry it later with the same key. A request that stopped before it answered keeps answering 409 until its key expires, so check whether it took effect before you send it again with a new key. - A request that fails, such as with a 4xx or 5xx, keeps nothing, so retry it with the same key.
- When keys can't be checked, a request with one answers 503
idempotency-unavailableand runs nothing. - Without the header, a request runs every time it is sent.
GETrequests ignore it.