# Agent Ready

> Agent Ready is a free tool that scores any website against the Vercel Agent Readability Spec, the llmstxt.org specification, and agent-protocol specs (MCP, A2A, agents.json, agent-permissions.json). It runs 72 checks — plus a separate accessibility sub-score from 23 WCAG 2.2 / layout-stability checks — and provides actionable fix guidance for every failing check.

This is the full context file — scoring logic, all 72 check definitions, the public API, and tier limits. For a compact link index, fetch [/llms.txt](https://agent-ready.dev/llms.txt).

Agent Ready checks three areas of agent readability:

- Discovery — Can AI agents find your pages? (llms.txt, sitemaps, robots.txt)
- Structure — Can agents parse your pages? (meta tags, headings, structured data, markdown mirrors)
- Context — Can agents understand your content? (skill files, content negotiation, code documentation)

Last updated: 2026-05-31. Spec compatibility: Vercel Agent Readability Spec · llmstxt.org · MCP 2025-11-25 (SEP-1649) · A2A v1.0.0 · Wildcard agents.json v0.1.0 · agent-permissions.json.

## Recommended Starting Pages

New to agent readability? Start here:

- [The complete guide to agent readability](https://agent-ready.dev/complete-guide-to-agent-readability): the hub guide — how agents discover, parse, and cite your site
- [Methodology](https://agent-ready.dev/methodology): how the 0–100 score is computed across all 72 checks
- [MCP vs A2A vs agents.json](https://agent-ready.dev/mcp-vs-a2a-vs-agents-json): choose the right agent-discovery protocol

## For developers

Agent Ready exposes a REST API, an MCP server, and a command-line client for programmatic use. MCP server: https://agent-ready.dev/api/v1/mcp.

**Start here:** [Agent Ready developer documentation](https://agent-ready.dev/docs) — single hub indexing every dev resource below.

- [Agent Ready developer documentation](https://agent-ready.dev/docs): canonical dev hub — REST API, MCP, OpenAPI, skills, GitHub, methodology
- [Agent Ready quickstart](https://agent-ready.dev/quickstart): first scan in 60 seconds — curl, Node, Python, MCP
- [Agent authentication for Agent Ready](https://agent-ready.dev/auth): how agents discover, register, use, and revoke credentials (WorkOS auth.md aligned)
- [Agent Ready API & integrations](https://agent-ready.dev/docs/api): REST API, MCP server, and GitHub Action reference
- [Agent Ready REST API reference](https://agent-ready.dev/docs/api/reference): interactive OpenAPI 3.1 console — every endpoint and schema
- [OpenAPI 3.1 spec](https://agent-ready.dev/api/v1/openapi.json): every endpoint, request/response schema, auth requirement
- [MCP server endpoint](https://agent-ready.dev/api/v1/mcp): streamable-http MCP server, Bearer-token authenticated
- [MCP Apps endpoint](https://agent-ready.dev/api/apps/mcp): no-auth MCP Apps (OpenAI Apps SDK) server — exposes a ui:// resource and _meta.ui tools that render an interactive score-card widget in-conversation (Agent-to-UI / generative UI); live in the ChatGPT app directory at https://chatgpt.com/apps/agent-ready/asdk_app_6a1cb1116f4881919bfa5e9a3d9d3b48
- [MCP App (dedicated surface)](https://mcp.agent-ready.dev/api/apps/mcp): the same MCP App as a standalone surface on the mcp. subdomain, with its own SEP-1649 server card at https://mcp.agent-ready.dev/.well-known/mcp/server-card.json — no auth; exposes the ui://widget/agent-ready-score.html resource and _meta.ui-bound tools (scan_site, get_scan) that render the interactive score card in ChatGPT / MCP-UI hosts, plus a text-only ask tool (NL search over Agent Ready's methodology, checks, and specs)
- [MCP server card](https://agent-ready.dev/.well-known/mcp/server-card.json): SEP-1649 discovery JSON for one-click MCP install
- [OAuth protected-resource metadata](https://agent-ready.dev/.well-known/oauth-protected-resource): RFC 9728 auth discovery document
- [OAuth authorization-server metadata](https://agent-ready.dev/.well-known/oauth-authorization-server): RFC 8414 + WorkOS auth.md agent_auth block
- [Pay per scan with x402](https://agent-ready.dev/.well-known/x402): Agent Ready accepts x402 micropayments — an anonymous agent over the free quota can pay per scan with no account ($0.02 USDC for 25 pages, $0.25 for 250 pages, USDC on Base mainnet); payable resources advertised at /.well-known/x402 and /discovery/resources
- [Agent Ready MCP server on GitHub](https://github.com/mlava/agent-ready-mcp): MIT-licensed stdio MCP wrapper for the Agent Ready REST API
- [agent-ready-mcp on npm](https://www.npmjs.com/package/agent-ready-mcp): `npx -y agent-ready-mcp@latest`
- [Agent Ready CLI on GitHub](https://github.com/mlava/agent-ready-cli): MIT-licensed command-line client for the Agent Ready REST API (scan, get, list, ask)
- [agent-ready CLI on npm](https://www.npmjs.com/package/agent-ready-scanner): standalone terminal client — `npx agent-ready-scanner scan <url>`, or `npm i -g agent-ready-scanner` (installs the `agent-ready` command)
- [Agent Ready SDKs on GitHub](https://github.com/mlava/agent-ready-sdk): MIT-licensed official client SDKs (JavaScript/TypeScript + Python) for the REST API — import the `AgentReady` class to scan, poll, list, and ask programmatically
- [agent-ready-client on npm](https://www.npmjs.com/package/agent-ready-client): JavaScript/TypeScript client SDK — `npm install agent-ready-client`; `import { AgentReady } from "agent-ready-client"`
- [agent-ready-client on PyPI](https://pypi.org/project/agent-ready-client/): Python client SDK — `pip install agent-ready-client`; `from agent_ready import AgentReady`
- [Agent Ready Skills on GitHub](https://github.com/mlava/agent-ready-skills): installable Agent Skills repo (two skills, MIT-licensed)
- [Agent Ready Skills on skills.sh](https://www.skills.sh/mlava/agent-ready-skills): canonical skills.sh listing — install both skills with `npx skills add mlava/agent-ready-skills`
- [agent-ready-api skill (skills.sh)](https://www.skills.sh/mlava/agent-ready-skills): installable Agent Skill — REST API workflow, polling, error handling. `npx skills add mlava/agent-ready-skills/skills/agent-ready-api`
- [agent-ready-mcp skill (skills.sh)](https://www.skills.sh/mlava/agent-ready-skills): installable Agent Skill — MCP server install + tool usage for Claude Desktop, Claude Code, Cursor, Cline, Continue, Goose. `npx skills add mlava/agent-ready-skills/skills/agent-ready-mcp`
- [agent-ready-cli skill (skills.sh)](https://www.skills.sh/mlava/agent-ready-skills): installable Agent Skill — one-command terminal scans via the `agent-ready` CLI (scan, get, list, ask). `npx skills add mlava/agent-ready-skills/skills/agent-ready-cli`
- [Agent Ready Cursor plugin on GitHub](https://github.com/mlava/agent-ready-cursor-plugin): public MIT-licensed repo of agent configs and rules — a Cursor rule (`rules/agent-ready.mdc`), MCP server config (`mcp.json`), and a skill that wire Agent Ready into Cursor
- [Agent Ready Gemini extension on GitHub](https://github.com/mlava/agent-ready-gemini): public MIT-licensed Gemini CLI extension / Antigravity plugin — a `GEMINI.md` agent config plus `/agent-ready:*` slash commands over the published MCP server and CLI. Install: `gemini extensions install https://github.com/mlava/agent-ready-gemini` (Antigravity: `agy plugin import gemini`)
- [Agent Ready in the Gemini CLI extensions directory](https://geminicli.com/extensions/?name=mlavaagent-ready-gemini): the extension's official listing in Google's Gemini CLI extensions directory — browse and install from the Gemini CLI catalog

## Pages

- [Home](https://agent-ready.dev): Enter a URL to scan your site
- [Pricing](https://agent-ready.dev/pricing): Free and Pro tiers — plus pay-per-scan via x402 micropayments ($0.02 / $0.25 USDC on Base, no account)
- [Agent Readability Score](https://agent-ready.dev/agent-readability-score): Get your Vercel Agent Readability score
- [llms.txt Checker](https://agent-ready.dev/llms-txt-checker): Validate your llms.txt file against the llmstxt.org spec
- [AGENTS.md Validator](https://agent-ready.dev/agents-md-validator): Check your skill file for coding agents
- [MCP Server Card Validator](https://agent-ready.dev/mcp-card-validator): Validate your MCP server card at /.well-known/mcp.json
- [A2A Agent Card Validator](https://agent-ready.dev/agent-card-validator): Validate your A2A agent card at /.well-known/agent-card.json
- [agents.json Validator](https://agent-ready.dev/agents-json-validator): Validate your Wildcard agents.json manifest
- [agent-permissions.json Validator](https://agent-ready.dev/agent-permissions-validator): Validate your agent-permissions.json manifest
- [API & integrations](https://agent-ready.dev/docs/api): REST API, MCP server, CLI, and CI/CD action — CLI and stdio MCP scans work keyless on the anonymous free tier; REST keys and the Action are Pro
- [Quickstart](https://agent-ready.dev/quickstart): Run your first Agent Ready scan in under 60 seconds — curl, Node, Python, MCP
- [Authentication](https://agent-ready.dev/auth): How agents authenticate to Agent Ready — Bearer tokens, OAuth protected-resource metadata, WWW-Authenticate discovery
- [Ask (NLWeb)](https://agent-ready.dev/ask): Public natural-language /ask endpoint over Agent Ready's methodology, checks, and specs — POST JSON, returns Schema.org-typed results; also exposed as the `ask` MCP tool at /api/v1/mcp

## Specs

- [Vercel Agent Readability Spec](https://vercel.com/kb/guide/agent-readability-spec): The full specification we check against
- [llmstxt.org](https://llmstxt.org): The llms.txt file specification
- [Model Context Protocol (2025-11-25)](https://modelcontextprotocol.io): MCP server cards + OAuth protected-resource metadata
- [A2A Protocol (v1.0.0)](https://a2a-protocol.org): Agent-to-agent discovery via /.well-known/agent-card.json
- Wildcard agents.json (v0.1.0): OpenAPI extension for agent-callable endpoints
- agent-permissions.json: Emerging convention for declaring agent action permissions

## Discovery

Agent Ready implements the conventions it audits — these first-party manifests are live and machine-readable:

- [MCP server card](https://agent-ready.dev/.well-known/mcp.json): SEP-1649 server metadata, transport, and capabilities (also at /.well-known/mcp/server-card.json)
- [A2A agent card](https://agent-ready.dev/.well-known/agent-card.json): A2A v1.0.0 capability and skill discovery
- [agents.json](https://agent-ready.dev/.well-known/agents.json): Wildcard v0.1.0 OpenAPI-backed action manifest
- [agent-permissions.json](https://agent-ready.dev/.well-known/agent-permissions.json): declared agent action permissions
- [API catalog](https://agent-ready.dev/.well-known/api-catalog): RFC 9727 linkset of the public API, its OpenAPI description, and the MCP endpoint
- [AI catalog](https://agent-ready.dev/.well-known/ai-catalog.json): AI Catalog v1.0 manifest — the Agentic Resource Discovery (ARD) data model — listing every agentic artifact on this domain in one typed list: both MCP surfaces, the A2A agent card, all four Agent Skills, the REST API, and llms.txt
- [OAuth protected-resource metadata](https://agent-ready.dev/.well-known/oauth-protected-resource): RFC 9728 metadata for the MCP endpoint
- [Schema feed](https://agent-ready.dev/schema/pages.json): JSON-LD @graph of primary pages with dateModified, indexed by /schemamap.xml

## Glossary

Canonical definitions of agent-readability terms. Full glossary at https://agent-ready.dev/glossary (Markdown mirror at /glossary.md).

### Core concepts

- **Agent readability** — The degree to which a website can be discovered, parsed, understood, and acted upon by AI agents — the machine-facing counterpart to human accessibility.
- **AI agent** — An autonomous or semi-autonomous AI system that reads web content and calls APIs to complete tasks on a user's behalf, rather than rendering pages for a person to view.
- **Answer engine** — An AI system such as ChatGPT, Perplexity, Claude, or Google AI Overviews that answers a query directly by synthesizing and citing sources instead of returning a list of links (optimizing for it is AEO / GEO).
- **Content negotiation** — An HTTP mechanism in which a client's Accept header tells the server which representation to return — e.g. Accept: text/markdown to receive a page's Markdown mirror instead of HTML.
- **Structured data (JSON-LD)** — Machine-readable metadata embedded in a page using Schema.org vocabulary in JSON-LD format, letting agents extract entities, relationships, and facts without parsing prose.
- **Vercel Agent Readability Spec** — Vercel's specification defining the discovery files, structured data, and content conventions that make a site readable by AI agents.
- **.well-known** — A standardized URI prefix (RFC 8615) under which a site publishes machine-readable metadata at predictable paths, e.g. /.well-known/mcp.json or /.well-known/agent-card.json.

### Discovery and indexing files

- **llms.txt** — A Markdown file at a site's root giving AI agents a curated index of its most useful pages and resources, with a summary and categorized links. Defined by the llmstxt.org specification.
- **llms-full.txt** — A companion to llms.txt that concatenates a site's primary content as a single Markdown document for one-request ingestion by large-context agents.
- **AGENTS.md** — A Markdown skill file telling coding agents how to build, test, and work within a project; a vendor-neutral convention that supersedes CLAUDE.md and .cursorrules.
- **sitemap.md** — A Markdown counterpart to sitemap.xml listing a site's pages as a readable linked outline rather than raw XML.
- **Markdown mirror** — A plain-Markdown version of an HTML page, served at /<page>.md or via content negotiation, so AI extractors can read clean text without parsing markup.

### Agent protocols and cards

- **Model Context Protocol (MCP)** — An open protocol letting AI applications connect to external tools, resources, and prompts over a standard JSON-RPC interface. An MCP server exposes capabilities any MCP-compatible client can call.
- **MCP server card** — A JSON manifest at /.well-known/mcp.json advertising an MCP server's metadata, transport, and capabilities. Specified in SEP-1649.
- **Agent2Agent Protocol (A2A)** — An open protocol for agent-to-agent communication and capability discovery, letting independent agents find one another and delegate tasks.
- **A2A agent card** — A JSON manifest at /.well-known/agent-card.json describing an agent's identity, capabilities, and skills under the A2A protocol.
- **agents.json** — A manifest, defined by Wildcard as an OpenAPI extension, mapping a REST API's endpoints to agent-callable actions.
- **agent-permissions.json** — An emerging manifest convention for declaring which actions AI agents are and are not permitted to take on a site.
- **NLWeb** — An open Microsoft protocol giving a website a natural-language /ask endpoint returning Schema.org-typed results; every NLWeb instance is also an MCP server.

### Agentic-commerce protocols

- **x402** — A payment protocol built on the HTTP 402 Payment Required status code, letting agents pay for an API call or resource through a machine-to-machine handshake.
- **Agentic Commerce Protocol (ACP)** — A protocol for agent-surface checkout — completing a purchase from within an AI agent's interface on the buyer's behalf.
- **Universal Commerce Protocol (UCP)** — A protocol focused on merchant interoperability for agent-driven commerce, advertised at /.well-known/ucp.
- **Agent Payments Protocol (AP2)** — A protocol for delegated payment authorization, letting a user grant an agent scoped authority to pay on their behalf.

---

## How It Works

Enter any URL and Agent Ready runs a comprehensive scan:

1. Fetches site-wide resources in parallel (llms.txt, robots.txt, sitemap.xml, sitemap.md, AGENTS.md)
2. Parses the sitemap to discover pages (up to 25 on the free tier)
3. Runs 15 site-wide checks and 25 per-page checks against the Vercel Agent Readability Spec
4. Runs 10 checks against the llmstxt.org specification
5. Runs 21 protocol checks (MCP, A2A, agents.json, agent-permissions.json, UCP, x402, NLWeb, API Catalog, Web Bot Auth, Agent Skills Discovery, A2UI, MPP, AP2, ACP, plus cloaking detection) — discover-then-validate, so only endpoints the site exposes are graded
6. Runs 23 accessibility checks (WCAG 2.2 + layout stability) over the homepage, scored as a separate accessibility sub-score
7. Computes scores (0-100) with ratings

### Vercel Agent Readability Score

Formula: `score = round((passed checks / total checks) × 100)`

The denominator compounds: 15 site-wide checks + (25 per-page checks × number of pages scanned). A systemic issue like missing canonical links on every page compounds significantly.

| Score   | Rating            |
|---------|-------------------|
| 90-100  | Excellent         |
| 70-89   | Good              |
| 50-69   | Fair              |
| 0-49    | Needs Improvement |

### llmstxt.org Score

Weighted scoring: required checks (L1-L3) count 3×, recommended (L4-L9) count 1×, optional (L10) counts 0.5×.

## Check Reference

### Site-wide checks (S1-S15)

| Check | What it verifies |
|-------|-----------------|
| S1 | llms.txt exists at /llms.txt, /.well-known/llms.txt, /docs/llms.txt, or /llms-full.txt |
| S2 | llms.txt served with Content-Type: text/plain |
| S3 | llms.txt file is not empty |
| S4 | URLs in llms.txt use .md/.mdx extensions, not .html |
| S5 | robots.txt does not block GPTBot, ClaudeBot, CCBot, Google-Extended, PerplexityBot, YouBot, Bytespider, Applebot-Extended, or cohere-ai |
| S6 | robots.txt does not disallow /llms.txt |
| S7 | robots.txt file exists |
| S8 | sitemap.xml is valid XML with <urlset> or <sitemapindex> containing <loc> entries |
| S9 | sitemap.xml entries have <lastmod> dates |
| S10 | sitemap.md exists at /sitemap.md, /docs/sitemap.md, or /.well-known/sitemap.md |
| S11 | sitemap.md contains headings and markdown links |
| S12 | Skill file exists at /AGENTS.md, /agents.md, /.well-known/agents.md, /docs/AGENTS.md, /CLAUDE.md, /.cursor/rules, or /.cursorrules |
| S13 | Skill file contains at least 2 of: installation instructions, configuration details, usage examples |
| S14 | Site is served over HTTPS (or HTTP redirects to HTTPS) |
| S15 | API-first sites publish an OpenAPI spec at /openapi.json, /openapi.yaml, /api/openapi.json, or /.well-known/openapi.json |

### Per-page checks (P1-P25)

| Check | What it verifies |
|-------|-----------------|
| P1 | Page returns HTTP 200 |
| P2 | Redirect chain is 0-1 hops (not 2+) |
| P3 | Content-Type header includes text/html |
| P4 | x-robots-tag does not contain noindex, noai, or noimageai |
| P5 | Canonical link tag is present |
| P6 | Meta description is present and at least 50 characters |
| P7 | og:title meta tag is present |
| P8 | og:description meta tag is present |
| P9 | HTML lang attribute is present |
| P10 | JSON-LD structured data block is present |
| P11 | JSON-LD contains headline, description, URL, dateModified, and BreadcrumbList |
| P12 | Page has 3+ section headings (h1-h3) |
| P13 | Text-to-HTML ratio is above 15% (after stripping scripts, styles, nav, header, footer) |
| P14 | Page links to a glossary or terminology page |
| P15 | Markdown mirror (.md/.mdx version) of the page exists |
| P16 | Markdown mirror includes title, description, and last_updated frontmatter |
| P17 | HTML includes <link rel="alternate" type="text/markdown"> |
| P18 | Markdown endpoint returns Link header with rel="canonical" |
| P19 | Accept: text/markdown request returns markdown with Content-Type: text/markdown |
| P20 | Markdown page includes ## Sitemap section linking to /sitemap.md |
| P21 | Code blocks have language-* or lang-* CSS classes |
| P22 | API pages link to openapi.json, swagger.json, swagger.yaml, or schema.json |
| P23 | Static HTML contains rendered text (page is not JS-render-dependent) |
| P24 | Page declares the llms.txt that covers it (rel="describedby" link element or Link header, per llms.txt v2) |
| P25 | AI snippet directives: max-snippet:-1 and max-image-preview:large set (meta robots/googlebot or X-Robots-Tag), so AI Overviews can show full text and large images |

### llmstxt.org checks (L1-L10)

| Check | Weight | What it verifies |
|-------|--------|-----------------|
| L1 | 3× (required) | /llms.txt returns HTTP 200 |
| L2 | 3× (required) | File starts with an H1 heading |
| L3 | 3× (required) | File is valid, parseable markdown |
| L4 | 1× (recommended) | Blockquote summary present below H1 |
| L5 | 1× (recommended) | At least one H2 section with a link list |
| L6 | 1× (recommended) | Links use [name](url) format, optionally with : notes |
| L7 | 1× (recommended) | Sampled linked URLs return HTTP 200 |
| L8 | 1× (recommended) | ## Optional section used correctly for secondary content |
| L9 | 1× (recommended) | Content-Type is text/plain |
| L10 | 0.5× (optional) | /llms-full.txt or /llms-ctx-full.txt exists |

### Protocol checks (C1-C22)

Discover-then-validate: each check runs only when the relevant endpoint exists, so a site is never penalised for protocols it has no reason to publish.

| Check | What it verifies |
|-------|-----------------|
| C1 | MCP Server Card exists at /.well-known/mcp.json |
| C2 | MCP Server Card includes the required fields |
| C3 | MCP servers publish OAuth Protected Resource metadata |
| C4 | A2A Agent Card exists at /.well-known/agent-card.json |
| C5 | A2A Agent Card includes the required fields |
| C6 | Wildcard agents.json manifest present on API-first sites |
| C7 | agent-permissions.json manifest present when declared |
| C8 | UCP profile present at /.well-known/ucp |
| C9 | UCP OAuth Authorization Server metadata resolves |
| C10 | Paid endpoint answers HTTP 402 with an x402 accepts array |
| C11 | x402 accepts entries carry valid fields |
| C12 | NLWeb natural-language /ask endpoint responds |
| C13 | API Catalog linkset at /.well-known/api-catalog (RFC 9727) |
| C14 | Web Bot Auth message-signatures directory present |
| C15 | Agent Skills Discovery manifest at /.well-known/agent-skills/index.json |
| C16 | Content parity — AI-crawler response matches the baseline (no cloaking) |
| C17 | Agent-driven UI (A2UI) surfaces declared on the MCP card |
| C18 | WWW-Authenticate: Payment (MPP) challenge present |
| C19 | MPP challenge carries the required params |
| C20 | AP2 payment-protocol support advertised via the A2A extension |
| C21 | ACP profile present at /.well-known/acp.json |
| C22 | Endpoints the site's own manifests advertise are crawlable under its robots.txt |

### Accessibility checks (A1-A23)

23 WCAG 2.2 and layout-stability checks run over the homepage, scored as a separate accessibility sub-score (0-100) — the accessibility tree is what assistive tech and AI agents both parse to act on a page. Kept out of the 71: accessibility is WCAG, not the Vercel Agent Readability Spec, so it never moves the Vercel score. Checks with nothing to grade (no tables, no media, no ARIA) are marked not-applicable and excluded from the sub-score rather than counted as passes.

| Check | What it verifies |
|-------|-----------------|
| A1 | Images (and image inputs / areas) carry a text alternative — WCAG 1.1.1 |
| A2 | Form controls have a programmatic label — WCAG 1.3.1 / 4.1.2 |
| A3 | Links and buttons expose an accessible name — WCAG 4.1.2 |
| A4 | Media (img/iframe/video) declares explicit dimensions — layout stability / CLS proxy |
| A5 | aria-labelledby / label-for references resolve to real elements — WCAG 1.3.1 |
| A6 | Iframes have an accessible name (title or aria-label) — WCAG 4.1.2 |
| A7 | Heading hierarchy is well-formed (no skipped levels) — WCAG 1.3.1 |
| A8 | No positive tabindex values that hijack focus order — WCAG 2.4.3 |
| A9 | The viewport meta does not disable pinch-zoom — WCAG 1.4.4 |
| A10 | The document has a non-empty <title> — WCAG 2.4.2 |
| A11 | An aria-label contains the control's visible text — WCAG 2.5.3 |
| A12 | A main landmark or working skip link bypasses the chrome — WCAG 2.4.1 |
| A13 | The lang value is a well-formed BCP-47 tag — WCAG 3.1.1 |
| A14 | No focusable element sits inside aria-hidden — WCAG 4.1.2 |
| A15 | No interactive control contains another — WCAG 4.1.2 |
| A16 | Headings are not empty — WCAG 1.3.1 |
| A17 | No timed meta refresh — WCAG 2.2.1 / 3.2.5 |
| A18 | autocomplete values are valid HTML autofill tokens — WCAG 1.3.5 |
| A19 | Tables declare headers, with scope and headers refs that resolve — WCAG 1.3.1 |
| A20 | SVGs exposed as images carry a text alternative — WCAG 1.1.1 |
| A21 | Audio/video declares a captions track — WCAG 1.2.2 |
| A22 | Lists contain only list items, and items sit in a list — WCAG 1.3.1 |
| A23 | ARIA roles and attributes are valid and complete — WCAG 4.1.2 |

## Public API (no auth)

### Scan a website

```bash
curl -X POST https://agent-ready.dev/api/scan \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'
```

Returns `{ scan: {...}, shareUrl: "/scan/TOKEN" }`.

### Pay per scan with x402 (no account)

When an anonymous caller exceeds the free quota (3 scans / 30 days), instead of a 429 it can pay per scan via [x402](https://www.x402.org). Opt in with `"payment": true` (or an `X-PAYMENT` header) and the endpoint returns HTTP 402 with the payment requirements:

```bash
curl -X POST https://agent-ready.dev/api/scan \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/some/path", "payment": true}'
# → HTTP 402 { x402Version: 1, accepts: [ $0.02 / 25 pages, $0.25 / 250 pages ] }
```

Sign the EIP-3009 USDC authorization, resend with the `X-PAYMENT` header, and the scan runs and settles on Base mainnet — the facilitator pays gas, and you get the scan result plus an `X-PAYMENT-RESPONSE` header. Two tiers: $0.02 USDC (25 pages) and $0.25 (250 pages). Payable resources are discoverable at [/.well-known/x402](https://agent-ready.dev/.well-known/x402) and [/discovery/resources](https://agent-ready.dev/discovery/resources).

There is also a dedicated always-paid endpoint, `/api/x402/scan` (x402 v2, CAIP-2 `eip155:8453`), whose bare 402 carries the `PAYMENT-REQUIRED` header — that is the resource registered across the x402 ecosystem: [x402scan](https://www.x402scan.com/server/171b24ae-08d1-448e-ac02-91209c90718f), [Agentic.Market](https://agentic.market/services/agent-ready-dev), and the [Coinbase CDP Bazaar](https://api.cdp.coinbase.com/platform/v2/x402/discovery/resources). Real-money settlements are live on Base mainnet.

This is an agent-facing payment path only — for autonomous agents that carry a wallet and call `/api/scan` directly. It is not a payment option for human users, and the Agent Ready CLI, MCP server, and SDK do not use it (they authenticate with an API key against `/api/v1/scans`).

### Get scan results

```bash
curl https://agent-ready.dev/api/scan/TOKEN
```

### Badge endpoint

```
https://agent-ready.dev/api/badge/example.com
```

Returns an SVG badge showing the Vercel score. Cached for 24 hours.

Embed in markdown:

```markdown
[![Agent Ready](https://agent-ready.dev/api/badge/example.com)](https://agent-ready.dev)
```

## Authenticated API v1 (Pro / Team)

Pro subscribers issue keys from [/dashboard/api-keys](https://agent-ready.dev/dashboard/api-keys) and authenticate via `Authorization: Bearer ar_live_<prefix>_<secret>`. Full reference at [/docs/api](https://agent-ready.dev/docs/api); OpenAPI 3.1 spec at [/api/v1/openapi.json](https://agent-ready.dev/api/v1/openapi.json); interactive docs at [/docs/api/reference](https://agent-ready.dev/docs/api/reference). No key is needed to try the clients: the CLI (`npx agent-ready-scanner scan <url>`) and the stdio MCP server (`agent-ready-mcp`) fall back to the anonymous free tier (3 scans/30 days per IP, 25-page depth).

Endpoints:

- `POST /api/v1/scans` — start an async scan (202 + poll URL)
- `GET /api/v1/scans/{id}` — fetch a single scan
- `GET /api/v1/scans?limit=N` — list recent scans (limit 1-100, default 20)

Rate limits: Pro 10/min, 200/day. Team 60/min, 2000/day.

Idempotency: send an optional `Idempotency-Key` header (1-255 chars, `[A-Za-z0-9_-]`) on a POST to make retries safe — the same key replays the original response (`Idempotency-Replayed: true`) instead of starting a duplicate scan. Reusing a key with a different body returns 422; an in-flight key returns 409. Keys are retained for 24 hours.

## MCP server

Thin wrapper over the API v1, authenticated with the same key. Exposes `scan_site` and `get_scan` tools.

- HTTP transport: `POST https://agent-ready.dev/api/v1/mcp`
- Server Card: [/.well-known/mcp.json](https://agent-ready.dev/.well-known/mcp.json)
- OAuth metadata: [/.well-known/oauth-protected-resource](https://agent-ready.dev/.well-known/oauth-protected-resource)

Local install via `mcp-remote` is documented on [/docs/api](https://agent-ready.dev/docs/api).

## CI/CD integration

Composite GitHub Action, public at [github.com/mlava/agent-ready-action](https://github.com/mlava/agent-ready-action). Invoked as:

```yaml
- uses: mlava/agent-ready-action@v1
  with:
    api-key: ${{ secrets.AGENT_READY_API_KEY }}
    url: https://your-preview.vercel.app
    min-vercel-score: 80
```

Posts a PR comment with scores and fails the workflow if the Vercel score drops below the threshold. Requires a Pro API key.

## Tier Limits

|                   | Free | Pro ($19/mo) |
|-------------------|------|--------------|
| Pages per scan    | 25   | 250          |
| Scans per month   | 3    | 50           |
| Monitoring        | No   | Weekly cron + regression email alerts |
| API keys          | No   | Yes          |
| MCP server access | No   | Yes          |
| CI/CD action      | No   | Yes          |
| Shareable URLs    | Yes  | Yes          |
| Badge embed       | Yes  | Yes          |