Referência da API de Sessões e Resultados

A API de Sessões e Resultados oferece acesso programático às suas sessões do Axe Developer Hub e seus resultados de acessibilidade. Utilize o endpoint Sessões para descobrir sessões de um projeto e, em seguida, use o endpoint Resultados para obter os resultados detalhados de qualquer sessão específica.

Ambos os endpoints requerem um ID de projeto. Encontre-o em Axe Developer Hub ou procure pelo nome do projeto com a API de Projetos.

Autenticação

Todas as solicitações requerem uma chave de API. Forneça-a usando o cabeçalho X-API-Key:

X-API-Key: <DEQUE_API_KEY>

Encontre sua chave de API no Portal de Contas Axe. Escolha uma chave de API do Axe Developer Hub para projetos web ou CI/CD, ou uma chave de API do Axe DevTools Mobile para projetos móveis.

Trate sua chave de API como um segredo: armazene-a em uma variável de ambiente ou no armazenamento secreto da sua plataforma CI/CD em vez de codificá-la diretamente em suas solicitações.

Controle de Acesso

As seguintes regras de acesso se aplicam a ambos os endpoints:

• Membros do projeto pode acessar sessões e resultados de qualquer projeto ao qual pertençam.
• Admins da Organização com uma assinatura ativa do Axe Developer Hub ou do Axe DevTools Mobile pode acessar sessões e resultados de qualquer projeto em sua organização, independentemente da associação ao projeto. O acesso está limitado ao produto da chave de API: uma chave de API do Axe Developer Hub retorna apenas dados do Axe Developer Hub, e uma chave de API do Axe DevTools Mobile retorna apenas dados do Axe DevTools Mobile. Um Admin da Organização não pode usar uma chave de API do Axe DevTools Mobile para recuperar dados do Axe Developer Hub, nem uma chave de API do Axe Developer Hub para recuperar dados do Axe DevTools Mobile.
• Usuários não membros, nem administradores recebem uma resposta de acesso negado.
• Uma assinatura inativa retorna 401 Unauthorized.

Endpoint de Sessões

Retorna uma lista paginada e filtrável de sessões para um projeto dado.

Solicitação

• Endpoint: GET https://axe.deque.com/api-pub/v1/results/projects/{project_id}/sessions
• Cabeçalhos (obrigatórios):
  • X-API-Key: <DEQUE_API_KEY>
  • Accept: application/json

Substitua {project_id} pelo ID do projeto cujas sessões você deseja recuperar. Encontre seu ID de projeto em Axe Developer Hub.

Parâmetros de Consulta

Todos os parâmetros de consulta são opcionais.

Corpo da Resposta

Uma resposta bem-sucedida retorna um objeto JSON com um array sessions. Cada objeto de sessão contém os seguintes campos:

Exemplo de Corpo de Resposta

{
  "sessions": [
    {
      "session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Main CI run for PR 451",
      "created_at": "2026-06-01T14:23:00.000Z",
      "is_canonical_source": true,
      "git_branch": "feature/new-nav",
      "git_url": "https://github.com/example/webapp",
      "commit_sha": "9eabf5b536662000f79978c4d1b6e4eff5c8d785",
      "created_by_user_name": "Jane Smith",
      "created_by_user_email": "jane.smith@example.com",
      "created_by_user_api_key_name": "CI Pipeline Key"
    },
    {
      "session_id": "f0e1d2c3-b4a5-6789-0123-456789abcdef",
      "created_at": "2026-05-30T09:00:00.000Z",
      "is_canonical_source": false,
      "git_branch": null,
      "git_url": null,
      "commit_sha": null,
      "created_by_user_email": null,
      "created_by_user_api_key_name": "Unknown Member"
    }
  ]
}

Paginação por Cursor

O endpoint de Sessões usa paginação baseada em cursor. Quando há mais resultados além da página atual, um valor de cursor opaco é retornado no cabeçalho de resposta x-pagination-cursor. Passe este valor como o parâmetro de consulta after em sua próxima solicitação para recuperar a próxima página.

Quando o cabeçalho x-pagination-cursor está ausente da resposta, você atingiu a última página.

Limitação de Filtro de Email

Respostas de Erro do Endpoint de Sessões

Endpoint de Resultados

Retorna os resultados de acessibilidade para uma sessão específica. Os resultados são retornados assincronamente: se os resultados ainda não estiverem prontos, o endpoint retorna 204 No Content e você faz polling até que estejam.

Desduplicação

Para projetos web, ambos os formatos de resposta retornam resultados desduplicados. Quando o mesmo problema é encontrado em mais de um estado de página na sessão, ele é relatado uma vez, no primeiro estado de página onde foi encontrado. Dois resultados contam como o mesmo problema quando têm a mesma regra e URL de página e o mesmo elemento, correspondendo por seletor CSS, XPath ou ancestralidade. Veja Duplicado para as regras completas de correspondência.

• format=summary: a contagem das questões por impacto e por regra considera cada problema único uma vez.
• format=full: cada problema único aparece uma vez na lista de problemas, e as contagens resumidas do cabeçalho são contagens únicas.

A desduplicação ocorre apenas dentro de uma única sessão: os resultados não são comparados com outras sessões, e a resposta não indica quantos duplicados foram removidos ou se um problema é novo. Resultados móveis não são desduplicados.

Solicitação

• Endpoint: GET https://axe.deque.com/api-pub/v1/results/sessions/{session_id}/results
• Cabeçalhos (obrigatórios):
  • X-API-Key: <DEQUE_API_KEY>
  • Accept: application/json
• Cabeçalhos (recomendado):
  • Accept-Encoding: br: solicita a resposta comprimida com Brotli, que é baixada mais rapidamente. Veja Compressão de Resposta.

Substitua {session_id} com o valor session_id retornado pelo endpoint de Sessões. Deve ser um UUID válido.

Parâmetros de Consulta

Compressão de Resposta

O endpoint de Resultados comprime sua resposta com base no cabeçalho Accept-Encoding do seu pedido. Ele usa Brotli (br) se você aceitar, caso contrário, gzip, ou então sem compressão. O cabeçalho Content-Encoding da resposta informa qual codificação foi utilizada.

Use Brotli sempre que possível. Os resultados são armazenados comprimidos com Brotli, então uma resposta Brotli é enviada como está. Uma resposta gzip ou não comprimida precisa ser descomprimida e re-codificada no servidor primeiro, o que é muito mais lento: grandes downloads de format=full, ou vários downloads ao mesmo tempo, podem falhar antes de serem concluídos.

Se não puder usar Brotli (por exemplo, se um proxy ou VPN na rede remove br de Accept-Encoding), respostas gzip e não comprimidas ainda funcionam. Espere downloads mais lentos e faça downloads de grandes resultados uma sessão de cada vez.

A maioria dos clientes HTTP não solicita Brotli por padrão:

• curl: Add --compressed. curl then requests every encoding it supports and decompresses the response for you. It only requests Brotli if your curl build supports it: run curl -V and check for brotli in the Features line. Some builds, including the curl that ships with macOS, don't include Brotli and fall back to gzip. A curl installed from a package manager such as Homebrew typically includes it. If your curl doesn't support Brotli, request it with -H "Accept-Encoding: br" (without --compressed) and decompress the saved file with brotli -d.
• Python requests: Instale o pacote brotli (pip install brotli). Com ele instalado, requests solicita Brotli e descomprime a resposta automaticamente.
• Outros clientes: Configure Accept-Encoding: br e certifique-se de que seu cliente descomprime respostas Brotli. Se não, salve a resposta e descomprime você mesmo, por exemplo, com brotli -d.

Estado da Sessão e o Padrão de Polling

Quando os resultados de uma sessão ainda não foram processados, o endpoint de Resultados aciona o processamento automaticamente e responde com 204 No Content (sem corpo de resposta). Seu cliente deve fazer polling no mesmo endpoint até receber uma resposta 200 OK.

Corpo de resposta para error

{
  "state": "ERROR",
  "message": "We were unable to process your session. Please try again, if the issue persists contact helpdesk."
}

Lidando com 429 Too Many Requests

Durante períodos de alta carga, o endpoint de Resultados pode responder com 429 Too Many Requests em vez de acionar o processamento imediatamente. Isso não significa que sua solicitação foi perdida: o trabalho subjacente permanece na fila, e tentar novamente não cria processamento duplicado para a mesma sessão.

Uma resposta 429 inclui um cabeçalho Retry-After, em segundos. Espere pelo menos esse tempo antes de tentar novamente — o exemplo abaixo lida com isso junto ao caso normal de polling 204.

Corpo da resposta

{
  "error": "Too many requests. Retry after the Retry-After interval."
}

Exemplo: Polling para Resultados

#!/bin/bash

SESSION_ID="a1b2c3d4-e5f6-7890-abcd-ef1234567890"
URL="https://axe.deque.com/api-pub/v1/results/sessions/$SESSION_ID/results"
MAX_ATTEMPTS=20
DELAY=5
TEMP_FILE=$(mktemp)

for ((i=1; i<=MAX_ATTEMPTS; i++)); do
    echo "Attempt $i..."

    HEADERS_FILE=$(mktemp)
    # --compressed requests Brotli (if your curl supports it) and decompresses the response
    STATUS=$(curl -s -w '%{http_code}' -L --compressed \
      -H "Accept: application/json" \
      -H "X-API-Key: $API_KEY" \
      -D "$HEADERS_FILE" \
      -o "$TEMP_FILE" \
      "$URL?format=full")

    case $STATUS in
        200)
            echo "Results ready!"
            cat "$TEMP_FILE"
            rm "$TEMP_FILE" "$HEADERS_FILE"
            exit 0
            ;;
        204)
            echo "Still processing, waiting ${DELAY}s..."
            sleep $DELAY
            ;;
        429)
            RETRY_AFTER=$(grep -i '^retry-after:' "$HEADERS_FILE" | tr -d '\r' | awk '{print $2}')
            RETRY_AFTER=${RETRY_AFTER:-$DELAY}
            echo "Too many requests, waiting ${RETRY_AFTER}s per Retry-After..."
            sleep "$RETRY_AFTER"
            ;;
        *)
            echo "Error: HTTP $STATUS"
            cat "$TEMP_FILE"
            rm "$TEMP_FILE" "$HEADERS_FILE"
            exit 1
            ;;
    esac
    rm -f "$HEADERS_FILE"
done

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

Formatos de Resposta

format=summary(padrão)

Retorna o mesmo formato JSON que o endpoint de relatório para download legado. Use este formato se você tiver ferramentas existentes construídas contra o endpoint de relatório para download e quiser uma substituição direta.

format=full

Retorna os resultados completos a nível de problema em JSON Universal (Formato Comum de Exportação). Este formato inclui todos os problemas de acessibilidade encontrados durante a sessão, incluindo detalhes a nível de página e regra.

Os resultados completos podem ser muito grandes, então solicite-os comprimidos com Brotli (Accept-Encoding: br, ou --compressed com um curl habilitado para Brotli). A Content-Encoding da resposta é negociada a partir do seu cabeçalho Accept-Encoding; veja Compressão de Resposta.

Respostas de Erro do Endpoint de Resultados

Fluxos de Trabalho Comuns

Recuperar Todas as Sessões de um Projeto e Baixar Resultados Completos

Este exemplo usa curl e jq para percorrer todas as sessões de um projeto e baixar os resultados JSON Universais completos para cada uma. Para projetos web, cada arquivo contém os problemas desduplicados da sessão; veja Desduplicação.

#!/bin/bash

# Set these environment variables before running:
# API_KEY: your Axe Developer Hub API key
# PROJECT_ID: your project ID

BASE_URL="https://axe.deque.com/api-pub/v1/results"
CURSOR=""

while true; do
    QUERY="page_size=100"
    if [ -n "$CURSOR" ]; then
        QUERY="$QUERY&after=$CURSOR"
    fi

    RESPONSE=$(curl -s -D - -H "Accept: application/json" -H "X-API-Key: $API_KEY" \
      "$BASE_URL/projects/$PROJECT_ID/sessions?$QUERY")

    NEXT_CURSOR=$(echo "$RESPONSE" | grep -i "x-pagination-cursor:" | tr -d '\r' | awk '{print $2}')
    BODY=$(echo "$RESPONSE" | sed -n '/^\r\{0,1\}$/,$p' | tail -n +2)

    SESSION_IDS=$(echo "$BODY" | jq -r '.sessions[].session_id')

    for SESSION_ID in $SESSION_IDS; do
        echo "Fetching results for session $SESSION_ID..."

        while true; do
            # --compressed requests Brotli (if your curl supports it) and decompresses the response
            STATUS=$(curl -s -w '%{http_code}' -L --compressed \
              -H "Accept: application/json" \
              -H "X-API-Key: $API_KEY" \
              -o "${SESSION_ID}.json" \
              "$BASE_URL/sessions/$SESSION_ID/results?format=full")

            if [ "$STATUS" = "200" ]; then
                echo "Saved ${SESSION_ID}.json"
                break
            elif [ "$STATUS" = "204" ]; then
                echo "  Still processing, waiting..."
                sleep 5
            else
                echo "  Error: HTTP $STATUS"
                break
            fi
        done
    done

    if [ -z "$NEXT_CURSOR" ]; then
        break
    fi
    CURSOR="$NEXT_CURSOR"
done