---
title: "API & integrations — Agent Ready"
description: REST API, MCP server, and CI/CD reference for agent-ready.dev. Pro subscribers can issue keys from the dashboard.
last_updated: 2026-05-28
canonical_url: https://agent-ready.dev/docs/api
---

# API & integrations

> Programmatic access to agent-ready.dev scans. Pro subscribers can issue API keys from the dashboard. Four surfaces, one key: REST API, MCP server, a command-line client, and a GitHub Action for CI/CD gating.

## 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](https://agent-ready.dev/pricing) to unlock API access.
2. **Issue a key.** Visit [/dashboard/api-keys](https://agent-ready.dev/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`.

```bash
# 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](https://agent-ready.dev/docs/api/reference) generates client code in 20+ languages from the [OpenAPI spec](https://agent-ready.dev/api/v1/openapi.json).

## 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:

```bash
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](https://agent-ready.dev/.well-known/oauth-protected-resource) (RFC 9728) so MCP clients can discover it programmatically. See [the MCP install guide](https://agent-ready.dev/mcp) for client-specific config.

## Rate limits and 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`](https://datatracker.ietf.org/doc/html/rfc7231#section-7.1.3) — 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.

```ts
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;

    if (res.status === 429) {
      const ra = Number(res.headers.get("Retry-After") ?? "1");
      await sleep(ra * 1000);
      continue;
    }
    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));
```

## REST API

`POST /api/v1/scan` accepts a JSON body with a `url` field and returns scan results. Full schema lives in the [interactive reference](https://agent-ready.dev/docs/api/reference) and the [OpenAPI 3.1 spec](https://agent-ready.dev/api/v1/openapi.json).

Rate limits on Pro: 10 requests/minute, 200/day.

## MCP server

Run scans from Claude Desktop, Claude Code, Cursor, Cline, VS Code, or Windsurf. Three install paths — hosted Streamable HTTP endpoint, the published [`agent-ready-mcp`](https://www.npmjs.com/package/agent-ready-mcp) npm package, or the community `mcp-remote` bridge. Listings on [Smithery](https://smithery.ai/servers/agent-ready/agent-ready-mcp) and the [official MCP registry](https://registry.modelcontextprotocol.io/v0/servers?search=agent-ready-mcp).

Full guide: [agent-ready.dev/mcp](https://agent-ready.dev/mcp).

## CLI

Run scans from your terminal or CI without writing HTTP calls. The [`agent-ready-scanner`](https://www.npmjs.com/package/agent-ready-scanner) npm package is a thin, zero-dependency wrapper over the REST API; installing it provides the `agent-ready` command.

```bash
# one-off, no install
npx agent-ready-scanner scan https://example.com

# or install the `agent-ready` command globally
npm install -g agent-ready-scanner
agent-ready scan https://example.com --json
```

Commands: `scan` (start + poll to completion), `get <id>`, `list`, and the public `ask`. Human-readable output by default; pass `--json` for scripting. Authenticate with the same `ar_live_...` key via `AGENT_READY_API_KEY` or `--api-key` (`ask` needs no key). Source: [github.com/mlava/agent-ready-cli](https://github.com/mlava/agent-ready-cli).

## Ask (NLWeb)

A public [NLWeb](https://agent-ready.dev/what-is-nlweb) `/ask` endpoint for natural-language queries over Agent Ready's own content — methodology, the check registry, and the specs it validates. No API key required. Returns NLWeb result objects (flat fields plus a nested Schema.org `schema_object`). `query` is the natural-language string — pass it as a URL parameter (GET) or a JSON body field (POST). Add `streaming: true` (or `?stream=true`) for Server-Sent Events. The same query is exposed as the `ask` MCP tool, so every NLWeb instance (this one included) is also an MCP server.

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

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

Canonical path is `/api/v1/ask`; `/ask` is the conventional NLWeb alias. The endpoint is documented in the [OpenAPI 3.1 spec](https://agent-ready.dev/api/v1/openapi.json).

## GitHub Action

Composite GitHub Action for PR-level agent-readability gating. Invoked as:

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

Fails the PR check when scores drop below the configured thresholds. Useful as a deployment gate on preview URLs.

## Versioning and 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`](https://datatracker.ietf.org/doc/html/rfc8594) and [`Deprecation`](https://datatracker.ietf.org/doc/html/rfc9745) response headers with the planned removal date, mark the operation `deprecated: true` in the [OpenAPI spec](https://agent-ready.dev/api/v1/openapi.json), and announce the deprecation in the changelog at least 90 days before removal. No `/api/v1` endpoint is currently deprecated.

## Links

- [Interactive REST API reference](https://agent-ready.dev/docs/api/reference)
- [OpenAPI 3.1 spec](https://agent-ready.dev/api/v1/openapi.json)
- [Pricing](https://agent-ready.dev/pricing)
- [Methodology](https://agent-ready.dev/methodology)

## Sitemap

See the full [sitemap](https://agent-ready.dev/sitemap.md) for all pages on agent-ready.dev.