Developer Docs · For site owners

Scanner API reference

Scan any URL across 58 agent-readiness checks — via REST, async jobs, MCP, or the CLI — and get a scored report with prioritized fixes. Five scans a day to evaluate; unlimited pay-per-scan over x402.

← All docs · Answer Gateway reference →

Quick start

One call returns a full JSON report — five scans a day per caller, no key needed.

curl "https://botvisibility.com/api/scan?url=https://stripe.com&format=json"

The response includes a top-level score summary plus every check with id, status (pass | fail | partial | na), level, message, and recommendation. Full schema: /openapi.json.

Endpoints

MethodPathDescription
GET/api/scan?url=<site>&format=jsonScan a URL, JSON report (recommended for agents). Five per day per caller, then HTTP 402.
GET/api/scan?url=<site>Same scan as a Server-Sent Events stream (for UIs).
POST/api/scanJSON body {"url":"..."}. Accepts an Idempotency-Key header for safe retries.
POST/api/scan/jobsSubmit an async scan job → 202 + job id. Poll GET /api/scan/jobs/{id} until completed. For callers that don't want to hold a request open.
POST/api/v1/scan-gatewayPaid deep scan via the pay.sh gateway — $0.10 USDC on Solana over x402. Returns 402 with payment requirements when unpaid.
GET/api/badge?url=<site>SVG badge showing a site's score and level.
GET/api/screenshot?url=<site>Cached screenshot of a scanned site.
POST/api/mcpModel Context Protocol server (Streamable HTTP). 11 tools incl. scan_url, compare_sites, deep_scan.
POST/api/monitorsCreate a scheduled monitor: re-scan a URL on a cadence and receive a signed webhook when the score changes.

Authentication & pricing

Public access needs no credentials. To raise your daily allowance, request an anonymous OAuth 2.0 client-credentials token (scan:read scope) and send it as a bearer token. Discovery follows RFC 8414 and RFC 9728:

# Discover the auth server + protected-resource metadata GET /.well-known/oauth-authorization-server GET /.well-known/oauth-protected-resource # Then call with a bearer token (or an X-API-Key header) curl -H "Authorization: Bearer <token>" \ "https://botvisibility.com/api/scan?url=example.com&format=json"

Past the daily allowance, the API returns HTTP 402 with x402 payment requirements — $0.10 USDC per scan on Solana at the pay.sh gateway, no account needed. See how agents pay.

MCP server

BotVisibility runs a live Model Context Protocol server over Streamable HTTP. Point any MCP client (Claude Desktop, Cursor) at the endpoint below; the manifest lives at /.well-known/mcp.json.

https://botvisibility.com/api/mcp

Tools include scan_url, compare_sites, get_recommendations, deep_scan, scan_batch, and validate_llms_txt.

CLI

Scan a site or local codebase from your terminal — no install needed.

npx botvisibility stripe.com

See the CLI guide for flags, CI usage, and JSON output.

Webhooks & monitoring

Create a monitor to re-scan a URL on a cadence and get a webhook when its readiness score changes — useful for watching your own site or a dependency for regressions.

curl -X POST https://botvisibility.com/api/monitors \ -H "Content-Type: application/json" \ -d '{ "url": "https://example.com", "callback_url": "https://hooks.example.com/botvisibility", "events": ["score.changed"], "interval_sec": 86400 }' # -> { "id": "mon_…", "secret": "whsec_…", ... } (secret shown once)

Manage a monitor at GET/DELETE /api/monitors/{id}, and fire a sample delivery with POST /api/monitors/{id}/test. Every delivery is signed:

X-BotVisibility-Signature: t=<unix>,v1=<hex hmac_sha256(t + "." + body)> # verify (pseudo): expected = hmac_sha256(secret, f"{t}.{raw_body}").hexdigest() assert constant_time_eq(expected, v1) and abs(now - t) < 300

Payloads and the full schema are documented in openapi.json (see x-webhooks) and auth.md.

Ready to scan your site?

Scan your site