ADAGuard API Documentation

Start a new accessibility scan

Returns immediately with a scan_id. The scan runs in the background. Poll GET /v1/scan/{scan_id}/status until status is 'completed' or 'failed'.

Required scopes: scans:write

Request Body

{
  "url": "https://example.com",
  "scan_mode": "single",
  "max_pages": 1,
  "min_score": 80,
  "auth_session_id": null,
  "viewport": "desktop",
  "exclude_paths": []
}

Response

{
  "scan_id": "abc-123",
  "status": "queued",
  "url": "https://example.com",
  "created_at": "2025-01-01T00:00:00Z",
  "poll_url": "/v1/scan/abc-123/status"
}

• scan_mode: single (default) | crawl | sitemap | layout
• max_pages: 1–5000, capped to your plan limit. Ignored for single mode.
• min_score: CI/CD gate — result includes passed:true/false when set.
• viewport: desktop (1920×1080) | mobile (390×844 / iPhone 14 Pro)
• exclude_paths: path prefixes to skip during crawl, e.g. ["/blog"]

Poll scan progress

Call repeatedly until status is 'completed' or 'failed'. Use poll_again_in (seconds) as the suggested retry interval.

Required scopes: scans:read, scans:write

Response

{
  "scan_id": "abc-123",
  "status": "completed",
  "url": "https://example.com",
  "score": 87,
  "passed": true,
  "pages_scanned": 1,
  "max_pages": 1,
  "issues_critical": 2,
  "issues_warning": 5,
  "issues_info": 3,
  "auth_status": "not_requested",
  "error": null,
  "poll_again_in": null
}

• auth_status values: not_requested | authenticated | expired_fallback | public_only
• passed is null if min_score was not set at scan creation
• poll_again_in is null when status is completed or failed

Get full scan results including all issues

Returns the complete scan document with all accessibility issues, WCAG criteria, severity levels, element selectors, and remediation suggestions.

Required scopes: scans:read, scans:write

• Large scans (100+ pages) may take a moment to load from storage
• Issues include: severity, type, description, impact, difficulty, count, wcag, help_url, elements

Download a scan report

Generates and downloads a report for a completed scan. The scan must be in 'completed' status.

Required scopes: scans:read, scans:write

Query Parameters

• Returns 409 if scan is not yet completed
• PDF reports include a watermark on Free tier

List scans

Returns scan history sorted newest first.

Required scopes: scans:read, scans:write

Query Parameters

Response

{
  "scans": [
    {
      "id": "abc-123",
      "url": "https://example.com",
      "timestamp": "2025-01-01T00:00:00Z",
      "score": 87,
      "status": "completed",
      "pages_scanned": 1,
      "issues_critical": 2,
      "issues_warning": 5,
      "issues_info": 3,
      "passed": true,
      "auth_status": "not_requested"
    }
  ],
  "total": 42,
  "limit": 10,
  "offset": 0,
  "has_more": true
}

Get usage statistics

Returns scan counts, monthly quota usage, and aggregate issue totals.

Required scopes: stats:read

Response

{
  "user_id": "usr_abc",
  "total_scans": 42,
  "completed_scans": 40,
  "scans_used": 12,
  "scans_limit": 30,
  "average_score": 84.5,
  "total_issues": {
    "critical": 18,
    "warning": 67,
    "info": 120
  }
}

List authenticated sessions

Lists stored browser auth sessions. Sessions are created in the dashboard (Settings → Authenticated Scans). Use session_id as auth_session_id in POST /v1/scan.

Required scopes: scans:read, scans:write

Response

{
  "auth_sessions": [
    {
      "session_id": "sess_abc",
      "domain": "example.com",
      "url": "https://example.com/login",
      "status": "active",
      "created_at": "2025-01-01T00:00:00Z",
      "expires_at": "2025-02-01T00:00:00Z",
      "last_used": "2025-01-15T00:00:00Z"
    }
  ],
  "total": 1
}

• Sessions with status 'expired' trigger auth_status='expired_fallback' in scan results
• Sessions cannot be created via API — use the dashboard

Delete a scan

Permanently deletes a scan and all its stored data. This action cannot be undone.

Required scopes: scans:delete

Response

{
  "success": true,
  "message": "Scan deleted successfully",
  "scan_id": "abc-123"
}