Audits

The audits system provides two levels of evaluation: a fast instant audit that returns a single score, and a full audit that runs a comprehensive analysis and delivers results by email.

Audit Levels

Type	Endpoint	Turnaround	Output
Instant	POST /api/audits/instant	Under 10 seconds	Numeric score + top issues
Full	POST /api/audits/full	2-5 minutes	Detailed report delivered by email

Both endpoints accept a URL or uploaded prototype reference. The instant audit is suitable for CI/CD integration. The full audit is for design reviews and stakeholder reporting.

Endpoints

POST /api/audits/instant JWT

Run a quick accessibility audit and return a score

Analyzes the target URL for common accessibility violations and returns a score with the top issues found. Designed to complete in under 10 seconds.

Request body

{
  "url": "https://staging.example.com/checkout",
  "viewport": {
    "width": 1440,
    "height": 900
  },
  "checkCategories": ["contrast", "keyboard", "aria", "images"]
}

Field	Type	Required	Description
url	string	Yes	Publicly accessible URL to audit
viewport	object	No	Browser viewport dimensions. Defaults to { width: 1280, height: 800 }.
checkCategories	array of strings	No	Limit checks to these categories. Defaults to all.

Available check categories

Category	What it checks
contrast	Text and UI component color contrast ratios (WCAG AA/AAA)
keyboard	Focus order, keyboard trappability, skip links
aria	ARIA roles, labels, and landmark usage
images	Alt text presence and quality
forms	Label associations, error identification, autocomplete
headings	Heading hierarchy and presence

Response

{
  "success": true,
  "data": {
    "auditId": "audit_instant_001",
    "url": "https://staging.example.com/checkout",
    "score": 74,
    "grade": "C",
    "topIssues": [
      {
        "issueId": "i_001",
        "category": "contrast",
        "severity": "critical",
        "element": "button.checkout-cta",
        "description": "Contrast ratio is 2.8:1. Minimum required is 4.5:1 for normal text.",
        "wcagCriteria": "1.4.3"
      },
      {
        "issueId": "i_002",
        "category": "images",
        "severity": "serious",
        "element": "img.product-thumbnail",
        "description": "Image has no alt attribute.",
        "wcagCriteria": "1.1.1"
      },
      {
        "issueId": "i_003",
        "category": "keyboard",
        "severity": "moderate",
        "element": "div.custom-dropdown",
        "description": "Interactive element is not keyboard accessible.",
        "wcagCriteria": "2.1.1"
      }
    ],
    "issueCounts": {
      "critical": 1,
      "serious": 3,
      "moderate": 5,
      "minor": 4
    },
    "completedAt": "2026-03-16T10:00:07Z"
  },
  "error": null,
  "metadata": null
}

Score grades

Score	Grade
90-100	A
80-89	B
70-79	C
60-69	D
Below 60	F

POST /api/audits/full JWT

Run a full accessibility audit and deliver results by email

Performs a comprehensive audit covering all WCAG 2.1 Level AA criteria. The report is generated asynchronously and emailed to the requesting user when complete.

Request body

{
  "url": "https://staging.example.com",
  "crawl": true,
  "maxPages": 10,
  "viewport": {
    "width": 1440,
    "height": 900
  },
  "reportTitle": "Staging - Full Accessibility Audit",
  "recipientEmails": ["designer@example.com", "pm@example.com"]
}

Field	Type	Required	Description
url	string	Yes	Starting URL for the audit
crawl	boolean	No	Whether to follow internal links and audit multiple pages. Defaults to false.
maxPages	integer	No	Maximum pages to audit when crawl is true. Defaults to 5, max 50.
viewport	object	No	Browser viewport dimensions
reportTitle	string	No	Title shown on the delivered report
recipientEmails	array of strings	No	Additional email addresses to send the report to. The requesting user is always included.

Response

The endpoint responds immediately with a job ID. The audit runs in the background.

{
  "success": true,
  "data": {
    "auditJobId": "auditjob_001",
    "url": "https://staging.example.com",
    "crawl": true,
    "maxPages": 10,
    "status": "queued",
    "estimatedCompletionMinutes": 3,
    "reportDeliveredTo": [
      "requester@example.com",
      "designer@example.com",
      "pm@example.com"
    ],
    "queuedAt": "2026-03-16T10:00:00Z"
  },
  "error": null,
  "metadata": null
}

Email report contents

The delivered report includes:

• Overall accessibility score and grade
• Per-page score breakdown (when crawl is true)
• Full issue list grouped by category and severity
• WCAG 2.1 criteria reference for each issue
• Annotated screenshots for critical and serious issues
• Prioritized remediation recommendations

Status values for auditJobId

Poll GET /api/audits/:auditJobId (when available) or wait for the email. Status transitions: queued > running > complete or failed.