# Sites API

> The subscription businesses Checkbox monitors, how to install the snippet, and domain verification (which activates live mode).

| Operation | Endpoint |
|---|---|
| [List sites](#listSites) | `GET /v1/sites` |
| [Create a site](#createSite) | `POST /v1/sites` |
| [Retrieve a site](#retrieveSite) | `GET /v1/sites/{site}` |
| [Update a site](#updateSite) | `POST /v1/sites/{site}` |
| [Archive a site](#deleteSite) | `DELETE /v1/sites/{site}` |
| [Restore an archived site](#restoreSite) | `POST /v1/sites/{site}/restore` |
| [Retrieve domain verification](#retrieveDomainVerification) | `GET /v1/sites/{site}/domain_verification` |
| [Start domain verification](#createDomainVerification) | `POST /v1/sites/{site}/domain_verification` |
| [Check domain verification now](#checkDomainVerification) | `POST /v1/sites/{site}/domain_verification/check` |

## The Site object

A subscription business Checkbox monitors.

| Field | Type | Description |
|---|---|---|
| `id` | string | Unique identifier of the site (site_…). |
| `object` | enum | String representing the object's type. Always "site". |
| `livemode` | boolean | true for live-mode objects, false for test mode (ck_test_ keys act on an isolated sandbox). |
| `name` | string | Display name. |
| `url` | string | Base URL. |
| `platform` | enum | Billing platform. One of `stripe`, `shopify`, `recharge`, `chargebee`, `recurly`, `paddle`, `woocommerce`, `custom`. |
| `jurisdictions` | array of enum | Evaluated jurisdictions (empty = all). |
| `facts` | SiteFacts | Business facts that decide which legal requirements apply. |
| `checkout` | object | Synthetic-shopper configuration (secrets are never returned). |
| `checkout.url` | string | Checkout entry page. |
| `checkout.regions` | array of enum | States scanned from. |
| `checkout.devices` | array of enum | Devices scanned. |
| `checkout.checkout_steps` | integer | Number of configured checkout steps. |
| `checkout.completes_purchase` | boolean | A synthetic sign-up is configured. |
| `checkout.has_test_account` | boolean | A test account for the cancellation test is configured. |
| `checkout.test_account` | object \| null | The test account as configured (the password is write-only and never returned). |
| `checkout.cancel_steps` | integer | Number of explicit cancellation steps. |
| `monitoring` | SiteMonitoring | Scheduled monitoring. |
| `compliance` | SiteCompliance \| null | Latest verdict; null until the first evaluation. |
| `install` | SiteInstall | What to install on the merchant site. |
| `archived` | boolean | Archived (soft-deleted); evidence is retained. |
| `created` | integer | When the site was created. Unix timestamp in seconds. |
| `latest_scan` | Scan | Most recent scan (only with expand[]=latest_scan). |
| `domain_verification` | DomainVerification | Domain verification (only with expand[]=domain_verification). |

## List sites {#listSites}

`GET /v1/sites`

Returns the sites of the account in the current mode, newest first. Archived sites are included only with archived=true.

**Scope** `sites:read` · **Operation** `listSites`

SDK: `checkbox.sites.list()` (Node) · `checkbox.sites.list()` (Python). MCP / agents: operation `listSites`.

#### 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). |
| `archived` | query | enum | true lists only archived sites. One of `true`, `false`. |

#### Returns

Returns a list (`{ object: "list", data, has_more, url }`) of [Site](https://checkbox.site/docs/api/sites#the-site-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/sites \
  -u "$CHECKBOX_SECRET_KEY:" \
  -d limit=3
```
```node
import Checkbox from '@checkbox-site/cli';

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

const sites = await checkbox.sites.list({ limit: 3 });
console.log(sites.data);
```
```python
import os
from checkbox import Checkbox

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

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

```json title="Response"
{
  "object": "list",
  "data": [
    {
      "id": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
      "object": "site",
      "livemode": false,
      "name": "Acme Coffee Club",
      "url": "https://acme.example",
      "platform": "stripe",
      "jurisdictions": [],
      "facts": {
        "has_free_trial": true,
        "trial_days": 14,
        "term_months": 1,
        "online_signup": true,
        "sells_goods": false,
        "notice_channel_email": true,
        "price_increase_consent_or_refund": false,
        "payment_methods": [
          "card"
        ]
      },
      "checkout": {
        "url": "https://acme.example/pricing",
        "regions": [
          "US-CA"
        ],
        "devices": [
          "desktop"
        ],
        "checkout_steps": 0,
        "completes_purchase": false,
        "has_test_account": false,
        "test_account": {
          "login_url": "https://acme.example/login",
          "email": "test-subscriber@acme.example"
        },
        "cancel_steps": 0
      },
      "monitoring": {
        "enabled": true,
        "interval_minutes": 1440,
        "held_for_activation": false,
        "last_scanned": 1793318400
      },
      "compliance": {
        "score": 82,
        "insurable": false,
        "evaluated": 1793318400,
        "open_findings": 2,
        "needs_review": 1
      },
      "install": {
        "script_tag": "<script async src=\"https://app.checkbox.site/s.js\" data-key=\"ab12…\"></script>",
        "snippet_key": "ab12cd34ef56",
        "inbound_email": "ab12cd34ef56@in.checkbox.site",
        "webhook_urls": {
          "stripe": "https://app.checkbox.site/webhooks/stripe/…"
        }
      },
      "archived": false,
      "created": 1793318400,
      "latest_scan": {
        "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
      },
      "domain_verification": {
        "id": "dv_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
        "object": "domain_verification",
        "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
        "domain": "acme.example",
        "status": "pending",
        "method": null,
        "verified_at": 1793318400,
        "last_checked": 1793318400,
        "last_error": "TXT record not found",
        "dns_record": {
          "type": "TXT",
          "name": "_checkbox-verify.acme.example",
          "value": "checkbox-verify=Xy…"
        },
        "file": {
          "url": "https://acme.example/.well-known/checkbox-verify.txt",
          "contents": "Xy…"
        },
        "scan_target_problems": [],
        "account_activated": false,
        "next_action": {
          "type": "publish_dns_record",
          "message": "Publish the TXT record, then call checkDomainVerification.",
          "operation_id": "checkDomainVerification",
          "mcp_tool": "call_api"
        }
      }
    }
  ],
  "has_more": false,
  "url": "/v1/sites"
}
```

## Create a site {#createSite}

`POST /v1/sites`

Registers a subscription business. Only `url` is required; Checkbox derives the name and uses the URL as the checkout entry page. The response includes `install` (snippet tag, inbound email, platform webhook URLs). Next: install the snippet, then run createScan (or let `checkbox init` do both). In live mode before activation, monitoring is held until a domain is verified; in test mode, monitoring of a host that is not localhost or a domain the account verified is held the same way, and on-demand scans of such hosts are limited to a few a day.

**Scope** `sites:write` · **Idempotent** (send `Idempotency-Key`) · **Operation** `createSite`

SDK: `checkbox.sites.create()` (Node) · `checkbox.sites.create()` (Python). MCP / agents: operation `createSite`.

#### Body

| Field | Type | Description |
|---|---|---|
| `name` | string | Display name. |
| `url` **required** | string | Base URL of the business website. |
| `platform` | enum | Billing platform. One of `stripe`, `shopify`, `recharge`, `chargebee`, `recurly`, `paddle`, `woocommerce`, `custom`. |
| `jurisdictions` | array of enum | Jurisdictions to evaluate (empty = all US laws). |
| `facts` | SiteFacts | Business facts that decide which legal requirements apply. |
| `checkout_url` | string | Page with the subscribe button (defaults to url). Not a Stripe-hosted session link. |
| `checkout_steps` | array of ScanSteps | Steps to reach the final pre-payment screen. |
| `purchase` | SitePurchase | How the synthetic shopper completes a real (free) sign-up. |
| `test_account` | SiteTestAccount | A test customer account the synthetic shopper uses to try cancelling online. |
| `cancel_steps` | array of ScanSteps | Explicit cancellation steps (otherwise auto-discovered). |
| `regions` | array of enum | States the synthetic shopper visits from. |
| `devices` | array of enum | Devices to emulate. |
| `monitoring_interval_minutes` | integer | Scheduled re-scan interval (0 = off, minimum 60). Default 1440 in live mode, 0 in test mode. |

#### Returns

Returns a [Site](https://checkbox.site/docs/api/sites#the-site-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 \
  -u "$CHECKBOX_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://acme.example"
}'
```
```node
import Checkbox from '@checkbox-site/cli';

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

const site = await checkbox.sites.create({ url: 'https://acme.example' });
console.log(site);
```
```python
import os
from checkbox import Checkbox

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

site = checkbox.sites.create(url="https://acme.example")
print(site)
```

```json title="Response"
{
  "id": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "site",
  "livemode": false,
  "name": "Acme Coffee Club",
  "url": "https://acme.example",
  "platform": "stripe",
  "jurisdictions": [],
  "facts": {
    "has_free_trial": true,
    "trial_days": 14,
    "term_months": 1,
    "online_signup": true,
    "sells_goods": false,
    "notice_channel_email": true,
    "price_increase_consent_or_refund": false,
    "payment_methods": [
      "card"
    ]
  },
  "checkout": {
    "url": "https://acme.example/pricing",
    "regions": [
      "US-CA"
    ],
    "devices": [
      "desktop"
    ],
    "checkout_steps": 0,
    "completes_purchase": false,
    "has_test_account": false,
    "test_account": {
      "login_url": "https://acme.example/login",
      "email": "test-subscriber@acme.example"
    },
    "cancel_steps": 0
  },
  "monitoring": {
    "enabled": true,
    "interval_minutes": 1440,
    "held_for_activation": false,
    "last_scanned": 1793318400
  },
  "compliance": {
    "score": 82,
    "insurable": false,
    "evaluated": 1793318400,
    "open_findings": 2,
    "needs_review": 1
  },
  "install": {
    "script_tag": "<script async src=\"https://app.checkbox.site/s.js\" data-key=\"ab12…\"></script>",
    "snippet_key": "ab12cd34ef56",
    "inbound_email": "ab12cd34ef56@in.checkbox.site",
    "webhook_urls": {
      "stripe": "https://app.checkbox.site/webhooks/stripe/…"
    }
  },
  "archived": false,
  "created": 1793318400,
  "latest_scan": {
    "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
  },
  "domain_verification": {
    "id": "dv_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "object": "domain_verification",
    "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "domain": "acme.example",
    "status": "pending",
    "method": null,
    "verified_at": 1793318400,
    "last_checked": 1793318400,
    "last_error": "TXT record not found",
    "dns_record": {
      "type": "TXT",
      "name": "_checkbox-verify.acme.example",
      "value": "checkbox-verify=Xy…"
    },
    "file": {
      "url": "https://acme.example/.well-known/checkbox-verify.txt",
      "contents": "Xy…"
    },
    "scan_target_problems": [],
    "account_activated": false,
    "next_action": {
      "type": "publish_dns_record",
      "message": "Publish the TXT record, then call checkDomainVerification.",
      "operation_id": "checkDomainVerification",
      "mcp_tool": "call_api"
    }
  }
}
```

## Retrieve a site {#retrieveSite}

`GET /v1/sites/{site}`

Returns a site with its latest compliance verdict (score, insurable) and install details.

**Scope** `sites:read` · **Operation** `retrieveSite`

SDK: `checkbox.sites.retrieve()` (Node) · `checkbox.sites.retrieve()` (Python). MCP / agents: operation `retrieveSite`.

#### Parameters

| Parameter | In | Type | Description |
|---|---|---|---|
| `site` **required** | path | string | Unique identifier of the site (site_…). |
| `expand[]` | query | array of enum | Related objects to include inline: latest_scan, domain_verification. Pass as expand[]=name. |

#### Returns

Returns a [Site](https://checkbox.site/docs/api/sites#the-site-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 \
  -u "$CHECKBOX_SECRET_KEY:"
```
```node
import Checkbox from '@checkbox-site/cli';

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

const site = await checkbox.sites.retrieve('site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(site);
```
```python
import os
from checkbox import Checkbox

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

site = checkbox.sites.retrieve("site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(site)
```

```json title="Response"
{
  "id": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "site",
  "livemode": false,
  "name": "Acme Coffee Club",
  "url": "https://acme.example",
  "platform": "stripe",
  "jurisdictions": [],
  "facts": {
    "has_free_trial": true,
    "trial_days": 14,
    "term_months": 1,
    "online_signup": true,
    "sells_goods": false,
    "notice_channel_email": true,
    "price_increase_consent_or_refund": false,
    "payment_methods": [
      "card"
    ]
  },
  "checkout": {
    "url": "https://acme.example/pricing",
    "regions": [
      "US-CA"
    ],
    "devices": [
      "desktop"
    ],
    "checkout_steps": 0,
    "completes_purchase": false,
    "has_test_account": false,
    "test_account": {
      "login_url": "https://acme.example/login",
      "email": "test-subscriber@acme.example"
    },
    "cancel_steps": 0
  },
  "monitoring": {
    "enabled": true,
    "interval_minutes": 1440,
    "held_for_activation": false,
    "last_scanned": 1793318400
  },
  "compliance": {
    "score": 82,
    "insurable": false,
    "evaluated": 1793318400,
    "open_findings": 2,
    "needs_review": 1
  },
  "install": {
    "script_tag": "<script async src=\"https://app.checkbox.site/s.js\" data-key=\"ab12…\"></script>",
    "snippet_key": "ab12cd34ef56",
    "inbound_email": "ab12cd34ef56@in.checkbox.site",
    "webhook_urls": {
      "stripe": "https://app.checkbox.site/webhooks/stripe/…"
    }
  },
  "archived": false,
  "created": 1793318400,
  "latest_scan": {
    "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
  },
  "domain_verification": {
    "id": "dv_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "object": "domain_verification",
    "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "domain": "acme.example",
    "status": "pending",
    "method": null,
    "verified_at": 1793318400,
    "last_checked": 1793318400,
    "last_error": "TXT record not found",
    "dns_record": {
      "type": "TXT",
      "name": "_checkbox-verify.acme.example",
      "value": "checkbox-verify=Xy…"
    },
    "file": {
      "url": "https://acme.example/.well-known/checkbox-verify.txt",
      "contents": "Xy…"
    },
    "scan_target_problems": [],
    "account_activated": false,
    "next_action": {
      "type": "publish_dns_record",
      "message": "Publish the TXT record, then call checkDomainVerification.",
      "operation_id": "checkDomainVerification",
      "mcp_tool": "call_api"
    }
  }
}
```

## Update a site {#updateSite}

`POST /v1/sites/{site}`

Updates the given fields; omitted fields keep their values. Changing `url` to another domain forgets the domain verification and ends the active certificate.

**Scope** `sites:write` · **Idempotent** (send `Idempotency-Key`) · **Operation** `updateSite`

SDK: `checkbox.sites.update()` (Node) · `checkbox.sites.update()` (Python). MCP / agents: operation `updateSite`.

#### Parameters

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

#### Body

| Field | Type | Description |
|---|---|---|
| `name` | string | Display name. |
| `url` | string | Base URL of the business website. |
| `platform` | enum | Billing platform. One of `stripe`, `shopify`, `recharge`, `chargebee`, `recurly`, `paddle`, `woocommerce`, `custom`. |
| `jurisdictions` | array of enum | Jurisdictions to evaluate (empty = all US laws). |
| `facts` | SiteFacts | Business facts that decide which legal requirements apply. |
| `checkout_url` | string | Page with the subscribe button (defaults to url). Not a Stripe-hosted session link. |
| `checkout_steps` | array of ScanSteps | Steps to reach the final pre-payment screen. |
| `purchase` | SitePurchase | How the synthetic shopper completes a real (free) sign-up. |
| `test_account` | SiteTestAccount | A test customer account the synthetic shopper uses to try cancelling online. |
| `cancel_steps` | array of ScanSteps | Explicit cancellation steps (otherwise auto-discovered). |
| `regions` | array of enum | States the synthetic shopper visits from. |
| `devices` | array of enum | Devices to emulate. |
| `monitoring_interval_minutes` | integer | Scheduled re-scan interval (0 = off, minimum 60). Default 1440 in live mode, 0 in test mode. |

#### Returns

Returns a [Site](https://checkbox.site/docs/api/sites#the-site-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 \
  -u "$CHECKBOX_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Acme Coffee Club"
}'
```
```node
import Checkbox from '@checkbox-site/cli';

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

const site = await checkbox.sites.update('site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b', { name: 'Acme Coffee Club' });
console.log(site);
```
```python
import os
from checkbox import Checkbox

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

site = checkbox.sites.update("site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b", name="Acme Coffee Club")
print(site)
```

```json title="Response"
{
  "id": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "site",
  "livemode": false,
  "name": "Acme Coffee Club",
  "url": "https://acme.example",
  "platform": "stripe",
  "jurisdictions": [],
  "facts": {
    "has_free_trial": true,
    "trial_days": 14,
    "term_months": 1,
    "online_signup": true,
    "sells_goods": false,
    "notice_channel_email": true,
    "price_increase_consent_or_refund": false,
    "payment_methods": [
      "card"
    ]
  },
  "checkout": {
    "url": "https://acme.example/pricing",
    "regions": [
      "US-CA"
    ],
    "devices": [
      "desktop"
    ],
    "checkout_steps": 0,
    "completes_purchase": false,
    "has_test_account": false,
    "test_account": {
      "login_url": "https://acme.example/login",
      "email": "test-subscriber@acme.example"
    },
    "cancel_steps": 0
  },
  "monitoring": {
    "enabled": true,
    "interval_minutes": 1440,
    "held_for_activation": false,
    "last_scanned": 1793318400
  },
  "compliance": {
    "score": 82,
    "insurable": false,
    "evaluated": 1793318400,
    "open_findings": 2,
    "needs_review": 1
  },
  "install": {
    "script_tag": "<script async src=\"https://app.checkbox.site/s.js\" data-key=\"ab12…\"></script>",
    "snippet_key": "ab12cd34ef56",
    "inbound_email": "ab12cd34ef56@in.checkbox.site",
    "webhook_urls": {
      "stripe": "https://app.checkbox.site/webhooks/stripe/…"
    }
  },
  "archived": false,
  "created": 1793318400,
  "latest_scan": {
    "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
  },
  "domain_verification": {
    "id": "dv_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "object": "domain_verification",
    "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "domain": "acme.example",
    "status": "pending",
    "method": null,
    "verified_at": 1793318400,
    "last_checked": 1793318400,
    "last_error": "TXT record not found",
    "dns_record": {
      "type": "TXT",
      "name": "_checkbox-verify.acme.example",
      "value": "checkbox-verify=Xy…"
    },
    "file": {
      "url": "https://acme.example/.well-known/checkbox-verify.txt",
      "contents": "Xy…"
    },
    "scan_target_problems": [],
    "account_activated": false,
    "next_action": {
      "type": "publish_dns_record",
      "message": "Publish the TXT record, then call checkDomainVerification.",
      "operation_id": "checkDomainVerification",
      "mcp_tool": "call_api"
    }
  }
}
```

## Archive a site {#deleteSite}

`DELETE /v1/sites/{site}`

Archives (soft-deletes) the site: monitoring stops and it disappears from lists, but evidence and findings are retained for the warranty. Undo with restoreSite.

**Scope** `sites:write` · **Operation** `deleteSite`

SDK: `checkbox.sites.del()` (Node) · `checkbox.sites.delete()` (Python). MCP / agents: operation `deleteSite`.

#### Parameters

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

#### Returns

Returns a [Site](https://checkbox.site/docs/api/sites#the-site-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 \
  -u "$CHECKBOX_SECRET_KEY:" \
  -X DELETE
```
```node
import Checkbox from '@checkbox-site/cli';

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

const site = await checkbox.sites.del('site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(site);
```
```python
import os
from checkbox import Checkbox

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

site = checkbox.sites.delete("site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(site)
```

```json title="Response"
{
  "id": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "site",
  "livemode": false,
  "name": "Acme Coffee Club",
  "url": "https://acme.example",
  "platform": "stripe",
  "jurisdictions": [],
  "facts": {
    "has_free_trial": true,
    "trial_days": 14,
    "term_months": 1,
    "online_signup": true,
    "sells_goods": false,
    "notice_channel_email": true,
    "price_increase_consent_or_refund": false,
    "payment_methods": [
      "card"
    ]
  },
  "checkout": {
    "url": "https://acme.example/pricing",
    "regions": [
      "US-CA"
    ],
    "devices": [
      "desktop"
    ],
    "checkout_steps": 0,
    "completes_purchase": false,
    "has_test_account": false,
    "test_account": {
      "login_url": "https://acme.example/login",
      "email": "test-subscriber@acme.example"
    },
    "cancel_steps": 0
  },
  "monitoring": {
    "enabled": true,
    "interval_minutes": 1440,
    "held_for_activation": false,
    "last_scanned": 1793318400
  },
  "compliance": {
    "score": 82,
    "insurable": false,
    "evaluated": 1793318400,
    "open_findings": 2,
    "needs_review": 1
  },
  "install": {
    "script_tag": "<script async src=\"https://app.checkbox.site/s.js\" data-key=\"ab12…\"></script>",
    "snippet_key": "ab12cd34ef56",
    "inbound_email": "ab12cd34ef56@in.checkbox.site",
    "webhook_urls": {
      "stripe": "https://app.checkbox.site/webhooks/stripe/…"
    }
  },
  "archived": false,
  "created": 1793318400,
  "latest_scan": {
    "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
  },
  "domain_verification": {
    "id": "dv_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "object": "domain_verification",
    "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "domain": "acme.example",
    "status": "pending",
    "method": null,
    "verified_at": 1793318400,
    "last_checked": 1793318400,
    "last_error": "TXT record not found",
    "dns_record": {
      "type": "TXT",
      "name": "_checkbox-verify.acme.example",
      "value": "checkbox-verify=Xy…"
    },
    "file": {
      "url": "https://acme.example/.well-known/checkbox-verify.txt",
      "contents": "Xy…"
    },
    "scan_target_problems": [],
    "account_activated": false,
    "next_action": {
      "type": "publish_dns_record",
      "message": "Publish the TXT record, then call checkDomainVerification.",
      "operation_id": "checkDomainVerification",
      "mcp_tool": "call_api"
    }
  }
}
```

## Restore an archived site {#restoreSite}

`POST /v1/sites/{site}/restore`

Un-archives a site (counts against the fair-use site limit again).

**Scope** `sites:write` · **Idempotent** (send `Idempotency-Key`) · **Operation** `restoreSite`

SDK: `checkbox.sites.restore()` (Node) · `checkbox.sites.restore()` (Python). MCP / agents: operation `restoreSite`.

#### Parameters

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

#### Returns

Returns a [Site](https://checkbox.site/docs/api/sites#the-site-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/restore \
  -u "$CHECKBOX_SECRET_KEY:" \
  -X POST
```
```node
import Checkbox from '@checkbox-site/cli';

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

const site = await checkbox.sites.restore('site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(site);
```
```python
import os
from checkbox import Checkbox

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

site = checkbox.sites.restore("site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(site)
```

```json title="Response"
{
  "id": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "site",
  "livemode": false,
  "name": "Acme Coffee Club",
  "url": "https://acme.example",
  "platform": "stripe",
  "jurisdictions": [],
  "facts": {
    "has_free_trial": true,
    "trial_days": 14,
    "term_months": 1,
    "online_signup": true,
    "sells_goods": false,
    "notice_channel_email": true,
    "price_increase_consent_or_refund": false,
    "payment_methods": [
      "card"
    ]
  },
  "checkout": {
    "url": "https://acme.example/pricing",
    "regions": [
      "US-CA"
    ],
    "devices": [
      "desktop"
    ],
    "checkout_steps": 0,
    "completes_purchase": false,
    "has_test_account": false,
    "test_account": {
      "login_url": "https://acme.example/login",
      "email": "test-subscriber@acme.example"
    },
    "cancel_steps": 0
  },
  "monitoring": {
    "enabled": true,
    "interval_minutes": 1440,
    "held_for_activation": false,
    "last_scanned": 1793318400
  },
  "compliance": {
    "score": 82,
    "insurable": false,
    "evaluated": 1793318400,
    "open_findings": 2,
    "needs_review": 1
  },
  "install": {
    "script_tag": "<script async src=\"https://app.checkbox.site/s.js\" data-key=\"ab12…\"></script>",
    "snippet_key": "ab12cd34ef56",
    "inbound_email": "ab12cd34ef56@in.checkbox.site",
    "webhook_urls": {
      "stripe": "https://app.checkbox.site/webhooks/stripe/…"
    }
  },
  "archived": false,
  "created": 1793318400,
  "latest_scan": {
    "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
  },
  "domain_verification": {
    "id": "dv_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "object": "domain_verification",
    "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
    "domain": "acme.example",
    "status": "pending",
    "method": null,
    "verified_at": 1793318400,
    "last_checked": 1793318400,
    "last_error": "TXT record not found",
    "dns_record": {
      "type": "TXT",
      "name": "_checkbox-verify.acme.example",
      "value": "checkbox-verify=Xy…"
    },
    "file": {
      "url": "https://acme.example/.well-known/checkbox-verify.txt",
      "contents": "Xy…"
    },
    "scan_target_problems": [],
    "account_activated": false,
    "next_action": {
      "type": "publish_dns_record",
      "message": "Publish the TXT record, then call checkDomainVerification.",
      "operation_id": "checkDomainVerification",
      "mcp_tool": "call_api"
    }
  }
}
```

## Retrieve domain verification {#retrieveDomainVerification}

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

Status of the site domain verification, with the DNS record / file to publish.

**Scope** `sites:read` · **Operation** `retrieveDomainVerification`

SDK: `checkbox.domainVerifications.retrieve()` (Node) · `checkbox.domain_verifications.retrieve()` (Python). MCP / agents: operation `retrieveDomainVerification`.

#### Parameters

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

#### Returns

Returns a `DomainVerification` 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/domain_verification \
  -u "$CHECKBOX_SECRET_KEY:"
```
```node
import Checkbox from '@checkbox-site/cli';

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

const domainVerification = await checkbox.domainVerifications.retrieve('site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(domainVerification);
```
```python
import os
from checkbox import Checkbox

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

domain_verification = checkbox.domain_verifications.retrieve("site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(domain_verification)
```

```json title="Response"
{
  "id": "dv_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "domain_verification",
  "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "domain": "acme.example",
  "status": "pending",
  "method": null,
  "verified_at": 1793318400,
  "last_checked": 1793318400,
  "last_error": "TXT record not found",
  "dns_record": {
    "type": "TXT",
    "name": "_checkbox-verify.acme.example",
    "value": "checkbox-verify=Xy…"
  },
  "file": {
    "url": "https://acme.example/.well-known/checkbox-verify.txt",
    "contents": "Xy…"
  },
  "scan_target_problems": [],
  "account_activated": false,
  "next_action": {
    "type": "publish_dns_record",
    "message": "Publish the TXT record, then call checkDomainVerification.",
    "operation_id": "checkDomainVerification",
    "mcp_tool": "call_api"
  }
}
```

## Start domain verification {#createDomainVerification}

`POST /v1/sites/{site}/domain_verification`

Starts verification of the site domain and returns a DNS TXT record and a /.well-known file; publishing either proves control. Then call checkDomainVerification. Verifying a live-mode site activates live mode for the account (instant, self-serve).

**Scope** `sites:write` · **Idempotent** (send `Idempotency-Key`) · **Operation** `createDomainVerification`

SDK: `checkbox.domainVerifications.create()` (Node) · `checkbox.domain_verifications.create()` (Python). MCP / agents: operation `createDomainVerification`.

#### Parameters

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

#### Body

| Field | Type | Description |
|---|---|---|
| `rotate` | boolean | Issue a new token (invalidates the old one). |

#### Returns

Returns a `DomainVerification` 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/domain_verification \
  -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 domainVerification = await checkbox.domainVerifications.create('site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(domainVerification);
```
```python
import os
from checkbox import Checkbox

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

domain_verification = checkbox.domain_verifications.create("site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(domain_verification)
```

```json title="Response"
{
  "id": "dv_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "domain_verification",
  "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "domain": "acme.example",
  "status": "pending",
  "method": null,
  "verified_at": 1793318400,
  "last_checked": 1793318400,
  "last_error": "TXT record not found",
  "dns_record": {
    "type": "TXT",
    "name": "_checkbox-verify.acme.example",
    "value": "checkbox-verify=Xy…"
  },
  "file": {
    "url": "https://acme.example/.well-known/checkbox-verify.txt",
    "contents": "Xy…"
  },
  "scan_target_problems": [],
  "account_activated": false,
  "next_action": {
    "type": "publish_dns_record",
    "message": "Publish the TXT record, then call checkDomainVerification.",
    "operation_id": "checkDomainVerification",
    "mcp_tool": "call_api"
  }
}
```

## Check domain verification now {#checkDomainVerification}

`POST /v1/sites/{site}/domain_verification/check`

Looks for the DNS TXT record and the /.well-known file now. On success in live mode, the account is activated and held monitoring starts.

**Scope** `sites:write` · **Idempotent** (send `Idempotency-Key`) · **Operation** `checkDomainVerification`

SDK: `checkbox.domainVerifications.check()` (Node) · `checkbox.domain_verifications.check()` (Python). MCP / agents: operation `checkDomainVerification`.

#### Parameters

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

#### Returns

Returns a `DomainVerification` 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/domain_verification/check \
  -u "$CHECKBOX_SECRET_KEY:" \
  -X POST
```
```node
import Checkbox from '@checkbox-site/cli';

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

const domainVerification = await checkbox.domainVerifications.check('site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(domainVerification);
```
```python
import os
from checkbox import Checkbox

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

domain_verification = checkbox.domain_verifications.check("site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(domain_verification)
```

```json title="Response"
{
  "id": "dv_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "object": "domain_verification",
  "site": "site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b",
  "domain": "acme.example",
  "status": "pending",
  "method": null,
  "verified_at": 1793318400,
  "last_checked": 1793318400,
  "last_error": "TXT record not found",
  "dns_record": {
    "type": "TXT",
    "name": "_checkbox-verify.acme.example",
    "value": "checkbox-verify=Xy…"
  },
  "file": {
    "url": "https://acme.example/.well-known/checkbox-verify.txt",
    "contents": "Xy…"
  },
  "scan_target_problems": [],
  "account_activated": false,
  "next_action": {
    "type": "publish_dns_record",
    "message": "Publish the TXT record, then call checkDomainVerification.",
    "operation_id": "checkDomainVerification",
    "mcp_tool": "call_api"
  }
}
```