Skip to content
Overwatch API

Trigger an accessibility scan

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

Start just the accessibility render pass over the already-persisted page set — no re-crawl. Same permissions as triggering a crawl.

  • 202 Accepted — a scan was started (started: true).
  • 200 OK — a no-op: a crawl or scan is already in flight, or there is no persisted page set yet (started: false).

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 ”

Nothing was started (busy, or no page set yet).

Media typeapplication/json

The result of triggering a crawl.

object
started
required

true if a new crawl was started, false if one was already running.

boolean
status
required

Live crawl state from the crawler. Unlike persisted records, these are camelCase counters describing the in-progress run.

object
state
required
string
Allowed values: seeding crawling idle
runId
required
string format: uuid
pagesCrawled
required
integer
linksChecked
required
integer
brokenCount
required
integer
inFlight
required

URLs currently leased and being checked.

integer
pending
required

URLs waiting in the frontier to be leased.

integer
window
required

The adaptive in-flight window size.

integer
Example
{
  "status": {
    "state": "seeding"
  }
}

202

Section titled “ 202 ”

A new accessibility scan was started.

Media typeapplication/json

The result of triggering a crawl.

object
started
required

true if a new crawl was started, false if one was already running.

boolean
status
required

Live crawl state from the crawler. Unlike persisted records, these are camelCase counters describing the in-progress run.

object
state
required
string
Allowed values: seeding crawling idle
runId
required
string format: uuid
pagesCrawled
required
integer
linksChecked
required
integer
brokenCount
required
integer
inFlight
required

URLs currently leased and being checked.

integer
pending
required

URLs waiting in the frontier to be leased.

integer
window
required

The adaptive in-flight window size.

integer
Example
{
  "status": {
    "state": "seeding"
  }
}

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"
}

403

Section titled “ 403 ”

The caller’s role or key scope does not allow this action.

Media typeapplication/json
object
error
required

A human-readable error message.

string
Example
{
  "error": "only owners and admins can edit site settings"
}

404

Section titled “ 404 ”

No site with that id is visible to the caller.

Media typeapplication/json
object
error
required

A human-readable error message.

string
Example
{
  "error": "site not found"
}

409

Section titled “ 409 ”

The Accessibility app is not enabled for this site.

Media typeapplication/json
object
error
required

A human-readable error message.

string
Example
{
  "error": "accessibility scanning is not enabled for this site"
}