# AgentReady API (agentready.market)

Free, keyless reads. Canonical versioned base: `https://www.agentready.market/api/v1` (unversioned
aliases stay available; breaking changes only ever ship under a new /vN prefix).
Deprecation policy: a deprecated endpoint keeps working >= 6 months and answers
with `Deprecation` + `Sunset` headers (RFC 8594) before removal — nothing is
deprecated today.

## Endpoints
- `GET https://www.agentready.market/api/v1` — discovery document (this list, machine-readable).
- `GET https://www.agentready.market/api/v1/scan?url=<store>&vertical=<vertical>` — run a scan (~30s).
  Returns JSON: score /100, grade, capped, pillars, top_fixes, scan_id,
  report_url, neighbors (2 stores above/below you on the Agent-Ready Index).
- `GET https://www.agentready.market/api/v1/scan/<scan_id>.json` — read a stored report.
- `GET https://www.agentready.market/api/v1/scan/<scan_id>/brief.md` — **agent brief** (Pro Bearer
  key): the full fix job as one markdown file for a coding agent — sequenced
  how-tos, paste-ready artifacts (JSON-LD, llms.txt, attribute map), verify loop.
- `POST https://www.agentready.market/api/v1/reports` — bulk/batch read: latest report for up to 100
  hosts in one request (body `{"hosts": [...]}`, Pro Bearer key).
- `GET https://www.agentready.market/badge/<host>.svg` · `GET https://www.agentready.market/verify/<host>`

## Errors & limits
- Errors are structured JSON: `{"error", "code", "message", "next_action?"}` —
  including unknown /api paths (404, code NOT_FOUND), never an HTML error page.
- Responses carry IETF RateLimit headers; 429 includes Retry-After.
- Anonymous: a few scans/hour. Pro key: 30/hour, 1000/30 days.
- Idempotency: every endpoint is read-only, hence idempotent by construction —
  safe to retry. `POST https://www.agentready.market/api/v1/reports` accepts an `Idempotency-Key`
  header and echoes it back. Auth guide: https://www.agentready.market/auth.md

## MCP server (Streamable HTTP, no auth)
`https://www.agentready.market/mcp` — tools: check_merchant_readiness(host), get_readiness_report(host),
list_agent_ready_stores(vertical?, limit?). Server card:
https://www.agentready.market/.well-known/mcp/server-card.json

## More
OpenAPI 3.1: https://www.agentready.market/openapi.json · auth: https://www.agentready.market/auth.md · llms.txt: https://www.agentready.market/llms.txt ·
human docs: https://www.agentready.market/api