Agent Ready quickstart

Step 1 — Get an Agent Ready API key

Sign in at /sign-in and open /dashboard/api-keys. Click Create key, name it after the workload, and copy the Bearer token. Treat it like a password — never commit it to a repo. Pro plan required (see pricing and the auth guide).

Step 2 — Run your first scan

POST to /api/v1/scans with the Bearer token and a JSON body containing the URL to scan. The response returns immediately with a scan id and status: queued.

# 1. Start a scan
curl -X POST https://agent-ready.dev/api/v1/scans \
  -H "Authorization: Bearer $AGENT_READY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

# Response:
# {"id":"scan_01HXYZ...","status":"queued","shareUrl":null}

# 2. Poll for results
curl https://agent-ready.dev/api/v1/scans/scan_01HXYZ... \
  -H "Authorization: Bearer $AGENT_READY_KEY"

# When status flips to "complete":
# {"id":"scan_01HXYZ...","status":"complete","score":87,"rating":"good","shareUrl":"https://agent-ready.dev/scan/..."}

Step 3 — Poll for results

GET /api/v1/scans/{id} every two or three seconds until status flips to complete. The completed body includes the score, the per-check breakdown, and a shareable URL.

Node (TypeScript)

// npm install undici  (or use the built-in global fetch on Node 18+)

const KEY = process.env.AGENT_READY_KEY!;
const base = "https://agent-ready.dev/api/v1";

const start = await fetch(`${base}/scans`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ url: "https://example.com" }),
}).then((r) => r.json());

let result = start;
while (result.status !== "complete") {
  await new Promise((r) => setTimeout(r, 2_000));
  result = await fetch(`${base}/scans/${start.id}`, {
    headers: { Authorization: `Bearer ${KEY}` },
  }).then((r) => r.json());
}

console.log("Score:", result.score, result.shareUrl);

Python

# pip install requests
import os, time, requests

KEY = os.environ["AGENT_READY_KEY"]
base = "https://agent-ready.dev/api/v1"
h = {"Authorization": f"Bearer {KEY}"}

start = requests.post(
    f"{base}/scans",
    headers={**h, "Content-Type": "application/json"},
    json={"url": "https://example.com"},
).json()

result = start
while result["status"] != "complete":
    time.sleep(2)
    result = requests.get(f"{base}/scans/{start['id']}", headers=h).json()

print("Score:", result["score"], result["shareUrl"])

Step 4 — Integrate via MCP

Agent Ready exposes an MCP server at https://agent-ready.dev/api/v1/mcp. The server card at /.well-known/mcp/server-card.json advertises three tools: scan_site, get_scan, and ask. Add a server entry to your MCP client config (Claude Desktop, Cursor, Cline, Continue, Goose):

{
  "mcpServers": {
    "agent-ready": {
      "transport": "streamable-http",
      "url": "https://agent-ready.dev/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${AGENT_READY_KEY}"
      }
    }
  }
}

Your agent can now run scans and search the Agent Ready glossary, guides, and methodology without any custom code. The ask tool uses the same NLWeb-compatible search exposed at /ask on the public site.

API reference

Full OpenAPI 3.1 spec: /api/v1/openapi.json (alias /openapi.json). Public endpoints under /api/v1:

• POST /api/v1/scans — start a scan. Body: {"url": "https://example.com"}.
• GET /api/v1/scans/{id} — fetch scan status and results.
• POST /api/v1/ask — NLWeb-compatible search over Agent Ready content. Body: {"query": "what is llms.txt?"}.
• POST /api/v1/mcp — MCP streamable-http endpoint. Same Bearer token, same rate-limit budget.

Rate limits: 10 req/min, 200 req/day per key (sliding window). Discovery aliases: the OpenAPI spec is also linked from the homepage via an RFC 8288 Link header with rel="service-desc".

Frequently asked questions

Do I need to sign up to run a scan?

No — anonymous one-off scans run from the homepage at https://agent-ready.dev/ without sign-up (3 scans per IP per 30 days). To use the REST API or MCP server, you need a Pro account and an API key from /dashboard/api-keys.

How long does a scan take?

Free tier scans complete in 5-15 seconds (25 pages). Pro scans complete in 15-60 seconds (250 pages). The /api/v1/scans response returns immediately with a scan id; poll /api/v1/scans/{id} until the status field flips from queued to complete. There is no webhook callback yet.

Can I use the same API key for REST and MCP?

Yes — the same Bearer token authenticates POST /api/v1/scans, GET /api/v1/scans/{id}, POST /api/v1/ask, and POST /api/v1/mcp. The per-minute (10) and per-day (200) rate-limit budgets are shared across all surfaces.

What does the MCP server expose?

Three tools: scan_site (start a scan), get_scan (fetch results), and ask (NLWeb-style search over the Agent Ready glossary, guides, and methodology). The server card at /.well-known/mcp/server-card.json describes the full surface in SEP-1649 format. Claude Desktop, Cursor, Cline, and other MCP clients can install it from the card URL.

Where is the OpenAPI spec?

OpenAPI 3.1 at https://agent-ready.dev/api/v1/openapi.json (alias: /openapi.json). The spec covers every public endpoint, request schema, response schema, and authentication requirement. Use it with OpenAPI codegen (openapi-typescript, openapi-generator, swagger-codegen) to produce a typed client in your language of choice.