Referencia de API de Proyectos

La API de Proyectos le permite gestionar proyectos y la membresía de Axe Developer Hub programáticamente, utilizando la misma clave API de Axe Account que ya usa para el resto de las API REST de Axe Developer Hub. No hay credenciales separadas para la gestión de proyectos. Para una introducción paso a paso, consulte Comience con la Automatización de Gestión de Proyectos.

Si solo necesita descubrir el ID de un proyecto a partir de su nombre para poder llamar a la API de Sesiones y Resultados, consulte Listar Proyectos a continuación. Si ya conoce su ID de proyecto, puede encontrarlo en Axe Developer Hub y llamar directamente a la API de Sesiones y Resultados.

Autenticación

Todas las solicitudes requieren una clave API. Proporciónela utilizando 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 de Axe Developer Hub para proyectos web o CI/CD. Elija una clave API de Axe DevTools Mobile para proyectos móviles.

Trate su clave API como un secreto: almacénela en una variable de entorno o en el almacén de secretos de su plataforma CI/CD en lugar de codificarla en sus solicitudes.

Control de Acceso y Permisos

• Crear un proyecto requiere una suscripción activa (licencia) para el tipo de ese proyecto. Quien crea un proyecto se convierte automáticamente en su administrador de proyecto.
• Roles de proyecto son administrador y miembro. Un administrador de proyectos puede actualizar o eliminar el proyecto y gestionar su membresía. Un miembro del proyecto puede acceder al proyecto pero no gestionarlo ni a su membresía.
• Admins de Organización pueden ver y gestionar cada proyecto de los tipos con licencia de su organización, independientemente de su propia membresía de proyecto. No necesitan una licencia personal para ver, actualizar, eliminar o gestionar los miembros de un proyecto existente. Crear un proyecto es la única excepción: siempre requiere una licencia activa, ya sea que el solicitante sea un administrador de organización o no.
• Agregar un miembro a un proyecto no requiere que ese miembro tenga una licencia. La API los registra como miembros del proyecto de inmediato, pero no pueden acceder al proyecto hasta que tengan una licencia. El usuario objetivo ya debe pertenecer a la organización. No puede agregar a alguien que no sea ya miembro de la organización.
• Eliminar un proyecto es definitivo. No hay una opción de restauración automática para un proyecto eliminado.
• En todos los casos, la respuesta está limitada al producto de la clave API. Una clave API de Axe Developer Hub devuelve y gestiona solo proyectos de Axe Developer Hub (web). Una clave API de Axe DevTools Mobile devuelve y gestiona solo proyectos de Axe DevTools Mobile.

Una suscripción inactiva devuelve 401 Unauthorized.

Valores de Configuración del Tipo de Proyecto

Cada proyecto tiene un selected_project_type, y cada tipo acepta solo un conjunto específico y fijo de valores test_language / test_platform:

El selected_project_type de un proyecto se fija cuando se crea el proyecto. Para utilizar un tipo diferente, cree un nuevo proyecto.

Listar Proyectos

Devuelve la lista de proyectos a los que la clave API autenticada puede acceder.

Solicitud

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

Parámetros de consulta

Todos los parámetros de consulta son opcionales.

Cuerpo de la respuesta

Una respuesta exitosa devuelve un array JSON de objetos de proyecto. Cada objeto de proyecto incluye los siguientes campos:

Las respuestas pueden incluir campos adicionales que no están listados aquí, y se pueden agregar nuevos campos con el tiempo. Ignore cualquier campo que no reconozca, y no dependa de campos no documentados.

Cuerpo de respuesta de ejemplo

[
  {
    "project_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "webapp-ci",
    "selected_project_type": "axe-devtools-watcher",
    "test_language": "typescript",
    "test_platform": "Playwright",
    "role": "admin",
    "user_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "enterprise_id": "3f2b8e1a-6c4d-4f7e-9a0b-1d2c3e4f5a6b",
    "is_enterprise_project": true,
    "created_at": "2026-06-01T14:23:00.000Z",
    "updated_at": "2026-06-10T16:45:00.000Z",
    "run_by": "Jane Developer",
    "last_session_created_at": "2026-06-14T09:12:00.000Z",
    "has_git_information": true,
    "git_url": "https://github.com/example/webapp",
    "latest_session": {
      "id": "0d4a85a2-9e6f-44ef-b814-fee8412abeb0",
      "created_at": "2026-06-14T09:12:00.000Z",
      "git_branch": "main"
    }
  },
  {
    "project_id": "f0e1d2c3-b4a5-6789-0123-456789abcdef",
    "name": "design-system",
    "selected_project_type": "axe-devtools-html",
    "test_language": null,
    "test_platform": null,
    "role": "admin",
    "user_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "enterprise_id": "3f2b8e1a-6c4d-4f7e-9a0b-1d2c3e4f5a6b",
    "is_enterprise_project": true,
    "created_at": "2026-05-20T08:00:00.000Z",
    "updated_at": null,
    "run_by": null,
    "last_session_created_at": null,
    "has_git_information": false,
    "git_url": null,
    "latest_session": null
  },
  {
    "project_id": "c4d5e6f7-a8b9-4c0d-9e1f-2a3b4c5d6e7f",
    "name": "ios-app-ci",
    "selected_project_type": "axe-devtools-mobile",
    "test_language": null,
    "test_platform": "XCUITest",
    "role": "admin",
    "user_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "enterprise_id": "3f2b8e1a-6c4d-4f7e-9a0b-1d2c3e4f5a6b",
    "is_enterprise_project": true,
    "created_at": "2026-06-03T10:15:00.000Z",
    "updated_at": null,
    "run_by": "Jane Developer",
    "last_session_created_at": "2026-06-15T11:05:00.000Z",
    "has_git_information": false,
    "git_url": null,
    "latest_session": {
      "id": "5b6c7d8e-9f0a-4b1c-8d2e-3f4a5b6c7d8e",
      "created_at": "2026-06-15T11:05:00.000Z",
      "git_branch": null
    }
  }
]

Para mantener el ejemplo corto, cada objeto de latest_session muestra solo tres de sus campos. La API devuelve más.

Paginación por cursor

La paginación es opcional. No envíe page_size ni after, y la respuesta devolverá su lista completa de proyectos en una sola respuesta, sin un encabezado de cursor.

Para paginar a través de los resultados, la API de Proyectos usa la misma paginación basada en cursores que la Punto final de sesiones. Cuando hay más resultados más allá de la página actual, la respuesta devuelve un valor de cursor opaco en el encabezado 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 la respuesta no tiene el encabezado x-pagination-cursor, está en la última página.

Buscar un ID de proyecto por nombre

Este ejemplo utiliza curl y jq para encontrar el ID de un proyecto a partir de su nombre:

curl -s \
  -H "Accept: application/json" \
  -H "X-API-Key: $API_KEY" \
  "https://axe.deque.com/api-pub/v1/results/projects" \
  | jq -r '.[] | select(.name == "webapp-ci") | .project_id'

Pase el ID devuelto al Punto final de sesiones para listar las sesiones de ese proyecto.

Listar respuestas de error de proyectos

Recuperar un proyecto

Devuelve un solo proyecto por su ID, con el mismo formato que Listar Proyectos.

Solicitud

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

Recuperar respuestas de error de proyecto

Crear un proyecto

Solicitud

• Punto final: POST https://axe.deque.com/api-pub/v1/results/projects
• Encabezados (requeridos):
  • X-API-Key: <DEQUE_API_KEY>
  • Content-Type: application/json
  • Accept: application/json

Cuerpo de la Solicitud

Ejemplo de Cuerpo de Solicitud

{
  "name": "webapp-ci",
  "selected_project_type": "axe-devtools-watcher",
  "test_language": "typescript",
  "test_platform": "Playwright"
}

Cuerpo de la respuesta

Devuelve el proyecto creado, con la misma estructura que Listar Proyectos. Quien crea un proyecto se convierte automáticamente en su administrador de proyecto, por lo que no se necesita una llamada de membresía por separado. Una creación exitosa devuelve 201 Created.

Crear un Proyecto Respuestas de Error

Actualizar un Proyecto

Solicitud

• Punto final: PATCH https://axe.deque.com/api-pub/v1/results/projects/{project_id}
• Encabezados (requeridos):
  • X-API-Key: <DEQUE_API_KEY>
  • Content-Type: application/json
  • Accept: application/json

Cuerpo de la Solicitud

Ejemplo de Cuerpo de Solicitud

{
  "name": "webapp-ci-renamed"
}

Cuerpo de la respuesta

Devuelve el proyecto actualizado, con la misma estructura que Listar Proyectos. Una actualización exitosa devuelve 200 OK.

Actualizar un Proyecto Respuestas de Error

Eliminar un Proyecto

Solicitud

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

Cuerpo de la respuesta

{ "deleted": true }

Eliminar un Proyecto Respuestas de Error

Membresía del Proyecto

La membresía de un proyecto es un sub-recurso del proyecto. Un administrador de proyecto puede gestionar el proyecto y su membresía. Un miembro del proyecto (el rol de member en las operaciones de membresía a continuación) puede acceder al proyecto pero no gestionarlo. Las operaciones de membresía identifican a los usuarios por su dirección de correo electrónico. Agregar un miembro no requiere que posea una licencia. La API los registra inmediatamente, pero no pueden acceder al proyecto hasta que posean una licencia. El usuario objetivo debe pertenecer ya a su organización. No puedes agregar a alguien que no sea ya miembro de la organización.

Use las operaciones en lote a continuación siempre que sea posible. Las tres operaciones de escritura aceptan múltiples usuarios en una sola llamada. Esto reduce el número de solicitudes que necesita realizar. Si gestiona la membresía para una organización grande, aplique backoff y reintento cuando reciba una respuesta de 429. Consulte 429 Too Many Requests para el patrón general.

Listado de Miembros del Proyecto

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

Cuerpo de la respuesta

{
  "members": [
    {
      "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "role": "admin",
      "email": "jane@example.com",
      "first_name": "Jane",
      "last_name": "Doe",
      "active_license": true,
      "created_at": "2026-06-01T14:23:00.000Z"
    }
  ]
}

Agregar Miembros al Proyecto

• Punto final: POST https://axe.deque.com/api-pub/v1/results/projects/{project_id}/memberships
• Encabezados (requeridos): X-API-Key: <DEQUE_API_KEY>, Content-Type: application/json, Accept: application/json

Cuerpo de la Solicitud

{
  "user_email_role_pairs": [
    { "user_email": "sam@example.com", "role": "member" },
    { "user_email": "alex@example.com", "role": "admin" }
  ]
}

user_email es la dirección de correo electrónico de la cuenta de Axe del usuario. La coincidencia ignora mayúsculas y minúsculas y espacios circundantes. role acepta admin o member (contributor también se acepta como sinónimo de member). Cada usuario puede aparecer solo una vez en una solicitud. Agregar un usuario que ya pertenece al proyecto no tiene efecto en esa entrada: no cambia su rol existente. Esta es una operación por lotes. Una entrada no válida rechaza toda la solicitud, y la API no escribe nada. El mensaje de error lista cada entrada que falló, para que pueda corregir un lote en un solo intento.

Una solicitud exitosa devuelve 201 Created con { "created": true }, haya o no agregado la solicitud nuevas membresías.

Cambiar Roles de Miembros

• Punto final: PATCH https://axe.deque.com/api-pub/v1/results/projects/{project_id}/memberships
• Encabezados (requeridos): X-API-Key: <DEQUE_API_KEY>, Content-Type: application/json, Accept: application/json
• Cuerpo de la solicitud: misma forma de user_email_role_pairs que Agregar Miembros al Proyecto

Cada user_email debe pertenecer a un miembro actual del proyecto. Un proyecto siempre debe conservar al menos un admin. La API rechaza una solicitud que deja al proyecto sin administrador. Un único miembro restante que sea el único administrador no puede cambiar su propio rol. Esto es una operación por lotes. Una entrada inválida rechaza toda la solicitud y la API no escribe nada.

Una solicitud exitosa devuelve 200 OK con { "ok": true }.

Eliminar Miembros del Proyecto

• Punto final: DELETE https://axe.deque.com/api-pub/v1/results/projects/{project_id}/memberships?user_emails={comma-separated,url-encoded,emails}
• Encabezados (requeridos): X-API-Key: <DEQUE_API_KEY>, Accept: application/json

Pase las direcciones de correo electrónico de los usuarios a eliminar como una lista separada por comas en un único parámetro de consulta user_emails, y codifique el valor en URL. Por ejemplo, un literal + en una dirección que no está codificada llega como un espacio y se rechaza por estar malformada. No hay cuerpo de solicitud. Eliminar a un usuario que no es miembro tiene éxito y no elimina nada, por lo que una solicitud repetida no es un error. Un proyecto siempre debe conservar al menos un admin. La API rechaza una solicitud que elimina al último administrador del proyecto. Un único miembro restante que sea el único administrador no puede eliminarse a sí mismo.

Una solicitud exitosa devuelve 200 OK con las direcciones que eliminó y las que no coincidieron con ningún miembro, para que pueda distinguir un error tipográfico de una eliminación completada:

{
  "deleted": true,
  "removed": ["sam@example.com"],
  "unmatched": ["alx@example.com"]
}

Respuestas de Error de Membresía del Proyecto