Referencia de la API de Sesiones y Resultados

La API de Sesiones y Resultados le brinda acceso programático a sus sesiones del Axe Developer Hub y sus resultados de accesibilidad. Use el endpoint de Sesiones para descubrir sesiones de un proyecto, luego use el endpoint de Resultados para recuperar los resultados detallados de cualquier sesión específica.

Ambos endpoints requieren un ID de proyecto. Encuéntrelo en Axe Developer Hub, o búsquelo por nombre de proyecto con la API de Proyectos.

Autenticación

Todas las solicitudes requieren una clave API. Proporciónela usando el encabezado X-API-Key:

X-API-Key: <DEQUE_API_KEY>

Encuentre su clave API en el Portal de Cuentas Axe. Elija una clave API del Axe Developer Hub para proyectos web o CI/CD, o una clave API de Axe DevTools Mobile para proyectos móviles.

Control de Acceso

Las siguientes reglas de acceso se aplican a ambos endpoints:

• Miembros del proyecto pueden acceder a sesiones y resultados de cualquier proyecto al que pertenezcan.
• Administradores de la organización con una suscripción activa al Axe Developer Hub o Axe DevTools Mobile pueden acceder a sesiones y resultados de cualquier proyecto en su organización, independientemente de la pertenencia al proyecto. El acceso está limitado al producto de la clave API: una clave API del Axe Developer Hub devuelve solo datos del Axe Developer Hub, y una clave API de Axe DevTools Mobile devuelve solo datos de Axe DevTools Mobile. Un administrador de la organización no puede usar una clave API de Axe DevTools Mobile para recuperar datos del Axe Developer Hub, ni una clave API del Axe Developer Hub para recuperar datos de Axe DevTools Mobile.
• Usuarios no miembros, no administradores reciben una respuesta de acceso denegado.
• Una suscripción inactiva devuelve 401 Unauthorized.

Endpoint de Sesiones

Devuelve una lista paginada y filtrable de sesiones para un proyecto dado.

Solicitud

• Endpoint: GET https://axe.deque.com/api-pub/v1/results/projects/{project_id}/sessions
• Encabezados (requeridos):
  • X-API-Key: <DEQUE_API_KEY>
  • Accept: application/json

Reemplace {project_id} con el ID del proyecto cuyas sesiones desea recuperar. Encuentre su ID de proyecto en Axe Developer Hub.

Parámetros de Consulta

Todos los parámetros de consulta son opcionales.

Cuerpo de la Respuesta

Una respuesta exitosa devuelve un objeto JSON con un arreglo sessions. Cada objeto de sesión contiene los siguientes campos:

Cuerpo de respuesta de ejemplo

{
  "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"
    }
  ]
}

Paginación con Cursor

El punto final de Sesiones utiliza paginación basada en cursores. Cuando hay más resultados más allá de la página actual, se devuelve un valor de cursor opaco en el encabezado de respuesta x-pagination-cursor. Pase este valor como el parámetro de consulta after en su próxima solicitud para recuperar la siguiente página.

Cuando el encabezado x-pagination-cursor está ausente de la respuesta, ha llegado a la última página.

Limitación del Filtro de Correo Electrónico

Respuestas de Error del Punto Final de Sesiones

Punto Final de Resultados

Devuelve los resultados de accesibilidad para una sesión específica. Los resultados se devuelven de manera asíncrona: si los resultados aún no están listos, el punto final devuelve 204 No Content y usted vuelve a consultar hasta que lo estén.

Solicitud

• Endpoint: GET https://axe.deque.com/api-pub/v1/results/sessions/{session_id}/results
• Encabezados (requeridos):
  • X-API-Key: <DEQUE_API_KEY>
  • Accept: application/json

Reemplace {session_id} con el valor session_id devuelto por el punto final de Sesiones. Debe ser un UUID válido.

Parámetros de Consulta

Estado de la Sesión y el Patrón de Consulta Recurrente

Cuando los resultados de una sesión aún no han sido procesados, el punto final de Resultados inicia el procesamiento automáticamente y responde con 204 No Content (sin cuerpo de respuesta). Su cliente debe consultar el mismo punto final hasta que reciba una respuesta 200 OK.

Manejo de 429 Too Many Requests

Durante períodos de alta carga, el punto final de Resultados puede responder con 429 Too Many Requests en lugar de iniciar el procesamiento de inmediato. Esto no significa que su solicitud se haya perdido: el trabajo subyacente permanece en cola y volver a intentar no crea procesamiento duplicado para la misma sesión.

Una respuesta 429 incluye un encabezado Retry-After, en segundos. Espere al menos tanto tiempo antes de volver a intentar: el ejemplo a continuación maneja esto junto con el caso normal de encuesta 204.

Cuerpo de respuesta

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

Ejemplo: Consulta Recurrente 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 Respuesta

format=summary (predeterminado)

Devuelve la misma estructura JSON que punto final de legacy downloadable-report. Use este formato si tiene herramientas existentes construidas contra el punto final de downloadable-report y desea un reemplazo directo.

format=full

Devuelve los resultados completos a nivel de problema en JSON Universal (Formato de Exportación Común). Este formato incluye todos los problemas de accesibilidad encontrados durante la sesión, incluyendo detalles a nivel de página y de regla.

La respuesta se entrega con Content-Encoding negociado desde el encabezado Accept-Encoding del cliente.

Respuestas de Error del Punto Final de Resultados

Flujos de Trabajo Comunes

Recuperar Todas las Sesiones para un Proyecto y Descargar Resultados Completos

Este ejemplo utiliza curl y jq para recorrer todas las sesiones de un proyecto y descargar los resultados completos en Universal JSON para cada una.

#!/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