Working with the API
Idempotency keys
Every write needs an Idempotency-Key header so a retried request never runs twice.
Updated
Browse the developer docs
Steps
- Send an
Idempotency-Keyheader with everyPOSTandDELETEunder/v1. Without it the API returns 400"the Idempotency-Key header is required for mutations". - Use a new unique value for each action you intend. If a request times out, retry it with the same key and the exact same body. You get the stored first response and the action is not repeated.
- Do not reuse a key for a different request. The same key with a different method, path or body returns 422
idempotency_conflict. The body is compared as raw text, so send the same JSON text when you retry. - If you get 409
conflict, a request with that key is still in progress. Wait and retry with the same key.
Notes
- Keys are scoped to your academy and to the credential that sent them. Two different keys or tokens can use the same value without clashing.
- If the first request failed with an error, nothing is stored, so you can retry with the same key.
- Write tools under
/v1/also need antools Idempotency-Keyheader. There, a tool that ran and failed has its failure stored, so use a new key after you fix the arguments.
Related guides
- Errors and request IDsThe shared error shape, every error type with its HTTP status, and the
X-Request-Idheader. - Webhooks: endpoints, signatures, retries and replayRegister an https endpoint, verify the
X-CC-Signatureheader, understand retries, and replay deliveries from the log. - MCP server for AI agentsConnect Claude, Cursor or another MCP client to
/api/with a personal access token. The agent acts as you through three tools.mcp
Still need help?
Email hello@chesscore.io. Using ChessCore day to day? Visit the Help centre.