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

SurfaceEndpointWhat it does
Scan APIhttps://api.sagbot.appRuns SagBot's AI-readiness scan: Agent-ready and Answer-ready scores and every fix. REST, synchronous.
AI visibility APIhttps://api.sagbot.appAsks AI answer engines a question and reports whether a brand is mentioned and cited. REST, queued.
MCP serverhttps://mcp.sagbot.app/mcpThe same scan as tools for coding agents (Claude Code, Cursor, Codex, VS Code and others).

Get a token

  1. Sign in to SagBot (a free account) and open Account → Credentials.
  2. Create a personal API token. It starts with sgb_ and is shown once, so copy it then.
  3. 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.

WhatPrice
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 togetherFree
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

LimitApplies to
3 a minute per accountScan calls: POST /v1/scan and the MCP tool scan_site, counted together, cached answers included
10 a minute per tokenPaid AI visibility checks (POST /v1/check without dry_run)
60 a minute per IP addressAuthenticated requests to api.sagbot.app
60 a minute per IP addressAny 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"
  }
}
StatuscodeMeaning
400invalid_requestBad body or parameter; the message says which
401unauthorizedMissing, unknown or revoked token
402insufficient_balanceThe call costs more than your balance; X-Balance-USD shows what is left
403site_hiddenThe site's results are hidden by its owner or SagBot and you aren't its verified owner. Not charged
404not_foundUnknown endpoint or check id, or a check that isn't yours
404no_scans_for_hostGET /v1/scans/latest: no stored scan of that site and type
413body_too_largeRequest body over 16 KB
429rate_limitedToo many requests; see Rate limits
500internalSomething 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