Evaluations API

Compliance verdicts: score 0-100 and the insurable flag, with the checks that block insurability.

Operation	Endpoint
Re-evaluate a site now	`POST /v1/sites/{site}/evaluations`
List evaluations	`GET /v1/evaluations`
Retrieve an evaluation	`GET /v1/evaluations/{evaluation}`
Get the current verdict of a site	`GET /v1/sites/{site}/evaluation`

The Evaluation object

A compliance verdict for a site at a point in time.

Field	Type	Description
`id`	string	Unique identifier of the evaluation (eval_…).
`object`	enum	String representing the object's type. Always "evaluation".
`livemode`	boolean	true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox).
`site`	string	The evaluated site.
`scan`	string	The scan row this evaluation belongs to.
`score`	number	Compliance score 0-100 (severity-weighted, one decimal place, e.g. 82.5).
`insurable`	boolean	No critical/high check failing, no critical check undecided, no high check without evidence.
`rules_version`	string	Legal catalog / rules version used.
`evaluated`	integer	When it was evaluated. Unix timestamp in seconds.
`observed`	integer \| null	Newest synthetic-shopper observation it used. Unix timestamp in seconds.
`summary`	object	Counts per status.
`summary.pass`	integer	Passing checks.
`summary.fail`	integer	Failing checks.
`summary.needs_review`	integer	Checks needing a human look.
`summary.not_applicable`	integer	Checks that do not apply.
`blockers`	array of CheckSummarys	Checks that keep the site from being insurable.
`checks`	array of CheckSummarys	Every check evaluated.

Re-evaluate a site now

POST /v1/sites/{site}/evaluations

Re-runs the legal rules against the evidence already collected (no new scan) and returns the verdict synchronously. Use after changing site facts, or to get a verdict right after evidence arrived.

Scope evaluations:write · Idempotent (send Idempotency-Key) · Operation createEvaluation

SDK: checkbox.evaluations.create() (Node) · checkbox.evaluations.create() (Python). MCP / agents: operation createEvaluation.

Parameters

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

Returns

Returns an Evaluation object.

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

curl https://app.checkbox.site/v1/sites/site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b/evaluations \
  -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 evaluation = await checkbox.evaluations.create('site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(evaluation);

import os
from checkbox import Checkbox

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

evaluation = checkbox.evaluations.create("site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(evaluation)

Response

{
  "id": "eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "evaluation",
  "livemode": false,
  "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "scan": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "score": 82,
  "insurable": false,
  "rules_version": "2026.10.1",
  "evaluated": 1793318400,
  "observed": 1793318400,
  "summary": {
    "pass": 20,
    "fail": 2,
    "needs_review": 1,
    "not_applicable": 9
  },
  "blockers": [
    {
      "check_id": "cancellation.online_cancel_available",
      "title": "Customers can cancel online",
      "status": "pass",
      "severity": "critical",
      "stage": "cancellation"
    }
  ],
  "checks": [
    {
      "check_id": "cancellation.online_cancel_available",
      "title": "Customers can cancel online",
      "status": "pass",
      "severity": "critical",
      "stage": "cancellation"
    }
  ]
}

List evaluations

GET /v1/evaluations

Verdicts newest first (score history), optionally for one site.

Scope evaluations:read · Operation listEvaluations

SDK: checkbox.evaluations.list() (Node) · checkbox.evaluations.list() (Python). MCP / agents: operation listEvaluations.

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 Evaluation objects.

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

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

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

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

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

import os
from checkbox import Checkbox

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

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

Response

{
  "object": "list",
  "data": [
    {
      "id": "eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
      "object": "evaluation",
      "livemode": false,
      "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
      "scan": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
      "score": 82,
      "insurable": false,
      "rules_version": "2026.10.1",
      "evaluated": 1793318400,
      "observed": 1793318400,
      "summary": {
        "pass": 20,
        "fail": 2,
        "needs_review": 1,
        "not_applicable": 9
      },
      "blockers": [
        {
          "check_id": "cancellation.online_cancel_available",
          "title": "Customers can cancel online",
          "status": "pass",
          "severity": "critical",
          "stage": "cancellation"
        }
      ],
      "checks": [
        {
          "check_id": "cancellation.online_cancel_available",
          "title": "Customers can cancel online",
          "status": "pass",
          "severity": "critical",
          "stage": "cancellation"
        }
      ]
    }
  ],
  "has_more": false,
  "url": "/v1/sites"
}

Retrieve an evaluation

GET /v1/evaluations/{evaluation}

Returns one verdict with all checks and the insurability blockers.

Scope evaluations:read · Operation retrieveEvaluation

SDK: checkbox.evaluations.retrieve() (Node) · checkbox.evaluations.retrieve() (Python). MCP / agents: operation retrieveEvaluation.

Parameters

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

Returns

Returns an Evaluation object.

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

curl https://app.checkbox.site/v1/evaluations/eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b \
  -u "$CHECKBOX_SECRET_KEY:"

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

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

const evaluation = await checkbox.evaluations.retrieve('eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(evaluation);

import os
from checkbox import Checkbox

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

evaluation = checkbox.evaluations.retrieve("eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(evaluation)

Response

{
  "id": "eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "evaluation",
  "livemode": false,
  "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "scan": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "score": 82,
  "insurable": false,
  "rules_version": "2026.10.1",
  "evaluated": 1793318400,
  "observed": 1793318400,
  "summary": {
    "pass": 20,
    "fail": 2,
    "needs_review": 1,
    "not_applicable": 9
  },
  "blockers": [
    {
      "check_id": "cancellation.online_cancel_available",
      "title": "Customers can cancel online",
      "status": "pass",
      "severity": "critical",
      "stage": "cancellation"
    }
  ],
  "checks": [
    {
      "check_id": "cancellation.online_cancel_available",
      "title": "Customers can cancel online",
      "status": "pass",
      "severity": "critical",
      "stage": "cancellation"
    }
  ]
}

Get the current verdict of a site

GET /v1/sites/{site}/evaluation

The latest evaluation of the site: is it compliant (score) and insurable, and what blocks it. 404 resource_missing with next_action createScan when the site was never evaluated.

Scope evaluations:read · Operation retrieveLatestEvaluation

SDK: checkbox.evaluations.retrieveLatest() (Node) · checkbox.evaluations.retrieve_latest() (Python). MCP / agents: operation retrieveLatestEvaluation.

Parameters

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

Returns

Returns an Evaluation object.

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

curl https://app.checkbox.site/v1/sites/site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b/evaluation \
  -u "$CHECKBOX_SECRET_KEY:"

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

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

const evaluation = await checkbox.evaluations.retrieveLatest('site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(evaluation);

import os
from checkbox import Checkbox

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

evaluation = checkbox.evaluations.retrieve_latest("site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(evaluation)

Response

{
  "id": "eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "evaluation",
  "livemode": false,
  "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "scan": "scan_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "score": 82,
  "insurable": false,
  "rules_version": "2026.10.1",
  "evaluated": 1793318400,
  "observed": 1793318400,
  "summary": {
    "pass": 20,
    "fail": 2,
    "needs_review": 1,
    "not_applicable": 9
  },
  "blockers": [
    {
      "check_id": "cancellation.online_cancel_available",
      "title": "Customers can cancel online",
      "status": "pass",
      "severity": "critical",
      "stage": "cancellation"
    }
  ],
  "checks": [
    {
      "check_id": "cancellation.online_cancel_available",
      "title": "Customers can cancel online",
      "status": "pass",
      "severity": "critical",
      "stage": "cancellation"
    }
  ]
}

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.

Evaluations API

#The Evaluation object

#Re-evaluate a site now

#Parameters

#Returns

#List evaluations

#Parameters

#Returns

#Retrieve an evaluation

#Parameters

#Returns

#Get the current verdict of a site

#Parameters

#Returns

The Evaluation object

Re-evaluate a site now

Parameters

Returns

List evaluations

Parameters

Returns

Retrieve an evaluation

Parameters

Returns

Get the current verdict of a site

Parameters

Returns