Reference

Blockquote's developer resources — API keys, documentation, and the free sandbox — are all on this page.

TL;DR: Blockquote is an AI citability audit with a REST API and a remote MCP server, and this page is the single index for using either as a developer. Four things live here: how to get an API key, where the documentation is, how to make your first call, and what the read-only fixture sandbox allows. By Arne Kellmann. Updated 2026-09-07.

Official agent integrations

The Blockquote agent integrations repository provides the portable plugin, MCP configuration, product skills, and JavaScript and Python SDKs. Install the skills with npx skills add ArneFfm/blockquote-agents.

Read the Markdown API reference or connect the documentation MCP endpoint at https://mcp.blockquote.io/docs/mcp. It provides public documentation resources and keyword search. Documentation search also accepts JSON POST requests at /ask. Send {"query":{"text":"API"},"prefer":{"streaming":true}} for a finite stream of start, result, and complete events.

Official SDK packages

Both language clients use the same versioned REST API. Choose the runtime already used by your project. Each package includes a blockquote CLI for scan creation, report reads, and comparisons.

Blockquote SDK package registries and supported runtimes
Language	Official package	Runtime
Python	blockquote-agents on PyPI	Python 3.10 or later
JavaScript	blockquote-agents on npm	Node.js 20 or later

Install the Python SDK and CLI

The official blockquote-agents package on PyPI requires Python 3.10 or later and has no runtime dependencies. It installs both the Python client and the blockquote command.

python -m pip install --upgrade blockquote-agents
blockquote --help
blockquote read SCAN_ID

Replace SCAN_ID with an existing report ID. Reading a public report needs no API key and starts no scan. The Python SDK reference covers scan creation, report reads, comparisons, and error handling.

Install the JavaScript SDK

Install the official blockquote-agents package from npm. It requires Node.js 20 or later and has no runtime dependencies. The GitHub release archive remains available as an alternative install source.

npm install blockquote-agents
npm exec -- blockquote --help
npm exec -- blockquote read SCAN_ID

The JavaScript SDK reference documents the client and its CLI. Both SDKs preserve HTTP status, response data, rate-limit headers, and retry guidance. Neither SDK retries or polls automatically.

Set BLOCKQUOTE_API_KEY for account access. Create keys on your account page with Pro or Agency. Scan creation still follows authentication, human verification, and quota rules in auth.md.

A CLI report read prints JSON with data, status, and headers. HTTP failures retain the server error and retry guidance, print to stderr, and exit with code 1. Installing either package does not create an account or start a scan.

Test with isolated fixtures

The sandbox serves a synthetic report without credentials or quota use. It performs no network fetches, scans, or storage writes. Read sandbox-example, or test a batch read with up to ten fixture IDs. Unknown IDs return 404. Invalid lists return 400. Production anonymous scans below use real quotas.

To read real stored reports in bulk, call GET /api/v1/batch?ids=ID1,ID2 with one to ten IDs. Each result includes its HTTP status, headers, and report or error body. The same account permissions and report limits apply as on individual reads. This endpoint starts no scans.

In short

API keys: self-serve on the account page — included on Pro and Agency, not on Free.
Documentation: /api/v1/docs (reference UI), /api/v1/openapi.json (the OpenAPI 3.1 source), /docs/ai-agents (MCP setup and the full agent FAQ).
Quickstart: one curl call or one MCP client config block — below.
No key needed to try it: anonymous scans, 1 per day and 3 per month per network address.

How do you get a Blockquote API key?

An API key is a bearer token that starts with bq_ and authenticates every REST and MCP call as your account. Keys are self-serve: open the account page, create a key, and copy the value — it is shown exactly once and cannot be read again. An account holds at most 5 keys you create yourself. Each key is created with a fixed scope: reports only, scans and reports (the default), or scans, reports and monitors. The scope stays fixed for the life of the key, and you revoke a key from the same page at any time.

API keys are a paid feature. The free plan carries no API keys; the Pro and Agency plans carry them. Sending a valid key switches metering from the anonymous per-IP limits to your plan's quotas, unlocks the complete fix list in every report view, and enables refresh, which skips the 24-hour report cache. The account page is also where you read the plan you are on and the scans it has spent. Plan prices and the right of withdrawal live on the pricing section and the refunds page, not here.

Plan	API keys
Free	No
Pro	Yes
Agency	Yes

The table restates the one column that decides API access. What each plan costs, what it includes beyond keys, and how withdrawal works are on the pricing section and the refunds page.

Where is the API documentation?

In three places, each written for a different reader. /api/v1/docs is the reference UI: every route, every parameter, and a request builder that runs in the browser. /api/v1/openapi.json is the document behind that UI, an OpenAPI 3.1 description of the whole /api surface, which you hand to a code generator or to an agent. /docs/ai-agents is the MCP side: the endpoint URL, a setup block per client, the nine tools, the two prompts, the three resources, and the full connection FAQ.

The OpenAPI document is hand-authored, and a test fails the build when the document and the router disagree in either direction — so the description matches the running code rather than trailing it. Start at the reference UI, switch to the raw document once you generate a client, and read the agent page when your caller is an AI agent rather than a script.

The machine-readable document conforms to the OpenAPI 3.1 specification, so any conforming generator produces a client from it without hand edits. Every route it describes is the same route the MCP tools call — the MCP server is a protocol adapter over this API, not a second product.

How do you make your first API call?

Two shapes. Over REST, POST /api/scan starts a scan and returns an id, GET /api/scan/{id} polls it, and that same route with the header Accept: text/markdown returns the finished report as one Markdown document instead of JSON. POST /api/scan needs a key on a paid plan or a Cloudflare Turnstile token. A key whose account has lapsed to Free still authenticates the call, but it does not skip the token. GET /api/scan/{id} reads any finished scan anonymously. Over MCP, point any client at https://mcp.blockquote.io/mcp and call start_scan, then get_scan. An MCP call needs neither a key nor an account. The first block below is plain JSON-RPC against the MCP endpoint plus the one-line Markdown read; the second is the config file Cursor and VS Code read.

Every current MCP client connects with a URL alone, because the server follows the Streamable HTTP transport of the MCP specification and keeps no session state. Claude Code takes one command. Add the Authorization header only when you want the call to run as your account rather than anonymously.

curl — JSON-RPC and the Markdown report

# Any HTTP client — plain JSON-RPC against the MCP endpoint:
curl -X POST https://mcp.blockquote.io/mcp \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"start_scan","arguments":{"url":"example.com"}}}'

# The whole report as one Markdown document, over plain REST:
curl -H "Accept: text/markdown" https://blockquote.io/api/scan/SCAN_ID

mcp.json — Cursor / VS Code

// Cursor (~/.cursor/mcp.json) and VS Code (.vscode/mcp.json) — same shape:
{
  "mcpServers": {
    "blockquote": {
      "url": "https://mcp.blockquote.io/mcp",
      "headers": { "Authorization": "Bearer bq_YOUR_KEY" }
    }
  }
}

The transport rules are in the MCP specification, and the server itself is built on Cloudflare's Agents SDK. Per-client setup for Claude Code, Claude Desktop, ChatGPT and the rest is on the AI agent setup page.

What can you do without an API key?

A full scan, scored, with no account at all. Anonymous callers get 1 scan per day and 3 scans per month from one network address, over the website, the REST API and the MCP endpoint alike — one budget, three front doors. The report is the anonymous tier: the 0–100 score, all 34 check results, and the top 1 recommendation, with the rest of the fix list locked.

That is deliberately the lowest hurdle the product can offer: a script or an agent produces a scored report before anyone signs anything. Hitting a limit returns a structured error carrying the retry delay, so a well-behaved caller backs off exactly as long as it needs to. There is no CAPTCHA on the MCP path, because human-verification widgets are unsolvable for headless callers by design — the relay authenticates itself and forwards your network address for metering. Anonymous POST /api/scan over plain REST does need a Cloudflare Turnstile token, so a headless REST caller scans over MCP or with a key on a paid plan.

The deeper answer — which calls stay anonymous, which need a key, and how the three limit layers interact — is in the Do you need an API key? section of the AI agent setup page. This page is itself listed in the site's llms.txt, per the llms.txt convention, so an agent finds the developer surface without crawling for it.