Get Started with the Axe Developer Hub APIs

This page is not available in the language you requested. You have been redirected to the English version of the page.

Link to this page copied to clipboard

Set up authentication, find your project ID, and make your first call to the Axe Developer Hub REST APIs

Not for use with personal data

Every Axe Developer Hub API uses the same setup: an Axe Account API key sent in a request header, and, for most requests, a project ID. This guide walks through that setup once, makes a first call to confirm it works, and then points you to the API for the task you have in mind.

note

There is no separate API credential. The Axe Account API key you already use to send test results to Axe Developer Hub also works for every Axe Developer Hub API.

Get Your API Key

Sign in to the Axe Account Portal.
Copy an API key for the product your project uses:
- An Axe Developer Hub API key for web and CI/CD projects.
- An Axe DevTools Mobile API key for mobile projects.

An API key only returns data for its own product. An Axe Developer Hub API key can't retrieve Axe DevTools Mobile data, and an Axe DevTools Mobile API key can't retrieve Axe Developer Hub data, even for an Org Admin. Which projects a key can access within its product depends on your project membership and role: see Access Control in the Sessions and Results API Reference and the Projects API Reference.

Send the API Key with Each Request

Send your API key in the X-API-Key header of every request, and ask for a JSON response with the Accept header:

X-API-Key: <DEQUE_API_KEY>
Accept: application/json

Treat your API key as a secret: store it in an environment variable or your CI/CD platform's secret store rather than hardcoding it in your requests. The examples in this guide read it from an API_KEY environment variable.

Find Your Project ID

Most requests identify a project by its project ID. You can find it in either of two ways:

In Axe Developer Hub: Go to your projects, open the Settings menu for your project, and select Configure project. The project ID appears at the top of the instructions page.
With the Projects API: Look up the ID from the project's name. See Look Up a Project ID by Name.

Make Your First Call

List the projects your API key can access. This request doesn't need a project ID, so it's a quick way to confirm your key works:

curl -s \
  -H "Accept: application/json" \
  -H "X-API-Key: $API_KEY" \
  "https://axe.deque.com/api-pub/v1/results/projects"

A 200 OK response with a JSON array of projects means your key is valid and active. Each project's project_id is the ID to use in the other APIs. If you get 401 Unauthorized instead, check that you copied the whole key and that it belongs to the product your projects use.

Choose Your Task

Gate a CI/CD Pipeline

Use the Commit Status API to fail a pull request or commit when accessibility errors are found. Your request passes a Git commit SHA and a project ID, and the response reports the number of accessibility errors from that commit's test run and how many are over your a11y threshold. Your project must use Git data.

If your pipeline runs on GitHub, use the GitHub Action instead of calling the API directly.

Retrieve Accessibility Results

Use the Sessions and Results API to download results. Call the Sessions endpoint to list a project's sessions, then pass a session's session_id to the Results endpoint.

Two behaviors of the Results endpoint affect how you write your client:

Results can take time to prepare. A 204 No Content response means the results aren't ready yet. Wait briefly and repeat the request until you get 200 OK. See Session State and the Polling Pattern.
Results download fastest with Brotli compression. Send Accept-Encoding: br (or use curl --compressed with a Brotli-enabled curl), especially for format=full. See Response Compression.

Manage Projects and Members

Use the Projects API to list your projects, page through them, or find a project ID by name. You can also create, update, and delete projects, and add, change, or remove project members. To automate that work, start with Get Started with Project Management Automation.

Handle Errors and Retries

The Axe Developer Hub APIs share a common set of error responses:

Status	Meaning	Retry?
`400 Bad Request`	A path or query parameter, or the request body, is invalid, for example a malformed ID or timestamp or a missing required field.	No. Fix the request first.
`401 Unauthorized`	The API key is invalid or missing, or its subscription is inactive.	No. Check the key and your subscription.
`403 Forbidden`	The API key doesn't have access to the requested project or operation, for example updating a project you aren't an admin of.	No. Check your project membership or role, and that your subscription covers the project type.
`404 Not Found`	The requested project, session, or commit doesn't exist.	No. Check the ID or SHA.
`429 Too Many Requests`	The system is under heavy load.	Yes, after the number of seconds in the `Retry-After` header.

When you poll the Results endpoint, 204 No Content isn't an error: it means the results aren't ready yet, and you retry the same request after a short wait. Wait longer between retries the more times you retry, and give up after a reasonable limit so a stuck session doesn't hold your pipeline indefinitely.

Each reference page lists the exact error responses for its endpoints. Build your retry logic so it can handle 429 Too Many Requests from any endpoint, not only the Results endpoint.