AccessPreflightAPI documentation
Open console
Scan workflows

Scan a URL or supplied HTML

URL scans render a public page in an isolated Chromium worker and run supported web checks. Supplied HTML scans analyze content you provide and disable external network access by default.

Public URL scan

Use a fully qualified http or https URL. The worker validates redirects and subresources against the safe-egress policy. Private, loopback, link-local, metadata, credential-bearing, and otherwise unsafe destinations are rejected.

{
  "environment": "test",
  "asset": {
    "type": "url",
    "url": "https://example.com/products",
    "viewport": "desktop",
    "wait": {
      "strategy": "dom_ready",
      "timeout_ms": 15000
    }
  },
  "profiles": ["wcag-2.2-aa-web@1.2.0"]
}

The response records the normalized submitted URL in the tenant-scoped scan. A website can redirect or change between runs, so preserve the scan timestamp and engine versions when comparing evidence.

Choose a wait strategy deliberately

Strategy Use when Trade-off
dom_ready Server-rendered pages and most conventional sites Fastest; late client content may not be present
network_idle The application loads important content after DOM ready Slower; bounded by timeout_ms
selector One stable element proves the tested state is ready Most precise; brittle selectors can time out

A wait strategy is not an authentication journey. A type: url scan observes one unauthenticated page state; it does not log in, complete a checkout, or prove an entire service is accessible. Use a whole-site scan for public same-origin page discovery.

timeout_ms must be 1,000–30,000 milliseconds. When the selected readiness condition is reached, the worker finishes requests already in flight once and then freezes the page network boundary. Analytics, long polling, refreshes, or other requests created after readiness are blocked and recorded as post_readiness_request_blocked reduced coverage; they cannot prolong the scan. For client-rendered applications, prefer a stable selector that marks the exact state you intend to test.

Desktop and mobile are separate observations

Use desktop for a 1440 × 900 viewport and mobile for a 390 × 844 viewport. Responsive content can differ materially, so scan both when the release depends on both layouts.

Raw HTML up to 1 MiB

For a small self-contained fragment or document, put html directly in the scan request.

{
  "environment": "test",
  "asset": {
    "type": "html",
    "html": "<!doctype html><html lang=\"en\"><title>Example</title><main><h1>Example</h1></main></html>"
  },
  "profiles": ["wcag-2.2-aa-web@1.2.0"]
}

External network access is disabled for supplied HTML. A missing remote image or stylesheet reduces relevant coverage; it does not automatically become an accessibility failure.

HTML bundles

For larger HTML or a static bundle, use the server-mediated upload flow with application/zip or text/html, wait until the upload is ready, then create an HTML scan with the upload ID.

{
  "asset": {
    "type": "html",
    "upload_id": "upl_REPLACE_ME"
  }
}

The public API uses type: html with upload_id for an uploaded bundle. A plain uploaded .html file may use the same shape. The ZIP contract is exact:

index.html                 required entry document
assets/site.css            optional local stylesheet
assets/logo.svg            optional local image
fonts/interface.woff2      optional local font
  • index.html must exist at the archive root and be detected as HTML. Custom entry paths are not part of the public API contract.
  • Paths use relative POSIX syntax. Absolute paths, .., NUL bytes, Windows drive prefixes, symlinks, duplicate paths, and encrypted entries are rejected.
  • The bundle may contain at most 5,000 entries and 20 MiB of expanded content. The web worker also enforces its 20 MiB bundle input limit even though the general upload endpoint accepts larger document files.
  • Relative HTML, CSS, images, and fonts are served from a synthetic isolated origin. Missing local resources return 404 and reduce coverage.
  • Scripts, forms, frames, objects, remote resources, and outbound connections are disabled. A bundle is a static-page preflight, not an application runtime.

The intake service validates media type, archive expansion, package integrity, malware state, and safety limits before the scan can start. Unsupported or unsafe bundles fail explicitly; they are not silently scanned as partial HTML.

Diagnose a URL failure

When a scan is terminal but not completed, inspect failure.code, failure.phase, failure.retryable, failure.failed_at, and failure.support_reference. The last value is safe to provide to support; it does not expose worker or target details. Common classes are safe-egress rejection, DNS/fetch failure, navigation timeout, unsupported content, and engine failure. Do not blindly retry deterministic policy rejections. See scan lifecycle for retry guidance.

Search documentation