Idempotency

Send a key

After a network error, you can’t tell whether a POST request reached us. If you send it with an Idempotency-Key header, you can safely send it again: the API runs it only once. Every POST endpoint accepts the header, including scans and batches.

• Create a key for each operation you want to run once, such as a UUID. A key is 1 to 255 characters long.
• Send the same key, with the same body, each time you retry that operation.
• We keep each key for 24 hours per API key. After that, the same key starts a new request.

The following request starts a scan that is safe to retry:

# Create one key per scan, and send the same key each time you retry it.
KEY=$(uuidgen)

curl -X POST "https://api.checkanysite.com/v1/scans" \
  -H "Authorization: Bearer $CHECKANYSITE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d '{"domain": "wikipedia.org", "checks": ["ai"]}'

The Python SDK sends a key with every POST request automatically.

Replayed responses

When you send the same key with the same body, the API returns the first request’s status and body, with an Idempotent-Replayed: true header. A replayed response is never charged, so a retried scan neither starts a second scan nor costs credits twice:

HTTP/2 202
Idempotent-Replayed: true
Location: https://api.checkanysite.com/v1/scans/0b5a7a6e-…

{"id": "0b5a7a6e-…", "status": "queued", …}

When a key is refused

• 422 idempotency_key_reused: the key was sent with a different body. Each key belongs to one request, so create a new key for a new request.
• 409 idempotency_key_in_use: the first request with this key is still running. Retry a moment later with the same key to get its response.