# ADAGuard

> Automated Web Accessibility Scanner & WCAG Compliance Reporter

ADAGuard is a SaaS platform that scans websites for WCAG 2.1/2.2 compliance issues and generates VPAT/ACR reports. It provides ~74% automated WCAG coverage with support for authenticated page scanning (login-protected pages).

## API Base URL

Production: `https://api.adaguard.io/v1`

Interactive docs (Swagger UI): `https://api.adaguard.io/v1/docs`

OpenAPI spec (machine-readable): `https://api.adaguard.io/v1/openapi.json`

## Authentication

All API requests require an API key passed via header:

```
X-API-Key: your_api_key_here
```

API keys are available from your dashboard at `https://app.adaguard.io/settings`.
API access requires the **Professional** plan or higher.

## Core Endpoints

### Start a Scan

`POST /v1/scan`

Returns immediately with a `scan_id`. The scan runs in the background — poll `/v1/scan/{scan_id}/status` to track progress.

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

- `scan_mode`: `single` (default) | `crawl` | `sitemap` | `layout`
- `max_pages`: 1–5000, capped to plan limit. Ignored for `single` mode.
- `min_score`: CI/CD gate — result includes `passed: true/false` when set.
- `auth_session_id`: reference a stored auth session for scanning login-protected pages.
- `viewport`: `desktop` (1920×1080) | `mobile` (390×844 / iPhone 14 Pro)
- `exclude_paths`: array of path prefixes to skip during crawl (e.g. `["/blog", "/admin"]`)

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

### Poll Scan Progress

`GET /v1/scan/{scan_id}/status`

Call repeatedly until `status` is `completed` or `failed`. Use `poll_again_in` as retry interval hint.

Response:
```json
{
  "scan_id": "abc123",
  "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",
  "poll_again_in": null
}
```

`auth_status` values:
- `not_requested` — no auth session provided
- `authenticated` — scan ran with the stored session
- `expired_fallback` — session expired; scan fell back to public pages
- `public_only` — site detected as public

### Get Full Scan Results

`GET /v1/scan/{scan_id}`

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

### Download Report

`GET /v1/scan/{scan_id}/report?format=json`

Formats: `json` (default) | `html` | `csv` | `pdf`

- `json` — structured data, ideal for CI/CD parsing
- `html` — self-contained HTML report
- `csv` — spreadsheet-friendly issue list for QA teams
- `pdf` — professional PDF for compliance/executive sharing

### List Scans

`GET /v1/scans?limit=10&offset=0&url=https://example.com`

Returns scan history sorted newest first. Filter by URL prefix with `?url=`.

### Usage Statistics

`GET /v1/scans/stats`

Returns total scans, scans used this month, average score, and issue counts.

### List Authenticated Sessions

`GET /v1/auth-sessions`

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

### Delete a Scan

`DELETE /v1/scan/{scan_id}`

Permanently deletes a scan and its stored data.

## Plan Limits

| Tier         | Price/mo | Scans/Month | Pages/Scan | API Access | Rate Limit      |
|-------------|----------|-------------|------------|------------|-----------------|
| Free         | $0       | 1           | 5          | No         | —               |
| Starter      | $49      | 4           | 50         | No         | —               |
| Professional | $129     | 30          | 200        | Yes        | 100 req/hour    |
| Business     | $249     | 150         | 1,000      | Yes        | 500 req/hour    |

Scan quota is per calendar month and resets on the 1st.

## Error Responses

All errors follow this shape:

```json
{
  "error": "Human-readable summary",
  "details": [{"field": "url", "message": "Only http and https URLs are allowed"}]
}
```

Common status codes:
- `422` — validation error (invalid request body)
- `429` — rate limit or monthly scan quota exceeded
- `404` — scan or session not found
- `409` — operation not valid for scan in current state (e.g. report on incomplete scan)

## Links

- Website: https://www.adaguard.io
- App: https://app.adaguard.io
- API Docs: https://api.adaguard.io/v1/docs
- OpenAPI Spec: https://api.adaguard.io/v1/openapi.json
- Status: https://status.adaguard.io