Create, Modify, and Run Scans by API

Axe Monitor admins can generate an API key in Axe Account and create, modify or run scans systematically, without using the user interface.

Learn more about Getting Started.

Endpoints

Create a Scan

Creates one scan from a single scan settings object. To create several scans at once, send one request per scan.

Note: To keep your credentials secure, the API doesn’t accept passwords, keystore files, or environment variable values. Add these values in the Axe Monitor user interface in the scan’s log-in details.

Example Request

GET
https://yourcompany.dequecloud.com/monitor-public-api/v1/scans
X-API-Key: <your_api_key>
Content-Type: application/json

Required Parameters

Optional Settings

Additional scan settings can be used with the Create Scan endpoint. View Scan Settings documentation.

Example Request

{
  "name": "Marketing Site - Production",
  "sites": ["https://www.example.com"],
  "axeCoreVersion": "latest",
  "standardLevel": "wcag22aa",
  "standardOptions": ["best-practice"],
  "depth": 3,
  "pageLimit": 100,
  "skipSpecificUrls": ["https://www.example.com/logout"],
  "teams": [
    { "name": "Digital Accessibility Team" }
  ],
  "notifyGroup": true
}

Example Response

Status: 201 Created

{
  "scanId": 12345
}

Use the returned [scanId] to read, edit, or run the scan.

Note: The API does not accept passwords, keystores, or environment variable values. If your scan signs in to a site or runs scripts that need secret values, create the scan through the API, then add those values in axe Monitor under Advanced Settings, Starting a session.

Error Responses

Edit a Scan

Updates one or more settings of an existing scan. Send only the settings you want to change; settings you leave out keep their current values.

Note:

• Some settings require IDs to be edited. View the documentation for getting IDs.
• When a scan has a preset applied, some settings may not be editable. View the preset documentation.
• View the full list of scan settings that can be edited via API.

Example Request

PATCH
https://yourcompany.dequecloud.com/monitor-public-api/v1/scans/[scanId]/settings
X-API-Key: <your_api_key>
Content-Type: application/json

Required Parameters

At least one additional setting is required to make a change. View Scan Settings documentation.

Note:

• ‘null’ resets a field to its default
• Arrays replace the stored value

Example Request

{
  "name": "Marketing Site - Production (weekly)",
  "depth": 4,
  "pageLimit": 250
}

Example Response

Status: 200 OK

{
  "scanId": 12345,
  "updatedFields": ["name", "depth", "pageLimit"]
}

updatedFields lists the settings that changed.

Error Response

Start a Scan Run

Queues a new run of an existing scan. The run starts when axe Monitor picks it up from the queue. To check its progress, use GET /scans/[scanId]/runs.

Example Request

POST
https://yourcompany.dequecloud.com/monitor-public-api/v1/scans/[scanId]/runs
X-API-Key: <your_api_key>

Required Parameters

Example Response

Status: 202 Accepted

The response has no body.

Example Error Response

{
  "title": "Bad Request",
  "status": 400,
  "detail": "Couldn't queue job since it's already running",
  "instance": "/v1/scans/20/runs"
}

Error Responses