API

One JSON endpoint for a scan, two for cached reports, one POST for MCP. Nothing to install and nothing to render.

By Scott Scheferman · Updated November 9, 2026 · ARI-100 v1.0

When to use it

Call /api/scan when you need a fresh score for a URL and can wait a few seconds. Read /report/{host}.json when you already scanned the host and want the cached report for free. Use the MCP endpoint when an agent is doing the work and wants the scan as a tool call rather than an HTTP fetch.

Endpoints

All endpoints are GET except checkout and MCP. Responses are JSON unless stated.

Method and path	Returns
GET /api/scan?url=	Full ARI-100 report, fresh or cached. refresh=1 forces a new scan.
GET /report/{host}.json	Cached report JSON for a host, 6-hour TTL.
GET /report/{host}.md	The same report as Markdown, text/markdown.
GET /openapi.json	OpenAPI 3.1 description with schemas and descriptions.
GET /last	Summary of the most recent scan in this process.
POST /mcp	JSON-RPC 2.0: initialize, tools/list, tools/call.
GET /healthz	Liveness and cache size.

Worked example

curl -s "https://agentpass.dev/api/scan?url=https://example.com" \
  -H "Accept: application/json"

Response, trimmed to the top-level keys:

{
  "url": "https://example.com",
  "finalUrl": "https://example.com/",
  "score": 78,
  "grade": "B",
  "level": 3,
  "accessScore": 91,
  "a11yScore": 86,
  "domains": [{ "id": "access", "weight": 20, "score": 88.6 }],
  "crawlers": [{ "ua": "OAI-SearchBot", "verdict": "allowed" }],
  "fixes": [{ "id": "md-negotiation", "weight": 3, "recoverable": 3 }]
}

Authentication and limits

The free endpoint needs no key: one call a day per host, cached for six hours. Paid keys go in Authorization: Bearer <key> and raise the limit to 60 requests a minute. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset.

Mutating calls accept an Idempotency-Key header; replaying a key returns the original result rather than starting a second scan. Access tokens follow the scopes scan:read and scan:write described in the RFC 8414 metadata.

Errors

Errors are JSON with a stable shape, so an agent can branch on status without parsing prose.

{ "type": "https://agentpass.dev/errors/invalid-url",
  "title": "Invalid URL", "status": 400,
  "detail": "url must be an absolute http or https URL" }

MCP

POST JSON-RPC 2.0 to /mcp. Two tools: scan_site takes { "url": "https://example.com" } and get_report takes { "host": "example.com" }. The server answers initialize with protocol 2025-06-18, capabilities.tools and its server info, then serves both tools as plain JSON.

curl -s https://agentpass.dev/mcp -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Discovery

The full set of machine surfaces is indexed at /.well-known/ard.json and described in openapi.json. A coding agent should read AGENTS.md first; it has the install, the config and a worked request.