Scan API
Run SagBot's AI-readiness scan over REST, from a script or CI: both scores and every failed or partial check with its fix, in one JSON response.
Overview
It is the scan behind sagbot.app and the MCP tool scan_site. SagBot fetches the public site, so deploy your changes (or use a public preview URL) before you scan again. Scans you run through the API show up in your Dashboard.
- Base URL:
https://api.sagbot.app - Auth:
Authorization: Bearer sgb_…(get a token) - Field names are snake_case; times are ISO 8601 in UTC.
Run a scan
POST /v1/scansynchronous, 20–60 s
| Field | Type | Description |
|---|---|---|
domain | string, required | Domain or URL of the live site, such as example.com |
site_type | string | content (blog, docs, marketing; the default), app (SaaS, web app) or shop |
rescan | boolean | true runs a fresh scan instead of reusing a recent one. Default false |
curl -X POST https://api.sagbot.app/v1/scan \
-H "Authorization: Bearer $SAGBOT_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "domain": "example.com", "site_type": "content", "rescan": false }'Recent results are reused. If the same site and type were scanned in the last 60 minutes (5 minutes when that scan didn't complete), you get the stored result with cached: true, for free. With rescan: true SagBot scans again, at most once per site every 2 minutes; inside that window you get the site's newest stored scan and rescan_in_seconds. That scan may be of another site_type, so check the site_type in the response.
Every POST counts toward the 3 scan calls a minute, cached answers included.
Response
200 with the scan. Fix texts are shortened here:
{
"host": "example.com",
"site_type": "content",
"scanned_at": "2026-11-17T09:41:07.000Z",
"cached": false,
"complete": true,
"scores": { "agent_ready": 62, "answer_ready": 71 },
"fixes": [
{
"id": "agent-llms-txt",
"title": "llms.txt",
"status": "fail",
"fix": "https://example.com/llms.txt returns HTTP 404. Serve /llms.txt as plain text or Markdown: an H1 with the site name, …"
},
{
"id": "seo-canonical",
"title": "Canonical URL",
"status": "partial",
"fix": "The homepage of example.com has no canonical link. Add exactly one absolute <link rel=\"canonical\"> in <head> …"
}
],
"could_not_verify": [{ "id": "agent-mcp-card", "title": "MCP server card" }],
"counts": { "pass": 31, "info": 4, "na": 3 },
"report": "https://sagbot.app/d/example.com",
"cost_usd": 0.06
}| Field | Description |
|---|---|
host | The host that was scanned, after redirects |
site_type | content, app or shop |
scanned_at | When the scan ran |
cached | true for a stored result; never charged |
rescan_in_seconds | Only after rescan: true inside the 2-minute window: seconds until a fresh scan is possible |
complete | false when the site couldn't be fully scanned (down, blocked, opted out) |
fail_reason | Only when complete is false: why |
scores | agent_ready and answer_ready, 0 to 100, or null when there is nothing to score |
fixes | Every failed or partial check, highest impact first: id, title, status (fail or partial) and fix, instructions written for a coding agent |
could_not_verify | Checks SagBot couldn't decide (id, title) |
counts | How many checks passed (pass), are informational (info) or don't apply (na) |
report | The public report page on sagbot.app |
cost_usd | What this call cost: 0 or 0.06. POST only |
Headers: X-Cost-USD on every scan; X-Balance-USD when the call was paid. Both are decimal strings with six places.
HTTP/2 200
content-type: application/json
x-cost-usd: 0.060000
x-balance-usd: 9.940000Read the latest scan
GET /v1/scans/latest?domain=…&site_type=…free
Returns the newest stored scan of a site and type, complete or not, without scanning. It is free and doesn't count toward the 3 scan calls a minute. site_type defaults to content. The body is the scan above, without cost_usd, and cached is always true. No scan yet: 404no_scans_for_host.
curl "https://api.sagbot.app/v1/scans/latest?domain=example.com&site_type=content" \
-H "Authorization: Bearer $SAGBOT_TOKEN"What a scan costs
- A stored result (
cached: true) is free. - Scans of your own verified domains are free, with no cap, unless the domain redirects to another site.
- Other sites: the first 3 new scans a day (UTC) are free, shared with the MCP server. Each further one costs $0.06 from your balance.
- A scan that ends with
complete: false(the site was down or blocked us) still counts and is charged. - A scan that fails on our side, or is cut off, costs no money: you pay only once the result is stored. It, and a
402answer, still use one of the day's 3 free scans.
When a paid scan finds the balance short, the call returns 402 with your balance in X-Balance-USD:
{
"error": {
"code": "insufficient_balance",
"message": "Today's 3 free scans of other sites are used. Each further scan costs $0.06 from your balance: top up at https://sagbot.app/account/billing. Scans of your own verified domains are free, unless the domain redirects to another site."
}
}Timeouts in scripts and CI
There is no idempotency key on POST /v1/scan. After a timeout, don't post again: the scan finishes anyway. Read it with GET /v1/scans/latest and compare scanned_at.
# Scan. On a timeout (curl exit 28) read the stored result instead of posting again;
# on an HTTP error (402, 429, 5xx) print it and fail the job.
curl -sS --fail-with-body --max-time 90 -X POST https://api.sagbot.app/v1/scan \
-H "Authorization: Bearer $SAGBOT_TOKEN" -H "Content-Type: application/json" \
-d '{ "domain": "example.com" }' > scan.json && rc=0 || rc=$? # works under set -e (GitHub Actions)
if [ $rc -eq 28 ]; then
sleep 30
curl -sS --fail-with-body "https://api.sagbot.app/v1/scans/latest?domain=example.com" \
-H "Authorization: Bearer $SAGBOT_TOKEN" > scan.json || exit 1
elif [ $rc -ne 0 ]; then
cat scan.json; exit 1
fi
jq '{ scanned_at, scores }' scan.jsonErrors
Errors use the shared shape { "error": { "code", "message" } }.
| Status | code | When |
|---|---|---|
| 400 | invalid_request | Missing, too long or unreadable domain, or an unknown site_type |
| 401 | unauthorized | Missing, unknown or revoked token |
| 402 | insufficient_balance | Today's free scans are used and the balance is under $0.06 |
| 403 | site_hidden | The site's results are hidden by its owner or SagBot and you aren't its verified owner. Not charged |
| 404 | no_scans_for_host | GET /v1/scans/latest only: nothing stored for that site and type |
| 413 | body_too_large | Body over 16 KB |
| 429 | rate_limited | More than 3 POST /v1/scan calls a minute on your account (cached answers and MCP scan_site calls included), or 60 requests a minute from your IP |