API Documentation

Integrate CompliaScan into your development workflow with our REST API. Programmatically create scans, retrieve results, enforce CI/CD quality gates, and receive real-time webhook notifications.

Base URL: https://compliascan.com/api/v1

Authentication

All API requests require a Bearer token in the Authorization header. API keys are prefixed with cs_ and can be generated from your dashboard settings.

Authorization: Bearer cs_live_your_api_key_here

Rate Limit: All endpoints are rate-limited to 100 requests per minute per API key. Exceeding this limit returns a 429 status code with a Retry-After header.

Endpoints

POST/api/v1/scan

Create a new accessibility scan. The scan runs asynchronously and returns immediately with a scan ID you can use to poll for results.

Request Body

Parameter	Type	Required	Description
`url`	string	Yes	The URL to scan. Must be a valid, publicly accessible URL.
`multiPage`	boolean	No	When true, crawls and scans linked pages from the root URL. Defaults to false.
`callbackUrl`	string	No	A webhook URL to receive a POST notification when the scan completes.
`waitForSelector`	string	No	CSS selector to wait for before scanning. Useful for SPAs that load content dynamically.
`waitTime`	number	No	Additional wait time in milliseconds (0-10000) after page load before scanning.

Response 202 Accepted

{
  "scanId": "scn_a1b2c3d4e5f6",
  "status": "pending",
  "statusUrl": "/api/v1/scan/scn_a1b2c3d4e5f6"
}

GET/api/v1/scan/{scanId}

Retrieve the results of a completed scan. While the scan is still running, the response will include "status": "running". Poll this endpoint until the status changes to "complete".

Response 200 OK

{
  "scan": {
    "id": "scn_a1b2c3d4e5f6",
    "url": "https://example.com",
    "status": "complete",
    "score": 72,
    "totalIssues": 18,
    "criticalCount": 2,
    "seriousCount": 5,
    "moderateCount": 7,
    "minorCount": 4,
    "pagesScanned": 1
  },
  "results": [
    {
      "ruleId": "color-contrast",
      "impact": "serious",
      "description": "Elements must have sufficient color contrast",
      "helpText": "Ensure foreground and background colors meet WCAG 2 AA minimum contrast ratio thresholds.",
      "wcagCriteria": ["1.4.3"],
      "affectedNodes": [
        {
          "html": "<p class=\"light-text\">...</p>",
          "selector": ".hero > p.light-text",
          "failureSummary": "Element has insufficient color contrast of 2.8:1 (foreground: #999999, background: #ffffff, expected ratio: 4.5:1)"
        }
      ]
    }
  ]
}

GET/api/v1/scan/{scanId}/gate

CI/CD quality gate endpoint. Returns a pass or fail verdict based on configurable thresholds. Use this in your deployment pipeline to block releases that introduce accessibility regressions.

Query Parameters

Parameter	Type	Description
`threshold`	number	Minimum accessibility score to pass (0-100). Defaults to 70.
`maxCritical`	number	Maximum critical issues allowed before failing. Optional.
`maxSerious`	number	Maximum serious issues allowed before failing. Optional.

Response 200 OK

{
  "passed": true,
  "score": 92,
  "threshold": 70,
  "gates": {
    "score": { "passed": true, "actual": 92, "threshold": 70 },
    "critical": { "passed": true, "actual": 0, "threshold": 1 }
  },
  "summary": {
    "totalIssues": 5,
    "critical": 0,
    "serious": 2,
    "moderate": 2,
    "minor": 1
  },
  "scanUrl": "https://compliascan.com/scan/scn_a1b2c3d4e5f6"
}

GET/api/v1/export

Export all scan data for your account as a JSON array. Useful for data warehousing, custom reporting, or backing up your compliance history.

Query Parameters

Parameter	Type	Description
`from`	string	ISO 8601 start date filter (e.g. `2025-01-01`).
`to`	string	ISO 8601 end date filter (e.g. `2025-12-31`).

Response 200 OK

{
  "scans": [
    {
      "id": "scn_a1b2c3d4e5f6",
      "url": "https://example.com",
      "score": 72,
      "totalIssues": 18,
      "createdAt": "2025-06-15T10:30:00Z"
    }
  ],
  "totalCount": 142,
  "exportedAt": "2025-07-01T12:00:00Z"
}

POST/api/v1/scan/{scanId}/fixStarter+

Generate fix instructions for all violations in a completed scan. Uses your BYOK API key (OpenAI, Anthropic, or Gemini) if configured, otherwise returns deterministic rule-based suggestions.

Response 200 OK

{
  "fixes": [
    {
      "scanResultId": "uuid",
      "ruleId": "color-contrast",
      "impact": "serious",
      "instruction": "Increase the contrast ratio...",
      "codeSnippet": "<!-- Before -->\n<p style=\"color: #999\">...\n<!-- After -->\n<p style=\"color: #595959\">...",
      "provider": "deterministic",
      "model": "rule-templates-v1"
    }
  ],
  "count": 18
}

GET/api/v1/scan/{scanId}/fix/{resultId}Starter+

Get a specific fix instruction for a single scan result. Returns the cached fix if already generated.

Response 200 OK

{
  "fix": {
    "id": "uuid",
    "scanResultId": "uuid",
    "ruleId": "image-alt",
    "impact": "critical",
    "instruction": "Add descriptive alt text...",
    "codeSnippet": "<img src=\"logo.png\" alt=\"Company logo\" />",
    "provider": "openai",
    "model": "gpt-4o-mini",
    "createdAt": "2026-02-15T10:30:00Z"
  },
  "cached": true
}

GET/api/v1/sites/{siteId}/history

Get score history for a monitored site. Useful for tracking accessibility improvements over time.

Query Parameters

Parameter	Type	Description
`days`	number	Number of days of history to return (1-365). Defaults to 30.

Response 200 OK

{
  "history": [
    {
      "score": 78,
      "totalIssues": 12,
      "criticalCount": 1,
      "seriousCount": 3,
      "recordedAt": "2026-02-15T10:30:00Z"
    },
    {
      "score": 82,
      "totalIssues": 9,
      "criticalCount": 0,
      "seriousCount": 2,
      "recordedAt": "2026-02-08T10:30:00Z"
    }
  ],
  "days": 30
}

GET/api/v1/sites/{siteId}/alerts

Get monitoring alert configurations for a site. Alerts trigger email notifications when accessibility metrics change.

Response 200 OK

{
  "alerts": [
    {
      "alertType": "score_drop",
      "threshold": 5,
      "enabled": true,
      "notifyEmail": "dev@example.com"
    },
    {
      "alertType": "new_critical",
      "enabled": true,
      "notifyEmail": "dev@example.com"
    }
  ]
}

Webhooks

If you provide a callback_url when creating a scan, CompliaScan will send a POST request to that URL when the scan completes. This eliminates the need for polling.

Webhook Payload

{
  "event": "scan.complete",
  "scanId": "scn_a1b2c3d4e5f6",
  "data": {
    "url": "https://example.com",
    "score": 72,
    "totalIssues": 18,
    "criticalCount": 2,
    "seriousCount": 5,
    "moderateCount": 7,
    "minorCount": 4
  },
  "detailsUrl": "https://compliascan.com/api/v1/scan/scn_a1b2c3d4e5f6"
}

Your endpoint should return a 2xx status code within 10 seconds. CompliaScan will retry failed deliveries up to 3 times with exponential backoff.

Error Codes

All errors follow a consistent format with a machine-readable code and a human-readable message.

Code	HTTP Status	Description
`AUTH_REQUIRED`	401	No Authorization header was provided in the request.
`INVALID_KEY`	401	The provided API key is invalid, expired, or revoked.
`RATE_LIMITED`	429	You have exceeded the rate limit of 100 requests per minute. Retry after the duration specified in the `Retry-After` header.
`VALIDATION`	400	The request body failed validation. Check the `details` field for specific field errors.
`INVALID_URL`	400	The provided URL is malformed or not publicly accessible.
`NOT_FOUND`	404	The requested scan or site ID does not exist or does not belong to your account.
`PLAN_REQUIRED`	403	This feature requires a higher plan. Check the endpoint documentation for plan requirements.
`SCAN_NOT_COMPLETE`	400	The scan has not finished processing yet. Poll the scan status endpoint until complete.

Error Response Format

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 32 seconds.",
    "retryAfter": 32
  }
}

Quick Start

Get up and running in two steps. Replace cs_live_your_api_key with your actual API key from the dashboard.

1. Create a scan

curl -X POST https://compliascan.com/api/v1/scan \
  -H "Authorization: Bearer cs_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "multiPage": false,
    "callback_url": "https://your-server.com/webhooks/compliascan"
  }'

2. Check scan results

curl https://compliascan.com/api/v1/scan/scn_a1b2c3d4e5f6 \
  -H "Authorization: Bearer cs_live_your_api_key"

3. Check CI/CD gate

curl "https://compliascan.com/api/v1/scan/scn_a1b2c3d4e5f6/gate?threshold=70&maxCritical=0" \
  -H "Authorization: Bearer cs_live_your_api_key"

4. Generate fix suggestions

curl -X POST https://compliascan.com/api/v1/scan/scn_a1b2c3d4e5f6/fix \
  -H "Authorization: Bearer cs_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{}'

5. Export all scan data

curl "https://compliascan.com/api/v1/export" \
  -H "Authorization: Bearer cs_live_your_api_key"

Ready to integrate?

API access is available on paid plans. Generate API keys from your dashboard settings and start scanning programmatically today.

Get API Access

API Documentation

Authentication

Endpoints

Request Body

Response 202 Accepted

Response 200 OK

Query Parameters

Response 200 OK

Query Parameters

Response 200 OK

Response 200 OK

Response 200 OK

Query Parameters

Response 200 OK

Response 200 OK

Webhooks

Webhook Payload

Error Codes

Error Response Format

Quick Start

1. Create a scan

2. Check scan results

3. Check CI/CD gate

4. Generate fix suggestions

5. Export all scan data

Ready to integrate?

Related Resources

All Features

View Pricing

Contact Us