API Reference

Name: Colter
Author: Colter

Complete reference for the Colter public API, CLI commands, and MCP tools.

TL;DR: Use colter check, colter fix, colter test, and colter verify from the CLI, or call the hosted API when you need read-only HTTPS endpoints. Prefer JSON output and MCP tools when an AI agent needs deterministic, structured responses.

Overview

Colter provides three interfaces for interacting with agentic commerce across five capabilities --- Check, Fix, Lens, Test, and Verify:

CLI — Command-line tools for readiness scanning, AI persona testing, fix generation, verification, Evidence Pack management, and server operations
MCP Server — Model Context Protocol tools for AI agents
Public API — Hosted HTTP endpoints for agent-readiness checks, test runs, and fix plans

Important boundary: the Public API is read-only and only runs readiness scans, test runs, and fix plans. It does not perform agent commerce actions (cart/checkout/receipt) and does not require credentials. Commerce actions are available via the local CLI and MCP server with an explicitly configured backend (colter.yaml).

These endpoints return structured JSON optimized for AI agent and automation consumption.

Public API

The hosted API is available at https://agenticcom.ai/api/v1/check. No authentication required. Rate limited to 5 requests/minute/IP.

POST /api/v1/check

Check whether a store is ready for AI shopping agents.

Request:

curl -X POST https://agenticcom.ai/api/v1/check \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example-store.com"}'

Request Body:

{
  "url": "https://example-store.com"
}

Field	Type	Required	Description
`url`	string	Yes	Store URL to check. Scheme is optional (defaults to `https://`).

Response (200):

{
  "url": "example-store.com",
  "agent_ready": true,
  "fully_covered": true,
  "protocols": {
    "ucp": {
      "detected": true,
      "endpoint": "/.well-known/ucp",
      "version": "2026-01-23",
      "error": ""
    },
    "acp": {
      "detected": true,
      "endpoint": "/.well-known/acp",
      "version": "1.0",
      "error": ""
    },
    "mcp": {
      "detected": false,
      "endpoint": "",
      "version": "",
      "error": "/.well-known/mcp returned HTTP 404"
    }
  },
  "store": {
    "platform": "shopify",
    "platform_confidence": 0.92,
    "product_count": 42,
    "psp": "shopify_payments",
    "detectable": true
  },
  "coverage": {
    "google_ecosystem": true,
    "openai_ecosystem": true
  },
  "web_signals": {
    "json_ld_found": true,
    "json_ld_types": ["Product", "Organization"],
    "sitemap_found": true,
    "robots_txt_found": true,
    "og_tags_found": true
  },
  "verdict": "AGENT-READY",
  "recommendation": "",
  "next_step": null,
  "plain_language": {
    "merchant": "Your store is fully ready for AI shopping agents. Both ChatGPT and Google AI can find and purchase your products.",
    "agency": "This store passes 2/2 protocol checks. Full agent coverage across UCP and ACP ecosystems.",
    "developer": "Protocol support: UCP (pass), ACP (pass). Full ecosystem coverage."
  },
  "checked_at": "2026-02-07T12:00:00.000Z"
}

Response Schema

Field	Type	Description
`url`	string	Normalized hostname of the store that was checked.
`agent_ready`	boolean	`true` if at least one protocol (UCP or ACP) is detected.
`fully_covered`	boolean	`true` if both UCP and ACP are detected.
`protocols`	object	Protocol detection results (see below).
`store`	object	Store platform detection (see below).
`coverage`	object	Ecosystem coverage map (see below).
`web_signals`	object	Foundational web discoverability signals (see below).
`verdict`	string	One of: `AGENT-READY`, `PARTIALLY AGENT-READY`, `NOT AGENT-READY`.
`recommendation`	string	Suggested next CLI command, or empty if fully ready.
`next_step`	object \| null	Structured next-step suggestion (see below).
`plain_language`	object	Role-appropriate summary strings (see below).
`checked_at`	string	ISO 8601 timestamp of when the check was performed.

protocols

Each protocol (ucp, acp, mcp) has these fields:

Field	Type	Description
`detected`	boolean	Whether the protocol endpoint was found and returned valid JSON.
`endpoint`	string	The well-known path probed (e.g. `/.well-known/ucp`). Empty if not found.
`version`	string	Protocol version from the manifest, if available.
`error`	string	Error message if detection failed. Empty on success.

store

Field	Type	Description
`platform`	string	Detected platform (e.g. `shopify`, `woocommerce`, or empty).
`platform_confidence`	number	Confidence score for platform detection (0..1).
`product_count`	number	Number of products detected, or `0` if unknown.
`psp`	string	Payment provider (if known).
`detectable`	boolean	Whether the store platform could be identified.

coverage

Field	Type	Description
`google_ecosystem`	boolean	`true` if UCP detected (Gemini, AI Mode, Copilot).
`openai_ecosystem`	boolean	`true` if ACP detected (ChatGPT, Operator).

web_signals

Field	Type	Description
`json_ld_found`	boolean	`true` if the page contains JSON-LD structured data.
`json_ld_types`	string[]	Schema.org types found (e.g. `["Product", "Organization"]`).
`sitemap_found`	boolean	`true` if `/sitemap.xml` is accessible.
`robots_txt_found`	boolean	`true` if `/robots.txt` exists and allows crawling.
`og_tags_found`	boolean	`true` if Open Graph meta tags (`og:type`, `og:title`, `og:image`) are present.

plain_language

Field	Type	Description
`merchant`	string	Business-focused summary for store owners.
`agency`	string	Portfolio-focused summary for agencies managing multiple stores.
`developer`	string	Technical summary with protocol pass/fail details.

next_step

If the store is not fully covered, Colter may also return a structured next-step hint:

{
  "kind": "cli",
  "command": "colter",
  "args": ["verify", "example-store.com", "--protocols=acp"],
  "reason": "Run ACP conformance checks and generate an Evidence Pack."
}

This is intended for deterministic integrations that don't want to parse a multi-line recommendation string.

Error Responses

Status	Description
400	Invalid JSON body or missing `url` field.
422	URL validation failed (private IP, unsupported scheme, direct IP address).
429	Rate limited. `Retry-After` header included.

{
  "error": "Missing required field: url"
}

POST /api/v1/fix

Generate a fix plan for a store URL. Identifies fixable issues and predicts score improvements.

Request:

curl -X POST https://agenticcom.ai/api/v1/fix \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example-store.com"}'

Field	Type	Required	Description
`url`	string	Yes	Store URL to generate fix plan for.
`include_content`	boolean	No	If `true`, includes generated fix content. Default `false`.

Returns a fix plan with operations sorted by score impact. Each op includes type, description, score_impact, dimension, risk_level (apply or manual), and optionally generated_content. Rate limited to 3 requests/minute/IP.

See the OpenAPI spec for the full response schema.

GET /api/v1/results/:id

Fetch a stored readiness result by result_id returned from POST /api/v1/check.

Notes:

Results are public to anyone with the ID.
For client deliverables, prefer share tokens (below) so you can revoke/expire links.

GET /api/v1/results/:id/pdf

Download a PDF report for a stored readiness result.

Query params:

brand (optional)
logo (optional, https only)
whitelabel=true (optional)
client_friendly=true (optional)

Share tokens are intended for agency/client-facing deliverables.

POST /api/v1/shares with { "result_id": "..." } to mint a token
Share the returned URL (/s/<token>)
Revoke later with POST /api/v1/shares/<token>/revoke and the revoke_token secret

Endpoints:

POST /api/v1/shares
GET /api/v1/shares/:token
GET /api/v1/shares/:token/pdf
POST /api/v1/shares/:token/revoke

Tip: the full contract is published in openapi.yaml at the site root.

Test Run Endpoints

Run and retrieve AI persona test results via the API.

POST /api/v1/test-runs

Start a new AI persona test run against a store URL.

Request:

curl -X POST https://agenticcom.ai/api/v1/test-runs \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example-store.com", "models": ["claude", "gemini"]}'

Field	Type	Required	Description
`url`	string	Yes	Store URL to test.
`models`	string[]	No	Models to use: `claude`, `gpt`, `gemini`. Default: all 3 models.
`personas`	string[]	No	Persona IDs to run. Default: all.
`scenarios`	string[]	No	Scenario IDs to run. Default: all.
`budget`	number	No	Max spend in USD. Default: `1.00`.

Returns 202 Accepted with a run_id for polling.

GET /api/v1/test-runs

List test runs. Supports pagination and filtering.

curl https://agenticcom.ai/api/v1/test-runs?url=example-store.com&limit=10

Param	Type	Description
`url`	string	Filter by store URL.
`limit`	number	Max results (default: 20, max: 100).
`offset`	number	Pagination offset.

GET /api/v1/test-runs/compare

Compare two test runs side by side. Useful for before/after analysis.

curl "https://agenticcom.ai/api/v1/test-runs/compare?run_a=abc123&run_b=def456"

Param	Type	Required	Description
`run_a`	string	Yes	First test run ID.
`run_b`	string	Yes	Second test run ID.

Returns a diff of scores, persona results, and scenario outcomes between the two runs.

GET /api/v1/test-runs/export

Export test run results as CSV or PDF.

curl "https://agenticcom.ai/api/v1/test-runs/export?run_id=abc123&format=pdf" -o report.pdf

Param	Type	Required	Description
`run_id`	string	Yes	Test run ID to export.
`format`	string	No	Export format: `csv` or `pdf`. Default: `csv`.

Lens Monitoring Endpoints (Authenticated)

Lens endpoints require either a dashboard session cookie or Authorization: Bearer <COLTER_API_KEY>.

GET /api/v1/lens/traffic

Fetch traffic analytics for a monitored Lens site.

curl "https://agenticcom.ai/api/v1/lens/traffic?site_id=site_123&period=7d" \
  -H "Authorization: Bearer $COLTER_API_KEY"

Param	Type	Required	Description
`site_id`	string	Yes	Lens site ID to query.
`period`	string	No	`24h`, `7d`, or `30d` (default: `7d`).

Response shape includes:

by_agent (agent buckets)
by_day, top_paths, top_products, by_country
by_verification (verification status breakdown by agent/class)
signature_failures (top signature verification failure reasons)

GET /api/v1/lens/journeys

Fetch reconstructed agent journey sessions and funnel/drop-off analytics.

curl "https://agenticcom.ai/api/v1/lens/journeys?site_id=site_123&period=7d" \
  -H "Authorization: Bearer $COLTER_API_KEY"

Param	Type	Required	Description
`site_id`	string	Yes	Lens site ID to query.
`period`	string	No	`1d`, `7d`, or `30d` (default: `7d`).
`agent`	string	No	Filter to one `agent_name`.

Response shape:

site_id, period
funnel (discovery, browse, protocol, cart, checkout, transaction)
by_agent (sessions, average pages/duration, outcomes, protocols attempted)
recent_sessions (latest 50 sessions with stage/outcome/path context)
drop_off (adjacent-stage conversion loss rates + top exits/errors)

GET /api/v1/lens/protocols

Fetch latest protocol health snapshot plus recent history for a monitored site.

curl "https://agenticcom.ai/api/v1/lens/protocols?site_id=site_123&limit=24" \
  -H "Authorization: Bearer $COLTER_API_KEY"

Param	Type	Required	Description
`site_id`	string	Yes	Lens site ID to query.
`limit`	number	No	History rows to return (default: 24, max: 100).

Response shape:

site_id
latest (full protocol snapshot row, or null if no checks yet)
history (recent score/protocol state rows)

latest includes payment-protocol fields from Sprint W4:

x402_detected, x402_endpoint, x402_error, x402_response_ms, x402_network, x402_min_price
acp_checkout_detected, acp_checkout_endpoint, acp_checkout_error, acp_checkout_response_ms

history includes:

x402_detected
acp_checkout_detected
markdown_for_agents_found
agents_md_found

GET /api/v1/lens/alerts

Fetch recent protocol/score alerts for a monitored site.

curl "https://agenticcom.ai/api/v1/lens/alerts?site_id=site_123&status=open&limit=20" \
  -H "Authorization: Bearer $COLTER_API_KEY"

Param	Type	Required	Description
`site_id`	string	Yes	Lens site ID to query.
`status`	string	No	Filter by `open`, `acknowledged`, or `resolved`.
`limit`	number	No	Max rows to return (default: 50, max: 200).

Response shape:

site_id
alerts (alert rows)
summary (status counts map)

Alert types include:

protocol_down, protocol_recovered, score_drop, signature_failure
new_agent
x402_down, x402_recovered
acp_checkout_down, acp_checkout_recovered
markdown_degraded, markdown_recovered
agents_md_degraded, agents_md_recovered

PATCH /api/v1/lens/alerts

Acknowledge or resolve an alert.

curl -X PATCH https://agenticcom.ai/api/v1/lens/alerts \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $COLTER_API_KEY" \
  -d '{"alert_id":"alert_123","status":"resolved"}'

Field	Type	Required	Description
`alert_id`	string	Yes	Alert row ID to update.
`status`	string	Yes	New status: `acknowledged` or `resolved`.

Response:

{ "ok": true }

GET /api/v1/lens/portfolio

Aggregate Lens metrics across all of a customer's monitored sites. Requires Business or Agency plan.

curl "https://agenticcom.ai/api/v1/lens/portfolio?period=7d" \
  -H "Authorization: Bearer $COLTER_API_KEY"

Param	Type	Required	Description
`period`	string	No	`1d`, `7d`, or `30d` (default: `7d`).

Response shape:

customer_id, period
sites array — per-site: site_id, url, status, total_events, unique_agents, composite_score, protocols_detected, deepest_stage_mode, session_count, open_alerts, events_delta_pct, revenue_cents
aggregate — total_sites, active_sites, total_events, avg_composite_score, total_open_alerts, total_sessions, total_revenue_cents

POST /api/v1/lens/revenue

Record a revenue event for a Lens site (edge-detected or merchant-provided).

curl -X POST https://agenticcom.ai/api/v1/lens/revenue \
  -H "Authorization: Bearer $COLTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "site_id": "site_123",
    "session_id": "sess_123",
    "order_id": "order_123",
    "currency": "USD",
    "amount_cents": 31900,
    "items_count": 3
  }'

Field	Type	Required	Description
`site_id`	string	Yes	Lens site ID.
`session_id`	string	No	Agent session ID for direct attribution.
`order_id`	string	Yes	Merchant order identifier.
`currency`	string	Yes	ISO currency code (for example `USD`).
`amount_cents`	number	Yes	Order value in cents.
`items_count`	number	No	Number of purchased items.

Response includes detected attribution_type (direct, assisted, or influenced).

GET /api/v1/lens/revenue

Return revenue attribution analytics for a monitored site.

curl "https://agenticcom.ai/api/v1/lens/revenue?site_id=site_123&period=7d" \
  -H "Authorization: Bearer $COLTER_API_KEY"

Param	Type	Required	Description
`site_id`	string	Yes	Lens site ID to query.
`period`	string	No	`1d`, `7d`, or `30d` (default: `7d`).

Response shape:

total_revenue_cents, total_orders
agent_attributed (direct, assisted, influenced)
by_agent (revenue/order breakdown per agent + attribution type)
conversion_funnel (visits -> cart -> checkout -> purchase)
comparison (previous_revenue_cents, delta_pct)

POST /api/v1/lens/revenue-webhook

Merchant order-completion webhook for backfilling accurate payment amounts.

curl -X POST https://agenticcom.ai/api/v1/lens/revenue-webhook \
  -H "Authorization: Bearer $COLTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "site_id": "site_123",
    "order_id": "order_123",
    "currency": "USD",
    "amount_cents": 31900,
    "items_count": 3,
    "session_id": "sess_123"
  }'

Field	Type	Required	Description
`site_id`	string	Yes	Lens site ID.
`order_id`	string	Yes	Merchant order identifier.
`currency`	string	Yes	ISO currency code.
`amount_cents`	number	Yes	Order value in cents.
`items_count`	number	No	Number of items purchased.
`session_id`	string	No	Session correlation hint.
`referrer`	string	No	Optional referrer hint.

GET /api/v1/lens/stream

Open a Server-Sent Events stream for live traffic and alert updates.

curl -N "https://agenticcom.ai/api/v1/lens/stream?site_id=site_123" \
  -H "Authorization: Bearer $COLTER_API_KEY"

Param	Type	Required	Description
`site_id`	string	Yes	Lens site ID to stream.

SSE event types:

traffic — agent request event updates
alert — new alert notifications
heartbeat — connection keepalive

GET /api/v1/lens/export

Export Lens analytics data as CSV, JSON, or PDF. CSV/JSON requires Pro+ plan; PDF requires Business+ plan.

curl "https://agenticcom.ai/api/v1/lens/export?site_id=site_123&type=traffic&period=7d&format=csv" \
  -H "Authorization: Bearer $COLTER_API_KEY" -o lens-traffic.csv

Param	Type	Required	Description
`site_id`	string	Yes	Lens site ID (not required for `type=portfolio`).
`type`	string	No	Export type: `traffic`, `events`, `sessions`, `protocols`, `portfolio` (default: `traffic`).
`period`	string	No	`1d`, `7d`, or `30d` (default: `7d`).
`format`	string	No	`csv`, `json`, or `pdf` (default: `csv`).

Export types:

traffic — daily aggregates: date, total_events, unique_agents, avg_response_ms, top_agent
events — raw event rows (capped at 10,000): timestamp, agent_name, method, path, status_code
sessions — session rows: started_at, agent_name, duration_ms, event_count, deepest_stage, outcome
protocols — health snapshots: checked_at, composite_score, protocol detection flags
portfolio — one row per site (requires portfolio_enabled)

PDF format returns application/pdf with Content-Disposition: attachment.

POST /api/v1/lens/ingest-logs

Ingest server access logs for non-Cloudflare merchants.

curl -X POST https://agenticcom.ai/api/v1/lens/ingest-logs \
  -H "Authorization: Bearer $COLTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"site_id":"site_123","format":"combined","logs":"93.184.216.34 - - [10/Oct/2025:13:55:36 -0700] \"GET /products/widget HTTP/1.1\" 200 2326 \"https://example.com/\" \"ChatGPT-User/1.0\""}'

Field	Type	Required	Description
`site_id`	string	Yes	Lens site ID.
`format`	string	No	`clf`, `combined`, `json`, or `auto` (default: `auto`).
`logs`	string	Yes	Raw log text, one entry per line. Max 10,000 lines.

Response shape:

processed
agents_found
skipped_human
errors

GET /api/v1/lens/benchmarks

Return anonymized category benchmarks against the selected merchant site.

curl "https://agenticcom.ai/api/v1/lens/benchmarks?site_id=site_123&period=7d" \
  -H "Authorization: Bearer $COLTER_API_KEY"

Param	Type	Required	Description
`site_id`	string	Yes	Lens site ID to benchmark.
`period`	string	No	`1d`, `7d`, or `30d` (default: `7d`).

Response shape:

merchant (events, unique agents, composite score)
category (anonymized averages, medians, top agents, protocol adoption)
percentile (merchant ranking by events and score)

GET /api/v1/lens/alert-rules

List configured alert rules for a site.

curl "https://agenticcom.ai/api/v1/lens/alert-rules?site_id=site_123" \
  -H "Authorization: Bearer $COLTER_API_KEY"

Param	Type	Required	Description
`site_id`	string	Yes	Lens site ID.

POST /api/v1/lens/alert-rules

Create a custom alert rule.

curl -X POST https://agenticcom.ai/api/v1/lens/alert-rules \
  -H "Authorization: Bearer $COLTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "site_id": "site_123",
    "name": "Traffic spike",
    "rule_type": "traffic_spike",
    "condition": {
      "metric": "total_events",
      "operator": "change_pct_above",
      "threshold": 200,
      "window_minutes": 60,
      "baseline_period": "7d"
    },
    "severity": "warning",
    "notify_channels": ["email","slack"],
    "slack_webhook_url": "https://hooks.slack.com/services/XXX/YYY/ZZZ"
  }'

Rule types:

traffic_spike
traffic_drop
protocol_down
new_agent
revenue_change
funnel_drop

PUT /api/v1/lens/alert-rules/:id

Update an alert rule in place.

DELETE /api/v1/lens/alert-rules/:id

Delete an alert rule.

POST /api/v1/lens/evaluate-alerts

Cron endpoint that evaluates enabled alert rules and creates alerts.

curl -X POST "https://agenticcom.ai/api/v1/lens/evaluate-alerts?limit=50&cursor=0" \
  -H "Authorization: Bearer $CRON_SECRET"

Notes:

Run hourly.
Supports pagination via limit (max 50) + cursor.
Applies cooldown + dedup checks before creating new alerts.

POST /api/v1/lens/digest

Cron endpoint for digest emails.

curl -X POST "https://agenticcom.ai/api/v1/lens/digest?kind=daily" \
  -H "Authorization: Bearer $CRON_SECRET"

kind values: daily or weekly.

GET /api/v1/lens/segments

List saved segments for site scope or portfolio scope.

curl "https://agenticcom.ai/api/v1/lens/segments?site_id=site_123" \
  -H "Authorization: Bearer $COLTER_API_KEY"

When site_id is omitted, returns portfolio-level segments (site_id = null).

POST /api/v1/lens/segments

Create a segment from a filter set.

curl -X POST https://agenticcom.ai/api/v1/lens/segments \
  -H "Authorization: Bearer $COLTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "site_id": "site_123",
    "name": "AI assistants · 7d",
    "filters": {
      "agentFilter": "ai_assistant",
      "period": "7d",
      "minStage": "cart",
      "pathPrefix": "/products"
    },
    "is_default": true
  }'

PUT /api/v1/lens/segments/:id

Update a saved segment.

DELETE /api/v1/lens/segments/:id

Delete a saved segment.

POST /api/v1/lens/segments/:id/apply

Mark a segment as default in its scope.

GET /api/v1/lens/paths

Read aggregated URL path analytics.

curl "https://agenticcom.ai/api/v1/lens/paths?site_id=site_123&period=7d" \
  -H "Authorization: Bearer $COLTER_API_KEY"

Response includes:

paths (flat list with visits, agents, stage, revenue, top agents)
tree (hierarchical path tree for treemap rendering)

POST /api/v1/lens/aggregate-paths

Cron endpoint to aggregate raw agent_events into lens_path_analytics.

curl -X POST https://agenticcom.ai/api/v1/lens/aggregate-paths \
  -H "Authorization: Bearer $CRON_SECRET"

GET /api/v1/shopify/auth

Validate Shopify embedded session token and exchange for offline token.

curl "https://agenticcom.ai/api/v1/shopify/auth" \
  -H "Authorization: Bearer <shopify-session-token>"

Returns linked shop, site_id, and customer_id.

GET /api/v1/shopify/callback

Compatibility redirect endpoint for install callback flows.

POST /api/v1/shopify/webhooks

Handle Shopify compliance + analytics webhooks.

Supported topics include:

Compliance: APP_UNINSTALLED, SHOP_UPDATE, CUSTOMERS_DATA_REQUEST, CUSTOMERS_REDACT, SHOP_REDACT
Analytics: ORDERS_CREATE, ORDERS_PAID, CHECKOUTS_CREATE, CHECKOUTS_UPDATE, PRODUCTS_CREATE, PRODUCTS_UPDATE, CARTS_CREATE, CARTS_UPDATE

HMAC is verified with X-Shopify-Hmac-Sha256 using SHOPIFY_API_SECRET.

CLI Reference

Global Options

These options are available on all commands:

colter [command] [options]

Global Options:
  -c, --config <path>   Path to config file (default: ./colter.yaml)
  -h, --help            Show help
  -v, --version         Show version

Many commands also accept -v (verbose) and --json flags; see each command's options for details.

colter auth

Authenticate the CLI. Manages credentials for the Colter API.

colter auth <subcommand>

Subcommands:
  login       Authenticate with browser-based device flow
  logout      Remove saved local credentials
  status      Show current authentication state
  token       Print current API key

Options:
  --api-base <url>      Auth API base URL (default: https://agenticcom.ai)

Examples:
  colter auth login
  colter auth status
  colter auth token
  colter auth logout

colter check

Quick agent-readiness diagnostic. Read-only, safe on production stores.

colter check <url> [options]

Arguments:
  url                Store URL to check

Options:
  -v, --verbose         Show detailed output
  --json                Output as JSON
  --api-url <url>       Override the Colter API base URL (default: https://agenticcom.ai)
  --batch <file>        YAML file with list of store URLs to check
  --concurrency <n>     Max concurrent checks for batch mode (default 5)
  --then-test           After check completes, automatically run AI persona tests
  --ci                  CI gate mode — exit non-zero if score is below threshold
  --threshold <n>       Minimum passing score for --ci mode (default 60)

Examples:
  colter check example-store.com
  colter check https://example-store.com --json
  colter check example-store.com -v
  colter check --batch stores.yaml
  colter check example-store.com --then-test
  colter check example-store.com --ci --threshold 70

The --json output mirrors the cloud API response and can be pointed at a self-hosted backend with --api-url. See Scoring Model for details on the agentic commerce level.

colter verify

Full conformance verification with Evidence Pack generation.

colter verify <target> [options]

Arguments:
  target             Store URL to verify

Options:
  --out <dir>              Output directory for Evidence Pack
  --protocols <p>          Test specific protocols (comma-separated, e.g. ucp,acp)
  --schema-acp <path>      Override ACP schema URL or file path
  --schema-ucp <path>      Override UCP schema URL or file path
  --tests <dirs>           Directories containing custom YAML test definitions
  --api-url <url>          Override the Colter API base URL used for readiness
  --batch <file>           YAML file with list of store URLs to verify
  --concurrency <n>        Max concurrent verifications for batch mode (default 5)
  --json                   Output as JSON
  -v                       Show URLs being probed

Examples:
  colter verify example-store.com
  colter verify example-store.com --out ./evidence/
  colter verify example-store.com --json > result.json
  colter verify example-store.com --protocols=acp

Returns exit code 0 on pass, 1 on fail. Suitable for CI/CD pipelines.

colter pack

Create an Evidence Pack from a target.

colter pack <target> [options]

Arguments:
  target             Store URL to pack

Options:
  --out <dir>            Output directory
  --schema-acp <path>    Override ACP schema URL or file path
  --schema-ucp <path>    Override UCP schema URL or file path

Examples:
  colter pack example-store.com
  colter pack example-store.com --out ./evidence/

colter replay

Deterministic replay from an Evidence Pack.

colter replay <pack-path> [options]

Arguments:
  pack-path          Path to Evidence Pack directory

Options:
  --live             Replay against live target (default for localhost)
  -v, --verbose      Show all assertions (not just failures)
  --json             Output as JSON

Examples:
  colter replay ./evidence/
  colter replay ./evidence/ --live

colter diff

Compare two Evidence Packs.

colter diff <pack-a> <pack-b> [options]

Arguments:
  pack-a             Path to first Evidence Pack directory
  pack-b             Path to second Evidence Pack directory

Options:
  --json             Output as JSON

Examples:
  colter diff ./evidence/pack-before/ ./evidence/pack-after/
  colter diff ./pack-a/ ./pack-b/ --json

colter scout

Auto-detect store platform and generate configuration.

colter scout <url> [options]

Arguments:
  url                Store URL to scan

Options:
  --format <fmt>     Output format: text, json, or yaml (default: text)
  --output <file>    Write output to file

Examples:
  colter scout example-store.com
  colter scout example-store.com --format json

colter batch

Run agent-readiness checks against a list of store URLs. Accepts a text file (one URL per line, # for comments) or a YAML file with a stores key.

colter batch <file> [options]

Arguments:
  file               Text or YAML file containing store URLs

Options:
  -n, --concurrency <n>   Max concurrent checks (default 10)
  -f, --format <fmt>      Output format: json or csv (default: json)
  --api-url <url>         Override the Colter API base URL (default: https://agenticcom.ai)
  -o, --output <file>     Write results to file

Examples:
  colter batch stores.txt
  colter batch stores.txt --concurrency 10 --output results.json
  colter batch stores.txt --format csv --output results.csv

colter export

Export an Evidence Pack as HTML, JSON, or PDF.

colter export <pack-path> [options]

Arguments:
  pack-path          Path to Evidence Pack

Options:
  --format <fmt>     Export format: html, json, pdf, or auto (default: auto)
  -o, --output <file>  Output file path (default: stdout)

Examples:
  colter export ./evidence/ --format pdf -o report.pdf
  colter export ./evidence/ --format html -o report.html

colter fix

Analyze a store's agent readiness and generate a fix plan with actionable improvements.

By default, shows a plan with descriptions and score impacts. Use --apply to generate content and write fix files. Use --dry-run to generate content without writing files.

colter fix <url> [options]

Arguments:
  url                Store URL to analyze

Options:
  --apply               Apply fixes to files
  --dry-run             Generate content but don't write files
  --evidence            Generate evidence pack after apply
  --format <fmt>        Output format: json or liquid (default: json)
  --api-url <url>       Override the Colter API base URL (default: https://agenticcom.ai)
  --json                Output as JSON
  --output-dir <dir>    Directory for output files (default: ./colter-fixes)
  --platform <name>     Target platform: file, shopify, or rest
  --test-json <file>    Load a saved test run JSON (skips live check, enriches DEPLOY.md with test evidence)
  -v, --verbose         Show verbose output

Examples:
  colter fix example-store.com
  colter fix example-store.com --apply --output-dir ./fixes/
  colter fix example-store.com --dry-run --json
  colter fix example-store.com --apply --evidence
  colter fix example-store.com --platform shopify --apply
  colter fix example-store.com --dry-run --verbose --format liquid

The fix plan identifies missing structured data, blocked AI crawlers, and other issues that reduce your agent-readiness score. Each operation includes a description, expected score impact, and risk level (apply for auto-fixable, manual for merchant action required).

colter test

Run AI persona tests against a store using real LLM calls (Claude, GPT, Gemini). Each persona runs through multiple scenarios and scores how well the store serves agentic commerce queries.

Requires authentication with a Pro plan or higher (colter auth login).

colter test <url> [options]

Arguments:
  url                Store URL to test

Options:
  --api-url <url>       Override the Colter API base URL (default: https://agenticcom.ai)
  --models <list>       Comma-separated model list: claude,gpt,gemini (default: all 3 models)
  --personas <list>     Comma-separated persona IDs to run (default: all)
  --scenarios <list>    Comma-separated scenario IDs to run (default: all)
  --json                Output as JSON
  --parallel <n>        Max concurrent persona tests (default: 3)
  --timeout <dur>       Per-test timeout (default: 60s)
  --budget <amount>     Max spend in USD (default: 1.00)
  --threshold <n>       Minimum passing score (exit 1 if below, default: 60)
  --fix                 Run colter fix planning after test for dimensions below threshold
  --fix-threshold <n>   Dimension score cutoff used with --fix (default: 70)
  --apply               Apply fixes after test when used with --fix
  --dry-run             Generate fix content without writing when used with --fix
  --skip-check          Skip the pre-check store analysis phase
  --check-json <path>   Load pre-computed check.Result from a JSON file
  --pdf                 Generate a PDF report of test results
  --pdf-out <path>      Output path for the PDF report (default: ./colter-test-<run-id>.pdf)
  --upload              Upload test results to the Colter dashboard
  --improvement-dir <path>  Directory for persistent continuous-improvement memory (default: .cache/test-improvement)
  --no-improvement-memory   Disable persistence of continuous-improvement memory
  --headed              Show browser window for debugging (default: headless)
  --browser             Run browser-based test using Chrome DevTools MCP (requires WebMCP tools)

  # Internal/dev flags (not customer-facing):
  # --local               Use local API keys instead of Colter-managed auth
  # --smoke               Run smoke test against 3 default stores (Shopify, WooCommerce, custom)

Examples:
  colter test https://mystore.com
  colter test https://mystore.com --models claude,gemini
  colter test https://mystore.com --personas gemini_shopper,browser_shopper --json
  colter test https://mystore.com --budget 0.50 --parallel 5
  colter test https://mystore.com --threshold 70 --json
  colter test https://mystore.com --fix --fix-threshold 75
  colter test https://mystore.com --skip-check --check-json check-result.json
  colter test https://mystore.com --pdf --pdf-out ./reports/test-report.pdf
  colter test https://mystore.com --upload
  colter test https://mystore.com --headed --personas browser_shopper
  colter test https://mystore.com --browser

colter lens

colter lens <url> [options]

Arguments:
  url                Store URL to monitor

Options:
  --json                Output as JSON
  --api-base <url>      Lens API base URL (default: https://agenticcom.ai)
  --api-key <key>       Lens API key (Bearer token)

Examples:
  colter lens https://mystore.com
  colter lens mystore.com --json
  colter lens status --site-id <site-id>
  colter lens status --url https://mystore.com --period 7d
  colter lens report --site-id <site-id> --period 7d
  colter lens deploy --url https://mystore.com --cf-account-id <id> --cf-api-token <token>
  colter lens alerts --site-id <site-id> --status open
  colter lens protocols --site-id <site-id>

Lens subcommands:

colter lens status [options]

Options:
  --site-id <id>        Lens site ID to inspect
  --url <url>           Store URL to resolve site ID
  --period <window>     report period: 24h, 7d, or 30d
  --json                Output as JSON
  --api-base <url>      Lens API base URL
  --api-key <key>       Lens API key (Bearer token)

colter lens deploy [options]

Options:
  --url <url>              Store URL to register and deploy
  --site-id <id>           Lens site ID (skip registration)
  --cf-account-id <id>     Cloudflare account ID (or set CF_ACCOUNT_ID)
  --cf-api-token <token>   Cloudflare API token (or set CF_API_TOKEN)
  --json                   Output as JSON
  --api-base <url>         Lens API base URL
  --api-key <key>          Lens API key (Bearer token)

colter lens alerts [options]

Options:
  --site-id <id>        Lens site ID
  --url <url>           Store URL to resolve site ID
  --status <state>      open, acknowledged, or resolved
  --json                Output as JSON
  --api-base <url>      Lens API base URL
  --api-key <key>       Lens API key (Bearer token)

colter lens protocols [options]

Options:
  --site-id <id>        Lens site ID
  --url <url>           Store URL to resolve site ID
  --json                Output as JSON
  --api-base <url>      Lens API base URL
  --api-key <key>       Lens API key (Bearer token)

colter lens report [options]

Options:
  --site-id <id>        Lens site ID
  --url <url>           Store URL to resolve site ID
  --period <window>     report period: 1d, 7d, or 30d
  --json                Output as JSON
  --api-base <url>      Lens API base URL
  --api-key <key>       Lens API key (Bearer token)

colter lens export [options]

Options:
  --site-id <id>        Lens site ID
  --url <url>           Store URL to resolve site ID
  --type <type>         Export type: traffic, events, sessions, protocols, portfolio
  --period <window>     Report period: 1d, 7d, or 30d
  --format <fmt>        Output format: csv, json, pdf
  --out <path>          Output file path (required for PDF; stdout if omitted)
  --api-base <url>      Lens API base URL
  --api-key <key>       Lens API key (Bearer token)

SDK Lens Methods

The Node SDK exposes authenticated Lens helpers:

import { ColterClient } from "@getcolter/sdk";

const client = new ColterClient({
  baseUrl: "https://agenticcom.ai",
  apiKey: process.env.COLTER_API_KEY,
});

await client.lensTraffic({ siteId: "site_123", period: "7d" });
await client.lensAlerts({ siteId: "site_123", status: "open" });
await client.lensProtocols({ siteId: "site_123", limit: 24 });
await client.lensJourneys({ siteId: "site_123", period: "7d" });
await client.lensPortfolio({ period: "7d" });

colter serve

Start the HTTP + MCP server for local development and web deployments.

colter serve [options]

Options:
  --port <n>         Port to listen on (default: 3000)
  --http-only        HTTP server only (no MCP)
  --mcp-only         MCP server only (stdio, for Claude Desktop)
  --admin-tools      Enable admin MCP tools (configure, scout, validate, info)

Examples:
  colter serve
  colter serve --port 8080
  colter serve --http-only

colter mcp

Start the MCP (Model Context Protocol) server over stdio.

colter mcp [options]

Options:
  --admin-tools      Enable admin tools (scout, configure, etc.)

Examples:
  colter mcp
  colter mcp --admin-tools

The MCP server uses stdio transport (JSON-RPC over stdin/stdout). Use this for Claude Desktop integration.

MCP Tools Reference

When using Colter as an MCP server (colter mcp), these tools are available to AI agents.

Check, Test & Fix Tools

Tool	Description
`colter.check`	Run agent-readiness check (same as `colter check --json`)
`colter.test`	Run AI persona tests against a store using real LLM calls
`colter.fix`	Generate a fix plan and optionally apply fixes (plan-only by default, apply with `apply: true`)
`colter.lens`	Query Lens monitoring data (`status`, `traffic`, `alerts`, `protocols`, `report`)

Verification & Evidence Tools

Tool	Description
`colter.verify.run`	Full readiness + conformance test with Evidence Pack generation
`colter.verify.readiness`	Readiness-only scan (faster, no conformance tests)
`colter.verify.report`	Render human-readable summary from an Evidence Pack
`colter.verify.diff`	Compare two Evidence Packs and show regressions/improvements
`colter.replay.run`	Deterministic replay of an Evidence Pack against a live or local target
`colter.pack.create`	Create a new Evidence Pack with readiness data
`colter.packs.list`	List Evidence Packs in a directory

Agent Commerce Tools (from Agent Kit)

These tools require a configured backend (colter.yaml) and enable AI agents to perform commerce actions:

Tool	Description
`colter.agent.workflow`	Returns the recommended tool call sequence for a given task
`colter.agent.discover`	Discover a store's capabilities and supported protocols
`colter.agent.products.search`	Search for products in a connected store
`colter.agent.cart.create`	Create a shopping cart
`colter.agent.cart.add`	Add items to cart
`colter.agent.cart.quote`	Get price quote for cart contents
`colter.agent.checkout.initiate`	Start checkout process
`colter.agent.checkout.complete`	Finalize purchase
`colter.agent.receipt.get`	Get receipt for a completed order

Admin Tools

Requires the --admin-tools flag when starting the MCP server. Gated behind the flag to prevent accidental configuration changes.

Tool	Description
`colter.scout`	Auto-discover store platform, generate config
`colter.configure`	Update Colter configuration
`colter.config.get`	Read current config values
`colter.config.schema`	List valid config keys and types
`colter.validate`	Validate config completeness
`colter.info`	Version, runtime, diagnostics

Claude Desktop Setup

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "colter": {
      "command": "colter",
      "args": ["mcp", "--admin-tools"]
    }
  }
}

Configuration

Config File

Default location: ./colter.yaml (override with --config <path>)

# colter.yaml
version: "1"

store:
  name: "My Store"
  url: "https://your-store.com"

backend:
  type: rest          # rest | shopify | protocol
  rest:
    base_url: "https://api.your-store.com"
    auth:
      type: bearer
      token: ""
    endpoints:
      products: "/api/products"
      product: "/api/products/{id}"

protocols:
  ucp:
    enabled: true
    capabilities: ["checkout"]
  acp:
    enabled: true

See colter.yaml.example in the repository for the complete configuration reference including Shopify backend, PSP, server, and storage settings.

Error Codes

Structured error codes returned by CLI and MCP tools:

Code	Description	Recovery
`CART_NOT_FOUND`	Cart ID is invalid or does not exist.	Create a new cart with `colter.agent.cart.create`.
`CART_EXPIRED`	Cart session has timed out.	Create a new cart and re-add items.
`CHECKOUT_NOT_FOUND`	Checkout ID is invalid.	Initiate a new checkout with `colter.agent.checkout.initiate`.
`BACKEND_NOT_CONFIGURED`	No store backend configured.	Run `colter scout <url>` to auto-detect.
`URL_UNREACHABLE`	Target URL could not be reached.	Verify the URL is correct and includes `https://`.
`STORE_UNREACHABLE`	Store backend is not responding.	Confirm the store is online and retry.
`RATE_LIMITED`	Too many requests.	Wait and retry after a delay.
`VALIDATION_FAILED`	Input validation failed.	Check required fields and format.

Next Steps

Getting Started — Installation and quick start
Agent Kit — Build AI shopping agents
Verify — Test store compatibility
Fix — Generate the infrastructure described in this reference
Evidence Packs — Understand the proof format

API Reference

Overview

Public API

POST /api/v1/check

Response Schema

protocols

store

coverage

web_signals

plain_language

next_step

Error Responses

POST /api/v1/fix

GET /api/v1/results/:id

GET /api/v1/results/:id/pdf

Share Links (revocable + expiring)

Test Run Endpoints

POST /api/v1/test-runs

GET /api/v1/test-runs

GET /api/v1/test-runs/compare

GET /api/v1/test-runs/export

Lens Monitoring Endpoints (Authenticated)

GET /api/v1/lens/traffic

GET /api/v1/lens/journeys

GET /api/v1/lens/protocols

GET /api/v1/lens/alerts

PATCH /api/v1/lens/alerts

GET /api/v1/lens/portfolio

POST /api/v1/lens/revenue

GET /api/v1/lens/revenue

POST /api/v1/lens/revenue-webhook

GET /api/v1/lens/stream

GET /api/v1/lens/export

POST /api/v1/lens/ingest-logs

GET /api/v1/lens/benchmarks

GET /api/v1/lens/alert-rules

POST /api/v1/lens/alert-rules

PUT /api/v1/lens/alert-rules/:id

DELETE /api/v1/lens/alert-rules/:id

POST /api/v1/lens/evaluate-alerts

POST /api/v1/lens/digest

GET /api/v1/lens/segments

POST /api/v1/lens/segments

PUT /api/v1/lens/segments/:id

DELETE /api/v1/lens/segments/:id

POST /api/v1/lens/segments/:id/apply

GET /api/v1/lens/paths

POST /api/v1/lens/aggregate-paths

GET /api/v1/shopify/auth

GET /api/v1/shopify/callback

POST /api/v1/shopify/webhooks

CLI Reference

Global Options

colter auth

colter check

colter verify

colter pack

colter replay

colter diff

colter scout

colter batch

colter export

colter fix

colter test

colter lens

SDK Lens Methods

colter serve

colter mcp

MCP Tools Reference

Check, Test & Fix Tools

Verification & Evidence Tools

Agent Commerce Tools (from Agent Kit)

Admin Tools

Claude Desktop Setup

Configuration

Config File

Error Codes

Next Steps