API reference

The Checkbox REST API — base URL, authentication, versioning, errors, pagination, idempotency and expansion. Every operation is listed by resource.

The API is REST over HTTPS with JSON in and out, at https://app.checkbox.site/v1. It follows the conventions you know from Stripe: secret keys in the Authorization header, test and live mode chosen by the key, prefixed ids, cursor pagination, Idempotency-Key on POST, dated versions and errors with stable codes. The machine-readable contract is OpenAPI 3.1 at /v1/openapi.json (also /v1/openapi.yaml).

#Authentication

Send a secret key as a Bearer token, or as the HTTP Basic user name (curl's -u "$KEY:"):

curl https://app.checkbox.site/v1/account \
  -H "Authorization: Bearer $CHECKBOX_SECRET_KEY"

A missing or wrong key is 401 (api_key_missing, api_key_invalid); a key without the scope is 403 (insufficient_scope). See test and live mode.

#Conventions

• Objects have id, object (the type) and livemode; timestamps are Unix seconds (created); fields are snake_case.
• Ids are <prefix>_<32 hex> (site_…, scan_…, fnd_…, task_…, evt_…). Inputs also accept the raw UUID.
• Lists return { "object": "list", "data": [...], "has_more": true, "url": "/v1/..." }. Page with limit (1–100, default 10), starting_after and ending_before (object ids).
• Expansion: expand[]=latest_scan or expand[]=domain_verification on retrieveSite includes the related object.
• Request ids: every response has a Request-Id header (req_…), also inside error bodies. Include it when you contact support.

curl -G https://app.checkbox.site/v1/sites \
  -u "$CHECKBOX_SECRET_KEY:" \
  -d limit=2

#Errors

Errors have an HTTP status and a body with a stable code:

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "price (major units, e.g. 19.99) or amount (minor units) is required",
    "param": "price",
    "doc_url": "https://checkbox.site/docs/api/errors#parameter_invalid",
    "request_id": "req_1eead3177abc4ebc906a8af0fddcc0c4",
    "next_action": { "type": "fix_request", "message": "Correct price and call the check again." }
  }
}

type is one of invalid_request_error, authentication_error, permission_error, rate_limit_error, idempotency_error, api_error. Codes are never renamed or reused; every code is documented. next_action, when present, tells an agent what to do about it.

#Idempotency

Every POST accepts an Idempotency-Key header (up to 255 characters). The same key with the same body within 24 hours returns the stored response with Idempotent-Replayed: true; with a different body it is 400 idempotency_key_reused; while the first request is still running, 409 idempotency_key_in_use. Server errors are not stored, so retrying with the same key is always safe. The SDKs send a key on every POST automatically.

curl https://app.checkbox.site/v1/sites \
  -u "$CHECKBOX_SECRET_KEY:" \
  -H "Idempotency-Key: create-joybox-site" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://joybox.example" }'

#Versioning

Versions are dates. Send Checkbox-Version: 2026-10-30 to pin a request; without it, the account's pinned version is used (set on first use; change it with updateAccount). Responses echo Checkbox-Version and Checkbox-Mode. Known versions: 2026-10-30.

#Rate limits

300 requests per minute per account and mode, with RateLimit-* headers. Over the limit: 429 rate_limit_exceeded with Retry-After. Some routes have their own limits (preflight checks 120 per minute; scans and evaluations 60 per hour per site).

#Resources

Checkbox is compliance software, not a law firm; nothing in these docs is legal advice (details). For AI agents: every page is available as Markdown at the same URL plus .md; the index is /llms.txt.