Skip to content

API reference

Your UX Agent API

Version 1.0.0. Read your audits and findings, quote and start audits, and set a finding's status from your own tools. This page is rendered from the API's OpenAPI document.

Before you start

You create an API key in Settings › Integrations. A key belongs to your account and reaches only the projects you choose when you create it. Every key can read. You choose whether it can also run audits and change finding status. Version 1 reads your projects, audits, findings and finding ledger, quotes and starts audits, and sets the status of a finding.

Our CI gate is one script with no dependencies that uses this API. It quotes an audit, starts it with your commit as the reference, waits for it to finish, and by default fails the job when the audit finds critical or high findings that are new or have come back. It runs wherever Node 20 or newer does, such as a GitHub Actions or GitLab CI job. Read the script before you run it, or take the GitLab CI template.

Tools can read this reference as an OpenAPI 3.1 document at /api/v1/openapi.json. It needs no key.

How the API works

Base address: https://youruxagent.com/api/v1

Read your projects, audits, findings and finding ledger with an API key, quote and start audits with a key that has the run audits permission, and mark findings fixed, accepted or open with a key that has the write findings permission.

Send the key as Authorization: Bearer uxa_.... A key belongs to your account, is limited to the projects chosen when it was created, and acts as the member who created it: it stops working when that member leaves.

Times are Unix seconds. Every URL we return is masked: a query value that looks like a secret is replaced.

Lists return totals, items and nextCursor. Pass limit (1 to 100, default 25) and the nextCursor of the previous page as cursor. A cursor belongs to one list and its filters.

Errors are { "error": "snake_case_code" }. A project or audit outside the key's scope is 404, the same as one that does not exist. A key without a permission an endpoint needs gets 403 permission_required.

Starting an audit is two steps. Quote it, then start it with the quote's operationId within 10 minutes; calling the start confirms the spend. Nothing is charged by a quote or by a refused start. Send a reference such as a commit SHA to make a retry return the run the first call started.

bearerAuth: HTTP bearer authentication. An API key created in Settings › Integrations › API keys. It starts with uxa_.

Endpoints

This document

GET /openapi.json

The OpenAPI 3.1 document of this API. It needs no key and may be cached for an hour.

Needs no API key.

Responses

StatusWhat it meansBody
200

OpenAPI document

object
404
  • not_found: the API is not switched on for this server.
Error

The key making the call

GET /key

The key's name, last four characters, permissions, projects and dates. Never its secret.

Needs an API key sent as Authorization: Bearer uxa_….

Responses

StatusWhat it meansBody
200

The key

Key
400
  • invalid_request: a query parameter or body field is not allowed, or the body is not JSON. field names it (query or body for the whole); its value is not echoed.
Error
401
  • invalid_api_key: the key is missing, malformed, unknown, revoked or expired, or its creator can no longer use the account. One code for all of them, with WWW-Authenticate: Bearer.

Header WWW-Authenticate: Always Bearer.

Error
403
  • terms_acceptance_required: the key's creator has not agreed to the current terms.
Error
429
  • rate_limited: a key may make 120 calls a minute, and an address with many failed keys is refused for a while.

Header Retry-After: Seconds to wait before calling again.

Error
503
  • api_unavailable: we could not read what you asked for. Try again.
Error

The key's projects

GET /projects

The projects the key was given, by name, each with its URLs and the latest completed audit that is not archived.

Needs an API key sent as Authorization: Bearer uxa_….

Parameters

NameTypeDescription
limit
query, optional
integer
1 to 100
default 25
How many items to return, 1 to 100. Default 25.
cursor
query, optional
string
1 to 2000 characters
The nextCursor of the previous page of the same list, exactly as returned.

Responses

StatusWhat it meansBody
200

A page of projects

ProjectList
400
  • invalid_request: a query parameter or body field is not allowed, or the body is not JSON. field names it (query or body for the whole); its value is not echoed.
  • invalid_cursor: the cursor is not one we issued, or belongs to another list or other filters.
Error
401
  • invalid_api_key: the key is missing, malformed, unknown, revoked or expired, or its creator can no longer use the account. One code for all of them, with WWW-Authenticate: Bearer.

Header WWW-Authenticate: Always Bearer.

Error
403
  • terms_acceptance_required: the key's creator has not agreed to the current terms.
Error
409
  • cursor_list_changed: the list changed since the cursor was made. Start again from the first page.
Error
429
  • rate_limited: a key may make 120 calls a minute, and an address with many failed keys is refused for a while.

Header Retry-After: Seconds to wait before calling again.

Error
503
  • api_unavailable: we could not read what you asked for. Try again.
Error

A project's audits

GET /projects/{projectId}/audits

The project's audits, newest first. Archived audits are not listed.

Needs an API key sent as Authorization: Bearer uxa_….

Parameters

NameTypeDescription
projectId
path, required
stringThe project's id.
limit
query, optional
integer
1 to 100
default 25
How many items to return, 1 to 100. Default 25.
cursor
query, optional
string
1 to 2000 characters
The nextCursor of the previous page of the same list, exactly as returned.
status
query, optional
string
one of "queued", "running", "completed", "failed", "cancelled"
Only audits in this status.

Responses

StatusWhat it meansBody
200

A page of audits

AuditList
400
  • invalid_request: a query parameter or body field is not allowed, or the body is not JSON. field names it (query or body for the whole); its value is not echoed.
  • invalid_cursor: the cursor is not one we issued, or belongs to another list or other filters.
Error
401
  • invalid_api_key: the key is missing, malformed, unknown, revoked or expired, or its creator can no longer use the account. One code for all of them, with WWW-Authenticate: Bearer.

Header WWW-Authenticate: Always Bearer.

Error
403
  • terms_acceptance_required: the key's creator has not agreed to the current terms.
Error
404
  • project_not_found: no such project in this key's scope. A project that does not exist, one of another account and one the key was not given answer the same.
Error
429
  • rate_limited: a key may make 120 calls a minute, and an address with many failed keys is refused for a while.

Header Retry-After: Seconds to wait before calling again.

Error
503
  • api_unavailable: we could not read what you asked for. Try again.
Error

Start an audit

POST /projects/{projectId}/audits

Starts the audit a quote priced. Calling it confirms the spend (confirmed is implied): send the operationId of a quote made in the last 10 minutes for the same selection, and elevatedConfirmation: true when the quote says requiresElevatedConfirmation. Answers 202 with the audit when this call started it; poll GET /audits/{auditId}. A repeat of the same operationId, or of the same reference in this project, answers 200 with the existing audit and charges nothing, even when its quote has expired. A start that is refused charges nothing. The key needs the run audits permission, and the audit is recorded as started by the key and its creator.

Needs an API key sent as Authorization: Bearer uxa_….

Parameters

NameTypeDescription
projectId
path, required
stringThe project's id.

Request body

Sent as application/json, required: StartAuditRequest.

NameTypeDescription
mode
required
string
one of "full", "url"
full audits the project's site; url audits one address.
url
optional
string
up to 2048 characters
For mode url: the address to audit. An address copied from one of our answers, whose secret value is replaced, is refused.
projectUrlId
optional
string
1 to 100 characters
One of the project's URLs, from GET /projects. For mode full, the one to audit; for mode url, the one the address belongs to.
label
optional
string
up to 160 characters
For mode url: a label for the address.
depth
optional
string
one of "standard", "deep"
standard by default. deep walks the same goal once per chosen persona and needs personas.
personas
optional
array of string
up to 10 items
each item: 1 to 80 characters
At depth deep only: one to three persona keys.
operationId
required
string
1 to 64 characters
The operationId of a quote made in the last 10 minutes for this same selection.
elevatedConfirmation
optional
booleanSend true to accept the spend when the quote has requiresElevatedConfirmation. A pipeline that sets it accepts that spend on every run.
reference
optional
string
1 to 180 characters
matches ^[^\p{Cc}\p{Cf}\p{Zl}\p{Zp}]+$
Your idempotency reference, 1 to 180 characters, for example a commit SHA. A second start in the same project with the same reference returns the run the first one started, with 200 and no charge, even when its quote has expired. It is per project and case-sensitive. A reference that already has an audit returns it whatever operationId is sent; archiving an audit clears its reference, so the next start with it is a new audit, and a start whose operationId already started an audit that was archived since is refused as operation_input_mismatch.

Responses

StatusWhat it meansBody
200

The audit this call, or an earlier one with the same operationId or reference, started

AuditDetail
202

The audit this call started

AuditDetail
400
  • invalid_request: a query parameter or body field is not allowed, or the body is not JSON. field names it (query or body for the whole); its value is not echoed.
  • masked_url_input: url is an address copied from one of our answers, where a secret query value is replaced. Send the real address.
  • invalid_target_url: url is not an address we can audit.
  • audit_target_mismatch: url is not the address of projectUrlId.
  • invalid_depth: depth is not standard or deep.
  • invalid_personas: personas is not a list of persona keys.
  • personas_require_deep: personas is only for depth deep.
  • personas_required: depth deep needs one to three personas.
  • too_many_personas: more personas than a deep audit walks.
  • unknown_persona: a persona key is not one we know.
  • deep_unavailable_for_url: depth deep is not available for a single-address audit.
Error
401
  • invalid_api_key: the key is missing, malformed, unknown, revoked or expired, or its creator can no longer use the account. One code for all of them, with WWW-Authenticate: Bearer.

Header WWW-Authenticate: Always Bearer.

Error
403
  • permission_required: the key lacks the permission; permission names it. Checked before anything else is read or charged.
  • email_unverified: the account owner's email is not verified yet.
  • terms_acceptance_required: the key's creator has not agreed to the current terms.
Error
404
  • project_not_found: no such project in this key's scope. A project that does not exist, one of another account and one the key was not given answer the same.
  • project_url_not_found: projectUrlId is not one of the project's URLs.
  • audit_not_found: no such audit in this key's scope, the same answer for every case, an archived audit included.
Error
409
  • primary_url_required: the project has no primary URL to audit.
  • audit_source_required: there is nothing to audit: no pages were found for this selection.
  • transport_confirmation_required: the site has a connection problem that needs a person's acknowledgement. Version 1 of the API cannot acknowledge it; start the audit in the app.
  • excluded_resource_confirmation_required: url is a document or file, not a page. Version 1 of the API cannot confirm it; start the audit in the app.
  • journeys_unavailable: depth deep is off for this project.
  • persona_requires_access: a chosen persona needs a test account the project does not have.
  • operation_not_found: no quote with this operationId in the account.
  • operation_quote_expired: the quote is older than 10 minutes. Quote again; nothing was charged.
  • operation_input_mismatch: the selection or project differs from the one that was quoted, or the operation already started an audit under another reference or none (an audit archived since, whose reference was cleared, included); quote again. Nothing was charged.
  • operation_not_confirmable: the quote can no longer be confirmed. Quote again.
  • elevated_confirmation_required: the quote has requiresElevatedConfirmation; send elevatedConfirmation: true to accept it. The answer carries maximumCredits, thresholdCredits and reason. Nothing was charged.
  • insufficient_credits: the balance does not cover the audit. The answer carries the amounts. Nothing was charged.
Error
422
  • operation_cost_exceeds_absolute_cap: the audit would cost more than the absolute cap. Documented for completeness: an audit quote has no cap above its price, so this is not returned today.
Error
429
  • free_operation_limit_reached: a free operation's limit is used up. Documented for completeness: an audit is not a free operation, so this is not returned today.
  • rate_limited: a key may make 120 calls a minute, and an address with many failed keys is refused for a while. Starts also share the account's allowance of 10 an hour with the app; a repeat that returns an existing audit uses none of it.

Header Retry-After: Seconds to wait before calling again.

Error
502
  • discovery_unavailable: we could not read the site to plan the audit. Try again.
Error
503
  • audit_start_busy: another start of this operation holds it. Retry with the same operationId.
  • audit_unavailable: we could not quote or start the audit. Nothing was charged; try again.
  • api_unavailable: we could not read what you asked for. Try again.
Error

A project's finding ledger

GET /projects/{projectId}/ledger

The project's findings with their current status across audits, most urgent first. Reading it first brings the ledger up to date with audits that completed recently.

Needs an API key sent as Authorization: Bearer uxa_….

Parameters

NameTypeDescription
projectId
path, required
stringThe project's id.
limit
query, optional
integer
1 to 100
default 25
How many items to return, 1 to 100. Default 25.
cursor
query, optional
string
1 to 2000 characters
The nextCursor of the previous page of the same list, exactly as returned.
status
query, optional
string
up to 200 characters
matches ^(open|fix_applied|resolved|regressed|accepted)(,(open|fix_applied|resolved|regressed|accepted))*$
Only findings with one of these ledger statuses. Comma-separated: open, fix_applied, resolved, regressed, accepted.

Responses

StatusWhat it meansBody
200

A page of ledger findings

LedgerList
400
  • invalid_request: a query parameter or body field is not allowed, or the body is not JSON. field names it (query or body for the whole); its value is not echoed.
  • invalid_cursor: the cursor is not one we issued, or belongs to another list or other filters.
Error
401
  • invalid_api_key: the key is missing, malformed, unknown, revoked or expired, or its creator can no longer use the account. One code for all of them, with WWW-Authenticate: Bearer.

Header WWW-Authenticate: Always Bearer.

Error
403
  • terms_acceptance_required: the key's creator has not agreed to the current terms.
Error
404
  • project_not_found: no such project in this key's scope. A project that does not exist, one of another account and one the key was not given answer the same.
Error
409
  • cursor_list_changed: the list changed since the cursor was made. Start again from the first page.
Error
429
  • rate_limited: a key may make 120 calls a minute, and an address with many failed keys is refused for a while.

Header Retry-After: Seconds to wait before calling again.

Error
503
  • api_unavailable: we could not read what you asked for. Try again.
Error

An audit's status and finding totals

GET /audits/{auditId}

The audit's status, phase, scope, times and page and template counts. A completed audit also has its finding totals, which is what a CI gate polls.

Needs an API key sent as Authorization: Bearer uxa_….

Parameters

NameTypeDescription
auditId
path, required
stringThe audit's id.

Responses

StatusWhat it meansBody
200

The audit

AuditDetail
400
  • invalid_request: a query parameter or body field is not allowed, or the body is not JSON. field names it (query or body for the whole); its value is not echoed.
Error
401
  • invalid_api_key: the key is missing, malformed, unknown, revoked or expired, or its creator can no longer use the account. One code for all of them, with WWW-Authenticate: Bearer.

Header WWW-Authenticate: Always Bearer.

Error
403
  • terms_acceptance_required: the key's creator has not agreed to the current terms.
Error
404
  • audit_not_found: no such audit in this key's scope, the same answer for every case, an archived audit included.
Error
429
  • rate_limited: a key may make 120 calls a minute, and an address with many failed keys is refused for a while.

Header Retry-After: Seconds to wait before calling again.

Error
503
  • api_unavailable: we could not read what you asked for. Try again.
Error

An audit's findings

GET /audits/{auditId}/findings

The audit's failed checks, grouped by rule and page, most severe first, each with its ledger status and how this audit found it. Advice that sites may decline is not a finding and is not listed. Reading it first brings the ledger up to date with audits that completed recently. 409 audit_not_completed until the audit completes.

Needs an API key sent as Authorization: Bearer uxa_….

Parameters

NameTypeDescription
auditId
path, required
stringThe audit's id.
limit
query, optional
integer
1 to 100
default 25
How many items to return, 1 to 100. Default 25.
cursor
query, optional
string
1 to 2000 characters
The nextCursor of the previous page of the same list, exactly as returned.
status
query, optional
string
up to 200 characters
matches ^(open|fix_applied|resolved|regressed|accepted)(,(open|fix_applied|resolved|regressed|accepted))*$
Only findings whose ledger status is one of these. Comma-separated: open, fix_applied, resolved, regressed, accepted.
severity
query, optional
string
up to 200 characters
matches ^(critical|high|medium|low)(,(critical|high|medium|low))*$
Only findings of these severities. Comma-separated: critical, high, medium, low.
change
query, optional
string
up to 200 characters
matches ^(new|regressed|persisting|resolved)(,(new|regressed|persisting|resolved))*$
Only findings that changed this way in this audit. Findings this audit resolved are returned only when the list names resolved. Comma-separated: new, regressed, persisting, resolved.

Responses

StatusWhat it meansBody
200

A page of findings

FindingList
400
  • invalid_request: a query parameter or body field is not allowed, or the body is not JSON. field names it (query or body for the whole); its value is not echoed.
  • invalid_cursor: the cursor is not one we issued, or belongs to another list or other filters.
Error
401
  • invalid_api_key: the key is missing, malformed, unknown, revoked or expired, or its creator can no longer use the account. One code for all of them, with WWW-Authenticate: Bearer.

Header WWW-Authenticate: Always Bearer.

Error
403
  • terms_acceptance_required: the key's creator has not agreed to the current terms.
Error
404
  • audit_not_found: no such audit in this key's scope, the same answer for every case, an archived audit included.
Error
409
  • audit_not_completed: the audit has no findings yet. status holds its status; poll GET /audits/{auditId}.
  • cursor_list_changed: the list changed since the cursor was made. Start again from the first page.
Error
429
  • rate_limited: a key may make 120 calls a minute, and an address with many failed keys is refused for a while.

Header Retry-After: Seconds to wait before calling again.

Error
503
  • api_unavailable: we could not read what you asked for. Try again.
Error

Quote an audit

POST /projects/{projectId}/audits/quote

Prices an audit of the project, a full one or one address, and returns the operationId of the quote, valid for 10 minutes, with what it would cost and whether starting it needs elevatedConfirmation. Nothing is charged. The key needs the run audits permission. Audits that need a person's acknowledgement of a connection problem, or a document rather than a page, are not quoted through this API: they answer 409 with their code.

Needs an API key sent as Authorization: Bearer uxa_….

Parameters

NameTypeDescription
projectId
path, required
stringThe project's id.

Request body

Sent as application/json, required: QuoteAuditRequest.

NameTypeDescription
mode
required
string
one of "full", "url"
full audits the project's site; url audits one address.
url
optional
string
up to 2048 characters
For mode url: the address to audit. An address copied from one of our answers, whose secret value is replaced, is refused.
projectUrlId
optional
string
1 to 100 characters
One of the project's URLs, from GET /projects. For mode full, the one to audit; for mode url, the one the address belongs to.
label
optional
string
up to 160 characters
For mode url: a label for the address.
depth
optional
string
one of "standard", "deep"
standard by default. deep walks the same goal once per chosen persona and needs personas.
personas
optional
array of string
up to 10 items
each item: 1 to 80 characters
At depth deep only: one to three persona keys.

Responses

StatusWhat it meansBody
200

The quote

AuditQuote
400
  • invalid_request: a query parameter or body field is not allowed, or the body is not JSON. field names it (query or body for the whole); its value is not echoed.
  • masked_url_input: url is an address copied from one of our answers, where a secret query value is replaced. Send the real address.
  • invalid_target_url: url is not an address we can audit.
  • audit_target_mismatch: url is not the address of projectUrlId.
  • invalid_depth: depth is not standard or deep.
  • invalid_personas: personas is not a list of persona keys.
  • personas_require_deep: personas is only for depth deep.
  • personas_required: depth deep needs one to three personas.
  • too_many_personas: more personas than a deep audit walks.
  • unknown_persona: a persona key is not one we know.
  • deep_unavailable_for_url: depth deep is not available for a single-address audit.
Error
401
  • invalid_api_key: the key is missing, malformed, unknown, revoked or expired, or its creator can no longer use the account. One code for all of them, with WWW-Authenticate: Bearer.

Header WWW-Authenticate: Always Bearer.

Error
403
  • permission_required: the key lacks the permission; permission names it. Checked before anything else is read or charged.
  • email_unverified: the account owner's email is not verified yet.
  • terms_acceptance_required: the key's creator has not agreed to the current terms.
Error
404
  • project_not_found: no such project in this key's scope. A project that does not exist, one of another account and one the key was not given answer the same.
  • project_url_not_found: projectUrlId is not one of the project's URLs.
Error
409
  • primary_url_required: the project has no primary URL to audit.
  • audit_source_required: there is nothing to audit: no pages were found for this selection.
  • transport_confirmation_required: the site has a connection problem that needs a person's acknowledgement. Version 1 of the API cannot acknowledge it; start the audit in the app.
  • excluded_resource_confirmation_required: url is a document or file, not a page. Version 1 of the API cannot confirm it; start the audit in the app.
  • journeys_unavailable: depth deep is off for this project.
  • persona_requires_access: a chosen persona needs a test account the project does not have.
Error
429
  • rate_limited: a key may make 120 calls a minute, and an address with many failed keys is refused for a while. Quotes also share the account's allowance of 30 an hour with the app.

Header Retry-After: Seconds to wait before calling again.

Error
502
  • discovery_unavailable: we could not read the site to plan the audit. Try again.
Error
503
  • audit_unavailable: we could not quote or start the audit. Nothing was charged; try again.
  • api_unavailable: we could not read what you asked for. Try again.
Error

Set a finding's status

POST /projects/{projectId}/ledger/{ledgerId}/status

Records that a finding is fix_applied (marked fixed), accepted or open again, with an optional note, in the finding's status history beside the key and the member who created it. resolved and regressed are refused with 400 invalid_request and field: "status": the next audit that measures the finding decides them, so a fix marked here is checked by the next audit. A call whose status is the one the finding already has changes nothing: no history row, and its note is not recorded (a note travels with a status change); it answers 200 with the current finding. The key needs the write findings permission. Answers with the finding as GET /projects/{projectId}/ledger lists it.

Needs an API key sent as Authorization: Bearer uxa_….

Parameters

NameTypeDescription
projectId
path, required
stringThe project's id.
ledgerId
path, required
stringThe finding's ledgerId, from the ledger or an audit's findings.

Request body

Sent as application/json, required: SetFindingStatusRequest.

NameTypeDescription
status
required
string
one of "open", "fix_applied", "accepted"
fix_applied (marked fixed), accepted or open (back to open). resolved and regressed are refused: the next audit that measures the finding decides them.
note
optional
string
1 to 1000 characters
matches ^[^\p{Cc}\p{Cf}\p{Zl}\p{Zp}]+$
Why, 1 to 1000 printable characters on one line, recorded in the finding's status history beside the key and the member who created it. Not recorded when the finding already has the status you send: a note travels with a status change.

Responses

StatusWhat it meansBody
200

The finding with its new status

LedgerItem
400
  • invalid_request: a query parameter or body field is not allowed, or the body is not JSON. field names it (query or body for the whole); its value is not echoed.
Error
401
  • invalid_api_key: the key is missing, malformed, unknown, revoked or expired, or its creator can no longer use the account. One code for all of them, with WWW-Authenticate: Bearer.

Header WWW-Authenticate: Always Bearer.

Error
403
  • permission_required: the key lacks the permission; permission names it. Checked before anything else is read or charged.
  • terms_acceptance_required: the key's creator has not agreed to the current terms.
Error
404
  • project_not_found: no such project in this key's scope. A project that does not exist, one of another account and one the key was not given answer the same.
  • ledger_item_not_found: no such finding in this project. An id that does not exist, one of another project or account, one that is not a finding, and one the project's answer about the accessibility statement hides, all answer the same.
Error
429
  • rate_limited: a key may make 120 calls a minute, and an address with many failed keys is refused for a while.

Header Retry-After: Seconds to wait before calling again.

Error
503
  • api_unavailable: we could not read what you asked for. Try again.
Error

Schemas

QuoteAuditRequest

NameTypeDescription
mode
required
string
one of "full", "url"
full audits the project's site; url audits one address.
url
optional
string
up to 2048 characters
For mode url: the address to audit. An address copied from one of our answers, whose secret value is replaced, is refused.
projectUrlId
optional
string
1 to 100 characters
One of the project's URLs, from GET /projects. For mode full, the one to audit; for mode url, the one the address belongs to.
label
optional
string
up to 160 characters
For mode url: a label for the address.
depth
optional
string
one of "standard", "deep"
standard by default. deep walks the same goal once per chosen persona and needs personas.
personas
optional
array of string
up to 10 items
each item: 1 to 80 characters
At depth deep only: one to three persona keys.

StartAuditRequest

NameTypeDescription
mode
required
string
one of "full", "url"
full audits the project's site; url audits one address.
url
optional
string
up to 2048 characters
For mode url: the address to audit. An address copied from one of our answers, whose secret value is replaced, is refused.
projectUrlId
optional
string
1 to 100 characters
One of the project's URLs, from GET /projects. For mode full, the one to audit; for mode url, the one the address belongs to.
label
optional
string
up to 160 characters
For mode url: a label for the address.
depth
optional
string
one of "standard", "deep"
standard by default. deep walks the same goal once per chosen persona and needs personas.
personas
optional
array of string
up to 10 items
each item: 1 to 80 characters
At depth deep only: one to three persona keys.
operationId
required
string
1 to 64 characters
The operationId of a quote made in the last 10 minutes for this same selection.
elevatedConfirmation
optional
booleanSend true to accept the spend when the quote has requiresElevatedConfirmation. A pipeline that sets it accepts that spend on every run.
reference
optional
string
1 to 180 characters
matches ^[^\p{Cc}\p{Cf}\p{Zl}\p{Zp}]+$
Your idempotency reference, 1 to 180 characters, for example a commit SHA. A second start in the same project with the same reference returns the run the first one started, with 200 and no charge, even when its quote has expired. It is per project and case-sensitive. A reference that already has an audit returns it whatever operationId is sent; archiving an audit clears its reference, so the next start with it is a new audit, and a start whose operationId already started an audit that was archived since is refused as operation_input_mismatch.

SetFindingStatusRequest

NameTypeDescription
status
required
string
one of "open", "fix_applied", "accepted"
fix_applied (marked fixed), accepted or open (back to open). resolved and regressed are refused: the next audit that measures the finding decides them.
note
optional
string
1 to 1000 characters
matches ^[^\p{Cc}\p{Cf}\p{Zl}\p{Zp}]+$
Why, 1 to 1000 printable characters on one line, recorded in the finding's status history beside the key and the member who created it. Not recorded when the finding already has the status you send: a note travels with a status change.

Error

NameTypeDescription
error
required
stringA snake_case code; the documented ones are listed on each operation.
field
optional
stringFor invalid_request: the query field that was refused. Its value is never echoed.
status
optional
string
one of "queued", "running", "completed", "failed", "cancelled"
For audit_not_completed: the audit's status.
permission
optional
string
always "run_audits"
For permission_required: the permission the key lacks.
maximumCredits
optional
numberFor elevated_confirmation_required: the most the audit may draw, in the quote's unit.
thresholdCredits
optional
numberFor elevated_confirmation_required: the size above which the extra confirmation is needed.
reason
optional
stringFor elevated_confirmation_required: pack or over_20pct_monthly.
availableCredits
optional
numberFor insufficient_credits: what the account has.
requestedCredits
optional
numberFor insufficient_credits: what the audit needs.

Key

NameTypeDescription
name
required
string
lastFour
required
string
permissions
required
object
permissions.read
required
boolean
always true
permissions.runAudits
required
boolean
permissions.writeFindings
required
boolean
projects
required
array of object
projects[].id
required
string
projects[].name
required
string
expiresAt
required
integer or null
at least 0
Null for a key that never expires.
createdAt
required
integer
at least 0

Project

NameTypeDescription
id
required
string
name
required
string
workspace
required
object
workspace.id
required
string
workspace.name
required
string
status
required
string
one of "active", "setup"
urls
required
array of object
urls[].id
required
string
urls[].label
required
string
urls[].environment
required
string
urls[].url
required
stringSecret-looking query values are replaced.
urls[].isPrimary
required
boolean
latestAudit
required
object or nullThe latest completed audit that is not archived; null before the first.
latestAudit.id
required
string
latestAudit.reportNumber
required
integer
latestAudit.completedAt
required
integer or null
at least 0

ProjectList

NameTypeDescription
totals
required
object
totals.projects
required
integer
items
required
array of Project
nextCursor
required
string or nullPass as cursor for the next page; null on the last page.

AuditScope

When kind is "site"

NameTypeDescription
kind
required
string
always "site"
pages
required
integer
templates
required
integer

When kind is "url"

NameTypeDescription
kind
required
string
always "url"
url
required
string
label
required
string or null

Audit

NameTypeDescription
id
required
string
projectId
required
string
projectUrlId
required
string or null
reportNumber
required
integer
status
required
string
one of "queued", "running", "completed", "failed", "cancelled"
phase
required
string
one of "preparing", "auditing", "reporting", "completed", "failed", "cancelled"
scope
required
AuditScope
createdAt
required
integer
at least 0
startedAt
required
integer or null
at least 0
completedAt
required
integer or null
at least 0
pagesAudited
required
integer
templatesAudited
required
integer

AuditQuote

NameTypeDescription
operationId
required
stringPass to POST /projects/{projectId}/audits with the same selection. Valid until expiresAt.
expiresAt
required
integer
at least 0
When the quote lapses, 10 minutes after it was made.
unit
required
string
one of "credits", "pages"
The unit of estimatedCredits and maximumCredits: audited pages under a plan, credits otherwise.
estimatedCredits
required
numberWhat the audit is expected to cost, in unit.
maximumCredits
required
numberThe most it can cost, in unit. It is also what is held when the audit starts.
quotedPages
required
integer or nullThe pages the quote prices.
requiresElevatedConfirmation
required
booleanWhen true, the start needs elevatedConfirmation: true.
elevatedReason
required
string or null
one of "pack", "over_20pct_monthly"
Why: the audit draws on a purchased pack, or uses more than 20% of the monthly allowance. Null when none is needed.
scope
required
AuditScope

AuditList

NameTypeDescription
totals
required
object
totals.audits
required
integerAudits in the list, under the status filter.
items
required
array of Audit
nextCursor
required
string or nullPass as cursor for the next page; null on the last page.

FindingTotals

NameTypeDescription
total
required
integerFailed checks of this audit, grouped by rule and page, advisories left out.
bySeverity
required
object
bySeverity.critical
required
integer
bySeverity.high
required
integer
bySeverity.medium
required
integer
bySeverity.low
required
integer
byChange
required
object
byChange.new
required
integer
byChange.regressed
required
integer
byChange.persisting
required
integer
resolved
required
integerFindings this audit resolved. Includes closures because our check for a rule changed, which are not verified fixes.

AuditDetail

NameTypeDescription
id
required
string
projectId
required
string
projectUrlId
required
string or null
reportNumber
required
integer
status
required
string
one of "queued", "running", "completed", "failed", "cancelled"
phase
required
string
one of "preparing", "auditing", "reporting", "completed", "failed", "cancelled"
scope
required
AuditScope
createdAt
required
integer
at least 0
startedAt
required
integer or null
at least 0
completedAt
required
integer or null
at least 0
pagesAudited
required
integer
templatesAudited
required
integer
findings
required
FindingTotals or nullNull until the audit is completed.

Finding

NameTypeDescription
id
required
string or nullThe finding group in this audit; null for a finding this audit resolved.
ledgerId
required
string or nullThe finding's id in the project URL's ledger, the one status changes name; null when the audit has no ledger.
ruleId
required
string
ruleVersion
required
integer or null
title
required
string
severity
required
string
one of "critical", "high", "medium", "low"
Raised one level when a law the project chose requires the rule's criterion.
measuredSeverity
required
string or null
one of "critical", "high", "medium", "low"
The severity we measured, set only when severity was raised.
standards
required
array of object
standards[].kind
required
string
one of "wcag", "en-clause"
standards[].criterion
required
string
standards[].title
required
string
standards[].level
required
string or null
standards[].enClause
required
string or null
pageUrl
required
string
templateLabel
required
string or null
occurrenceCount
required
integer
viewports
required
array of object
viewports[].width
required
integer or null
viewports[].height
required
integer or null
viewports[].label
required
string or null
viewports[].kind
required
string
one of "configured", "adaptive"
ledgerStatus
required
string or null
one of "open", "fix_applied", "resolved", "regressed", "accepted"
The ledger's current status for the finding, which later audits and people may have changed since this audit.
change
required
string or null
one of "new", "regressed", "persisting", "resolved"
How this audit found it: new (first seen here), regressed (resolved before, found again), persisting, or resolved (this audit confirmed it gone). Null when the audit has no ledger.

FindingList

NameTypeDescription
totals
required
object
totals.findings
required
integerFindings in the list, under the filters.
totals.bySeverity
required
object
totals.bySeverity.critical
required
integer
totals.bySeverity.high
required
integer
totals.bySeverity.medium
required
integer
totals.bySeverity.low
required
integer
totals.byChange
required
object
totals.byChange.new
required
integer
totals.byChange.regressed
required
integer
totals.byChange.persisting
required
integer
totals.byChange.resolved
required
integer
items
required
array of Finding
nextCursor
required
string or nullPass as cursor for the next page; null on the last page.

LedgerItem

NameTypeDescription
ledgerId
required
string
projectUrlId
required
string
ruleId
required
string or null
title
required
string
severity
required
string or null
one of "critical", "high", "medium", "low"
status
required
string
one of "open", "fix_applied", "resolved", "regressed", "accepted"
pageUrl
required
string
occurrenceCount
required
integerIn how many completed audits the finding appeared.
firstSeenAt
required
integer
at least 0
lastSeenAt
required
integer
at least 0
firstAuditId
required
string or null
lastAuditId
required
string or nullThe audit that last measured the finding.
statusChangedAt
required
integer or null
at least 0

LedgerList

NameTypeDescription
totals
required
object
totals.items
required
integerFindings in the list, under the status filter.
totals.byStatus
required
object
totals.byStatus.open
required
integer
totals.byStatus.fix_applied
required
integer
totals.byStatus.resolved
required
integer
totals.byStatus.regressed
required
integer
totals.byStatus.accepted
required
integer
items
required
array of LedgerItem
nextCursor
required
string or nullPass as cursor for the next page; null on the last page.