--- title: "Blockquote's developer surface is a REST API, an OpenAPI document and a remote MCP server." description: "The index of Blockquote's developer documentation: the REST API reference, the OpenAPI document, the remote MCP server and the webhook contract." canonical: "https://blockquote.io/docs" --- # Blockquote's developer surface is a REST API, an OpenAPI document and a remote MCP server. Docs This page is the index of that surface. It names every reference document, states which interface fits which caller, and links the specifications each one follows. By Arne Kellmann. Updated 2026-08-23. In short - Machine-readable contract: [Blockquote OpenAPI document](https://blockquote.io/api/v1/openapi.json), rendered as the [Blockquote API reference](https://blockquote.io/api/v1/docs). - For agents: the remote MCP server at [**mcp.blockquote.io/mcp**](https://mcp.blockquote.io/mcp), over Streamable HTTP. - For your own code: **REST** under `/api/`, with `Authorization: Bearer bq_…` keys on the Pro and Agency plans. - For weekly results: **HMAC-signed webhooks**, one delivery per monitored URL per run. - Guides: [AI agent setup](https://blockquote.io/docs/ai-agents), [webhook reference](https://blockquote.io/docs/webhooks) and [continuous optimization](https://blockquote.io/docs/continuous-optimization). ## Where does each document live? Six documents cover the whole surface. Two are machine-readable and four are written for a person to read once before wiring anything up. - [**/api/v1/openapi.json**](https://blockquote.io/api/v1/openapi.json) — the OpenAPI 3.1 document describing every `/api` route, its parameters and its responses. This is the file to hand a code generator. - [**/api/v1/docs**](https://blockquote.io/api/v1/docs) — the same document rendered as a browsable reference, with a request example per route. - [**mcp.blockquote.io/mcp**](https://mcp.blockquote.io/mcp) — the remote MCP server itself. It is a stateless Streamable HTTP endpoint, not a page, so a browser shows nothing useful; point an MCP client at it. - [**AI agent setup**](https://blockquote.io/docs/ai-agents) — how to connect Claude, Cursor, ChatGPT or any other MCP client, plus API keys and limits. - [**Webhook reference**](https://blockquote.io/docs/webhooks) — the payload schema, the signature scheme, the headers and the retry policy. - [**Continuous optimization**](https://blockquote.io/docs/continuous-optimization) — receiver recipes that turn a weekly result into a pull request. ## Which specifications does this follow? Nothing here is a house format. The MCP server implements the [Model Context Protocol specification](https://modelcontextprotocol.io/specification), in its Streamable HTTP transport. The REST contract is an [OpenAPI 3.1](https://spec.openapis.org/oas/v3.1.1.html) document, so any conforming client or generator reads it without special handling. The crawl rules in [robots.txt](https://blockquote.io/robots.txt) follow [RFC 9309](https://datatracker.ietf.org/doc/html/rfc9309), including the longest-match rule that lets the `Allow: /api/docs` and `Allow: /api/openapi.json` lines in that file narrow the `/api/` block. Every endpoint runs on [Cloudflare Workers](https://developers.cloudflare.com/workers/), at the edge, which is why a scan starts in the same request that asked for it and why there is no polling queue to wait on. Pricing for the plans these limits belong to is on the [home page](https://blockquote.io/#pricing). ## Which interface should you choose? Choose MCP when a model drives the call. The remote MCP server describes every tool to the client, so an agent picks the tool and fills the arguments without a hand-written HTTP layer. Nine tools are exposed: start_scan, get_scan, compare_scans, list_checks, explain_check, get_account, list_monitors, add_monitor and remove_monitor. Choose the REST API when your own code drives the call. It is the same product surface behind a plain HTTP contract, described by the OpenAPI document, and it is what a script, a CI job or a backend service should use. A finished report is also available as one Markdown document: send Accept: text/markdown on GET /api/scan/{id}. Choose webhooks when nothing of yours is driving the call. Weekly monitoring re-scans each saved URL and posts the result to your endpoint, HMAC-signed. That is the only interface where Blockquote makes the request and your server answers it. ## What does a scan request look like end to end? POST /api/scan with a JSON body carrying the target url. A bare domain gets https:// prefixed for you. When a fresh report for that URL is already cached, the response is a scan id with status done and cached true, and GET /api/scan/{id} answers the report at once. Otherwise the response is a scan id and the scan runs asynchronously. From the id there are two ways to reach the finished report. Poll GET /api/scan/{id} until its status leaves pending, or subscribe to GET /api/scan/{id}/events, a Server-Sent Events stream that pushes each lifecycle event as it happens. The stream is the cheaper of the two and is what the site's own report page uses. Two rules govern the cost. Anonymous callers are rate-limited per IP and signed-in callers per plan, and only a dispatched scan spends a slot — a report answered from the cache is free. Cloudflare Turnstile challenges an anonymous or free-account caller, when the deployment has Turnstile configured. Pro, Agency, the internal MCP relay and a signed-in refresh of a URL that already has a report skip the challenge. Send refresh true to skip the cache and re-scan the live page; that needs a session or an API key. ## What does an API key unlock? An API key widens the report and meters you per account instead of per network. Anonymous callers get 1 scan per day and 3 per month from one network, the full score and all check results, and the top 1 fix. A key needs Pro or Agency: Pro allows 30 scans a day and 200 a month, Agency 60 a day and 500 a month. A Pro or Agency key adds the complete fix list, scan history, monitored URLs and, on Agency, webhook delivery. Keys are bearer tokens. Send Authorization: Bearer bq_… on a REST request, or set the same header on the MCP transport. Keys are created and revoked on the account page; the value is shown once when it is created. ## What does a scan actually measure? A scan runs 34 checks over one URL and weights them into three categories: schema at 40 percent, structure at 30 percent and citability at 30 percent. 29 checks are deterministic and read the parsed page. 5 run a language model against a fixed rubric at temperature 0, and the report labels them. A check that does not apply to a page is marked N/A and left out of the score rather than counted against it. Every failure carries a fix, and a schema failure carries generated JSON-LD you can paste. Blockquote does not measure keyword rank, backlinks or Core Web Vitals. ## Which parts of the site may a crawler index? The public pages, the legal pages and the API reference at /api/v1/docs. The reference is a page a person reads, so it is indexable like any other page. The OpenAPI document at /api/v1/openapi.json is a machine format, so it sends X-Robots-Tag: noindex: a crawler may fetch and read it and will not list it. robots.txt opens the home page, /about, /contact, /checks, /llm-friendly, /docs, the pages under /docs/, /developers and the legal pages: every user-agent group that the file does not deny at the root carries Allow: /. It names the reference UI and the OpenAPI document as the two exceptions to the /api/ block, each under both bases: /api/v1/docs and /api/v1/openapi.json, plus their unversioned forms. The rest of /api/ stays blocked, and so do scan result pages under /scan/, the account page and the sign-in page. A scan report belongs to the account that ran it and is not search-engine material. ## How does an agent discover this surface on its own? Through three files at fixed paths. /llms.txt lists the pages, the plans and the agent endpoints in plain text. /.well-known/ai-catalog.json describes the service for catalogue crawlers, and its host field is did:web:blockquote.io, which resolves to /.well-known/did.json. /sitemap.xml lists every indexable page. None of the three needs a key. An agent that reads llms.txt first finds the MCP endpoint and the OpenAPI document without visiting a rendered page. --- Canonical HTML page: