Skip to content
Overwatch API

Get the accessibility report

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

The accessibility report from the site’s most recent accessibility run: the issue list plus a per-run summary with the 0–100 score, an AA conformance verdict, POUR-principle rollups, and compliance tallies for EN 301 549 and Section 508. Parallels the dead-link report.

summary.score is null when the latest run didn’t scan (the site is not opted in via a11yEnabled). Suppressions (“Ignore”) and the site’s excludePaths globs are applied here — suppressed and excluded findings are removed from issues and the score is recomputed from what remains, retroactively and reversibly.

Authorizations

Section titled “ Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
id
required
string format: uuid

The site’s UUID.

Responses

Section titled “ Responses ”

200

Section titled “ 200 ”

The latest run, its active issues, summary, and audit layers.

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
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
issues
required

Findings from the latest run, with suppressed and exclude-path findings removed. Each finding is tagged with the standards its rule maps to.

Array

A finding as returned in the report: the persisted row plus the standards its rule maps to and its WCAG success criterion + POUR principle.

object
id
required
string format: uuid
tenant_id
required
string
run_id
required
string format: uuid
page_url
required

The page the finding was made on.

string format: uri
rule
required

The axe-core rule id (e.g. color-contrast, image-alt).

string
impact
required

Axe impact — critical, serious, moderate, or minor.

string | null
wcag
required

The WCAG success criteria the rule maps to.

string | null
help
required

A short human-readable description of the rule.

string
help_url
required

Link to the rule’s documentation.

string format: uri
type
required

violation is confirmed; incomplete needs human review.

string
Allowed values: violation incomplete
count
required

How many elements on the page matched.

integer
nodes
required

JSON-encoded capped example nodes (selector/snippet/summary).

string
created_at
required

Epoch ms.

integer
standards
required
object
wcagLevel
required

The WCAG conformance level of the rule, or null for best-practice rules.

string | null
Allowed values: A AA AAA
en301549
required

Whether the rule falls under EN 301 549 (the EU Accessibility Act’s standard).

boolean
section508
required

Whether the rule falls under US Section 508.

boolean
sc
required

The WCAG success criterion (e.g. 1.1.1), or null.

string | null
principle
required
string | null
Allowed values: Perceivable Operable Understandable Robust
descriptions
required

Per-rule one-line descriptions (“what this checks”), keyed by rule id.

object
key
additional properties
string
w3cUrls
required

Per-rule W3C Understanding-WCAG page URLs, keyed by rule id.

object
key
additional properties
string
gainByRule
required

Score points recoverable by fixing each rule, keyed by rule id — for ranking issues by real impact on the score. Empty when the run has no score.

object
key
additional properties
number
byPage
required

Every page with an active finding, ranked worst-first.

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

The page’s own 0–100 score.

integer
issues
required

Distinct (page, rule) findings on the page.

integer
violations
required

Confirmed violation occurrences.

integer
needsReview
required

Occurrences axe couldn’t decide on.

integer
coverage
required

The WCAG coverage matrix: every success criterion classified as fail (an active violation maps to it), pass (auto-testable and clean), or manual (no automated rule can test it — a human must). Grouped by principle → guideline, ready to render.

object
totals
required
object
fail
required
integer
pass
required
integer
manual
required
integer
total
required
integer
principles
required

The four POUR principles, each with its guidelines and criteria in WCAG order.

Array<object>
object
principle
required
string
Allowed values: Perceivable Operable Understandable Robust
guidelines
required
Array<object>
object
guideline
required
string
criteria
required
Array<object>
object
sc
required
string
name
required
string
level
required
string
Allowed values: A AA AAA
status
required
string
Allowed values: fail pass manual
pages
required

Distinct pages with a violation mapping to this SC.

integer
rules
required

The axe rule ids that failed this SC.

Array<string>
w3cUrl
required

The criterion’s W3C “Understanding” page.

string format: uri
manualChecks
required

Manual WCAG review states, keyed by success criterion (e.g. "2.1.4"). A documentation layer — it never affects the score or verdict.

object
key
additional properties
object
status
required
string
Allowed values: verified not_applicable failed
note
required
string | null
by
required

The user who set the state, if known.

string | null
at
required

Epoch ms of the last change.

integer
summary
required

Per-run accessibility summary. Severity counts reflect the exclusion-filtered findings; the score additionally reflects suppressions.

object
score
required

0–100 score recomputed after suppressions, or null when the run didn’t scan.

integer | null
<= 100
critical
required
integer
serious
required
integer
moderate
required
integer
minor
required
integer
pagesScanned
required
integer
verdict
required

The pass/fail conformance judgment at the AA target level, decoupled from the score: any confirmed violation of a level-A or -AA success criterion breaks conformance (AAA and best-practice rules don’t).

object
compliant
required
boolean
targetLevel
required
string
Allowed value: AA
risk
required

Legal-exposure band when not compliant; null when compliant.

string | null
byPrinciple
required

Active findings rolled up by POUR principle.

object
key
additional properties
object
violations
required
integer
needsReview
required
integer
pages
required
integer
resolvedSinceLastScan
required

Violations present in the previous scan but gone in this one.

integer
compliance
required

How many active rules/occurrences fall under each legal standard.

object
en301549
required
object
rules
required

Distinct rules with active findings under the standard.

integer
occurrences
required

Total matched elements across those findings.

integer
section508
required
object
rules
required

Distinct rules with active findings under the standard.

integer
occurrences
required

Total matched elements across those findings.

integer
suppressions
required
Array<object>

A suppression as returned in the report, with how many current findings it hides.

object
id
required
string format: uuid
rule
required
string
selector
required
string | null
page_url
required
string | null
reason
required
string | null
created_at
required

Epoch ms.

integer
matchedCount
required

How many of the latest run’s findings this suppression hides.

integer
Example
{
  "run": {
    "state": "running",
    "kind": "crawl"
  },
  "issues": [
    {
      "type": "violation",
      "standards": {
        "wcagLevel": "A"
      },
      "principle": "Perceivable"
    }
  ],
  "coverage": {
    "principles": [
      {
        "principle": "Perceivable",
        "guidelines": [
          {
            "criteria": [
              {
                "level": "A",
                "status": "fail"
              }
            ]
          }
        ]
      }
    ]
  },
  "manualChecks": {
    "additionalProperty": {
      "status": "verified"
    }
  },
  "summary": {
    "verdict": {
      "targetLevel": "AA"
    }
  }
}

401

Section titled “ 401 ”

Missing or invalid credentials.

Media typeapplication/json
object
error
required

A human-readable error message.

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

404

Section titled “ 404 ”

The site was not found, or it has no runs yet.

Media typeapplication/json
object
error
required

A human-readable error message.

string
Example
{
  "error": "no runs yet"
}