Skip to main content
This guide starts a scan with the API, waits for it to finish, and fails the build if the surface has open critical issues. It uses curl and jq, so it runs in most CI systems.
Starting scans with an API key needs a plan that includes API triggers: Pro, an active trial, or Enterprise.

1. Find the domain’s slug

Keep the slug for the scan routes and the id for filtering issues.

2. Start the scan

An empty body scans every active page with the surface’s own WCAG target and engines. You can override them: The response is a list of scan runs, one per engine. Most surfaces run one engine, so there is usually one run. Keep its id. If a scan is already running on the domain, the request fails with 409 and names the running scan in conflicts. If there’s nothing to scan, it fails with 422 and reason set to no_active_pages or no_unscanned_pages.

3. Wait for it to finish

Poll GET /v1/scans/{id} until status is complete, failed, or canceled:
A large site can take a while. Poll every 30 seconds or so rather than continuously.

4. Read the results

The domain summary has the open issue counts by severity:
To list the open critical issues, pass the domain’s id from step 1 as DOMAIN_ID:

Full example: GitHub Actions

Add your key as a repository secret named ILITY_API_KEY, then run this after your deploy step:
.github/workflows/accessibility.yml