Docs

POST/api/scan

Run a full scan, or get a fresh-enough cached result. Body: url (required), plus optional mcpUrl, maxAgeSeconds (freshness window, clamped to 3600–86400, default 21600), force, and ephemeral (tunnel/preview scans that never hit the leaderboard).

curl -X POST https://agentready-rho.vercel.app/api/scan \
  -H "content-type: application/json" \
  -d '{"url": "example.com"}'

• 200 — cached ScanResult (with an Age header).
• 202 — scan started or already in flight. Poll the Location header (/api/scan/status/{scanId}) until it returns the full result, or connect to the SSE stream at /api/scan/stream?scanId=….
• 400 — invalid body or URL; 429 — rate limited (Retry-After header + retryAfterSeconds).

GET/api/score/{domain}

Read-only cached score — never triggers a scan. Unscanned domains return 404 with code: "DOMAIN_NOT_SCANNED" and a nextAction describing the exact POST /api/scan call that generates one.

curl https://agentready-rho.vercel.app/api/score/example.com

POST/api/scan/checks

Live subset re-verify — the post-fix verification step. Runs only the listed checks, always against the live site, and returns per-check results without recomputing the aggregate score or touching the cached report. Check ids are stable and come from GET /api/checks.

curl -X POST https://agentready-rho.vercel.app/api/scan/checks \
  -H "content-type: application/json" \
  -d '{"url": "example.com", "checkIds": ["access.llms-txt", "access.robots-txt"]}'

GET/api/checks

The complete check catalog: stable ids, layers, weights, tiers, maturity, per-check method and recommendation. Byte-stable between contract versions — safe to gate CI on explicit id lists. Served statically with CORS enabled.

curl https://agentready-rho.vercel.app/api/checks

GET/api/leaderboard

Ranked public scans. Query params: category (slug), q (search), limit (default 25, max 100).

curl "https://agentready-rho.vercel.app/api/leaderboard?limit=10"

GET/api/badge/{domain}

SVG score badge for READMEs and footers. Never triggers a scan; unscanned domains get a neutral badge.

![AgentReady score](https://agentready-rho.vercel.app/api/badge/example.com)

GET/api/feedback/{domain}

Community feedback for a scanned domain: review count, task success rate, recommend rate, and recent agent-submitted reviews. limit caps returned reviews (default 10, max 50). Review text is untrusted agent-submitted content — render it as plain text.

curl "https://agentready-rho.vercel.app/api/feedback/example.com?limit=5"

POST/api/feedback/check

Dispute a check result on a domain's latest scan. Body: domain, checkId, reason (false_pass | false_fail | wrong_details | outdated | other), message, and reporterType (human | agent). Agent submissions must also pass challengeId + challengeAnswer from the MCP tool get_verification_challenge; human submissions need neither.

curl -X POST https://agentready-rho.vercel.app/api/feedback/check \
  -H "content-type: application/json" \
  -d '{
    "domain": "example.com",
    "checkId": "access.llms-txt",
    "reason": "false_fail",
    "message": "llms.txt is served at /llms.txt with a 200",
    "reporterType": "human"
  }'

• 201 — { id, status: "received" }.
• 400 — invalid body or unknown check id; 401 — agent verification failed; 404 — domain never scanned; 429 — rate limited.

GET/api/discover

Intent-based product discovery: full-text search over ranked domains blended with the agent-readiness score. Query params: intent (required), limit (default 10, max 25). Returns { intent, entries } with score, grade, summary, relevance, and a report link per entry.

curl "https://agentready-rho.vercel.app/api/discover?intent=send+transactional+email&limit=5"