Developers

Every machine surface AgentCapable has, on one page. No API keys anywhere: scans require a contact name and email in the request body, the same policy as the web form, and everything else is open reads (the machine-readable surfaces are CORS-enabled).

Scan API

One POST runs the same fresh dual-vantage scan the site runs. The response is the full report as JSON: headline verdict, 0-100 readability score with per-category breakdown, confidence, the per-agent access matrix with raw HTTP statuses from both networks, every scored check, and, when the report is archived, its permalink (ephemeral tunnel scans are never archived).

curl -X POST https://agentcapable.dev/scan \
  -H 'content-type: application/json' \
  -d '{"domain":"yourdomain.com",
       "lead":{"name":"Your Name","email":"you@yourdomain.com"}}'

Results are tri-state. unknown and inconclusive mean our vantages could not measure something and are never evidence against a site. Optional fields: "profile" pins the rubric profile (general, dev-platform, docs, publisher), "fresh": true forces past the double-submit window. Rate limits: one scan per domain per minute with a small burst, plus per-caller caps; a 429 says how long to wait.

OpenAPI specification

The whole API is specified in OpenAPI 3.1, validated in CI: /openapi.json (also served at /.well-known/openapi.json and /swagger.json). It covers the scan endpoint, the check catalog, report permalinks, the CLI vantage upload, and the badge.

Check catalog

The scored rubric is public and machine-readable: every check with its stable id, category, frozen weight, why it matters, and fix guidance. Current rubric: rubric-v1.1. Ids are stable across rubric versions, so CI can gate on a specific check regressing.

curl https://agentcapable.dev/api/checks

MCP server

Any MCP client can scan a site mid-conversation. Endpoint: POST https://agentcapable.dev/mcp (stateless streamable HTTP, JSON responses; a GET with Accept: text/event-stream opens a compatibility SSE stream). Discovery manifest: /.well-known/mcp.json. Server version 1.0.0, tools:

• scan_site: run a live scan (contact name and email are tool parameters, the same policy as every scan surface)
• get_report: fetch an archived scan by id
• list_checks: the scored-check catalog

CLI

npx agentcapable runs the hosted scan and then re-runs the same probe grid from your own network, merging that third vantage into the same report URL as clearly labeled, self-reported evidence. That is the view a hosted scanner alone cannot capture: how the same probes behave from a user network. The hosted verdict and score stay frozen; the extra vantage is recorded alongside them. Roster roster-v1.0, same frozen rubric.

npx agentcapable scan yourdomain.com \
  --name "Your Name" --email you@yourdomain.com --min-score 70

Exit codes are tri-state and CI-safe: 0 scan completed and the --min-score gate (if any) passed, 1 gate failed, 2 could not test. agentcapable scan localhost:3000 runs the readability rubric locally before you deploy; nothing is uploaded. Scans of ephemeral tunnel hosts (ngrok and similar) are never archived or counted.

MCP-server scanning

The scanner also takes an MCP server as the target: POST /scan-mcp with {"target": "example.com/mcp", "lead": {...}} probes the discovery manifest, the initialize handshake, protocol version, tool schemas and descriptions, and JSON-RPC error semantics. The result is a tri-state checklist, deliberately unscored: we publish no weights we cannot yet back. A server that requires credentials is exercising policy, not failing, and "unreachable" always means our vantage could not measure.

Report permalinks and badge

Every archived scan gets a read-only permalink at /r/{scanId} (ephemeral tunnel-host scans are never archived, so they have none). The latest archived scan of a domain renders as an embeddable badge at /badge/{domain}.svg.

Authentication

None. Scanning and reading are open; the only credential in the system is the per-scan CLI upload token a fresh, archived scan response can issue, which authorizes merging that one scan's user-network vantage and nothing else. There is no OAuth, no account, and no user-issued credential to leak. The full story, in the file agents probe for: /auth.md.

Related

• Methodology: roster, verdict rules, and all scored checks with weights, generated from the frozen modules
• agents.md: when and how agents should use this service
• llms.txt: the site's own agent-facing index
• robots.txt recipes for common AI-agent policies

Last updated: 22 August 2026