DocsAPI Reference

REST API

API Reference

Build custom integrations, dashboards, or pipelines on top of Aulys. The REST API gives you full programmatic access to scans, projects, and reports.

Base URL: https://api.aulys.app/v1

Authentication

All API requests must include your API key in the Authorization header as a Bearer token. Generate an API key in the Aulys dashboard under Settings → API Keys.

Authentication header

Authorization: Bearer aul_sk_live_xxxxxxxxxxxxxxxxxxxx

# Example: authenticate a curl request
curl https://api.aulys.app/v1/scans \
  -H "Authorization: Bearer aul_sk_live_xxxxxxxxxxxxxxxxxxxx"

Live key prefix

aul_sk_live_

Charges against your plan quota

Test key prefix

aul_sk_test_

Does not charge quota — limited features

Keep your API key secret. Never expose it in client-side JavaScript, public repos, or build logs. If compromised, rotate it immediately in the dashboard.

Rate limits

Plan	Requests / min	Scans / month	Concurrent scans
Free	10	25 pages	1
Pro	60	500 pages	5
Team	120	2,500 pages	10
Enterprise	Custom	Unlimited	Custom

Rate limit headers are returned on every response: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Error codes

Status	Code	Meaning
`400`	`invalid_request`	Missing or malformed request body
`401`	`unauthorized`	Missing or invalid API key
`403`	`forbidden`	API key does not have permission for this resource
`404`	`not_found`	The scan or project does not exist
`422`	`scan_failed`	The URL could not be reached or rendered
`429`	`rate_limited`	Too many requests — check X-RateLimit-Reset header
`500`	`internal_error`	Aulys server error — retry after a few seconds

Endpoints

POST/v1/scans

Create a new accessibility scan for a URL.

Request body

{
  "url": "https://example.com",          // required
  "wcagVersion": "2.2",                  // "2.1" | "2.2"
  "wcagLevel": "AA",                     // "A" | "AA" | "AAA"
  "projectId": "proj_abc123",            // optional
  "metadata": { "env": "staging" }       // optional key-value tags
}

Response

{
  "id": "scan_xyz789",
  "status": "pending",
  "url": "https://example.com",
  "createdAt": "2024-06-15T10:30:00Z",
  "estimatedSeconds": 15
}

GET/v1/scans/{scan_id}

Retrieve the result of a completed scan.

Response

{
  "id": "scan_xyz789",
  "status": "completed",      // pending | running | completed | failed
  "url": "https://example.com",
  "score": 72,
  "summary": {
    "critical": 3,
    "warning": 11,
    "info": 4,
    "passed": 48
  },
  "violations": [
    {
      "id": "viol_001",
      "criterion": "1.4.3",
      "level": "AA",
      "severity": "critical",
      "description": "Text has insufficient contrast ratio (2.3:1, needs 4.5:1)",
      "element": "<p class='hint-text'>Required field</p>",
      "selector": "form.contact > p.hint-text",
      "fix": "Change color from #aaaaaa to #6b7280"
    }
  ],
  "completedAt": "2024-06-15T10:30:18Z"
}

GET/v1/scans

List all scans for your account, paginated.

Response

{
  "data": [ ...scan objects... ],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "total": 143,
    "nextCursor": "cur_abc"
  }
}

POST/v1/projects

Create a project to group related scans.

Request body

{
  "name": "My Website",
  "baseUrl": "https://example.com",
  "wcagLevel": "AA"
}

Response

{
  "id": "proj_abc123",
  "name": "My Website",
  "createdAt": "2024-06-15T09:00:00Z"
}

GET/v1/reports/{scan_id}

Generate a downloadable compliance report (VPAT / EAA / Section 508).

Response

{
  "id": "rep_def456",
  "scanId": "scan_xyz789",
  "format": "vpat",       // vpat | eaa | section508
  "downloadUrl": "https://cdn.aulys.app/reports/rep_def456.pdf",
  "expiresAt": "2024-06-22T10:30:00Z"
}

Webhooks

Instead of polling for scan results, configure a webhook to receive a POST request when a scan completes. Set up webhooks in the dashboard under Settings → Webhooks.

Webhook payload (scan.completed)

{
  "event": "scan.completed",
  "scanId": "scan_xyz789",
  "url": "https://example.com",
  "score": 72,
  "summary": {
    "critical": 3,
    "warning": 11
  },
  "timestamp": "2024-06-15T10:30:18Z",
  "signature": "sha256=..."  // HMAC-SHA256 of the payload using your webhook secret
}

Always verify the signature header before processing webhook payloads. Compute HMAC-SHA256(payload, webhookSecret) and compare with the received value.

Plan

Requests / min

Scans / month

Concurrent scans

Free

25 pages

Pro

500 pages

Team

120

2,500 pages

Enterprise

Custom

Unlimited

Custom

Error codes

Status	Code	Meaning
`400`	`invalid_request`	Missing or malformed request body
`401`	`unauthorized`	Missing or invalid API key
`403`	`forbidden`	API key does not have permission for this resource
`404`	`not_found`	The scan or project does not exist
`422`	`scan_failed`	The URL could not be reached or rendered
`429`	`rate_limited`	Too many requests — check X-RateLimit-Reset header
`500`	`internal_error`	Aulys server error — retry after a few seconds

Endpoints

POST/v1/scans

Create a new accessibility scan for a URL.

Request body

{
  "url": "https://example.com",          // required
  "wcagVersion": "2.2",                  // "2.1" | "2.2"
  "wcagLevel": "AA",                     // "A" | "AA" | "AAA"
  "projectId": "proj_abc123",            // optional
  "metadata": { "env": "staging" }       // optional key-value tags
}

Response

{
  "id": "scan_xyz789",
  "status": "pending",
  "url": "https://example.com",
  "createdAt": "2024-06-15T10:30:00Z",
  "estimatedSeconds": 15
}

GET/v1/scans/{scan_id}

Retrieve the result of a completed scan.

Response

{
  "id": "scan_xyz789",
  "status": "completed",      // pending | running | completed | failed
  "url": "https://example.com",
  "score": 72,
  "summary": {
    "critical": 3,
    "warning": 11,
    "info": 4,
    "passed": 48
  },
  "violations": [
    {
      "id": "viol_001",
      "criterion": "1.4.3",
      "level": "AA",
      "severity": "critical",
      "description": "Text has insufficient contrast ratio (2.3:1, needs 4.5:1)",
      "element": "<p class='hint-text'>Required field</p>",
      "selector": "form.contact > p.hint-text",
      "fix": "Change color from #aaaaaa to #6b7280"
    }
  ],
  "completedAt": "2024-06-15T10:30:18Z"
}

GET/v1/scans

List all scans for your account, paginated.

Response

{
  "data": [ ...scan objects... ],
  "pagination": {
    "page": 1,
    "perPage": 20,
    "total": 143,
    "nextCursor": "cur_abc"
  }
}

POST/v1/projects

Create a project to group related scans.

Request body

{
  "name": "My Website",
  "baseUrl": "https://example.com",
  "wcagLevel": "AA"
}

Response

{
  "id": "proj_abc123",
  "name": "My Website",
  "createdAt": "2024-06-15T09:00:00Z"
}

GET/v1/reports/{scan_id}

Generate a downloadable compliance report (VPAT / EAA / Section 508).

Response

{
  "id": "rep_def456",
  "scanId": "scan_xyz789",
  "format": "vpat",       // vpat | eaa | section508
  "downloadUrl": "https://cdn.aulys.app/reports/rep_def456.pdf",
  "expiresAt": "2024-06-22T10:30:00Z"
}

Webhooks

Instead of polling for scan results, configure a webhook to receive a POST request when a scan completes. Set up webhooks in the dashboard under Settings → Webhooks.

Webhook payload (scan.completed)

{
  "event": "scan.completed",
  "scanId": "scan_xyz789",
  "url": "https://example.com",
  "score": 72,
  "summary": {
    "critical": 3,
    "warning": 11
  },
  "timestamp": "2024-06-15T10:30:18Z",
  "signature": "sha256=..."  // HMAC-SHA256 of the payload using your webhook secret
}

Always verify the signature header before processing webhook payloads. Compute HMAC-SHA256(payload, webhookSecret) and compare with the received value.