Referência da API de Projetos

A API de Projetos permite que você gerencie projetos do Axe Developer Hub e sua associação programaticamente, usando a mesma chave de API da conta Axe que você já utiliza para as outras APIs REST do Axe Developer Hub. Não há credenciais separadas para gerenciamento de projetos. Para uma introdução passo a passo, veja Começar com a Automação de Gerenciamento de Projetos.

Se você só precisa descobrir o ID de um projeto a partir de seu nome para poder chamar a API de Sessões e Resultados, veja Listar Projetos abaixo. Se você já conhece o ID do seu projeto, você pode encontrá-lo em Axe Developer Hub e chamar diretamente a API de Sessões e Resultados.

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. Escolha 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 repositório de segredos da sua plataforma de CI/CD, em vez de codificá-la diretamente em suas requisições.

Controle de Acesso e Permissões

• Criando um projeto requer uma assinatura ativa (licença) para o tipo desse projeto. Quem criar um projeto torna-se automaticamente seu administrador.
• Funções do projeto são administrador e membro. Um administrador do projeto pode atualizar ou excluir o projeto e gerenciar sua associação. Um membro do projeto pode acessar o projeto, mas não gerenciá-lo ou sua associação.
• Admins da organização pode ver e gerenciar todos os projetos dos tipos licenciados de sua organização, independentemente de sua própria associação ao projeto. Eles não precisam de uma licença pessoal para visualizar, atualizar, excluir ou gerenciar os membros de um projeto existente. Criar um projeto é a única exceção: sempre exige uma licença ativa, seja o chamador um administrador da organização ou não.
• Adicionar um membro a um projeto não requer que o membro possua uma licença. A API os registra como membro do projeto imediatamente, mas eles não podem acessar o projeto até possuírem uma licença. O usuário alvo deve já pertencer à organização. Você não pode adicionar alguém que ainda não seja membro da organização.
• Excluir um projeto é definitivo. Não há recuperação automática para um projeto excluído.
• Em todos os casos, a resposta está limitada ao produto da chave de API. Uma chave de API do Axe Developer Hub retorna e gerencia apenas projetos do Axe Developer Hub (web). Uma chave de API do Axe DevTools Mobile retorna e gerencia apenas projetos do Axe DevTools Mobile.

Uma assinatura inativa retorna 401 Unauthorized.

Valores de Configuração do Tipo de Projeto

Cada projeto tem um selected_project_type, e cada tipo aceita apenas um conjunto específico e fixo de valores test_language / test_platform:

O selected_project_type de um projeto é fixado quando o projeto é criado. Para usar um tipo diferente, crie um novo projeto.

Listar Projetos

Retorna a lista de projetos que a chave de API autenticada pode acessar.

Solicitação

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

Parâmetros de Consulta

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

Corpo da Resposta

Uma resposta bem-sucedida retorna um array JSON de objetos de projeto. Cada objeto de projeto inclui os seguintes campos:

As respostas podem incluir campos adicionais que não estão listados aqui, e novos campos podem ser adicionados ao longo do tempo. Ignore qualquer campo que você não reconheça e não dependa de campos não documentados.

Exemplo de Corpo de Resposta

[
  {
    "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 manter o exemplo curto, cada objeto latest_session mostra apenas três de seus campos. A API retorna mais.

Paginação por Cursor

A paginação é opcional. Não envie nem page_size nem after, e a resposta retornará sua lista completa de projetos em uma única resposta, sem cabeçalho de cursor.

Para paginar os resultados, a API de Projetos usa a mesma paginação baseada em cursor que a Endpoint de Sessões. Quando houver mais resultados além da página atual, a resposta retorna um valor de cursor opaco no cabeçalho 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 a resposta não tem cabeçalho x-pagination-cursor, você está na última página.

Buscar um ID de Projeto pelo Nome

Este exemplo usa curl e jq para encontrar o ID de um projeto a partir do seu nome:

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'

Passe o ID retornado para o Endpoint de Sessões para listar as sessões desse projeto.

Listar Respostas de Erros dos Projetos

Recuperar um Projeto

Retorna um único projeto pelo seu ID, no mesmo formato que Listar Projetos.

Solicitação

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

Recuperar Respostas de Erros de um Projeto

Criar um Projeto

Solicitação

• Endpoint: POST https://axe.deque.com/api-pub/v1/results/projects
• Cabeçalhos (obrigatório):
  • X-API-Key: <DEQUE_API_KEY>
  • Content-Type: application/json
  • Accept: application/json

Corpo da Solicitação

Exemplo de Corpo da Solicitação

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

Corpo da Resposta

Retorna o projeto criado, no mesmo formato que Listar Projetos. Quem cria um projeto torna-se automaticamente seu administrador, então não é necessário uma chamada de associação separada. Uma criação bem-sucedida retorna 201 Created.

Criar Respostas de Erros de um Projeto

Atualizar um Projeto

Solicitação

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

Corpo da Solicitação

Exemplo de Corpo da Solicitação

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

Corpo da Resposta

Retorna o projeto atualizado, no mesmo formato que Listar Projetos. Uma atualização bem-sucedida retorna 200 OK.

Atualizar Respostas de Erros de um Projeto

Deletar um Projeto

Solicitação

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

Corpo da Resposta

{ "deleted": true }

Deletar Respostas de Erros de um Projeto

Associação de Projeto

A associação de um projeto é um sub-recurso do projeto. Um administrador de projeto pode gerenciar o projeto e sua associação. Um membro do projeto (o papel member nas operações de associação abaixo) pode acessar o projeto, mas não gerenciá-lo. As operações de associação identificam usuários por seu endereço de e-mail. Adicionar um membro não exige que ele possua uma licença. A API os registra imediatamente, mas eles não podem acessar o projeto até que possuam uma licença. O usuário alvo já deve pertencer à sua organização. Você não pode adicionar alguém que ainda não seja membro da organização.

Use as operações em lote abaixo sempre que possível. Todas as três operações de gravação aceitam múltiplos usuários em uma única chamada. Isso reduz o número de solicitações que você precisa fazer. Se você gerenciar a associação para uma grande organização, aplique retardo e tente novamente quando receber uma resposta 429. Veja 429 Too Many Requests para o padrão geral.

Listar Membros do Projeto

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

Corpo da Resposta

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

Adicionar Membros ao Projeto

• Endpoint: POST https://axe.deque.com/api-pub/v1/results/projects/{project_id}/memberships
• Cabeçalhos (obrigatório): X-API-Key: <DEQUE_API_KEY>, Content-Type: application/json, Accept: application/json

Corpo da Solicitação

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

user_email é o endereço de e-mail da Conta Axe do usuário. A correspondência ignora maiúsculas e espaços ao redor. role aceita admin ou member (contributor também é aceito como sinônimo de member). Cada usuário pode aparecer apenas uma vez em uma solicitação. Adicionar um usuário que já pertence ao projeto não altera o papel existente: é uma operação sem efeito para essa entrada. Esta é uma operação em lote. Uma entrada inválida rejeita toda a solicitação e a API não grava nada. A mensagem de erro lista todas as entradas que falharam, permitindo corrigir um lote de uma só vez.

Uma solicitação bem-sucedida retorna 201 Created com { "created": true }, independentemente de a solicitação realmente ter adicionado novas associações.

Alterar Funções dos Membros

• Endpoint: PATCH https://axe.deque.com/api-pub/v1/results/projects/{project_id}/memberships
• Cabeçalhos (obrigatório): X-API-Key: <DEQUE_API_KEY>, Content-Type: application/json, Accept: application/json
• Corpo da solicitação: mesmo formato user_email_role_pairs que Adicionar Membros ao Projeto

Cada user_email deve pertencer a um membro atual do projeto. Um projeto deve sempre manter pelo menos um admin. A API rejeita uma solicitação que deixe o projeto sem administrador. Um único membro restante que é o único administrador do projeto não pode alterar sua própria função. Esta é uma operação em lote. Uma entrada inválida rejeita toda a solicitação e a API não grava nada.

Uma solicitação bem-sucedida retorna 200 OK com { "ok": true }.

Remover Membros do Projeto

• Endpoint: DELETE https://axe.deque.com/api-pub/v1/results/projects/{project_id}/memberships?user_emails={comma-separated,url-encoded,emails}
• Cabeçalhos (obrigatório): X-API-Key: <DEQUE_API_KEY>, Accept: application/json

Passe os endereços de e-mail dos usuários a serem removidos como uma lista separada por vírgulas em um único parâmetro de consulta user_emails, e codifique a URL do valor. Por exemplo, um literal + em um endereço que não está codificado chega como espaço e é rejeitado por estar malformado. Não há corpo de solicitação. Remover um usuário que não é membro tem sucesso e não remove nada, portanto, uma solicitação repetida não é um erro. Um projeto deve sempre manter pelo menos um admin. A API rejeita uma solicitação que remova o último administrador do projeto. Um único membro restante que é o único administrador do projeto não pode se remover.

Uma solicitação bem-sucedida retorna 200 OK com os endereços removidos e os que não corresponderam a nenhum membro, para que você possa distinguir um erro de digitação de uma remoção concluída:

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

Respostas de Erro de Associação de Projeto