# API documentation

Everything the AgentReady Check interface can do, the API can do. Three endpoints, one format, no exceptions.

- Base URL: `https://check.ai-agent-ready.com/api/v1`
- OpenAPI 3.1: `https://check.ai-agent-ready.com/api/v1/openapi.json`
- Format: JSON, UTF-8
- Every response carries a `pricing` field. Currently `{"model":"free"}` everywhere; the field exists so later agent payments can use HTTP 402 without breaking the format.

## Authentication

Optional. Without a key you get 3 scans per day and IP. With a bearer token that limit disappears:

```
Authorization: Bearer <your-key>
```

Keys are stored as SHA-256 hashes in `core.api_keys`. Request one at sascha@the-autopilot.com.

## POST /api/v1/scans

Starts a scan and answers once it is finished (typically 5–30 seconds).

**Request**

```json
{ "domain": "example.com" }
```

**Response 201**

```json
{
  "scan": {
    "id": "0e2f...",
    "domain": "example.com",
    "score": 62,
    "state": "yellow",
    "created_at": "2026-01-01T12:00:00.000Z",
    "url": "https://check.ai-agent-ready.com/scan/0e2f...",
    "checks": [
      {
        "id": "crawler",
        "title": "AI crawler access",
        "score": 18,
        "max": 25,
        "state": "warn",
        "summary": "...",
        "findings": [{ "label": "GPTBot", "state": "warn", "text": "..." }],
        "fix": "..."
      }
    ]
  },
  "pricing": { "model": "free" }
}
```

The API always returns all five checks — the email gate applies to the web interface only.

**Errors**

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `invalid_domain` | Domain missing or not scannable |
| 401 | `invalid_key` | Bearer token unknown |
| 429 | `rate_limited` | Daily limit without a key reached |
| 500 | `scan_failed` | Scan could not be stored |

## GET /api/v1/scans/{id}

Returns a stored result. Same response shape as POST, status 200. Unknown IDs return 404 with code `not_found`.

## GET /api/v1/stats

Aggregated, anonymous market data across all scans.

```json
{
  "stats": {
    "domains": 1284,
    "scans": 1731,
    "average_score": 41,
    "score_distribution": { "red": 812, "yellow": 705, "green": 214 },
    "check_averages": { "crawler": 14.2, "llmstxt": 1.1, "js": 13.8, "schema": 7.4, "basics": 9.9 }
  },
  "pricing": { "model": "free" }
}
```

## MCP

An MCP server is not part of this application. It is built separately as a Cloudflare Worker and consumes these three endpoints exclusively — each tool maps 1:1 to one endpoint:

| MCP tool | Endpoint |
| --- | --- |
| `scan_domain` | `POST /api/v1/scans` |
| `get_scan` | `GET /api/v1/scans/{id}` |
| `get_stats` | `GET /api/v1/stats` |

## Example

```bash
curl -s -X POST https://check.ai-agent-ready.com/api/v1/scans \
  -H "content-type: application/json" \
  -d '{"domain":"example.com"}' | jq '.scan.score'
```

---

A product by The Autopilot — https://the-autopilot.com