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

FieldTypeDescription
domainstring, requiredDomain or URL of the live site, such as example.com
site_typestringcontent (blog, docs, marketing; the default), app (SaaS, web app) or shop
rescanbooleantrue 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
}
FieldDescription
hostThe host that was scanned, after redirects
site_typecontent, app or shop
scanned_atWhen the scan ran
cachedtrue for a stored result; never charged
rescan_in_secondsOnly after rescan: true inside the 2-minute window: seconds until a fresh scan is possible
completefalse when the site couldn't be fully scanned (down, blocked, opted out)
fail_reasonOnly when complete is false: why
scoresagent_ready and answer_ready, 0 to 100, or null when there is nothing to score
fixesEvery failed or partial check, highest impact first: id, title, status (fail or partial) and fix, instructions written for a coding agent
could_not_verifyChecks SagBot couldn't decide (id, title)
countsHow many checks passed (pass), are informational (info) or don't apply (na)
reportThe public report page on sagbot.app
cost_usdWhat 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.940000

Read 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 402 answer, 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.json

Errors

Errors use the shared shape { "error": { "code", "message" } }.

StatuscodeWhen
400invalid_requestMissing, too long or unreadable domain, or an unknown site_type
401unauthorizedMissing, unknown or revoked token
402insufficient_balanceToday's free scans are used and the balance is under $0.06
403site_hiddenThe site's results are hidden by its owner or SagBot and you aren't its verified owner. Not charged
404no_scans_for_hostGET /v1/scans/latest only: nothing stored for that site and type
413body_too_largeBody over 16 KB
429rate_limitedMore 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