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
| Status | What it means | Body |
|---|---|---|
200 | OpenAPI document | object |
404 |
| 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
| Status | What it means | Body |
|---|---|---|
200 | The key | Key |
400 |
| Error |
401 |
Header | Error |
403 |
| Error |
429 |
Header | Error |
503 |
| 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
| Name | Type | Description |
|---|---|---|
limitquery, optional | integer 1 to 100 default 25 | How many items to return, 1 to 100. Default 25. |
cursorquery, optional | string 1 to 2000 characters | The nextCursor of the previous page of the same list, exactly as returned. |
Responses
| Status | What it means | Body |
|---|---|---|
200 | A page of projects | ProjectList |
400 |
| Error |
401 |
Header | Error |
403 |
| Error |
409 |
| Error |
429 |
Header | Error |
503 |
| 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
| Name | Type | Description |
|---|---|---|
projectpath, required | string | The project's id. |
limitquery, optional | integer 1 to 100 default 25 | How many items to return, 1 to 100. Default 25. |
cursorquery, optional | string 1 to 2000 characters | The nextCursor of the previous page of the same list, exactly as returned. |
statusquery, optional | string one of "queued", "running", "completed", "failed", "cancelled" | Only audits in this status. |
Responses
| Status | What it means | Body |
|---|---|---|
200 | A page of audits | AuditList |
400 |
| Error |
401 |
Header | Error |
403 |
| Error |
404 |
| Error |
429 |
Header | Error |
503 |
| 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
| Name | Type | Description |
|---|---|---|
projectpath, required | string | The project's id. |
Request body
Sent as application/json, required: StartAuditRequest.
| Name | Type | Description |
|---|---|---|
moderequired | string one of "full", "url" | full audits the project's site; url audits one address. |
urloptional | 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. |
projectoptional | 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. |
labeloptional | string up to 160 characters | For mode url: a label for the address. |
depthoptional | string one of "standard", "deep" | standard by default. deep walks the same goal once per chosen persona and needs personas. |
personasoptional | array of string up to 10 items each item: 1 to 80 characters | At depth deep only: one to three persona keys. |
operationrequired | string 1 to 64 characters | The operationId of a quote made in the last 10 minutes for this same selection. |
elevatedoptional | boolean | Send true to accept the spend when the quote has requiresElevatedConfirmation. A pipeline that sets it accepts that spend on every run. |
referenceoptional | 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
| Status | What it means | Body |
|---|---|---|
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 |
| Error |
401 |
Header | Error |
403 |
| Error |
404 |
| Error |
409 |
| Error |
422 |
| Error |
429 |
Header | Error |
502 |
| Error |
503 |
| 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
| Name | Type | Description |
|---|---|---|
projectpath, required | string | The project's id. |
limitquery, optional | integer 1 to 100 default 25 | How many items to return, 1 to 100. Default 25. |
cursorquery, optional | string 1 to 2000 characters | The nextCursor of the previous page of the same list, exactly as returned. |
statusquery, 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
| Status | What it means | Body |
|---|---|---|
200 | A page of ledger findings | LedgerList |
400 |
| Error |
401 |
Header | Error |
403 |
| Error |
404 |
| Error |
409 |
| Error |
429 |
Header | Error |
503 |
| 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
| Name | Type | Description |
|---|---|---|
auditpath, required | string | The audit's id. |
Responses
| Status | What it means | Body |
|---|---|---|
200 | The audit | AuditDetail |
400 |
| Error |
401 |
Header | Error |
403 |
| Error |
404 |
| Error |
429 |
Header | Error |
503 |
| 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
| Name | Type | Description |
|---|---|---|
auditpath, required | string | The audit's id. |
limitquery, optional | integer 1 to 100 default 25 | How many items to return, 1 to 100. Default 25. |
cursorquery, optional | string 1 to 2000 characters | The nextCursor of the previous page of the same list, exactly as returned. |
statusquery, 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. |
severityquery, 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. |
changequery, 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
| Status | What it means | Body |
|---|---|---|
200 | A page of findings | FindingList |
400 |
| Error |
401 |
Header | Error |
403 |
| Error |
404 |
| Error |
409 |
| Error |
429 |
Header | Error |
503 |
| 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
| Name | Type | Description |
|---|---|---|
projectpath, required | string | The project's id. |
Request body
Sent as application/json, required: QuoteAuditRequest.
| Name | Type | Description |
|---|---|---|
moderequired | string one of "full", "url" | full audits the project's site; url audits one address. |
urloptional | 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. |
projectoptional | 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. |
labeloptional | string up to 160 characters | For mode url: a label for the address. |
depthoptional | string one of "standard", "deep" | standard by default. deep walks the same goal once per chosen persona and needs personas. |
personasoptional | array of string up to 10 items each item: 1 to 80 characters | At depth deep only: one to three persona keys. |
Responses
| Status | What it means | Body |
|---|---|---|
200 | The quote | AuditQuote |
400 |
| Error |
401 |
Header | Error |
403 |
| Error |
404 |
| Error |
409 |
| Error |
429 |
Header | Error |
502 |
| Error |
503 |
| 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
| Name | Type | Description |
|---|---|---|
projectpath, required | string | The project's id. |
ledgerpath, required | string | The finding's ledgerId, from the ledger or an audit's findings. |
Request body
Sent as application/json, required: SetFindingStatusRequest.
| Name | Type | Description |
|---|---|---|
statusrequired | 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. |
noteoptional | 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
| Status | What it means | Body |
|---|---|---|
200 | The finding with its new status | LedgerItem |
400 |
| Error |
401 |
Header | Error |
403 |
| Error |
404 |
| Error |
429 |
Header | Error |
503 |
| Error |
Schemas
QuoteAuditRequest
| Name | Type | Description |
|---|---|---|
moderequired | string one of "full", "url" | full audits the project's site; url audits one address. |
urloptional | 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. |
projectoptional | 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. |
labeloptional | string up to 160 characters | For mode url: a label for the address. |
depthoptional | string one of "standard", "deep" | standard by default. deep walks the same goal once per chosen persona and needs personas. |
personasoptional | array of string up to 10 items each item: 1 to 80 characters | At depth deep only: one to three persona keys. |
StartAuditRequest
| Name | Type | Description |
|---|---|---|
moderequired | string one of "full", "url" | full audits the project's site; url audits one address. |
urloptional | 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. |
projectoptional | 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. |
labeloptional | string up to 160 characters | For mode url: a label for the address. |
depthoptional | string one of "standard", "deep" | standard by default. deep walks the same goal once per chosen persona and needs personas. |
personasoptional | array of string up to 10 items each item: 1 to 80 characters | At depth deep only: one to three persona keys. |
operationrequired | string 1 to 64 characters | The operationId of a quote made in the last 10 minutes for this same selection. |
elevatedoptional | boolean | Send true to accept the spend when the quote has requiresElevatedConfirmation. A pipeline that sets it accepts that spend on every run. |
referenceoptional | 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
| Name | Type | Description |
|---|---|---|
statusrequired | 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. |
noteoptional | 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
| Name | Type | Description |
|---|---|---|
errorrequired | string | A snake_case code; the documented ones are listed on each operation. |
fieldoptional | string | For invalid_request: the query field that was refused. Its value is never echoed. |
statusoptional | string one of "queued", "running", "completed", "failed", "cancelled" | For audit_not_completed: the audit's status. |
permissionoptional | string always "run_audits" | For permission_required: the permission the key lacks. |
maximumoptional | number | For elevated_confirmation_required: the most the audit may draw, in the quote's unit. |
thresholdoptional | number | For elevated_confirmation_required: the size above which the extra confirmation is needed. |
reasonoptional | string | For elevated_confirmation_required: pack or over_20pct_monthly. |
availableoptional | number | For insufficient_credits: what the account has. |
requestedoptional | number | For insufficient_credits: what the audit needs. |
Key
| Name | Type | Description |
|---|---|---|
namerequired | string | |
lastrequired | string | |
permissionsrequired | object | |
permissions.required | boolean always true | |
permissions.required | boolean | |
permissions.required | boolean | |
projectsrequired | array of object | |
projects[]required | string | |
projects[]required | string | |
expiresrequired | integer or null at least 0 | Null for a key that never expires. |
createdrequired | integer at least 0 |
Project
| Name | Type | Description |
|---|---|---|
idrequired | string | |
namerequired | string | |
workspacerequired | object | |
workspace.required | string | |
workspace.required | string | |
statusrequired | string one of "active", "setup" | |
urlsrequired | array of object | |
urls[]required | string | |
urls[]required | string | |
urls[]required | string | |
urls[]required | string | Secret-looking query values are replaced. |
urls[]required | boolean | |
latestrequired | object or null | The latest completed audit that is not archived; null before the first. |
latestrequired | string | |
latestrequired | integer | |
latestrequired | integer or null at least 0 |
ProjectList
| Name | Type | Description |
|---|---|---|
totalsrequired | object | |
totals.required | integer | |
itemsrequired | array of Project | |
nextrequired | string or null | Pass as cursor for the next page; null on the last page. |
AuditScope
When kind is "site"
| Name | Type | Description |
|---|---|---|
kindrequired | string always "site" | |
pagesrequired | integer | |
templatesrequired | integer |
When kind is "url"
| Name | Type | Description |
|---|---|---|
kindrequired | string always "url" | |
urlrequired | string | |
labelrequired | string or null |
Audit
| Name | Type | Description |
|---|---|---|
idrequired | string | |
projectrequired | string | |
projectrequired | string or null | |
reportrequired | integer | |
statusrequired | string one of "queued", "running", "completed", "failed", "cancelled" | |
phaserequired | string one of "preparing", "auditing", "reporting", "completed", "failed", "cancelled" | |
scoperequired | AuditScope | |
createdrequired | integer at least 0 | |
startedrequired | integer or null at least 0 | |
completedrequired | integer or null at least 0 | |
pagesrequired | integer | |
templatesrequired | integer |
AuditQuote
| Name | Type | Description |
|---|---|---|
operationrequired | string | Pass to POST /projects/{projectId}/audits with the same selection. Valid until expiresAt. |
expiresrequired | integer at least 0 | When the quote lapses, 10 minutes after it was made. |
unitrequired | string one of "credits", "pages" | The unit of estimatedCredits and maximumCredits: audited pages under a plan, credits otherwise. |
estimatedrequired | number | What the audit is expected to cost, in unit. |
maximumrequired | number | The most it can cost, in unit. It is also what is held when the audit starts. |
quotedrequired | integer or null | The pages the quote prices. |
requiresrequired | boolean | When true, the start needs elevatedConfirmation: true. |
elevatedrequired | 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. |
scoperequired | AuditScope |
AuditList
| Name | Type | Description |
|---|---|---|
totalsrequired | object | |
totals.required | integer | Audits in the list, under the status filter. |
itemsrequired | array of Audit | |
nextrequired | string or null | Pass as cursor for the next page; null on the last page. |
FindingTotals
| Name | Type | Description |
|---|---|---|
totalrequired | integer | Failed checks of this audit, grouped by rule and page, advisories left out. |
byrequired | object | |
byrequired | integer | |
byrequired | integer | |
byrequired | integer | |
byrequired | integer | |
byrequired | object | |
byrequired | integer | |
byrequired | integer | |
byrequired | integer | |
resolvedrequired | integer | Findings this audit resolved. Includes closures because our check for a rule changed, which are not verified fixes. |
AuditDetail
| Name | Type | Description |
|---|---|---|
idrequired | string | |
projectrequired | string | |
projectrequired | string or null | |
reportrequired | integer | |
statusrequired | string one of "queued", "running", "completed", "failed", "cancelled" | |
phaserequired | string one of "preparing", "auditing", "reporting", "completed", "failed", "cancelled" | |
scoperequired | AuditScope | |
createdrequired | integer at least 0 | |
startedrequired | integer or null at least 0 | |
completedrequired | integer or null at least 0 | |
pagesrequired | integer | |
templatesrequired | integer | |
findingsrequired | FindingTotals or null | Null until the audit is completed. |
Finding
| Name | Type | Description |
|---|---|---|
idrequired | string or null | The finding group in this audit; null for a finding this audit resolved. |
ledgerrequired | string or null | The finding's id in the project URL's ledger, the one status changes name; null when the audit has no ledger. |
rulerequired | string | |
rulerequired | integer or null | |
titlerequired | string | |
severityrequired | string one of "critical", "high", "medium", "low" | Raised one level when a law the project chose requires the rule's criterion. |
measuredrequired | string or null one of "critical", "high", "medium", "low" | The severity we measured, set only when severity was raised. |
standardsrequired | array of object | |
standards[]required | string one of "wcag", "en-clause" | |
standards[]required | string | |
standards[]required | string | |
standards[]required | string or null | |
standards[]required | string or null | |
pagerequired | string | |
templaterequired | string or null | |
occurrencerequired | integer | |
viewportsrequired | array of object | |
viewports[]required | integer or null | |
viewports[]required | integer or null | |
viewports[]required | string or null | |
viewports[]required | string one of "configured", "adaptive" | |
ledgerrequired | 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. |
changerequired | 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
| Name | Type | Description |
|---|---|---|
totalsrequired | object | |
totals.required | integer | Findings in the list, under the filters. |
totals.required | object | |
totals.required | integer | |
totals.required | integer | |
totals.required | integer | |
totals.required | integer | |
totals.required | object | |
totals.required | integer | |
totals.required | integer | |
totals.required | integer | |
totals.required | integer | |
itemsrequired | array of Finding | |
nextrequired | string or null | Pass as cursor for the next page; null on the last page. |
LedgerItem
| Name | Type | Description |
|---|---|---|
ledgerrequired | string | |
projectrequired | string | |
rulerequired | string or null | |
titlerequired | string | |
severityrequired | string or null one of "critical", "high", "medium", "low" | |
statusrequired | string one of "open", "fix_applied", "resolved", "regressed", "accepted" | |
pagerequired | string | |
occurrencerequired | integer | In how many completed audits the finding appeared. |
firstrequired | integer at least 0 | |
lastrequired | integer at least 0 | |
firstrequired | string or null | |
lastrequired | string or null | The audit that last measured the finding. |
statusrequired | integer or null at least 0 |
LedgerList
| Name | Type | Description |
|---|---|---|
totalsrequired | object | |
totals.required | integer | Findings in the list, under the status filter. |
totals.required | object | |
totals.required | integer | |
totals.required | integer | |
totals.required | integer | |
totals.required | integer | |
totals.required | integer | |
itemsrequired | array of LedgerItem | |
nextrequired | string or null | Pass as cursor for the next page; null on the last page. |