Is BotVisibility free?

Humans scan free in the browser. Agents get a daily free allowance on the JSON API, then pay per scan in USDC on Solana via x402 through the pay.sh gateway.

What does BotVisibility check for?

llms.txt, agent cards, OpenAPI specs, MCP servers, CORS and rate-limit headers, structured data, Content-Signals, API catalogs (RFC 9727), OAuth Protected Resource metadata (RFC 9728), x402 payments, AI search indexability, and more.

Developer Docs

API Reference & Developer Guide

Q: What is BotVisibility?

BotVisibility is an AI agent readiness scanner. It scans any URL across 58 checks and 5 levels — Discoverable, Usable, Optimized, Indexable, and Agent-Native — to measure how ready a site is for AI agents like Claude and GPT.

Q: How do agents call the BotVisibility API?

Send GET https://botvisibility.com/api/scan?url=https://example.com&format=json, or POST the same endpoint with {"url": "..."}. It is free up to a daily per-caller allowance; beyond that it returns HTTP 402 with x402 payment requirements ($0.10 USDC per scan on Solana). There is also an MCP server at /api/mcp and a CLI: npx botvisibility example.com.

Everything you need to integrate BotVisibility — REST API, MCP server, CLI, authentication, and payments. Scan any URL across 58 agent-readiness checks.

Quick start

One call returns a full JSON report. No key required for the free daily allowance.

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

Method	Path	Description
GET	/api/scan?url=<site>&format=json	Scan a URL, JSON report (recommended for agents). Free up to a daily per-caller allowance, then HTTP 402.
GET	/api/scan?url=<site>	Same scan as a Server-Sent Events stream (for UIs).
POST	/api/scan	JSON body {"url":"..."}. Accepts an Idempotency-Key header for safe retries.
POST	/api/v1/scan-gateway	Paid 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/mcp	Model Context Protocol server (Streamable HTTP). 11 tools incl. scan_url, compare_sites, deep_scan.
POST	/api/monitors	Create a scheduled monitor: re-scan a URL on a cadence and receive a signed webhook when the score changes.
GET	/.well-known/api-catalog	RFC 9727 linkset for API discovery.

Authentication

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"

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.

Discovery files

Machine-readable manifests agents can fetch to discover this API:

FAQ

What is BotVisibility?

An AI agent readiness scanner. It scans any URL across 58 checks and 5 levels — Discoverable, Usable, Optimized, Indexable, and Agent-Native — to measure how ready a site is for AI agents like Claude and GPT.

How do agents call the API?

GET /api/scan?url=https://example.com&format=json, or POST the same endpoint with a JSON body. It is free up to a daily per-caller allowance; beyond that it returns HTTP 402 with x402 payment requirements. There is also an MCP server at /api/mcp and a CLI (npx botvisibility example.com).

How does authentication work?

Public access needs no key. An optional anonymous OAuth 2.0 client-credentials token (scan:read scope) raises the daily allowance — discover it via /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource. An X-API-Key header is also accepted.

How do agents pay for scans?

Over the free allowance, the API returns HTTP 402 pointing at the pay.sh gateway, where an agent settles $0.10 USDC per scan on Solana via the x402 protocol, then receives the full report.

Ready to scan your site?

Run a free scan