Build with Blockquote
Blockquote is a citability API for your application. Try a read-only fixture before you scan real pages with an account key.
- Read a sandbox report without an API key.
- Install an SDK for Python or JavaScript.
- Start a scan with your account key.
Open API reference OpenAPI document
Try the API without a key
The sandbox returns a synthetic report. It spends no quota and starts no scan.
curl https://blockquote.io/api/v1/sandbox/scan/sandbox-example Open sandbox-example to inspect the response. Batch reads accept up to ten fixture IDs. Unknown IDs return 404; invalid lists return 400. The sandbox performs no network fetches or storage writes.
Use your existing runtime
Both official SDKs use the versioned REST API and include a blockquote CLI.
They have no runtime dependencies and do not retry or poll automatically.
| Language | Official package | Runtime |
|---|---|---|
| Python | blockquote-agents on PyPI | Python 3.10 or later |
| JavaScript | blockquote-agents on npm | Node.js 20 or later |
Python SDK and CLI
python -m pip install --upgrade blockquote-agents
blockquote --help
blockquote read SCAN_ID
Replace SCAN_ID with an existing report ID.
The Python SDK reference
covers scan creation, report reads, comparisons, and error handling.
JavaScript SDK and CLI
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.
Set BLOCKQUOTE_API_KEY for account access. A CLI report read prints JSON with
data, status, and headers.
HTTP failures print the server error to stderr and exit with code 1.
Installing a package does not create an account or start a scan.
Start a scan, then read its report
Create an API key on your account page with Pro or Agency. Send it as a bearer token when starting a real scan.
curl -X POST https://blockquote.io/api/v1/scan \
-H "Authorization: Bearer bq_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com"}'
The response contains an id. Replace SCAN_ID with that value.
Read until the status leaves pending, or subscribe to
GET /api/v1/scan/SCAN_ID/events for server-sent progress events.
curl https://blockquote.io/api/v1/scan/SCAN_ID \
-H "Authorization: Bearer bq_YOUR_KEY"
curl https://blockquote.io/api/v1/scan/SCAN_ID \
-H "Authorization: Bearer bq_YOUR_KEY" \
-H "Accept: text/markdown"
A cache hit returns an ID with status: done and cached: true.
Read the report with GET; the creation response contains no report.
For one to ten stored reports, use GET /api/v1/batch?ids=ID1,ID2.
Batch reads apply the same permissions and report limits as individual reads.
Keys, limits and anonymous access
Before scanning real pages
- API keys are included on Pro and Agency. Create and revoke them on your account page.
- No key needed to try it: anonymous scans, 1 per day and 3 per month per network address. Use MCP or the website; anonymous REST scan creation needs Turnstile.
- Read Authentication and Pricing and limits before production integration.
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.
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.
For recurring results, use signed webhooks on Agency. The continuous optimization guide shows receiver and pull-request workflows.
Connect an agent to the same API
Follow the agent setup guide for MCP configuration. The Blockquote agent integrations repository contains the portable plugin, MCP configuration, product skills, and SDK source.
npx skills add ArneFfm/blockquote-agents
For machine consumption, use the Markdown API reference
or the documentation MCP endpoint at https://mcp.blockquote.io/docs/mcp.
It provides public resources and keyword search.
Documentation search accepts JSON POST requests at /ask.
Send {"query":{"text":"API"},"prefer":{"streaming":true}}
for a finite stream of start, result, and complete events.
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 sixteen 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.
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.
# 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 // 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" }
}
}
}