Référence de l'API des projets

L'API Projects vous permet de gérer de manière programmatique les projets Axe Developer Hub et leur adhésion, en utilisant la même clé API Axe Account que vous utilisez déjà pour le reste des API REST de l'Axe Developer Hub. Il n'y a pas de justificatifs séparés pour la gestion de projet. Pour une introduction pas à pas, voir Commencer avec l'automatisation de la gestion de projet.

Si vous avez seulement besoin de découvrir l'ID d'un projet à partir de son nom pour pouvoir appeler le API de sessions et de résultats, voir Lister les projets ci-dessous. Si vous connaissez déjà l'ID de votre projet, vous pouvez le trouver dans Axe Developer Hub et appeler directement l'API Sessions et Résultats.

Authentification

Toutes les requêtes nécessitent une clé API. Fournissez-la en utilisant l'en-tête X-API-Key:

X-API-Key: <DEQUE_API_KEY>

Trouvez votre clé API dans le Portail de compte Axe. Choisissez une clé API Axe Developer Hub pour les projets web ou CI/CD. Choisissez une clé API Axe DevTools Mobile pour les projets mobiles.

Considérez votre clé API comme un secret : stockez-la dans une variable d'environnement ou dans le gestionnaire de secrets de votre plateforme CI/CD plutôt que de l'intégrer directement dans vos requêtes.

Contrôle d'accès et permissions

• Créer un projet nécessite un abonnement actif (licence) pour le type de projet concerné. Celui qui crée un projet devient automatiquement son administrateur.
• Rôles de projet sont administrateur et membre. Un administrateur de projet peut mettre à jour ou supprimer le projet et gérer ses membres. Un membre de projet peut accéder au projet mais ne peut pas le gérer ni ses membres.
• Administrateurs de l'organisation peuvent voir et gérer tous les projets des types licenciés de leur organisation, indépendamment de leur adhésion personnelle au projet. Ils n'ont pas besoin d'une licence personnelle pour visualiser, mettre à jour, supprimer ou gérer les membres d'un projet existant. Créer un projet est l'unique exception : une licence active est toujours requise, que l'appelant soit un administrateur de l'organisation ou non.
• Ajouter un membre à un projet ne requiert pas que ce membre détienne une licence. L'API les enregistre immédiatement comme membre du projet, mais ils ne peuvent accéder au projet qu'une fois qu'ils détiennent une licence. L'utilisateur ciblé doit déjà appartenir à l'organisation. Vous ne pouvez pas ajouter quelqu'un qui n'est pas déjà membre de l'organisation.
• La suppression d'un projet est définitive. Il n'y a pas de restauration en libre-service pour un projet supprimé.
• Dans tous les cas, la réponse est limitée au produit auquel la clé API donne accès. Une clé API Axe Developer Hub renvoie et gère uniquement les projets Axe Developer Hub (web). Une clé API Axe DevTools Mobile renvoie et gère uniquement les projets Axe DevTools Mobile.

Un abonnement inactif renvoie 401 Unauthorized.

Valeurs de configuration du type de projet

Chaque projet a une selected_project_type, et chaque type accepte uniquement un ensemble spécifique et fixe de valeurs test_language / test_platform :

Le selected_project_type d'un projet est fixé lors de sa création. Pour utiliser un type différent, créez un nouveau projet.

Lister les projets

Renvoie la liste des projets auxquels la clé API authentifiée peut accéder.

Requête

• Point de terminaison : GET https://axe.deque.com/api-pub/v1/results/projects
• En-têtes (obligatoires) :
  • X-API-Key: <DEQUE_API_KEY>
  • Accept: application/json

Paramètres de requête

Tous les paramètres de requête sont optionnels.

Corps de la réponse

Une réponse réussie renvoie un tableau JSON d'objets projet. Chaque objet projet inclut les champs suivants :

Les réponses peuvent inclure des champs supplémentaires qui ne sont pas listés ici, et de nouveaux champs peuvent être ajoutés au fil du temps. Ignorez tout champ que vous ne reconnaissez pas et ne vous fiez pas aux champs non documentés.

Exemple de Corps de Réponse

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

Pour garder l'exemple court, chaque objet latest_session montre seulement trois de ses champs. L'API en retourne plus.

Pagination par curseur

La pagination est facultative. N'envoyez ni page_size ni after, et la réponse renvoie votre liste complète de projets en une seule réponse, sans en-tête de curseur.

Pour paginer les résultats, l'API Projects utilise la même pagination par curseur que le Point de terminaison Sessions. Lorsque d'autres résultats existent au-delà de la page actuelle, la réponse renvoie une valeur de curseur opaque dans l'en-tête x-pagination-cursor. Passez cette valeur en tant que paramètre de requête after dans votre prochaine requête pour obtenir la page suivante.

Lorsque la réponse n'a pas d'en-tête x-pagination-cursor, vous êtes à la dernière page.

Rechercher un ID de Projet par Nom

Cet exemple utilise curl et jq pour trouver l'ID d'un projet à partir de son nom :

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'

Passez l'ID retourné à Point de terminaison Sessions pour lister les sessions de ce projet.

Réponses d'erreur pour la liste des projets

Récupérer un projet

Renvoie un seul projet par son ID, dans le même format que Lister les projets.

Requête

• Point de terminaison : GET https://axe.deque.com/api-pub/v1/results/projects/{project_id}
• En-têtes (obligatoires) :
  • X-API-Key: <DEQUE_API_KEY>
  • Accept: application/json

Réponses d'erreur pour la récupération d'un projet

Créer un projet

Requête

• Point de terminaison : POST https://axe.deque.com/api-pub/v1/results/projects
• En-têtes (obligatoires) :
  • X-API-Key: <DEQUE_API_KEY>
  • Content-Type: application/json
  • Accept: application/json

Corps de la requête

Exemple de corps de requête

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

Corps de la réponse

Renvoie le projet créé, dans le même format que Lister les projets. Quiconque crée un projet en devient automatiquement l'administrateur, il n'est donc pas nécessaire d'effectuer un appel de membre séparé. Une création réussie renvoie 201 Created.

Réponses d'erreur pour la création d'un projet

Mettre à jour un projet

Requête

• Point de terminaison : PATCH https://axe.deque.com/api-pub/v1/results/projects/{project_id}
• En-têtes (obligatoires) :
  • X-API-Key: <DEQUE_API_KEY>
  • Content-Type: application/json
  • Accept: application/json

Corps de la requête

Exemple de corps de requête

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

Corps de la réponse

Renvoie le projet mis à jour, dans le même format que Lister les projets. Une mise à jour réussie renvoie 200 OK.

Réponses d'erreur pour la mise à jour d'un projet

Supprimer un projet

Requête

• Point de terminaison : DELETE https://axe.deque.com/api-pub/v1/results/projects/{project_id}
• En-têtes (obligatoires) :
  • X-API-Key: <DEQUE_API_KEY>
  • Accept: application/json

Corps de la réponse

{ "deleted": true }

Réponses d'erreur pour la suppression d'un projet

Adhésion au projet

L'adhésion à un projet est une sous-ressource du projet. Un administrateur de projet peut gérer le projet et son adhésion. Un membre du projet (le rôle member dans les opérations d'adhésion ci-dessous) peut accéder au projet mais ne peut pas le gérer. Les opérations d'adhésion identifient les utilisateurs par leur adresse e-mail. Ajouter un membre ne nécessite pas que ce membre détienne une licence. L'API les enregistre immédiatement, mais ils ne peuvent pas accéder au projet tant qu'ils ne détiennent pas une licence. L'utilisateur cible doit déjà appartenir à votre organisation. Vous ne pouvez pas ajouter quelqu'un qui n'est pas déjà membre de l'organisation.

Utilisez autant que possible les opérations en lot ci-dessous. Les trois opérations d'écriture acceptent plusieurs utilisateurs en un seul appel. Cela réduit le nombre de requêtes à effectuer. Si vous gérez l'adhésion pour une grande organisation, appliquez le backoff et réessayez lorsque vous recevez une réponse 429. Voir 429 Too Many Requests pour le modèle général.

Lister les membres du projet

• Point de terminaison : GET https://axe.deque.com/api-pub/v1/results/projects/{project_id}/memberships
• En-têtes (obligatoires) : X-API-Key: <DEQUE_API_KEY>, Accept: application/json

Corps de la réponse

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

Ajouter des membres au projet

• Point de terminaison : POST https://axe.deque.com/api-pub/v1/results/projects/{project_id}/memberships
• En-têtes (obligatoires) : X-API-Key: <DEQUE_API_KEY>, Content-Type: application/json, Accept: application/json

Corps de la requête

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

user_email est l'adresse e-mail du compte Axe de l'utilisateur. La correspondance ignore la casse et les espaces environnants. role accepte admin ou member (contributor est également acceptée comme synonyme de member). Chaque utilisateur ne peut apparaître qu'une seule fois dans une demande. Ajouter un utilisateur déjà dans le projet n'entraîne aucune action pour cet enregistrement : cela ne change pas son rôle existant. C'est une opération par lots. Une entrée invalide rejette la demande entière, et l'API n'écrit rien. Le message d'erreur liste chaque entrée qui a échoué, de sorte que vous pouvez corriger un lot en une seule passe.

Une demande réussie renvoie 201 Created avec { "created": true }, que la demande ait effectivement ajouté de nouvelles adhésions ou non.

Modifier les rôles des membres

• Point de terminaison : PATCH https://axe.deque.com/api-pub/v1/results/projects/{project_id}/memberships
• En-têtes (obligatoires) : X-API-Key: <DEQUE_API_KEY>, Content-Type: application/json, Accept: application/json
• Corps de la demande : même forme user_email_role_pairs que Ajouter des membres au projet

Chaque user_email doit appartenir à un membre actuel du projet. Un projet doit toujours conserver au moins un admin. L'API rejette une demande qui laisse le projet sans administrateur. Un dernier membre restant qui est le seul administrateur du projet ne peut pas modifier son propre rôle. C'est une opération par lots. Une entrée invalide rejette la demande entière, et l'API n'écrit rien.

Une demande réussie renvoie 200 OK avec { "ok": true }.

Supprimer des membres du projet

• Point de terminaison : DELETE https://axe.deque.com/api-pub/v1/results/projects/{project_id}/memberships?user_emails={comma-separated,url-encoded,emails}
• En-têtes (obligatoires) : X-API-Key: <DEQUE_API_KEY>, Accept: application/json

Passez les adresses e-mail des utilisateurs à supprimer sous forme de liste séparée par des virgules dans un seul paramètre de requête user_emails, et encodez l'URL de la valeur. Par exemple, un + littéral dans une adresse qui n'est pas encodée arrive comme un espace et est rejeté comme malformé. Il n'y a pas de corps de demande. Supprimer un utilisateur qui n'est pas membre réussit et ne supprime rien, de sorte qu'une demande réessayée ne constitue pas une erreur. Un projet doit toujours conserver au moins un admin. L'API rejette une demande qui supprime le dernier administrateur du projet. Un dernier membre restant qui est le seul administrateur du projet ne peut pas se supprimer.

Une demande réussie renvoie 200 OK avec les adresses qu'elle a supprimées et celles qui ne correspondaient à aucun membre, afin que vous puissiez faire la différence entre une faute de frappe et une suppression terminée :

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

Réponses d'erreur d'adhésion au projet