# API

One JSON endpoint for a scan, two for cached reports, one POST for MCP.

## When to use it

Call /api/scan when you need a fresh score and can wait a few seconds. Read /report/{host}.json when the host was already scanned. Use the MCP endpoint when an agent wants the scan as a tool call.

## Endpoints

| 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, 6-hour TTL |
| GET /report/{host}.md | the same report as Markdown |
| GET /openapi.json | OpenAPI 3.1 with schemas and descriptions |
| GET /last | summary of the most recent scan |
| POST /mcp | JSON-RPC 2.0: initialize, tools/list, tools/call |
| GET /healthz | liveness and cache size |

## Worked example

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

## Authentication and limits

The free endpoint needs no key: one call a day per host, cached six hours. Paid keys go in `Authorization: Bearer <key>`. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. Mutating calls accept Idempotency-Key. Scopes are scan:read and scan:write.

## Errors

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

## Discovery

- [OpenAPI](https://www.agentpass.page/openapi.json)
- [Interface index](https://www.agentpass.page/.well-known/ard.json)
- [MCP card](https://www.agentpass.page/.well-known/mcp.json)
- [auth.md](https://www.agentpass.page/auth.md)