Skip to content

Get the AI readiness report

GET
/v1/sites/{id}/ai-report
curl --request GET \
--url https://api.overwatch.weareheavy.dev/v1/sites/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/ai-report \
--header 'x-api-key: <x-api-key>'

The AI readiness report, derived live from the latest crawl that captured AI signals: findings grouped by rule (ranked by severity, then by recoverable score points), a worst-first per-page view, and a summary with the 0-100 score, a verdict and the per-bot robots.txt access table.

The score measures whether AI assistants can read and cite the site, not whether they currently mention it. Training-bot blocks and llms.txt are reported as notes and never scored.

Issues are derived at read time from per-page snapshots, so changes to the site’s excludePaths globs apply retroactively. The score frozen on the run row feeds the trend; the report’s live score can differ briefly after a settings change.

id
required
string format: uuid

The site’s UUID.

The latest AI-capturing run, its findings, and summary.

Media typeapplication/json
object
run
required

A single crawl run and its summary metrics.

object
id
required
string format: uuid
tenant_id
required
string
site_id
required
string format: uuid
started_at
required

Epoch ms the run started.

integer
finished_at
required

Epoch ms the run finished, or null while running.

integer | null
state
required
string
Allowed values: running completed failed
pages_crawled
required
integer
links_checked
required
integer
broken_count
required

Distinct broken link targets found in the run.

integer
pages_with_broken_count
required

Distinct source pages that had at least one broken link.

integer
internal_broken
required
integer
external_broken
required
integer
a11y_score
required

Synthesized 0–100 accessibility score, or null when the run didn’t scan.

integer | null
<= 100
a11y_critical
required

Confirmed violations with critical impact.

integer
a11y_serious
required
integer
a11y_moderate
required
integer
a11y_minor
required
integer
a11y_pages_scanned
required

Internal pages the accessibility scan covered in this run.

integer
a11y_issue_count
required

Distinct confirmed (page, rule) accessibility violations this run (0 for crawl runs).

integer
a11y_resolved
required

Violations present in the previous accessibility run but gone in this one (the “fixed” trend).

integer
seo_score

Synthesized 0-100 SEO score, or null when the run didn’t extract SEO data.

integer | null
<= 100
seo_critical
integer
seo_serious
integer
seo_moderate
integer
seo_minor
integer
seo_pages_scanned

Pages an SEO snapshot was captured for (at most pages_crawled).

integer
seo_issue_count

Derived SEO issues at the time the run finalized.

integer
ai_score

Synthesized 0-100 AI readiness score, or null when the run didn’t capture AI signals.

integer | null
<= 100
ai_critical
integer
ai_serious
integer
ai_moderate
integer
ai_minor
integer
ai_pages_scanned

Pages an AI snapshot was captured for (at most pages_crawled).

integer
ai_issue_count

Derived AI readiness issues at the time the run finalized.

integer
ai_site_facts

JSON-encoded site-wide facts captured at seed (llmsTxt, cloudflare, trainingBlocked), or null. The /ai-report summary.notes is the parsed form.

string | null
seo_new

SEO issues opened this run. null on starting-point and pre-lifecycle runs.

integer | null
seo_resolved

SEO issues fixed this run (the page was crawled and the rule no longer fires).

integer | null
seo_gone

SEO issues closed because their page is no longer crawled. Not counted as fixed.

integer | null
seo_reopened

Fixed SEO issues that came back this run.

integer | null
pages_challenged

Pages that answered with a bot-protection challenge instead of their content. null on runs from before crawl-health tracking.

integer | null
pages_blocked

Pages that refused access (401/403, or still rate-limited after every retry). Never reported as broken. null on runs from before tracking.

integer | null
pages_rate_limited

Pages that were rate-limited at least once (the crawl slowed down and retried). null on runs from before tracking.

integer | null
error
required

Failure reason if state is failed, otherwise null.

string | null
kind
required

crawl for a broken-link crawl, a11y for a standalone accessibility scan.

string
Allowed values: crawl a11y
byRule
required

Findings grouped per rule, most severe and most impactful first.

Array<object>
object
rule
required

Stable rule id (e.g. ai-search-bot-blocked, ai-content-js-only).

string
severity
required
string
Allowed values: critical serious moderate minor
title
required
string
help
required

One-paragraph editor-facing remediation guidance.

string
siteWide
required

true for a rule evaluated once for the whole site (ai-no-organization). It has no examples and counts against every scanned page.

boolean
pages
required

Pages affected by this rule (all scanned pages when siteWide).

integer
gain
required

Score points recoverable by fixing this rule site-wide.

integer
examples
required

Affected pages (capped); empty for site-wide rules.

Array<object>
object
url
required
string format: uri
detail
required
string | null
content
required
string | null
byPage
required

Every page with at least one finding, ranked worst-first. Site-wide findings are not listed here.

Array<object>
object
url
required
string format: uri
score
required

The page’s own 0-100 score.

integer
issues
required
integer
findings
required
Array<object>
object
rule
required
string
severity
required
string
Allowed values: critical serious moderate minor
title
required
string
detail
required
string | null
content
required
string | null
summary
required
object
score
required
integer
<= 100
critical
required
integer
serious
required
integer
moderate
required
integer
minor
required
integer
issueCount
required
integer
pagesScanned
required
integer
verdict
required
object
status
required

blocked when a major AI search bot is blocked on at least a quarter of the scanned pages; otherwise hard-to-read when any critical or serious finding exists; else readable.

string
Allowed values: readable hard-to-read blocked
bots
required

Per-bot robots.txt access rolled up across the scanned pages, in catalog order. search bots are scored; training bots are noted only.

object
search
required
Array<object>

One AI crawler’s robots.txt access across the scanned pages.

object
agent
required

The robots.txt product token (e.g. OAI-SearchBot).

string
operator
required
string
purpose
required
string
status
required

allowed = no page blocked, partial = some pages blocked, blocked = every page blocked.

string
Allowed values: allowed partial blocked
note
required

Extra context for the bot, if any (e.g. Google-Extended also affects Gemini grounding).

string | null
training
required
Array<object>

One AI crawler’s robots.txt access across the scanned pages.

object
agent
required

The robots.txt product token (e.g. OAI-SearchBot).

string
operator
required
string
purpose
required
string
status
required

allowed = no page blocked, partial = some pages blocked, blocked = every page blocked.

string
Allowed values: allowed partial blocked
note
required

Extra context for the bot, if any (e.g. Google-Extended also affects Gemini grounding).

string | null
notes
required

Facts reported for information; never scored.

object
llmsTxt
required
One of:
object
url
required
string format: uri
present
required
boolean
cloudflare
required

Whether the front page is served through Cloudflare; null when the front page was not seen.

boolean | null
crawlHealth

Pages this crawl couldn’t read the way a visitor would, from the run’s pages_challenged / pages_blocked / pages_rate_limited. null when every page came through, or on runs from before tracking. Challenged and blocked pages are missing from the report’s findings.

object
challenged
required
integer
blocked
required
integer
rateLimited
required
integer
Example
{
"run": {
"state": "running",
"kind": "crawl"
},
"byRule": [
{
"severity": "critical"
}
],
"byPage": [
{
"findings": [
{
"severity": "critical"
}
]
}
],
"summary": {
"verdict": {
"status": "readable"
},
"bots": {
"search": [
{
"status": "allowed"
}
],
"training": [
{
"status": "allowed"
}
]
}
}
}

Missing or invalid credentials.

Media typeapplication/json
object
error
required

A human-readable error message.

string
Example
{
"error": "invalid api key"
}

The site was not found, the AI readiness app is not enabled, or no completed crawl has captured AI signals yet.

Media typeapplication/json
object
error
required

A human-readable error message.

string
Examples

App not installed

{
"error": "AI readiness is not enabled for this site"
}