# Evaluations API

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

| Operation | Endpoint |
|---|---|
| [Re-evaluate a site now](#createEvaluation) | `POST /v1/sites/{site}/evaluations` |
| [List evaluations](#listEvaluations) | `GET /v1/evaluations` |
| [Retrieve an evaluation](#retrieveEvaluation) | `GET /v1/evaluations/{evaluation}` |
| [Get the current verdict of a site](#retrieveLatestEvaluation) | `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 {#createEvaluation}

`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](https://checkbox.site/docs/api/evaluations#the-evaluation-object) object.

Errors use the [standard envelope](https://checkbox.site/docs/api/errors) with a stable `code` and, where useful, `next_action`.

```curl
curl https://app.checkbox.site/v1/sites/site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b/evaluations \
  -u "$CHECKBOX_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -d '{}'
```
```node
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);
```
```python
import os
from checkbox import Checkbox

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

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

```json title="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 {#listEvaluations}

`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](https://checkbox.site/docs/api/evaluations#the-evaluation-object) objects.

Errors use the [standard envelope](https://checkbox.site/docs/api/errors) with a stable `code` and, where useful, `next_action`.

```curl
curl -G https://app.checkbox.site/v1/evaluations \
  -u "$CHECKBOX_SECRET_KEY:" \
  -d limit=3
```
```node
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);
```
```python
import os
from checkbox import Checkbox

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

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

```json title="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 {#retrieveEvaluation}

`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](https://checkbox.site/docs/api/evaluations#the-evaluation-object) object.

Errors use the [standard envelope](https://checkbox.site/docs/api/errors) with a stable `code` and, where useful, `next_action`.

```curl
curl https://app.checkbox.site/v1/evaluations/eval_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b \
  -u "$CHECKBOX_SECRET_KEY:"
```
```node
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);
```
```python
import os
from checkbox import Checkbox

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

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

```json title="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 {#retrieveLatestEvaluation}

`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](https://checkbox.site/docs/api/evaluations#the-evaluation-object) object.

Errors use the [standard envelope](https://checkbox.site/docs/api/errors) with a stable `code` and, where useful, `next_action`.

```curl
curl https://app.checkbox.site/v1/sites/site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b/evaluation \
  -u "$CHECKBOX_SECRET_KEY:"
```
```node
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);
```
```python
import os
from checkbox import Checkbox

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

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

```json title="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"
    }
  ]
}
```