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.

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_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.

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

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

Parâmetros de Consulta

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.

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)
    STATUS=$(curl -s -w '%{http_code}' -L \
      -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.

A resposta é entregue com Content-Encoding negociado a partir do cabeçalho Accept-Encoding do cliente.

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 utiliza curl e jq para percorrer todas as sessões de um projeto e baixar os resultados completos em JSON Universal para cada uma.

#!/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
            STATUS=$(curl -s -w '%{http_code}' -L \
              -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