About the Accessibility Scans API

The Accessibility Scans API lets authorized apps and Wix users check a Wix site for accessibility issues and retrieve results that people, applications, and coding agents can understand and act on.

With the Accessibility Scans API, you can:

• Scan a full site.
• Scan one static, template, or generated page by Wix page ID or site URL.
• Discover and scan every page in an available Wix page collection, including pages created by installed Wix apps.
• Track an asynchronous scan until it finishes.
• Distinguish affected, clear, and failed pages.
• Retrieve paginated findings with severity, WCAG criteria, safe page and element references, remediation guidance, verification steps, and signals for decisions that require human input.

Scan targets

Each run request selects exactly one target:

• Full site: Checks every supported page and site-level rule.
• Page: Checks one page. Specify its Wix page ID when it uniquely identifies the page, or its absolute site URL for a generated page such as a specific product or blog post.
• Page collection: Checks every page in one supported collection. First, call List Accessibility Scan Page Collections. Then specify the returned collection ID without changing it. This supports any page collection currently available on the site without exposing implementation-specific page types.

Multi-page scans support up to 300 pages. The effective maximum can be lower when page metadata is large. If the target is too large, the API returns SCAN_SIZE_LIMIT_EXCEEDED with detectedPageCount and maxPageCount. Choose a narrower target and run another scan.

Asynchronous results

Run Accessibility Scan returns a scan ID immediately. Poll Get Accessibility Scan after the positive suggestedPollIntervalSeconds delay when the response includes it; otherwise, poll every 5 seconds. Stop polling when the status is ACCESSIBILITY_SCAN_STATUS_COMPLETED, ACCESSIBILITY_SCAN_STATUS_PARTIALLY_COMPLETED, or ACCESSIBILITY_SCAN_STATUS_FAILED.

• ACCESSIBILITY_SCAN_STATUS_COMPLETED means every requested check produced a usable result.
• ACCESSIBILITY_SCAN_STATUS_PARTIALLY_COMPLETED means usable results exist, but one or more pages or site-level checks failed. Inspect every page summary before treating the scan as complete.
• ACCESSIBILITY_SCAN_STATUS_FAILED means no usable result was produced. Inspect the public failure, correct the cause, and start a new scan.

Get Latest Accessibility Scan retrieves the most recently stored scan for a target without starting a new scan. Use it when a recent result may already satisfy the request.

Interpret results safely

Get Accessibility Scan returns lifecycle, progress, and aggregate totals. It doesn't return every page or finding. After completion:

1. Page through List Accessibility Scan Page Summaries to inspect every discovered page, including clear and failed pages.
2. Page through List Accessibility Scan Findings for actionable issues. Filter by page, rule, severity, or category when you need a focused result.
3. Check coverage before concluding that a missing finding means a rule or category passed. Coverage contains only checks that ran.

Generated-page references include a stable collection ID and public item ID. Use that identity with the owning Wix public API, such as Stores or Blog, to update the underlying content. Static-page or component changes may need to be applied in the Wix editor. When humanInputRequired is true, ask for the indicated content decision or approval before making the change.

Retry scans safely

Run requests are limited to 5 per minute per Wix site and can return HTTP 429. Wait before retrying. Reuse the same idempotency key when retrying the same intended scan so a lost response can't create duplicate work. Use a new key for a new scan.

If the API returns SCAN_ALREADY_IN_PROGRESS, poll the returned scan ID. If it returns SCAN_STATE_UNKNOWN, retry Get Accessibility Scan with the returned scan ID. Don't start a replacement scan until the existing scan reaches a terminal state.

Before you begin

It's important to note the following points before starting to code:

• The site is derived from the authenticated request. Don't specify a site ID in the request.
• Published sites are scanned from their published version. Unpublished sites are scanned from their latest saved version.
• Detailed results are retained for approximately 6 months. The scan resource includes the exact result-expiration date.
• A page or category is clear only when it has no matching findings, its page status is completed, and its coverage confirms that the relevant checks ran.

Use cases

• Scan, fix, and verify accessibility issues for a full site, one page, or a page collection.
• Reuse a recent scan result.

Terminology

• Scan target: The full site, one page, or one available page collection.
• Page collection: A discoverable group of generated pages, such as store products, blog posts, booking services, events, or restaurant menu pages.
• Coverage: The categories and rules that actually ran, including checks that passed.
• Terminal status: ACCESSIBILITY_SCAN_STATUS_COMPLETED, ACCESSIBILITY_SCAN_STATUS_PARTIALLY_COMPLETED, or ACCESSIBILITY_SCAN_STATUS_FAILED.