The Downloadable Reports REST Service

The downloadable reports REST service allows you to download your axe Developer Hub accessibility results as JSON data for further processing or importing into other software. The GET service expects an API key for the project whose data you want to download, and you can use two optional query parameters to limit to a specific Git commit SHA or a specific Git branch.

Request Summary

• Endpoint: https://axe.deque.com/api-pub/watcher/downloadable/report
• Request: GET
• Headers (required):
  • X-API-Key: your project's API key
  • Accept: application/json
• Query parameters (optional):
  • commit_sha
    • Description: Returns the downloadable report for the specified Git commit SHA.
    • Example usage: GET https://axe.deque.com/api-pub/watcher/downloadable/report?commit_sha=f73ea5a02386b359ffa79a76473f7a5ad41759d5
  • branch_name
    • Description: Returns the downloadable report for the specified Git branch name.
    • Example usage: GET https://axe.deque.com/api-pub/watcher/downloadable/report?branch_name=main

Example

• Example curl request:

  curl -L -H 'Accept: application/json' -H 'X-API-Key: 1bbad7d1-a45e-427d-8d64-7f783911e59d' 'https://axe.deque.com/api-pub/watcher/downloadable/report'

  note

  You could receive a 202 Processing response and should retry your request.

• Example response body:

  {
    "report_id": "a4990926-3014-4799-aa39-7aca31fce412",
    "source": {
      "product_name": "axe-devtools-html",
      "product_component_name": "axe-devtools-watcher",
      "product_version": "3.20.2"
    },
    "test_details": {
      "test_id": "da0c79a5-6f1e-4692-a255-5757629208fa",
      "start_date": "2025-05-05T20:02:31.883Z",
      "end_date": "2025-05-05T20:02:42.789Z"
    },
    "commit": {
      "sha": "f73ea5a02386b359ffa79a76473f7a5ad41759d5",
      "author": "John Doe",
      "author_email": "john.doe@example.com",
      "message": "Merge pull request #233 from deque/221-add-examples-for-using-global-config-fields-2",
      "branch_name": "main",
      "repository_url": "https://github.com/dequelabs/watcher-examples.git",
      "tag": null
    },
    "devhub_summary": {
      "issue_count_total": 17,
      "issue_count_by_impact": {
        "critical": 0,
        "serious": 2,
        "moderate": 15,
        "minor": 0
      },
      "issue_count_by_rule": [
        {
          "severity": "serious",
          "rule_id": "color-contrast",
          "rule_help": "Elements must meet minimum color contrast ratio thresholds",
          "rule_help_url": "https://dequeuniversity.com/rules/axe/4.10/color-contrast?application=axeAPI",
          "count": 2
        },
        {
          "severity": "moderate",
          "rule_id": "heading-order",
          "rule_help": "Heading levels should only increase by one",
          "rule_help_url": "https://dequeuniversity.com/rules/axe/4.10/heading-order?application=axeAPI",
          "count": 2
        },
        {
          "severity": "moderate",
          "rule_id": "landmark-one-main",
          "rule_help": "Document should have one main landmark",
          "rule_help_url": "https://dequeuniversity.com/rules/axe/4.10/landmark-one-main?application=axeAPI",
          "count": 2
        },
        {
          "severity": "moderate",
          "rule_id": "page-has-heading-one",
          "rule_help": "Page should contain a level-one heading",
          "rule_help_url": "https://dequeuniversity.com/rules/axe/4.10/page-has-heading-one?application=axeAPI",
          "count": 2
        },
        {
          "severity": "moderate",
          "rule_id": "region",
          "rule_help": "All page content should be contained by landmarks",
          "rule_help_url": "https://dequeuniversity.com/rules/axe/4.10/region?application=axeAPI",
          "count": 9
        }
      ]
    }
  }

Response Object

The following sections describe the JSON objects in the response object.

Top-Level Structure

source Object

Contains information about the product that generated the report:

test_details Object

Contains information about the test execution:

commit Object

Contains information about the Git commit associated with the test:

devhub_summary Object

Contains summary information about accessibility issues found:

issue_count_by_impact Object

Breaks down issues by impact level:

issue_count_by_rule Array

Each object in this array represents a rule with the following structure:

Handling a 202 Processing Response

This demonstration shell script shows how to use curl to re-request your report if you receive a 202 Processing response. It retries the request if it receives a 202 response up to 20 times with a five-second delay between attempts.

The sample requires the API_KEY environment variable to be set to your API key. Consider removing the echo statements if you want to redirect stdout to capture your downloadable report.

#!/bin/bash

URL="https://axe.deque.com/api-pub/watcher/downloadable/report"
MAX_ATTEMPTS=20
DELAY=5
TEMP_FILE=$(mktemp)

for ((i=1; i<=MAX_ATTEMPTS; i++)); do
    echo "Attempt $i..."
    
    # Get both status and response
    STATUS=$(curl -s -w '%{http_code}' -L -H "Accept: application/json" -H "X-API-Key: $API_KEY" -o "$TEMP_FILE" "$URL")
    
    case $STATUS in
        200)
            echo "Success!"
            cat "$TEMP_FILE"
            rm "$TEMP_FILE"
            exit 0
            ;;
        202)
            echo "Still processing, waiting ${DELAY}s..."
            sleep $DELAY
            ;;
        *)
            echo "Error: HTTP $STATUS"
            cat "$TEMP_FILE"
            rm "$TEMP_FILE"
            exit 1
            ;;
    esac
done

echo "Timeout after $MAX_ATTEMPTS attempts"
rm "$TEMP_FILE"
exit 1

Responses

• If the report is still being generated: This response indicates that the report is still being generated, and you need to retry your request after waiting. See Handling a 202 Processing Response for an example shell script.

  • Response code: 202 Processing

  • Response body:

    {
      "message": "Report is still processing",
      "state": "PROCESSING"
    }

• If the API key specified isn't valid:

  • Response error code: 401 Unauthorized

  • Response body:

    {
      "error": "Invalid API key"
    }

• If there is no required header with an API key:

  • Response error code: 401 Unauthorized

  • Response body:

    {
      "error": "X-API-Key or Authorization header required"
    }

• If the value supplied for commit_sha isn't a SHA-1 value:

  • Response error code: 400 Bad Request

  • Response body:

    {
      "error": "commit_sha must be a valid SHA-1 hash"
    }

• If the SHA value used with commit_sha could not be located: This error indicates that there is no data for this SHA in the axe Developer Hub data, which usually means that the test suite was not run against this Git commit. Note that this is the same error as returned with a branch name that doesn't exist. (See the next error.)

  • Response error code: 404 Not Found

  • Response body:

    {
      "error": "Session not found"
    }

• If the branch name supplied with branch_name doesn't exist: This error response is the same as the previous error (if the SHA supplied with the commit_sha query parameter doesn't exist in the axe Developer Hub data).

  • Response error code: 404 Not Found

  • Response body:

    {
      "error": "Session not found"
    }