Skip to content
BotReady
API and docs

Everything here is machine-readable

It would be difficult to sell a legibility check from a site an agent cannot read. So the scan API is public and needs no key, every page answers Accept: text/markdown with its own text, and the files below are the ones we tell everybody else to serve.

Start a scan

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

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

Answers { "scanId": "…", "cached": false, "domain": "example.com" }. A result less than 24 hours old is returned instead of crawling again, with cached: true — the window exists so that a link to a result page cannot be turned into traffic against the site it describes.

Read it

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

Poll it. A scan settles in about thirty seconds, because 5 clients a second apart and up to 6 pages a second apart is what a scan is. The fields that matter:

  • statusstringqueued, running, complete or error.
  • settledbooleanFalse while checks are still landing. Poll until it is true.
  • progress[]{ key, status }Each check as it finishes, in the order the scan ran them.
  • score.totalinteger0 to 100. Absent until settled.
  • score.gradestringA to F, from the bands published on the catalog page.
  • score.categoryScoresobjectEach of the six categories, 0 to 100 within itself.
  • score.failedChecksstring[]The keys that failed. Every key exists in the catalog.
  • score.scoringVersionstringThe version of the weights that produced this total.
  • scannerVersionstringThe version of the crawler that gathered the evidence.

Rate limits

5 scans an hour from an address without an account, 50 with one. A 429 carries retry-after and the three x-ratelimit-* headers, and the message says which limit you hit rather than making you guess.

What this site serves

Fetch any of these right now
  • /llms.txtWhat this site is and where the readable version of every page lives.
  • /llms-full.txtEvery public page inlined, so reading the whole site costs one request.
  • /openapi.jsonThe two endpoints below, as OpenAPI 3.1.
  • /.well-known/agent.jsonWhat a client can do here, what it costs, and how our own crawler behaves.
  • /.well-known/ai-plugin.jsonThe older manifest, pointing at the same OpenAPI description.
  • /index.mdAny page with .md appended is that page as markdown. So is Accept: text/markdown.
  • /sitemap.xmlEvery public page, with the date its content actually changed.
  • /robots.txtOpen to everything except the app, the account area and the API.

Our crawler

When we read your site we do it as BotreadyBot/1.0 (+https://botready.dev/bot), we read your robots.txt first, and we stop if it says to. The crawler page is the whole of it, including the four things we will never do to get past a block. The catalog and the weights are on what we check, at scoring version 1.2.

Something wrong, or something missing from the API? crawler@botready.dev reaches somebody who can change it.

API and docs — botready.dev