# Evaluations API

> Compliance verdicts: the compliance status (label and counts), with the blocking checks.

| 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. |
| `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 | Blocking checks: critical or high-severity checks that fail, are undecided (critical) or lack evidence (high). |
| `compliance` | ComplianceRollup | Roll-up of the user-facing statuses of the required checks. |
| `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/node';

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",
  "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",
      "compliance_status": "pending_live_check"
    }
  ],
  "compliance": {
    "status": "compliant",
    "label": "Compliant · 2 live checks pending",
    "counts": {
      "needs_fix": 0,
      "your_call": 0,
      "pending_live_check": 2,
      "verified_live": 3,
      "compliant": 9,
      "not_applicable": 6,
      "not_set_up": 0,
      "not_checked": 0
    },
    "pending_live_checks": [
      {
        "what": "Your acknowledgment email, seen sent for a real sign-up",
        "completes": "Run a proof, or BCC your real acknowledgment emails to your Checkbox inbound address.",
        "action": "bcc_real_sends",
        "due": "2026-11-20"
      }
    ],
    "suggestions": 1,
    "checkouts": [
      {
        "name": "Annual",
        "kind": "payment_link",
        "plan": "Annual",
        "status": "pending_live_check",
        "label": "Needs a fix",
        "open": [
          {
            "check_id": "signup.disclosure.price",
            "title": "recurring charge is stated",
            "status": "pending_live_check"
          }
        ]
      }
    ]
  },
  "checks": [
    {
      "check_id": "cancellation.online_cancel_available",
      "title": "Customers can cancel online",
      "status": "pass",
      "severity": "critical",
      "stage": "cancellation",
      "compliance_status": "pending_live_check"
    }
  ]
}
```

## List evaluations {#listEvaluations}

`GET /v1/evaluations`

Verdicts newest first (status 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/node';

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",
      "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",
          "compliance_status": "pending_live_check"
        }
      ],
      "compliance": {
        "status": "compliant",
        "label": "Compliant · 2 live checks pending",
        "counts": {
          "needs_fix": 0,
          "your_call": 0,
          "pending_live_check": 2,
          "verified_live": 3,
          "compliant": 9,
          "not_applicable": 6,
          "not_set_up": 0,
          "not_checked": 0
        },
        "pending_live_checks": [
          {
            "what": "Your acknowledgment email, seen sent for a real sign-up",
            "completes": "Run a proof, or BCC your real acknowledgment emails to your Checkbox inbound address.",
            "action": "bcc_real_sends",
            "due": "2026-11-20"
          }
        ],
        "suggestions": 1,
        "checkouts": [
          {
            "name": "Annual",
            "kind": "payment_link",
            "plan": "Annual",
            "status": "pending_live_check",
            "label": "Needs a fix",
            "open": []
          }
        ]
      },
      "checks": [
        {
          "check_id": "cancellation.online_cancel_available",
          "title": "Customers can cancel online",
          "status": "pass",
          "severity": "critical",
          "stage": "cancellation",
          "compliance_status": "pending_live_check"
        }
      ]
    }
  ],
  "has_more": false,
  "url": "/v1/sites"
}
```

## Retrieve an evaluation {#retrieveEvaluation}

`GET /v1/evaluations/{evaluation}`

Returns one verdict with all checks and the blocking checks.

**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/node';

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",
  "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",
      "compliance_status": "pending_live_check"
    }
  ],
  "compliance": {
    "status": "compliant",
    "label": "Compliant · 2 live checks pending",
    "counts": {
      "needs_fix": 0,
      "your_call": 0,
      "pending_live_check": 2,
      "verified_live": 3,
      "compliant": 9,
      "not_applicable": 6,
      "not_set_up": 0,
      "not_checked": 0
    },
    "pending_live_checks": [
      {
        "what": "Your acknowledgment email, seen sent for a real sign-up",
        "completes": "Run a proof, or BCC your real acknowledgment emails to your Checkbox inbound address.",
        "action": "bcc_real_sends",
        "due": "2026-11-20"
      }
    ],
    "suggestions": 1,
    "checkouts": [
      {
        "name": "Annual",
        "kind": "payment_link",
        "plan": "Annual",
        "status": "pending_live_check",
        "label": "Needs a fix",
        "open": [
          {
            "check_id": "signup.disclosure.price",
            "title": "recurring charge is stated",
            "status": "pending_live_check"
          }
        ]
      }
    ]
  },
  "checks": [
    {
      "check_id": "cancellation.online_cancel_available",
      "title": "Customers can cancel online",
      "status": "pass",
      "severity": "critical",
      "stage": "cancellation",
      "compliance_status": "pending_live_check"
    }
  ]
}
```

## Get the current verdict of a site {#retrieveLatestEvaluation}

`GET /v1/sites/{site}/evaluation`

The latest evaluation of the site: its compliance status 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/node';

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",
  "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",
      "compliance_status": "pending_live_check"
    }
  ],
  "compliance": {
    "status": "compliant",
    "label": "Compliant · 2 live checks pending",
    "counts": {
      "needs_fix": 0,
      "your_call": 0,
      "pending_live_check": 2,
      "verified_live": 3,
      "compliant": 9,
      "not_applicable": 6,
      "not_set_up": 0,
      "not_checked": 0
    },
    "pending_live_checks": [
      {
        "what": "Your acknowledgment email, seen sent for a real sign-up",
        "completes": "Run a proof, or BCC your real acknowledgment emails to your Checkbox inbound address.",
        "action": "bcc_real_sends",
        "due": "2026-11-20"
      }
    ],
    "suggestions": 1,
    "checkouts": [
      {
        "name": "Annual",
        "kind": "payment_link",
        "plan": "Annual",
        "status": "pending_live_check",
        "label": "Needs a fix",
        "open": [
          {
            "check_id": "signup.disclosure.price",
            "title": "recurring charge is stated",
            "status": "pending_live_check"
          }
        ]
      }
    ]
  },
  "checks": [
    {
      "check_id": "cancellation.online_cancel_available",
      "title": "Customers can cancel online",
      "status": "pass",
      "severity": "critical",
      "stage": "cancellation",
      "compliance_status": "pending_live_check"
    }
  ]
}
```