API reference

Response envelope

Every endpoint returns one of two shapes.

// Success
{ "ok": true, "data": { ... } }

// Failure
{ "ok": false, "error": { "code": "QUOTA_EXCEEDED", "message": "..." } }

Validation failures add a fields object mapping each invalid path to its messages. Branch on ok, then on error.code — the codes are stable, the messages are written for humans and may be reworded.

Authentication

Send your key as a bearer token. Keys are created in Settings, are stored hashed, and the plaintext is shown exactly once.

curl https://checkmysites.com/api/analyze \
  -H "Authorization: Bearer cms_live_..."

Status codes

A target site that cannot be reached returns 422, not 500. The request was well-formed; the failure is a fact about the audited site rather than about us.

POST /api/analyze

Runs an audit synchronously. Most complete in 15–45 seconds, so set a client timeout of at least 120 seconds.

curl -X POST https://checkmysites.com/api/analyze \
  -H "Authorization: Bearer $CMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

{
  "ok": true,
  "data": {
    "auditId": "clx...",
    "status": "COMPLETED",
    "domain": "example.com",
    "overallScore": 74,
    "grade": "B",
    "durationMs": 8421,
    "reportUrl": "/reports/clx..."
  }
}

Error codes

GET /api/analyze

Quota preflight — cheap, and does not consume an audit.

{
  "ok": true,
  "data": {
    "authenticated": true,
    "canAudit": true,
    "tier": "GROWTH",
    "used": 47, "limit": 200, "remaining": 153,
    "periodEnd": "2026-09-03T00:00:00.000Z"
  }
}

GET /api/report/:id

The complete report: category scores, every finding with its evidence and remediation, measured metrics, and the AI-written summary with grouped recommendations.

curl "https://checkmysites.com/api/report/$AUDIT_ID" \
  -H "Authorization: Bearer $CMS_API_KEY" \
  | jq '.data.findings[] | select(.status == "FAIL") | {checkId, title, severity}'

GET /api/history

Cursor-paginated. Cursors rather than offsets, because an offset shifts when a new audit is inserted mid-scroll and you end up skipping or duplicating rows.

POST /api/export/:format

:format is pdf, csv or json. Returns the file directly, not a JSON envelope.

curl -X POST https://checkmysites.com/api/export/pdf \
  -H "Authorization: Bearer $CMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"auditId": "clx..."}' \
  -o report.pdf

Nothing is stored server-side — exports are generated on demand and streamed. Rate limited to 30 per hour.

Check IDs

Every finding carries a stable, dot-namespaced checkId. These are safe to key dashboards and trend analysis on; the titles and descriptions are not.