Scans API

View as Markdown Open in Claude

Synthetic-shopper runs: Checkbox visits the checkout from each state and device, completes a sign-up when configured, receives the emails and tries to cancel online.

Operation	Endpoint
Run a scan	`POST /v1/sites/{site}/scans`
List scans	`GET /v1/scans`
Retrieve a scan	`GET /v1/scans/{scan}`

The Scan object

Most recent scan (only with expand[]=latest_scan).

Field	Type	Description
`id`	string	Unique identifier of the scan (scan_…).
`object`	enum	String representing the object's type. Always "scan".
`livemode`	boolean	true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox).
`site`	string	The scanned site.
`status`	enum	queued → running → completed \| failed. One of `queued`, `running`, `completed`, `failed`.
`trigger`	enum	What started the scan. One of `manual`, `scheduled`, `page_changed`, `api`.
`regions`	array of enum	States the synthetic shopper visited from (empty for evaluation-only runs).
`error`	string \| null	Why the scan failed.
`warnings`	array of strings	Partial failures of a scan that still produced results.
`evaluation`	string \| null	The evaluation this scan produced (null until evaluated).
`score`	number \| null	Score of that evaluation (0-100, one decimal place).
`insurable`	boolean \| null	Insurable flag of that evaluation.
`started`	integer \| null	When the scan started. Unix timestamp in seconds.
`finished`	integer \| null	When the scan finished. Unix timestamp in seconds.
`created`	integer	When the scan was queued. Unix timestamp in seconds.

Run a scan

POST /v1/sites/{site}/scans

Queues a synthetic-shopper scan of the site. Poll retrieveScan (or wait for the scan.completed webhook); a scan takes 1-3 minutes. When it completes, the evaluation and findings are updated. In live mode the account must be activated.

Scope scans:write · Idempotent (send Idempotency-Key) · Live mode needs activation · Operation createScan

SDK: checkbox.scans.create() (Node) · checkbox.scans.create() (Python). MCP / agents: operation createScan.

Parameters

Parameter	In	Type	Description
`site` required	path	string	Unique identifier of the site (site_…).

Body

Field	Type	Description
`regions`	array of enum	States to scan from (default: the site configuration).

Returns

Returns a Scan object.

In live mode before activation: 403 account_not_activated with next_action.operation_id: "createDomainVerification".

Errors use the standard envelope with a stable code and, where useful, next_action.

curl https://app.checkbox.site/v1/sites/site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b/scans \
  -u "$CHECKBOX_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -d '{}'

import Checkbox from '@checkbox-site/cli';

const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);

const scan = await checkbox.scans.create('site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(scan);

import os
from checkbox import Checkbox

checkbox = Checkbox(os.environ["CHECKBOX_SECRET_KEY"])

scan = checkbox.scans.create("site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(scan)

Response

{
  "id": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "scan",
  "livemode": false,
  "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "status": "completed",
  "trigger": "api",
  "regions": [
    "US-CA",
    "US-NY"
  ],
  "error": null,
  "warnings": [],
  "evaluation": "eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "score": 82,
  "insurable": false,
  "started": 1793318400,
  "finished": 1793318400,
  "created": 1793318400
}

List scans

GET /v1/scans

Scans newest first, optionally for one site.

Scope scans:read · Operation listScans

SDK: checkbox.scans.list() (Node) · checkbox.scans.list() (Python). MCP / agents: operation listScans.

Parameters

Parameter	In	Type	Description
`limit`	query	integer	Number of objects to return, 1-100 (default 10).
`starting_after`	query	string	Cursor: an object id; returns the objects after it (older).
`ending_before`	query	string	Cursor: an object id; returns the objects before it (newer).
`site`	query	string	Only objects of this site (site_…).

Returns

Returns a list ({ object: "list", data, has_more, url }) of Scan objects.

Errors use the standard envelope with a stable code and, where useful, next_action.

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

import Checkbox from '@checkbox-site/cli';

const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);

const scans = await checkbox.scans.list({ limit: 3 });
console.log(scans.data);

import os
from checkbox import Checkbox

checkbox = Checkbox(os.environ["CHECKBOX_SECRET_KEY"])

scans = checkbox.scans.list(limit=3)
print(scans.data)

Response

{
  "object": "list",
  "data": [
    {
      "id": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
      "object": "scan",
      "livemode": false,
      "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
      "status": "completed",
      "trigger": "api",
      "regions": [
        "US-CA"
      ],
      "error": null,
      "warnings": [],
      "evaluation": "eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
      "score": 82,
      "insurable": false,
      "started": 1793318400,
      "finished": 1793318400,
      "created": 1793318400
    }
  ],
  "has_more": false,
  "url": "/v1/sites"
}

Retrieve a scan

GET /v1/scans/{scan}

Returns a scan. When status is completed, evaluation names the verdict (retrieveEvaluation).

Scope scans:read · Operation retrieveScan

SDK: checkbox.scans.retrieve() (Node) · checkbox.scans.retrieve() (Python). MCP / agents: operation retrieveScan.

Parameters

Parameter	In	Type	Description
`scan` required	path	string	Unique identifier of the scan (scan_…).

Returns

Returns a Scan object.

Errors use the standard envelope with a stable code and, where useful, next_action.

curl https://app.checkbox.site/v1/scans/scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b \
  -u "$CHECKBOX_SECRET_KEY:"

import Checkbox from '@checkbox-site/cli';

const checkbox = new Checkbox(process.env.CHECKBOX_SECRET_KEY);

const scan = await checkbox.scans.retrieve('scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(scan);

import os
from checkbox import Checkbox

checkbox = Checkbox(os.environ["CHECKBOX_SECRET_KEY"])

scan = checkbox.scans.retrieve("scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(scan)

Response

{
  "id": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "scan",
  "livemode": false,
  "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "status": "completed",
  "trigger": "api",
  "regions": [
    "US-CA",
    "US-NY"
  ],
  "error": null,
  "warnings": [],
  "evaluation": "eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "score": 82,
  "insurable": false,
  "started": 1793318400,
  "finished": 1793318400,
  "created": 1793318400
}

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.

Scans API

#The Scan object

#Run a scan

#Parameters

#Body

#Returns

#List scans

#Parameters

#Returns

#Retrieve a scan

#Parameters

#Returns

The Scan object

Run a scan

Parameters

Body

Returns

List scans

Parameters

Returns

Retrieve a scan

Parameters

Returns