{"openapi":"3.1.0","info":{"title":"Your UX Agent API","version":"1.0.0","description":"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.\n\nSend 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.\n\nTimes are Unix seconds. Every URL we return is masked: a query value that looks like a secret is replaced.\n\nLists 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.\n\nErrors 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`.\n\nStarting 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."},"servers":[{"url":"https://youruxagent.com/api/v1"}],"security":[{"bearerAuth":[]}],"paths":{"/openapi.json":{"get":{"operationId":"getOpenApiDocument","summary":"This document","description":"The OpenAPI 3.1 document of this API. It needs no key and may be cached for an hour.","security":[],"parameters":[],"responses":{"200":{"description":"OpenAPI document","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"`not_found`: the API is not switched on for this server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/key":{"get":{"operationId":"getKey","summary":"The key making the call","description":"The key's name, last four characters, permissions, projects and dates. Never its secret.","parameters":[],"responses":{"200":{"description":"The key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Key"}}}},"400":{"description":"`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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`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`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"WWW-Authenticate":{"description":"Always `Bearer`.","schema":{"type":"string"}}}},"403":{"description":"`terms_acceptance_required`: the key's creator has not agreed to the current terms.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: a key may make 120 calls a minute, and an address with many failed keys is refused for a while.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before calling again.","schema":{"type":"integer"}}}},"503":{"description":"`api_unavailable`: we could not read what you asked for. Try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects":{"get":{"operationId":"listProjects","summary":"The key's projects","description":"The projects the key was given, by name, each with its URLs and the latest completed audit that is not archived.","parameters":[{"name":"limit","in":"query","required":false,"description":"How many items to return, 1 to 100. Default 25.","schema":{"default":25,"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"The nextCursor of the previous page of the same list, exactly as returned.","schema":{"type":"string","minLength":1,"maxLength":2000}}],"responses":{"200":{"description":"A page of projects","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectList"}}}},"400":{"description":"`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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`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`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"WWW-Authenticate":{"description":"Always `Bearer`.","schema":{"type":"string"}}}},"403":{"description":"`terms_acceptance_required`: the key's creator has not agreed to the current terms.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`cursor_list_changed`: the list changed since the cursor was made. Start again from the first page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: a key may make 120 calls a minute, and an address with many failed keys is refused for a while.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before calling again.","schema":{"type":"integer"}}}},"503":{"description":"`api_unavailable`: we could not read what you asked for. Try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{projectId}/audits":{"get":{"operationId":"listAudits","summary":"A project's audits","description":"The project's audits, newest first. Archived audits are not listed.","parameters":[{"name":"projectId","in":"path","required":true,"description":"The project's id.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"How many items to return, 1 to 100. Default 25.","schema":{"default":25,"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"The nextCursor of the previous page of the same list, exactly as returned.","schema":{"type":"string","minLength":1,"maxLength":2000}},{"name":"status","in":"query","required":false,"description":"Only audits in this status.","schema":{"type":"string","enum":["queued","running","completed","failed","cancelled"]}}],"responses":{"200":{"description":"A page of audits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditList"}}}},"400":{"description":"`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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`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`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"WWW-Authenticate":{"description":"Always `Bearer`.","schema":{"type":"string"}}}},"403":{"description":"`terms_acceptance_required`: the key's creator has not agreed to the current terms.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: a key may make 120 calls a minute, and an address with many failed keys is refused for a while.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before calling again.","schema":{"type":"integer"}}}},"503":{"description":"`api_unavailable`: we could not read what you asked for. Try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"startAudit","summary":"Start an audit","description":"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.","parameters":[{"name":"projectId","in":"path","required":true,"description":"The project's id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StartAuditRequest"}}}},"responses":{"200":{"description":"The audit this call, or an earlier one with the same operationId or reference, started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditDetail"}}}},"202":{"description":"The audit this call started","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditDetail"}}}},"400":{"description":"`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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`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`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"WWW-Authenticate":{"description":"Always `Bearer`.","schema":{"type":"string"}}}},"403":{"description":"`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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before calling again.","schema":{"type":"integer"}}}},"502":{"description":"`discovery_unavailable`: we could not read the site to plan the audit. Try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{projectId}/ledger":{"get":{"operationId":"listLedger","summary":"A project's finding ledger","description":"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.","parameters":[{"name":"projectId","in":"path","required":true,"description":"The project's id.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"How many items to return, 1 to 100. Default 25.","schema":{"default":25,"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"The nextCursor of the previous page of the same list, exactly as returned.","schema":{"type":"string","minLength":1,"maxLength":2000}},{"name":"status","in":"query","required":false,"description":"Only findings with one of these ledger statuses. Comma-separated: open, fix_applied, resolved, regressed, accepted.","schema":{"type":"string","maxLength":200,"pattern":"^(open|fix_applied|resolved|regressed|accepted)(,(open|fix_applied|resolved|regressed|accepted))*$"}}],"responses":{"200":{"description":"A page of ledger findings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LedgerList"}}}},"400":{"description":"`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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`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`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"WWW-Authenticate":{"description":"Always `Bearer`.","schema":{"type":"string"}}}},"403":{"description":"`terms_acceptance_required`: the key's creator has not agreed to the current terms.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`cursor_list_changed`: the list changed since the cursor was made. Start again from the first page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: a key may make 120 calls a minute, and an address with many failed keys is refused for a while.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before calling again.","schema":{"type":"integer"}}}},"503":{"description":"`api_unavailable`: we could not read what you asked for. Try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/audits/{auditId}":{"get":{"operationId":"getAudit","summary":"An audit's status and finding totals","description":"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.","parameters":[{"name":"auditId","in":"path","required":true,"description":"The audit's id.","schema":{"type":"string"}}],"responses":{"200":{"description":"The audit","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditDetail"}}}},"400":{"description":"`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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`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`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"WWW-Authenticate":{"description":"Always `Bearer`.","schema":{"type":"string"}}}},"403":{"description":"`terms_acceptance_required`: the key's creator has not agreed to the current terms.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`audit_not_found`: no such audit in this key's scope, the same answer for every case, an archived audit included.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: a key may make 120 calls a minute, and an address with many failed keys is refused for a while.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before calling again.","schema":{"type":"integer"}}}},"503":{"description":"`api_unavailable`: we could not read what you asked for. Try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/audits/{auditId}/findings":{"get":{"operationId":"listAuditFindings","summary":"An audit's findings","description":"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.","parameters":[{"name":"auditId","in":"path","required":true,"description":"The audit's id.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"How many items to return, 1 to 100. Default 25.","schema":{"default":25,"type":"integer","minimum":1,"maximum":100}},{"name":"cursor","in":"query","required":false,"description":"The nextCursor of the previous page of the same list, exactly as returned.","schema":{"type":"string","minLength":1,"maxLength":2000}},{"name":"status","in":"query","required":false,"description":"Only findings whose ledger status is one of these. Comma-separated: open, fix_applied, resolved, regressed, accepted.","schema":{"type":"string","maxLength":200,"pattern":"^(open|fix_applied|resolved|regressed|accepted)(,(open|fix_applied|resolved|regressed|accepted))*$"}},{"name":"severity","in":"query","required":false,"description":"Only findings of these severities. Comma-separated: critical, high, medium, low.","schema":{"type":"string","maxLength":200,"pattern":"^(critical|high|medium|low)(,(critical|high|medium|low))*$"}},{"name":"change","in":"query","required":false,"description":"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.","schema":{"type":"string","maxLength":200,"pattern":"^(new|regressed|persisting|resolved)(,(new|regressed|persisting|resolved))*$"}}],"responses":{"200":{"description":"A page of findings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindingList"}}}},"400":{"description":"`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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`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`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"WWW-Authenticate":{"description":"Always `Bearer`.","schema":{"type":"string"}}}},"403":{"description":"`terms_acceptance_required`: the key's creator has not agreed to the current terms.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`audit_not_found`: no such audit in this key's scope, the same answer for every case, an archived audit included.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: a key may make 120 calls a minute, and an address with many failed keys is refused for a while.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before calling again.","schema":{"type":"integer"}}}},"503":{"description":"`api_unavailable`: we could not read what you asked for. Try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{projectId}/audits/quote":{"post":{"operationId":"quoteAudit","summary":"Quote an audit","description":"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.","parameters":[{"name":"projectId","in":"path","required":true,"description":"The project's id.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteAuditRequest"}}}},"responses":{"200":{"description":"The quote","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditQuote"}}}},"400":{"description":"`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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`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`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"WWW-Authenticate":{"description":"Always `Bearer`.","schema":{"type":"string"}}}},"403":{"description":"`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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before calling again.","schema":{"type":"integer"}}}},"502":{"description":"`discovery_unavailable`: we could not read the site to plan the audit. Try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/projects/{projectId}/ledger/{ledgerId}/status":{"post":{"operationId":"setFindingStatus","summary":"Set a finding's status","description":"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.","parameters":[{"name":"projectId","in":"path","required":true,"description":"The project's id.","schema":{"type":"string"}},{"name":"ledgerId","in":"path","required":true,"description":"The finding's `ledgerId`, from the ledger or an audit's findings.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetFindingStatusRequest"}}}},"responses":{"200":{"description":"The finding with its new status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LedgerItem"}}}},"400":{"description":"`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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`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`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"WWW-Authenticate":{"description":"Always `Bearer`.","schema":{"type":"string"}}}},"403":{"description":"`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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: a key may make 120 calls a minute, and an address with many failed keys is refused for a while.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before calling again.","schema":{"type":"integer"}}}},"503":{"description":"`api_unavailable`: we could not read what you asked for. Try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"uxa_ key","description":"An API key created in Settings › Integrations › API keys. It starts with `uxa_`."}},"schemas":{"QuoteAuditRequest":{"type":"object","properties":{"mode":{"type":"string","enum":["full","url"],"description":"`full` audits the project's site; `url` audits one address."},"url":{"description":"For mode `url`: the address to audit. An address copied from one of our answers, whose secret value is replaced, is refused.","type":"string","maxLength":2048},"projectUrlId":{"description":"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.","type":"string","minLength":1,"maxLength":100},"label":{"description":"For mode `url`: a label for the address.","type":"string","maxLength":160},"depth":{"description":"`standard` by default. `deep` walks the same goal once per chosen persona and needs `personas`.","type":"string","enum":["standard","deep"]},"personas":{"description":"At depth `deep` only: one to three persona keys.","maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}}},"required":["mode"]},"StartAuditRequest":{"type":"object","properties":{"mode":{"type":"string","enum":["full","url"],"description":"`full` audits the project's site; `url` audits one address."},"url":{"description":"For mode `url`: the address to audit. An address copied from one of our answers, whose secret value is replaced, is refused.","type":"string","maxLength":2048},"projectUrlId":{"description":"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.","type":"string","minLength":1,"maxLength":100},"label":{"description":"For mode `url`: a label for the address.","type":"string","maxLength":160},"depth":{"description":"`standard` by default. `deep` walks the same goal once per chosen persona and needs `personas`.","type":"string","enum":["standard","deep"]},"personas":{"description":"At depth `deep` only: one to three persona keys.","maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":80}},"operationId":{"type":"string","minLength":1,"maxLength":64,"description":"The `operationId` of a quote made in the last 10 minutes for this same selection."},"elevatedConfirmation":{"description":"Send true to accept the spend when the quote has `requiresElevatedConfirmation`. A pipeline that sets it accepts that spend on every run.","type":"boolean"},"reference":{"type":"string","minLength":1,"maxLength":180,"pattern":"^[^\\p{Cc}\\p{Cf}\\p{Zl}\\p{Zp}]+$","description":"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."}},"required":["mode","operationId"]},"SetFindingStatusRequest":{"type":"object","properties":{"status":{"type":"string","enum":["open","fix_applied","accepted"],"description":"`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":{"description":"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.","type":"string","minLength":1,"maxLength":1000,"pattern":"^[^\\p{Cc}\\p{Cf}\\p{Zl}\\p{Zp}]+$"}},"required":["status"]},"Error":{"type":"object","properties":{"error":{"type":"string","description":"A snake_case code; the documented ones are listed on each operation."},"field":{"description":"For invalid_request: the query field that was refused. Its value is never echoed.","type":"string"},"status":{"description":"For audit_not_completed: the audit's status.","type":"string","enum":["queued","running","completed","failed","cancelled"]},"permission":{"description":"For permission_required: the permission the key lacks.","type":"string","const":"run_audits"},"maximumCredits":{"description":"For elevated_confirmation_required: the most the audit may draw, in the quote's unit.","type":"number"},"thresholdCredits":{"description":"For elevated_confirmation_required: the size above which the extra confirmation is needed.","type":"number"},"reason":{"description":"For elevated_confirmation_required: pack or over_20pct_monthly.","type":"string"},"availableCredits":{"description":"For insufficient_credits: what the account has.","type":"number"},"requestedCredits":{"description":"For insufficient_credits: what the audit needs.","type":"number"}},"required":["error"]},"Key":{"type":"object","properties":{"name":{"type":"string"},"lastFour":{"type":"string"},"permissions":{"type":"object","properties":{"read":{"type":"boolean","const":true},"runAudits":{"type":"boolean"},"writeFindings":{"type":"boolean"}},"required":["read","runAudits","writeFindings"]},"projects":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]}},"expiresAt":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"description":"Null for a key that never expires."},"createdAt":{"type":"integer","minimum":0}},"required":["name","lastFour","permissions","projects","expiresAt","createdAt"]},"Project":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"workspace":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"]},"status":{"type":"string","enum":["active","setup"]},"urls":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"environment":{"type":"string"},"url":{"type":"string","description":"Secret-looking query values are replaced."},"isPrimary":{"type":"boolean"}},"required":["id","label","environment","url","isPrimary"]}},"latestAudit":{"anyOf":[{"type":"object","properties":{"id":{"type":"string"},"reportNumber":{"type":"integer"},"completedAt":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}]}},"required":["id","reportNumber","completedAt"]},{"type":"null"}],"description":"The latest completed audit that is not archived; null before the first."}},"required":["id","name","workspace","status","urls","latestAudit"]},"ProjectList":{"type":"object","properties":{"totals":{"type":"object","properties":{"projects":{"type":"integer"}},"required":["projects"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/Project"}},"nextCursor":{"description":"Pass as cursor for the next page; null on the last page.","type":["string","null"]}},"required":["totals","items","nextCursor"]},"AuditScope":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","const":"site"},"pages":{"type":"integer"},"templates":{"type":"integer"}},"required":["kind","pages","templates"]},{"type":"object","properties":{"kind":{"type":"string","const":"url"},"url":{"type":"string"},"label":{"type":["string","null"]}},"required":["kind","url","label"]}]},"Audit":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"projectUrlId":{"type":["string","null"]},"reportNumber":{"type":"integer"},"status":{"type":"string","enum":["queued","running","completed","failed","cancelled"]},"phase":{"type":"string","enum":["preparing","auditing","reporting","completed","failed","cancelled"]},"scope":{"$ref":"#/components/schemas/AuditScope"},"createdAt":{"type":"integer","minimum":0},"startedAt":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}]},"pagesAudited":{"type":"integer"},"templatesAudited":{"type":"integer"}},"required":["id","projectId","projectUrlId","reportNumber","status","phase","scope","createdAt","startedAt","completedAt","pagesAudited","templatesAudited"]},"AuditQuote":{"type":"object","properties":{"operationId":{"type":"string","description":"Pass to `POST /projects/{projectId}/audits` with the same selection. Valid until `expiresAt`."},"expiresAt":{"type":"integer","minimum":0,"description":"When the quote lapses, 10 minutes after it was made."},"unit":{"type":"string","enum":["credits","pages"],"description":"The unit of `estimatedCredits` and `maximumCredits`: audited pages under a plan, credits otherwise."},"estimatedCredits":{"type":"number","description":"What the audit is expected to cost, in `unit`."},"maximumCredits":{"type":"number","description":"The most it can cost, in `unit`. It is also what is held when the audit starts."},"quotedPages":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"The pages the quote prices."},"requiresElevatedConfirmation":{"type":"boolean","description":"When true, the start needs `elevatedConfirmation: true`."},"elevatedReason":{"anyOf":[{"type":"string","enum":["pack","over_20pct_monthly"]},{"type":"null"}],"description":"Why: the audit draws on a purchased pack, or uses more than 20% of the monthly allowance. Null when none is needed."},"scope":{"$ref":"#/components/schemas/AuditScope"}},"required":["operationId","expiresAt","unit","estimatedCredits","maximumCredits","quotedPages","requiresElevatedConfirmation","elevatedReason","scope"]},"AuditList":{"type":"object","properties":{"totals":{"type":"object","properties":{"audits":{"type":"integer","description":"Audits in the list, under the status filter."}},"required":["audits"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/Audit"}},"nextCursor":{"description":"Pass as cursor for the next page; null on the last page.","type":["string","null"]}},"required":["totals","items","nextCursor"]},"FindingTotals":{"type":"object","properties":{"total":{"type":"integer","description":"Failed checks of this audit, grouped by rule and page, advisories left out."},"bySeverity":{"type":"object","properties":{"critical":{"type":"integer"},"high":{"type":"integer"},"medium":{"type":"integer"},"low":{"type":"integer"}},"required":["critical","high","medium","low"]},"byChange":{"type":"object","properties":{"new":{"type":"integer"},"regressed":{"type":"integer"},"persisting":{"type":"integer"}},"required":["new","regressed","persisting"]},"resolved":{"type":"integer","description":"Findings this audit resolved. Includes closures because our check for a rule changed, which are not verified fixes."}},"required":["total","bySeverity","byChange","resolved"]},"AuditDetail":{"type":"object","properties":{"id":{"type":"string"},"projectId":{"type":"string"},"projectUrlId":{"type":["string","null"]},"reportNumber":{"type":"integer"},"status":{"type":"string","enum":["queued","running","completed","failed","cancelled"]},"phase":{"type":"string","enum":["preparing","auditing","reporting","completed","failed","cancelled"]},"scope":{"$ref":"#/components/schemas/AuditScope"},"createdAt":{"type":"integer","minimum":0},"startedAt":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}]},"pagesAudited":{"type":"integer"},"templatesAudited":{"type":"integer"},"findings":{"anyOf":[{"$ref":"#/components/schemas/FindingTotals"},{"type":"null"}],"description":"Null until the audit is completed."}},"required":["id","projectId","projectUrlId","reportNumber","status","phase","scope","createdAt","startedAt","completedAt","pagesAudited","templatesAudited","findings"]},"Finding":{"type":"object","properties":{"id":{"description":"The finding group in this audit; null for a finding this audit resolved.","type":["string","null"]},"ledgerId":{"description":"The finding's id in the project URL's ledger, the one status changes name; null when the audit has no ledger.","type":["string","null"]},"ruleId":{"type":"string"},"ruleVersion":{"anyOf":[{"type":"integer"},{"type":"null"}]},"title":{"type":"string"},"severity":{"type":"string","enum":["critical","high","medium","low"],"description":"Raised one level when a law the project chose requires the rule's criterion."},"measuredSeverity":{"anyOf":[{"type":"string","enum":["critical","high","medium","low"]},{"type":"null"}],"description":"The severity we measured, set only when severity was raised."},"standards":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["wcag","en-clause"]},"criterion":{"type":"string"},"title":{"type":"string"},"level":{"type":["string","null"]},"enClause":{"type":["string","null"]}},"required":["kind","criterion","title","level","enClause"]}},"pageUrl":{"type":"string"},"templateLabel":{"type":["string","null"]},"occurrenceCount":{"type":"integer"},"viewports":{"type":"array","items":{"type":"object","properties":{"width":{"anyOf":[{"type":"integer"},{"type":"null"}]},"height":{"anyOf":[{"type":"integer"},{"type":"null"}]},"label":{"type":["string","null"]},"kind":{"type":"string","enum":["configured","adaptive"]}},"required":["width","height","label","kind"]}},"ledgerStatus":{"anyOf":[{"type":"string","enum":["open","fix_applied","resolved","regressed","accepted"]},{"type":"null"}],"description":"The ledger's current status for the finding, which later audits and people may have changed since this audit."},"change":{"anyOf":[{"type":"string","enum":["new","regressed","persisting","resolved"]},{"type":"null"}],"description":"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."}},"required":["id","ledgerId","ruleId","ruleVersion","title","severity","measuredSeverity","standards","pageUrl","templateLabel","occurrenceCount","viewports","ledgerStatus","change"]},"FindingList":{"type":"object","properties":{"totals":{"type":"object","properties":{"findings":{"type":"integer","description":"Findings in the list, under the filters."},"bySeverity":{"type":"object","properties":{"critical":{"type":"integer"},"high":{"type":"integer"},"medium":{"type":"integer"},"low":{"type":"integer"}},"required":["critical","high","medium","low"]},"byChange":{"type":"object","properties":{"new":{"type":"integer"},"regressed":{"type":"integer"},"persisting":{"type":"integer"},"resolved":{"type":"integer"}},"required":["new","regressed","persisting","resolved"]}},"required":["findings","bySeverity","byChange"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/Finding"}},"nextCursor":{"description":"Pass as cursor for the next page; null on the last page.","type":["string","null"]}},"required":["totals","items","nextCursor"]},"LedgerItem":{"type":"object","properties":{"ledgerId":{"type":"string"},"projectUrlId":{"type":"string"},"ruleId":{"type":["string","null"]},"title":{"type":"string"},"severity":{"anyOf":[{"type":"string","enum":["critical","high","medium","low"]},{"type":"null"}]},"status":{"type":"string","enum":["open","fix_applied","resolved","regressed","accepted"]},"pageUrl":{"type":"string"},"occurrenceCount":{"type":"integer","description":"In how many completed audits the finding appeared."},"firstSeenAt":{"type":"integer","minimum":0},"lastSeenAt":{"type":"integer","minimum":0},"firstAuditId":{"type":["string","null"]},"lastAuditId":{"description":"The audit that last measured the finding.","type":["string","null"]},"statusChangedAt":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}]}},"required":["ledgerId","projectUrlId","ruleId","title","severity","status","pageUrl","occurrenceCount","firstSeenAt","lastSeenAt","firstAuditId","lastAuditId","statusChangedAt"]},"LedgerList":{"type":"object","properties":{"totals":{"type":"object","properties":{"items":{"type":"integer","description":"Findings in the list, under the status filter."},"byStatus":{"type":"object","properties":{"open":{"type":"integer"},"fix_applied":{"type":"integer"},"resolved":{"type":"integer"},"regressed":{"type":"integer"},"accepted":{"type":"integer"}},"required":["open","fix_applied","resolved","regressed","accepted"]}},"required":["items","byStatus"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/LedgerItem"}},"nextCursor":{"description":"Pass as cursor for the next page; null on the last page.","type":["string","null"]}},"required":["totals","items","nextCursor"]}}}}