# API and docs

The public scan API, the fields it returns, the rate limits, and the machine-readable files this site serves.

Source: https://www.botready.dev/docs
Updated: 2026-09-04

## Start a scan

```http
POST https://www.botready.dev/api/scan
content-type: application/json

{ "url": "https://example.com" }
```

Returns `{ "scanId": "...", "cached": false, "domain": "example.com" }`. A result less than
24 hours old is returned instead of crawling again, with `cached: true`.

## Read a scan

```http
GET https://www.botready.dev/api/scan/{scanId}
```

Returns `status`, `scannerVersion`, `pagesCrawled`, a `progress` array of `{ key, status }` as checks land, and
once `settled` is true a `score` object of `{ total, grade, scoringVersion, categoryScores, failedChecks,
erroredChecks, skippedChecks }`.

## Rate limits

- 5 scans an hour without an account, 50 with one.
- `429` carries `retry-after` and the `x-ratelimit-*` headers.

## Machine-readable files this site serves

- `/index.md` — Are you BotReady?, as markdown.
- `/what-we-check.md` — What we check, as markdown.
- `/pricing.md` — Pricing, as markdown.
- `/docs.md` — API and docs, as markdown.
- `/bot.md` — Our crawler, as markdown.
- `/llms.txt` and `/llms-full.txt`
- `/openapi.json` — the two endpoints above, as OpenAPI 3.1.
- `/.well-known/agent.json` and `/.well-known/ai-plugin.json`
- `/sitemap.xml` and `/robots.txt`

Every page also answers `Accept: text/markdown` with its markdown representation, and advertises it with a
`Link: <...>; rel="alternate"; type="text/markdown"` header.