SagBot API and MCP docs
Scan sites for AI readiness and check what AI answer engines say about a brand from your own code, CI or coding agent. One token works everywhere.
What you can call
| Surface | Endpoint | What it does |
|---|---|---|
| Scan API | https://api.sagbot.app | Runs SagBot's AI-readiness scan: Agent-ready and Answer-ready scores and every fix. REST, synchronous. |
| AI visibility API | https://api.sagbot.app | Asks AI answer engines a question and reports whether a brand is mentioned and cited. REST, queued. |
| MCP server | https://mcp.sagbot.app/mcp | The same scan as tools for coding agents (Claude Code, Cursor, Codex, VS Code and others). |
Get a token
- Sign in to SagBot (a free account) and open Account → Credentials.
- Create a personal API token. It starts with
sgb_and is shown once, so copy it then. - Keep it in a secret store or an environment variable, for example
SAGBOT_TOKEN, never in a committed file.
The same token works for the Scan API, the AI visibility API and the MCP server. Revoke it on the same page at any time; a revoked token is refused at once.
Authentication
Send the token as a bearer token on every request:
curl "https://api.sagbot.app/v1/usage?days=7" \
-H "Authorization: Bearer $SAGBOT_TOKEN"GET /v1/engines, GET /v1/health and GET /openapi.yaml need no token. A missing, unknown or revoked token gets 401 (unauthorized).
Pricing
Paid calls draw on a prepaid USD balance: top up $10, $25 or $50 at Account → Billing. No subscription, and the balance doesn't expire.
| What | Price |
|---|---|
| Scan of your own verified domain (REST or MCP) | Free |
Stored scan result (cached, or read with GET /v1/scans/latest) | Free |
| New scan of any other site: the first 3 a day (UTC), REST and MCP together | Free |
| Each further new scan of another site | $0.06 |
| AI visibility answer: ChatGPT, Google AI Overviews, Gemini, Google AI Mode, Perplexity | $0.035 |
| AI visibility answer: Claude, ChatGPT API, Gemini API (web search on) | $0.06 |
Paid responses carry two headers: X-Cost-USD (what the call cost) and X-Balance-USD (your balance after it), both as decimal strings with six places, such as 0.060000. Failed AI engine answers are refunded automatically. All prices: Pricing.
Rate limits
| Limit | Applies to |
|---|---|
| 3 a minute per account | Scan calls: POST /v1/scan and the MCP tool scan_site, counted together, cached answers included |
| 10 a minute per token | Paid AI visibility checks (POST /v1/check without dry_run) |
| 60 a minute per IP address | Authenticated requests to api.sagbot.app |
| 60 a minute per IP address | Any request to mcp.sagbot.app |
Over a limit, the REST API answers 429 (rate_limited). Wait a minute and retry.
Errors
Every REST error has the same shape: a stable code to branch on and a message for people.
{
"error": {
"code": "insufficient_balance",
"message": "This check costs $0.210000"
}
}| Status | code | Meaning |
|---|---|---|
| 400 | invalid_request | Bad body or parameter; the message says which |
| 401 | unauthorized | Missing, unknown or revoked token |
| 402 | insufficient_balance | The call costs more than your balance; X-Balance-USD shows what is left |
| 403 | site_hidden | The site's results are hidden by its owner or SagBot and you aren't its verified owner. Not charged |
| 404 | not_found | Unknown endpoint or check id, or a check that isn't yours |
| 404 | no_scans_for_host | GET /v1/scans/latest: no stored scan of that site and type |
| 413 | body_too_large | Request body over 16 KB |
| 429 | rate_limited | Too many requests; see Rate limits |
| 500 | internal | Something went wrong on our side |
The MCP server reports errors the MCP way: a tool result with isError: true and the message as text.
Timeouts and retries
POST /v1/scan has no idempotency key. If it times out, don't post again: the scan still finishes and is stored. Read it with GET /v1/scans/latest, which is free.
A scan usually takes 20 to 60 seconds, so give the request a timeout of at least 90 seconds. A second POST while the first scan is still running starts another scan, which can be charged again.
POST /v1/check takes an Idempotency-Key header: a retry with the same key returns the same check and is never charged twice. See Create a check.
OpenAPI
The REST API is described in openapi.yaml (OpenAPI 3.1), for client generators, Postman or your coding agent.
curl -O https://api.sagbot.app/openapi.yaml