API Reference

Base URL: https://api.a11yrisk.eu

Authentication

CI/CD and report endpoints require an API key in the X-API-Key header. Create keys in Settings → API Keys. Keys have the prefix ar_live_.

Free public scan endpoints require no authentication.

CI/CD Integration

X-API-Key

post/v1/ci/scansSubmit a CI accessibility scan

Queue an accessibility scan from a CI/CD pipeline. Returns HTTP 202 with a `status_url` to poll. Authenticate with `X-API-Key` (create keys in Settings → API Keys). One credit per page scanned. Optional pass/fail thresholds: `min_score`, `max_violations`, `fail_on_severity`.

Request body application/json

Field	Type	Description
url*	uri	Publicly reachable URL to scan. Private/loopback addresses are rejected.
min_score	number?	Fail if accessibility score is below this value (0-100). Omit to skip.
max_violations	integer?	Fail if total violations exceed this count. Omit to skip.
fail_on_severity	"critical" \| "serious" \| "moderate" \| "minor"?	Fail if any violation exists at this severity or higher.
max_pages	integer	Pages to crawl and test. One credit consumed per page.(default: 5)
fail_on_truncation	boolean	Return 402 if credits are insufficient for max_pages. Set false to run a partial scan.(default: true)
wcag_level	"A" \| "AA" \| "AAA"	WCAG conformance level. AA required by EU EAA and US Section 508.(default: AA)
wcag_version	"2.1" \| "2.2"	WCAG version. 2.1 covers most legal requirements.(default: 2.1)

Responses

202Scan accepted and queued.

Field	Type	Description
scan_id*	uuid	Use in GET /v1/ci/scans/{scan_id} to poll results.
status*	string	Always 'queued' at submission time.
status_url*	string	Relative URL to poll. Append to your API base URL.
message*	string
pages_requested*	integer	Number of pages requested in the scan.
pages_reserved*	integer	Credits reserved. May be less than pages_requested if fail_on_truncation=false and balance was low.

402Insufficient credits and fail_on_truncation=true.

422Validation error or disallowed URL.

503Scan queue paused — retry after the Retry-After header.

get/v1/ci/scans/{scan_id}Poll scan status and result

Poll a queued scan for status and, when complete, pass/fail verdict. Returns HTTP 202 while in progress — poll every 5-10 seconds. Returns HTTP 200 when done and thresholds passed (or none set). Returns HTTP 422 when done and any threshold failed.

Path parameters

scan_iduuid

Responses

200Scan complete — all thresholds passed or no thresholds set.

Field	Type	Description
scan_id*	uuid
status*	string	queued \| crawling \| scanning \| aggregating \| generating \| done \| failed \| canceled
score	number?	Overall accessibility score 0-100. Null while scan is in progress.
violations_count	integer?	Total violations across all pages. Null while in progress.
violations_critical	integer?	Count of critical-severity violations.
violations_serious	integer?	Count of serious-severity violations.
violations_moderate	integer?	Count of moderate-severity violations.
violations_minor	integer?	Count of minor-severity violations.
passed	boolean?	True if all thresholds met. False if any failed. Null if no thresholds were set.
report_url	string?	Relative path to download the PDF report once scan is done.
message	string?	Reason for failure when passed=false.

202Scan still in progress — poll again.

422Scan complete — at least one threshold failed.

get/v1/ci/scans/{scan_id}/eventsStream scan progress as server-sent events

SSE stream of real-time scan progress. Connect once after submitting — the stream closes automatically when the scan reaches a terminal state. The final `data:` line carries the full pass/fail verdict and score (same fields as the poll endpoint). Keepalive comments (`: keepalive`) are emitted every 15 seconds; filter them with `grep '^data:'` in shell scripts. Authenticate with `X-API-Key`.

Path parameters

scan_iduuid

Responses

200text/event-stream. Each event is a JSON object on a `data:` line. Progress events: `{event, status, scan_id}`. Terminal event: `{event, scan_id, status, score, violations_count, violations_critical, violations_serious, violations_moderate, violations_minor, passed, message}`.

422Validation Error

Field	Type	Description
detail	object[]

Report Downloads

X-API-Key

get/v1/scans/{scan_id}/reportGet PDF report download URL

Returns a pre-signed URL to download the PDF accessibility report. The URL expires in 60 minutes — fetch the file immediately; do not cache the URL. Authenticate with `X-API-Key` or a dashboard session. Returns 409 if the scan is not yet complete.

Path parameters

scan_iduuid

Responses

200Pre-signed PDF report URL.

Field	Type	Description
url*	string	Pre-signed URL valid for 60 minutes. Fetch immediately; do not cache.
expires_in*	integer	Seconds until the URL expires.

404Report not found.

409Scan is not yet complete.

422Validation Error

Field	Type	Description
detail	object[]

get/v1/scans/{scan_id}/report/jsonGet JSON report download URL

Returns a pre-signed URL to download the JSON scan export. The URL expires in 60 minutes — fetch the file immediately; do not cache the URL. Authenticate with `X-API-Key` or a dashboard session. Returns 404 if no JSON export is available (legacy scans). Returns 409 if the scan is not yet complete.

Path parameters

scan_iduuid

Responses

200Pre-signed JSON export URL.

Field	Type	Description
url*	string	Pre-signed URL valid for 60 minutes. Fetch immediately; do not cache.
expires_in*	integer	Seconds until the URL expires.

404JSON export not available for this scan.

409Scan is not yet complete.

422Validation Error

Field	Type	Description
detail	object[]

Free Public Scan

No auth

post/v1/public/scan-requestSubmit Public Scan

Submit a URL for a free public accessibility scan. Queues one real Playwright+axe scan (single page) under the anonymous ghost organisation. Results are emailed to the supplied address when the scan completes (~2 minutes). Findings are automated test results only and do not constitute compliance evidence or legal certification.

Request body application/json

Field	Type	Description
url*	uri
email*	email
cf_turnstile_token	string	(default: )
locale	"en" \| "de" \| "fr" \| "nl" \| "pl"	(default: en)

Responses

200Successful Response

Field	Type	Description
token*	string
estimated_seconds*	integer

422Validation Error

Field	Type	Description
detail	object[]

get/v1/public/scan-status/{token}Get Scan Status

Poll the status of a public scan. Pass full=true to retrieve all violations.

Path parameters

tokenstring

Query parameters

Field	Type	Description
full	boolean	(default: false)

Responses

200Successful Response

Field	Type	Description
token*	string
status*	string
url*	string
violation_count	integer?
issues	object[]	(default: )
truncated	boolean	(default: false)

422Validation Error

Field	Type	Description
detail	object[]