API reference

The endpoints, their parameters, and the exact shape of the responses.

All requests go to https://api.canagentsbuyfromyou.com. Bodies are JSON, and so are responses — with one exception, the HTML report.

Authentication

By API key, in the Authorization header, with the Bearer prefix.

Authorization: Bearer ar_live_xxxxxxxxxxxx

The header is optional when creating an audit: without it, the audit runs anonymously, with tighter limits. But if it's present and invalid, the request fails outright — never a silent fallback to anonymous. A revoked key should be visible, not guessed at.

POST /audits

Creates an audit and queues it. Returns 201 without waiting for it to run.

options

general_scan: who actually gets it

Asking for general_scan: true doesn't guarantee it runs. The command line and the playground set it to true for you by default — that's a client-side default, not the API's; a direct call must opt in explicitly. Once requested, eligibility depends on how you're calling:

metadata

Three optional string fields: commit_sha, branch, ci_run_url. They tie an audit to whatever triggered it and show up as-is in the dashboard history. The command line fills them in automatically.

{
  "business": "https://my-store.com",
  "options": { "agent_simulation": true, "language": "en" },
  "metadata": {
    "commit_sha": "a1b2c3d",
    "branch": "main",
    "ci_run_url": "https://github.com/org/repo/actions/runs/42"
  }
}

GET /audits/{id}

The audit's state and, once finished, its full result.

{
  "id": "b3f1e2a0-...",
  "status": "done",
  "result": {
    "business": "https://my-store.com",
    "overall_score": 92,
    "checks": [
      { "check_id": "ucp_discovery", "status": "pass", "score": 100, "recommendation": "..." },
      { "check_id": "catalog_quality", "status": "pass", "score": 95, "recommendation": "..." }
    ],
    "general_readiness": {
      "tier": "agent_ready",
      "n_signals": 6,
      "n_categories": 3,
      "evidence": {
        "continuous_score": 61.4,
        "signals_present": { "llms_txt": 53.3, "content_signals_policy": 5.2, "api_catalog": 3.5 },
        "signals": {
          "llms_txt": { "general_category": "discoverability", "state": "present" },
          "oauth_authorization_server": { "general_category": "api_auth_mcp", "state": "absent" }
        }
      }
    }
  },
  "agent_brief": "# Audit of https://my-store.com\n...",
  "metadata": { "commit_sha": "a1b2c3d", "branch": "main", "ci_run_url": "..." }
}

Each check carries its own status, score and recommendation — actionable text, written to be read by whoever will fix it. The agent_brief field, present only when something still needs fixing, is that same material reshaped into a Markdown instruction you can paste straight into a coding assistant.

general_readiness is null unless general_scan actually ran (see the options table above — it silently degrades, so don't assume it's there just because you asked). evidence.signals has one entry per signal measured — 17 in total, trimmed here to two for readability, each carrying at least general_category and state. Its 4 categories:

GET /audits/{id}/report

The full HTML report, self-contained and shareable. Returns 404 until the audit reaches done.

Read access: anonymous audits and accounts

Generated reports remain available while the member or share link is authorized, even if the site is archived or the subscription ends. To show the Agent Readiness tier publicly, the badge exposes it without the report.

MCP server

The MCP server exposes the four pillars separately: Agent Readiness, Agent Commerce, Agent Performance and Web Findability. The first two create an audit job; the latter two create their specialized run. Every operation is asynchronous and launch tools consume the corresponding quota.

https://api.canagentsbuyfromyou.com/mcp/

Tool names and schemas are negotiated during the MCP handshake. The discovery card is published at /.well-known/mcp-server-card; never pass an API key as a tool argument.

To connect an MCP-compatible AI agent, add this server to the agent's MCP configuration with the endpoint above and a Bearer API key. The agent automatically negotiates the connection, discovers the available tools and chooses the right tool for the user's request. Keep the API key in the agent's secure configuration, never in a prompt or tool arguments. The eight available tools are:

Connect with Codex

Set your key in the terminal environment, then add the server to ~/.codex/config.toml. Codex and its IDE extension share the same configuration:

export CABFY_API_KEY="ar_live_…"
codex mcp list

[mcp_servers.cabfy]
url = "https://api.canagentsbuyfromyou.com/mcp/"
bearer_token_env_var = "CABFY_API_KEY"

Connect with Claude Code

Set CABFY_API_KEY in your environment, then add this server to the .mcp.json file at the project root. The variable is resolved when the connection starts, so the key must not be committed:

export CABFY_API_KEY="ar_live_…"
claude mcp list

{
  "mcpServers": {
    "cabfy": {
      "type": "http",
      "url": "https://api.canagentsbuyfromyou.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${CABFY_API_KEY}"
      }
    }
  }
}

In Claude Code, then use /mcp to verify the connection. For a personal configuration available across projects, add the server with claude mcp add --transport http --scope user and keep the key in your secret manager.

Launch tools are asynchronous. For Agent Readiness and Agent Commerce, pass only business, for example:

{
  "business": "https://my-store.com"
}

The server first returns an ID with pending status. Then call get_agent_audit_result with that ID until the status is done. Agent Performance and Web Findability require an existing Agent Readiness or Agent Commerce audit for the domain. Quotas and the active-site limit are enforced server-side, so a new URL may be rejected when the account has reached its site limit.

Account endpoints

The /account/* endpoints (profile, usage, keys, badges) exist. Profile and usage also accept an API key; account-management operations remain restricted to a dashboard session.

Machine-readable spec

A curated OpenAPI 3.1 description of these public endpoints is served at https://canagentsbuyfromyou.com/openapi.json, and referenced from https://canagentsbuyfromyou.com/.well-known/api-catalog as an RFC 9727 link set. It covers only what this page documents — audit creation, the two read endpoints, the health check and the public stats — and never the application's internal routes.

curl -sS https://canagentsbuyfromyou.com/openapi.json | jq '.paths | keys'

The authentication scheme itself — the Bearer key, the four error codes reachable with one, and pointers back to both resources above — is described at https://canagentsbuyfromyou.com/auth.md, in the plain-Markdown format an agent can read directly.