Agent Ready API & integrations

Quickstart

Get your first scan in under two minutes. The same Bearer key works against the REST API and the MCP server.

1. Sign in & upgrade. Create an account, then upgrade to Pro to unlock API access.
2. Issue a key. Visit /dashboard/api-keys and click Generate. The full secret (ar_live_…) is shown once — store it in your secret manager immediately.
3. Start a scan and poll until done. POST /api/v1/scans returns 202 with a polling URL in the Location header and a pollUrl in the body. Poll GET /api/v1/scans/{id} until status is completed or failed.

# 1. Start a scan (returns 202 with a pollUrl)
curl -X POST https://agent-ready.dev/api/v1/scans \
  -H "Authorization: Bearer $AGENT_READY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'
# → { "id": "V1StGXR8_Z", "pollUrl": "/api/v1/scans/V1StGXR8_Z", "status": "queued" }

# 2. Poll until status is "completed" or "failed"
curl https://agent-ready.dev/api/v1/scans/V1StGXR8_Z \
  -H "Authorization: Bearer $AGENT_READY_API_KEY"

Prefer Node, Python, or Go? The interactive reference generates client code in 20+ languages from the OpenAPI spec.

Authentication

The REST API and the hosted MCP server both use HTTP Bearer authentication with API keys issued from the dashboard. There is no OAuth flow — keys are long-lived secrets you manage yourself.

Key format

Keys look like ar_live_<prefix>_<secret>. The prefix is non-secret (used to identify the key in the dashboard); the secret is what authenticates you. Only the SHA-256 hash of the secret is stored server-side, so a leaked key cannot be recovered from our database — you must rotate it.

Sending the key

Set the Authorization header on every request:

curl https://agent-ready.dev/api/v1/scans \
  -H "Authorization: Bearer ar_live_abcd1234_••••••••••••••••"

Error responses

• 401 — missing or malformed Authorization header, or the key is revoked.
• 403 — the key is valid but the account is not on a Pro subscription.
• 429 — rate limit exceeded (10 requests/minute, 200/day on Pro).

Storing and rotating keys

• Treat the key like a password. Inject it via environment variables or a secret manager — never commit it to git or paste it into client code.
• For GitHub Actions, store the key as a repository secret named AGENT_READY_API_KEY and reference it as ${{ secrets.AGENT_READY_API_KEY }}.
• Rotate any time you suspect exposure: generate a new key in the dashboard, deploy it, then revoke the old one. Two keys can be active simultaneously for zero-downtime rotation.

MCP authentication

The hosted MCP endpoint accepts the same ar_live_… key as a Bearer token. The endpoint also advertises an OAuth Protected Resource Metadata document (RFC 9728) so MCP clients can discover it programmatically. See the MCP install guide for client-specific config.

Rate limits & retry

Every API response carries X-RateLimit-Limit and X-RateLimit-Remaining so clients can pace themselves before hitting a 429. When the limit is exceeded the response also carries Retry-After (seconds until a slot frees in the sliding window).

Limits

Per API key, on the Pro tier:

• Start a scan (POST /api/v1/scans): 10 / minute, 200 / day.
• Poll a scan (GET /api/v1/scans/{id}): 120 / minute.

Team plan multiplies those by roughly 6×. The list endpoint (GET /api/v1/scans) is not rate-limited beyond your account’s overall fair-use.

Retry strategy

On a 429, honour the Retry-After header — wait at least that long before the next attempt. For transient 5xx responses use exponential backoff with full jitter: delay = random(0, base × 2^attempt) with base~ 250 ms, capped at 30 s, over ~5 attempts. Jitter (the random component) is the important part — it stops clients re-synchronising into a thundering herd after a brief outage. Never retry a 4xx response other than 429; those are deterministic client errors and will keep failing.

async function callWithRetry(req: () => Promise<Response>) {
  const base = 250;   // ms
  const cap  = 30_000;
  for (let attempt = 0; attempt < 5; attempt++) {
    const res = await req();
    if (res.ok) return res;

    // 429: honour Retry-After.
    if (res.status === 429) {
      const ra = Number(res.headers.get("Retry-After") ?? "1");
      await sleep(ra * 1000);
      continue;
    }

    // Other 4xx: deterministic client errors — don't retry.
    if (res.status >= 400 && res.status < 500) return res;

    // 5xx: exponential backoff with full jitter.
    const delay = Math.random() * Math.min(cap, base * 2 ** attempt);
    await sleep(delay);
  }
  throw new Error("max retries exceeded");
}

const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));

Idempotency

To retry a scan safely after a dropped connection, send a unique Idempotency-Key header (1–255 chars, [A-Za-z0-9_-]) on POST requests. The first call runs the scan; any retry carrying the same key replays the original response (with Idempotency-Replayed: true) instead of starting a duplicate, rather than racing a second scan. Reusing a key with a different body returns 422; a key whose first request is still in flight returns 409. Keys are retained for 24 hours.

Ask (NLWeb)

A public NLWeb /askendpoint for natural-language queries over Agent Ready’s methodology, checks, and specs. No API key required — it returns Schema.org- typed JSON, and the same query is available as the ask MCP tool. Query it as /ask?query=… (GET) or a JSON POST body; add stream=true for Server-Sent Events. See the OpenAPI spec.

# GET form — a 'query' URL parameter (the NLWeb convention):
curl 'https://agent-ready.dev/ask?query=how+is+the+score+calculated'

# POST form — 'query' as a natural-language string (add "streaming": true for SSE):
curl -X POST https://agent-ready.dev/ask \
  -H 'Content-Type: application/json' \
  -d '{"query":"how is the score calculated?"}'

Versioning & deprecation policy

The REST API uses URL-based versioning. Stable endpoints live under /api/v1; breaking changes ship behind a new version prefix (/api/v2, …) and never on the existing one.

When an endpoint is scheduled for removal we set the Sunset and Deprecation response headers with the planned removal date, mark the operation deprecated: true in the OpenAPI spec, and announce the deprecation in the changelog at least 90 days before removal. No /api/v1 endpoint is currently deprecated.