The agent loop

How a coding agent connects a project with one human click, learns the business, and works a compliance plan to done — with the API calls behind each step.

The builder says "Add Checkbox". From there, Checkbox and the builder's agent talk to each other; the human clicks Approve once and reviews the result. This page shows each step and the API behind it, so you can drive it from the CLI, the MCP server or your own code.

agent  → MCP setup_checkbox  (or the CLI: checkbox init --yes --json)
agent  → POST /v1/device/authorize                   → a link with a code, e.g. BKRF-QXTP
human  → opens the link, signs in (email link, GitHub or Google), clicks Approve
agent  → POST /v1/device/token (polls)               → ck_test_ + pk_test_ keys, setup session, site
agent  → saves the key, adds the snippet to the root layout, reports the business URLs
Checkbox → fetches Terms / refund / cancellation pages, runs the first checks, (with permission) a test subscription
agent  → get_compliance_plan → apply task → verify_task → … until next_action.type is "done"
human  ← email: "Claude Code set up Checkbox for yoursite.com" with a review link (when the setup is finished)

#1. Connect: one call, one click

With the MCP server, call setup_checkbox with what you know from the code; with plain HTTP, call POST /v1/device/authorize and poll POST /v1/device/token. With the CLI:

npx @checkbox-site/cli init --yes --json --checkout-url https://joybox.example/pricing --merchant-name Joybox --plan 19.99/month,trial=7

• The command prints exactly one JSON document on stdout. The approval link and progress go to stderr: show the link to the human. New accounts are free and need no card.
• If the human has not approved yet, the result is status: "awaiting_approval" with next_action.command: "checkbox init --yes --json". Run it again; it resumes the same login.
• After approval the CLI writes CHECKBOX_SECRET_KEY and the publishable key to .env.local (and git-ignores it), installs the snippet in the root layout (between checkbox:snippet markers), and registers your site and policy pages.

What the CLI sends to Checkbox: framework, file paths and the matching lines of checkout code, URLs. Never your source code or .env values. A Stripe test key is used only after the human ticks the box for it on the approval page, and live keys are refused.

No shell? The MCP tool setup_checkbox does the same login: it returns the link for the human, then the keys.

#2. Teach Checkbox the business

The setup session is the checklist Checkbox keeps for the project. It always returns one next_action. An agent that already has a key (for example from the dashboard) can start one directly:

curl https://app.checkbox.site/v1/setup_sessions \
  -u "$CHECKBOX_SECRET_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "site_url": "https://joybox.example",
    "checkout_url": "https://joybox.example/pricing",
    "terms_url": "https://joybox.example/terms",
    "billing_platform": "stripe",
    "plans": [{ "name": "Pro", "amount": 1999, "currency": "usd", "interval": "month", "trial_days": 14 }]
  }'

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

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

const session = await checkbox.setupSessions.create({
  site_url: 'https://joybox.example',
  checkout_url: 'https://joybox.example/pricing',
  terms_url: 'https://joybox.example/terms',
  billing_platform: 'stripe',
  plans: [{ name: 'Pro', amount: 1999, currency: 'usd', interval: 'month', trial_days: 14 }],
});
console.log(session.steps.map((s) => `${s.key}: ${s.status}`));
console.log(session.next_action);

import os
from checkbox import Checkbox

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

session = checkbox.setup_sessions.create(
    site_url="https://joybox.example",
    checkout_url="https://joybox.example/pricing",
    terms_url="https://joybox.example/terms",
    billing_platform="stripe",
    plans=[{"name": "Pro", "amount": 1999, "currency": "usd", "interval": "month", "trial_days": 14}],
)
print([(s["key"], s["status"]) for s in session["steps"]])
print(session["next_action"])

Steps are account, site, snippet, policies, checks, fixes, lifecycle_test, domain, owner_notified, each done, pending, action_required, skipped or failed. A typical next_action:

{
  "type": "install_snippet",
  "message": "Add <script async src=\"https://app.checkbox.site/s.js\" data-key=\"…\"></script> to the <head> of every page (root layout), then report snippet_installed_in with updateSetupSession.",
  "operation_id": "updateSetupSession",
  "command": "checkbox init --yes --json"
}

Report what you did with updateSetupSession (snippet_installed_in, refund_url, plans…). After deploying, call verifySetupSession (checkbox init --verify --yes --json): Checkbox loads the site, confirms the snippet is live, re-fetches the policies, re-evaluates and queues the first scan. completeSetupSession sends the human the summary email. Policy pages are fetched and checked against the law too: a Terms of Service that says "no cancellations" or a refund policy that takes back a money-back promise on your pricing page shows up as a task.

#3. See every lifecycle step: the test subscription

With a Stripe test-mode key, Checkbox runs a synthetic subscription like a CMS preview: it subscribes a test customer with a test card, receives your acknowledgment and reminder emails at its own inbox, moves a Stripe test clock through the trial end and the first renewal, and cancels online. Every lifecycle check is observed, not inferred. Nothing is charged. See Test subscriptions.

#4. Work the compliance plan

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

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

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

const plan = await checkbox.plans.retrieve('site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(plan.status, plan.summary);
console.log(plan.next_action);

import os
from checkbox import Checkbox

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

plan = checkbox.plans.retrieve("site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(plan["status"], plan["summary"])
print(plan["next_action"])

The plan is an ordered list of tasks. Each task carries:

Plan status: action_required (an agent can apply open tasks), verifying (only confirmations pending), blocked (only human answers remain, or a critical/high task was declined), compliant. Before the first evaluation the plan's next_action is run_first_check: call verifySite.

#5. Verify, and repeat

After applying a task, ask Checkbox to check it. Send what changed — the rendered HTML before you deploy, the new Stripe params, or the new email copy — and Checkbox runs the fastest re-check now and queues the authoritative one (a scan, a billing sync, the next real email):

checkbox verify task_8c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f --wait --json

To re-check the whole site (for example after a deploy):

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

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

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

const verification = await checkbox.sites.verify('site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b');
console.log(verification.status, verification.next_action);

import os
from checkbox import Checkbox

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

verification = checkbox.sites.verify("site_3f9a1c2e7b4d4e0f9a8b7c6d5e4f3a2b")
print(verification["status"], verification["next_action"])

A verification is passed, failed (with what is still wrong) or pending; poll GET /v1/verifications/{id}?wait=30 or subscribe to the task.verified webhook. Fetch the plan again and continue until status is compliant — the site.compliant event fires once when it gets there.

#Questions only a human can answer

Some requirements cannot be observed: for example, New York requires reminders "in the manner the consumer selected". Those become manual tasks with a question. The agent asks the human and records the answer with answerTask; it never answers on the human's behalf. Manual tasks never block the others, and the plan summary says how many items rest on a human confirmation rather than an observation.

#next_action

Every agent-facing object and every error carries next_action: type (stable), a short message (setup, account, checks) or description (plans, verifications) for the model, and where useful operation_id (the API operation and SDK method to call), endpoint, command (the CLI equivalent) or url. Follow it; do not guess.

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.