Intégration API

Référence de l'API

Cette page est générée depuis le contrat OpenAPI 3.1.0 de 101Maintain API (version 1.0.0). Elle décrit chaque route, ses paramètres, ses réponses et ses schémas champ par champ.

Le contrat complet est servi par ce site : openapi.json et openapi.yaml. Les agents IA trouveront les autres ressources dans Ressources pour agents IA.

API externe authentifiée par clé personnelle. Chaque appel est attribué à la clé et au compte qui l’a créée. Les droits actuels du propriétaire sont relus à chaque appel : autorisation effective = compte actif ∩ rôle actuel sur le projet ∩ projets sélectionnés pour la clé ∩ scopes de la clé ∩ politiques courantes.

Cette API ne permet ni de créer ou modifier un accord de recette, ni d’administrer membres, politiques, intégrations ou clés, ni de qualifier un constat, répondre à une question, reprendre, archiver ou publier. Ces actions restent dans l’interface, réservées aux personnes.

Documentation lisible : chapitre « Intégration API » du site de documentation.

Serveur : https://maintain.example — Instance 101Maintain de votre organisation.

Authentification#

Schéma personalKey : http bearer, format 101m_<keyId>.<secret>.

Clé personnelle créée depuis l’écran Mes clés API (/account/api-keys) de l’instance. Format : 101m_ + identifiant public (UUID) + . + secret de 43 caractères base64url. Durée de 1 à 90 jours, 20 projets au plus, scopes explicites. Seul l’en-tête Authorization: Bearer … est accepté ; un cookie de session ou un jeton dans l’URL n’authentifie rien.

ScopeLibellé dans l’interfaceRôle minimal
projects:readLire les projetsLecteur
repositories:readLire les dépôtsLecteur
runs:readLire les exécutionsLecteur
runs:createDémarrer une exécutionOpérateur
runs:cancelAnnuler une exécutionOpérateur
audits:readLire les auditsLecteur
audits:createDemander un auditOpérateur
reports:readLire les rapportsLecteur
usage:readLire la consommationLecteur

Sommaire des opérations#

MéthodeRouteRésuméScope
GETundefinedContrat OpenAPI servi par l’instancepublic
GETundefinedLister les projets de la clé encore accessibles au propriétaireprojects:read
GETundefinedLister les dépôts d’un projetrepositories:read
GETundefinedLister les exécutions d’un projetruns:read
POSTundefinedDemander une exécution sur une issue déjà suivieruns:create
GETundefinedLire l’état d’une exécutionruns:read
POSTundefinedDemander l’arrêt d’une exécution (idempotent)runs:cancel
GETundefinedTélécharger le rapport d’incident (PDF) d’une exécutionreports:read
GETundefinedLister les audits d’un projetaudits:read
POSTundefinedDemander un audit statique d’un dépôtaudits:create
GETundefinedLire les contrôles et constats d’un auditaudits:read
GETundefinedLire le rapport final d’un audit (constats acceptés)reports:read
GETundefinedLire les agrégats et entrées de consommation d’un projetusage:read

Contrat#

Document OpenAPI servi par l’instance.

GET/api/v1/openapi.json#

Contrat OpenAPI servi par l’instance

operationId getOpenApiDocument · route publique, sans authentification

Seule route publique de l’API : servie sans authentification, elle ne contient ni secret ni donnée. Le contrat servi par l’instance est plus succinct que celui de la documentation ; les deux décrivent les mêmes routes.

Réponses#

CodeDescriptionCorpsEn-têtes
200Document OpenAPI 3.1 (JSON).application/json objectCache-Control

Projets#

Projets et dépôts accessibles à la clé.

GET/api/v1/projects#

Lister les projets de la clé encore accessibles au propriétaire

operationId listProjects · scope projects:read

Intersection des projets sélectionnés pour la clé et des adhésions actuelles du propriétaire (tous les projets de l’organisation pour un administrateur). Un projet retiré de la clé ou dont le propriétaire a perdu l’accès disparaît de la liste. Pages fixes de 50 projets triés par identifiant ; cette route n’accepte pas limit. Le quota de cette route est compté pour la clé hors projet.

Paramètres#

NomEmplacementTypeRequisDescription
afterrequêtestring (uuid)nonCurseur : identifiant du dernier élément de la page précédente (valeur next). Absent : première page.

Réponses#

CodeDescriptionCorpsEn-têtes
200Page de projets.application/json ProjectPageCache-Control, X-Content-Type-Options, Referrer-Policy
401Clé absente, mal formée, invalide, expirée ou révoquée, ou compte propriétaire inactif. Vérifiée avant toute validation de paramètre et toute recherche de ressource : la réponse est la même que l’identifiant demandé existe, soit inconnu ou mal formé. (Unauthenticated)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy, WWW-Authenticate
403Scope requis absent de la clé, ou rôle actuel du propriétaire insuffisant sur une ressource visible. (Forbidden)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy
404Ressource inexistante ou hors du périmètre de la clé (projet non sélectionné, accès du propriétaire perdu, dépôt hors du projet, issue jamais reçue, aucune édition de rapport prête). Si l’instance n’active pas les identités, toute route renvoie 404 avec seulement {"error":"not_found"}. (NotFound)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy
422Identifiant mal formé, pagination hors bornes, corps non JSON ou non objet, champ inconnu, valeur invalide, Idempotency-Key absente ou invalide, filtre de période invalide. (InvalidRequest)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy
429Quota de la clé dépassé pour ce projet : fenêtre fixe d’une minute, 120 requêtes par défaut (l’instance peut abaisser cette valeur). Le refus compte dans la fenêtre. (RateLimited)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy, Retry-After
503Service ou capacité temporairement indisponible. Réessayer plus tard. (Unavailable)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy

Exemple de réponse 200 :

json
{
  "projects": [
    {
      "id": "3f6c1a52-7b0e-4c1d-9a6e-2b8f4d5c6e71",
      "slug": "boutique",
      "name": "Boutique en ligne"
    },
    {
      "id": "8a2d9e14-5f3b-4a7c-b1d0-6e9f2c3a4b85",
      "slug": "intranet",
      "name": "Intranet"
    }
  ],
  "next": null
}

GET/api/v1/projects/{projectId}/repositories#

Lister les dépôts d’un projet

operationId listRepositories · scope repositories:read

Dépôts du projet triés par identifiant, par pages de limit éléments.

Paramètres#

NomEmplacementTypeRequisDescription
projectIdcheminstring (uuid)ouiIdentifiant du projet (UUID). Valeur mal formée : 422 (après authentification).
afterrequêtestring (uuid)nonCurseur : identifiant du dernier élément de la page précédente (valeur next). Absent : première page.
limitrequêteinteger (1 à 50 ; défaut 50)nonTaille de page, de 1 à 50 (défaut 50). Hors bornes : 422.

Réponses#

CodeDescriptionCorpsEn-têtes
200Page de dépôts.application/json RepositoryPageCache-Control, X-Content-Type-Options, Referrer-Policy
401Clé absente, mal formée, invalide, expirée ou révoquée, ou compte propriétaire inactif. Vérifiée avant toute validation de paramètre et toute recherche de ressource : la réponse est la même que l’identifiant demandé existe, soit inconnu ou mal formé. (Unauthenticated)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy, WWW-Authenticate
403Scope requis absent de la clé, ou rôle actuel du propriétaire insuffisant sur une ressource visible. (Forbidden)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy
404Ressource inexistante ou hors du périmètre de la clé (projet non sélectionné, accès du propriétaire perdu, dépôt hors du projet, issue jamais reçue, aucune édition de rapport prête). Si l’instance n’active pas les identités, toute route renvoie 404 avec seulement {"error":"not_found"}. (NotFound)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy
422Identifiant mal formé, pagination hors bornes, corps non JSON ou non objet, champ inconnu, valeur invalide, Idempotency-Key absente ou invalide, filtre de période invalide. (InvalidRequest)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy
429Quota de la clé dépassé pour ce projet : fenêtre fixe d’une minute, 120 requêtes par défaut (l’instance peut abaisser cette valeur). Le refus compte dans la fenêtre. (RateLimited)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy, Retry-After
503Service ou capacité temporairement indisponible. Réessayer plus tard. (Unavailable)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy

Exemple de réponse 200 :

json
{
  "repositories": [
    {
      "id": "5b7e2c90-1d4f-4e6a-8c3b-9f0a1d2e3c46",
      "fullName": "exemple-org/boutique",
      "defaultBranch": "main",
      "enabled": true
    }
  ],
  "next": null
}

Exécutions#

Demandes d’exécution de maintenance sur des issues suivies.

GET/api/v1/projects/{projectId}/runs#

Lister les exécutions d’un projet

operationId listRuns · scope runs:read

Exécutions (originales et reprises) du projet triées par identifiant, par pages de limit éléments.

Paramètres#

NomEmplacementTypeRequisDescription
projectIdcheminstring (uuid)ouiIdentifiant du projet (UUID). Valeur mal formée : 422 (après authentification).
afterrequêtestring (uuid)nonCurseur : identifiant du dernier élément de la page précédente (valeur next). Absent : première page.
limitrequêteinteger (1 à 50 ; défaut 50)nonTaille de page, de 1 à 50 (défaut 50). Hors bornes : 422.

Réponses#

CodeDescriptionCorpsEn-têtes
200Page d’exécutions.application/json RunPageCache-Control, X-Content-Type-Options, Referrer-Policy
401Clé absente, mal formée, invalide, expirée ou révoquée, ou compte propriétaire inactif. Vérifiée avant toute validation de paramètre et toute recherche de ressource : la réponse est la même que l’identifiant demandé existe, soit inconnu ou mal formé. (Unauthenticated)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy, WWW-Authenticate
403Scope requis absent de la clé, ou rôle actuel du propriétaire insuffisant sur une ressource visible. (Forbidden)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy
404Ressource inexistante ou hors du périmètre de la clé (projet non sélectionné, accès du propriétaire perdu, dépôt hors du projet, issue jamais reçue, aucune édition de rapport prête). Si l’instance n’active pas les identités, toute route renvoie 404 avec seulement {"error":"not_found"}. (NotFound)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy
422Identifiant mal formé, pagination hors bornes, corps non JSON ou non objet, champ inconnu, valeur invalide, Idempotency-Key absente ou invalide, filtre de période invalide. (InvalidRequest)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy
429Quota de la clé dépassé pour ce projet : fenêtre fixe d’une minute, 120 requêtes par défaut (l’instance peut abaisser cette valeur). Le refus compte dans la fenêtre. (RateLimited)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy, Retry-After
503Service ou capacité temporairement indisponible. Réessayer plus tard. (Unavailable)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy

Exemple de réponse 200 :

json
{
  "runs": [
    {
      "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
      "status": "prepared",
      "repositoryId": "5b7e2c90-1d4f-4e6a-8c3b-9f0a1d2e3c46",
      "issueNumber": 42,
      "startedAt": "2026-11-19T09:12:03.000Z",
      "finishedAt": "2026-11-19T09:18:47.000Z",
      "links": {
        "self": "/api/v1/runs/c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f"
      }
    }
  ],
  "next": null
}

POST/api/v1/projects/{projectId}/runs#

Demander une exécution sur une issue déjà suivie

operationId createRun · scope runs:create

Demande l’exécution de maintenance d’une issue GitHub déjà reçue par le webhook de la plateforme. Rôle minimal du propriétaire : opérateur du projet.

Conditions : dépôt du projet, actif, rattaché à la GitHub App et sous surveillance ; issue ouverte ; aucune exécution originale pour cette issue. Une seule exécution originale par issue : les reprises se demandent dans l’interface.

Pendant l’arrêt global de l’organisation, la demande est acceptée (202) avec waiting: "organization_stop" : elle reste en file et démarre une seule fois après la levée. Un rejeu idempotent renvoie le même identifiant.

La réponse 202 ne garantit pas le démarrage : le worker applique ensuite les plafonds de concurrence et de jetons de la politique, et recontrôle la clé, le compte et ses droits avant chaque étape. Une clé révoquée ou expirée annule une demande encore en attente.

Paramètres#

NomEmplacementTypeRequisDescription
projectIdcheminstring (uuid)ouiIdentifiant du projet (UUID). Valeur mal formée : 422 (après authentification).
Idempotency-Keyen-têtestring (8 à 128 car. ; motif ^[\x21-\x7e]{8,128}$)ouiObligatoire. 8 à 128 caractères ASCII visibles (0x21 à 0x7E). Unicité par propriétaire, clé API, projet et route. Même valeur et même corps : la première réponse est rejouée pendant 24 h avec Idempotent-Replayed: true. Même valeur et corps différent : 409. Absente ou invalide : 422.

Corps de la requête#

Objet JSON aux seuls champs déclarés ; tout autre champ renvoie 422.

Type application/json, obligatoire. Schéma : RunRequest.

ChampTypeRequisDescription
repositoryIdstring (uuid)ouiDépôt du projet, actif, rattaché et sous surveillance.
issueNumberinteger (1 à …)ouiNuméro de l’issue GitHub, déjà reçue par le webhook. Doit être un entier JSON (pas une chaîne).
json
{
  "repositoryId": "5b7e2c90-1d4f-4e6a-8c3b-9f0a1d2e3c46",
  "issueNumber": 42
}

Réponses#

CodeDescriptionCorpsEn-têtes
202Demande acceptée. Suivre la ressource indiquée par Location (et links.self dans le corps).application/json RunAcceptedCache-Control, X-Content-Type-Options, Referrer-Policy, Location, Idempotent-Replayed
401Clé absente, mal formée, invalide, expirée ou révoquée, ou compte propriétaire inactif. Vérifiée avant toute validation de paramètre et toute recherche de ressource : la réponse est la même que l’identifiant demandé existe, soit inconnu ou mal formé. (Unauthenticated)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy, WWW-Authenticate
403Scope requis absent de la clé, ou rôle actuel du propriétaire insuffisant sur une ressource visible. (Forbidden)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy
404Ressource inexistante ou hors du périmètre de la clé (projet non sélectionné, accès du propriétaire perdu, dépôt hors du projet, issue jamais reçue, aucune édition de rapport prête). Si l’instance n’active pas les identités, toute route renvoie 404 avec seulement {"error":"not_found"}. (NotFound)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy
409Conflit : ; issue fermée, ou dépôt inactif, non rattaché ou non surveillé (error: conflict, sans détail) ; ; exécution déjà existante pour l’issue : existingRun désigne la dernière tentative de l’issue uniquement si la clé détient aussi runs:read ; sinon le conflit reste générique ; ; Idempotency-Key déjà utilisée avec un autre corps.application/json RunConflictCache-Control, X-Content-Type-Options, Referrer-Policy
422Identifiant mal formé, pagination hors bornes, corps non JSON ou non objet, champ inconnu, valeur invalide, Idempotency-Key absente ou invalide, filtre de période invalide. (InvalidRequest)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy
429Quota de la clé dépassé pour ce projet : fenêtre fixe d’une minute, 120 requêtes par défaut (l’instance peut abaisser cette valeur). Le refus compte dans la fenêtre. (RateLimited)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy, Retry-After
503Service ou capacité temporairement indisponible. Réessayer plus tard. (Unavailable)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy

Exemple de réponse 202 :

json
{
  "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
  "status": "queued",
  "repositoryId": "5b7e2c90-1d4f-4e6a-8c3b-9f0a1d2e3c46",
  "issueNumber": 42,
  "links": {
    "self": "/api/v1/runs/c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f"
  }
}

Exemple de réponse 409 — Exécution existante, lisible par la clé :

json
{
  "error": "conflict",
  "message": "Une exécution existe déjà pour cette issue.",
  "existingRun": {
    "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
    "status": "running",
    "links": {
      "self": "/api/v1/runs/c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f"
    }
  }
}

Exemple de réponse 409 — Conflit générique :

json
{
  "error": "conflict",
  "message": "Conflit avec l’état actuel ou une requête idempotente différente."
}

GET/api/v1/runs/{runId}#

Lire l’état d’une exécution

operationId getRun · scope runs:read

État, étapes, résultat sans contenu de fichier, budgets de jetons, publication et tentative suivante. La consommation détaillée se lit sur /usage du projet.

Paramètres#

NomEmplacementTypeRequisDescription
runIdcheminstring (uuid)ouiIdentifiant de l’exécution (UUID).

Réponses#

CodeDescriptionCorpsEn-têtes
200Exécution.application/json RunCache-Control, X-Content-Type-Options, Referrer-Policy
401Clé absente, mal formée, invalide, expirée ou révoquée, ou compte propriétaire inactif. Vérifiée avant toute validation de paramètre et toute recherche de ressource : la réponse est la même que l’identifiant demandé existe, soit inconnu ou mal formé. (Unauthenticated)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy, WWW-Authenticate
403Scope requis absent de la clé, ou rôle actuel du propriétaire insuffisant sur une ressource visible. (Forbidden)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy
404Ressource inexistante ou hors du périmètre de la clé (projet non sélectionné, accès du propriétaire perdu, dépôt hors du projet, issue jamais reçue, aucune édition de rapport prête). Si l’instance n’active pas les identités, toute route renvoie 404 avec seulement {"error":"not_found"}. (NotFound)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy
422Identifiant mal formé, pagination hors bornes, corps non JSON ou non objet, champ inconnu, valeur invalide, Idempotency-Key absente ou invalide, filtre de période invalide. (InvalidRequest)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy
429Quota de la clé dépassé pour ce projet : fenêtre fixe d’une minute, 120 requêtes par défaut (l’instance peut abaisser cette valeur). Le refus compte dans la fenêtre. (RateLimited)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy, Retry-After
503Service ou capacité temporairement indisponible. Réessayer plus tard. (Unavailable)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy

Exemple de réponse 200 :

json
{
  "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
  "projectId": "3f6c1a52-7b0e-4c1d-9a6e-2b8f4d5c6e71",
  "status": "prepared",
  "repository": {
    "id": "5b7e2c90-1d4f-4e6a-8c3b-9f0a1d2e3c46",
    "fullName": "exemple-org/boutique"
  },
  "issue": {
    "number": 42,
    "open": true
  },
  "requestedBy": {
    "userId": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
    "apiKeyId": "1b2c3d4e-5f6a-4b7c-9d8e-0f1a2b3c4d5e"
  },
  "parentRunId": null,
  "startedAt": "2026-11-19T09:12:03.000Z",
  "finishedAt": "2026-11-19T09:18:47.000Z",
  "archivedAt": null,
  "result": {
    "status": "prepared",
    "summary": "Correction du calcul de TVA sur le panier.",
    "changedFiles": [
      "src/cart/vat.ts",
      "test/cart/vat.test.ts"
    ],
    "testsExecuted": false
  },
  "steps": [
    {
      "sequence": 1,
      "role": "explorer",
      "status": "succeeded",
      "reused": false
    },
    {
      "sequence": 2,
      "role": "analyst",
      "status": "succeeded",
      "reused": false
    },
    {
      "sequence": 3,
      "role": "designer",
      "status": "succeeded",
      "reused": false
    },
    {
      "sequence": 4,
      "role": "developer",
      "status": "succeeded",
      "reused": false
    },
    {
      "sequence": 5,
      "role": "reviewer",
      "status": "succeeded",
      "reused": false
    }
  ],
  "budgets": {
    "run": {
      "limit": 200000,
      "used": 48210,
      "held": 0,
      "unknown": 0,
      "remaining": 151790,
      "warning": false
    },
    "issue": {
      "limit": 200000,
      "used": 48210,
      "held": 0,
      "unknown": 0,
      "remaining": 151790,
      "warning": false
    }
  },
  "publication": {
    "status": "draft",
    "pullNumber": 128
  },
  "nextAttempt": null,
  "links": {
    "self": "/api/v1/runs/c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
    "cancel": "/api/v1/runs/c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f/cancel",
    "usage": "/api/v1/projects/3f6c1a52-7b0e-4c1d-9a6e-2b8f4d5c6e71/usage"
  }
}

POST/api/v1/runs/{runId}/cancel#

Demander l’arrêt d’une exécution (idempotent)

operationId cancelRun · scope runs:cancel

Marque la demande comme annulée. Rôle minimal du propriétaire : opérateur. Répéter l’appel est sans effet supplémentaire. Un appel au modèle déjà parti peut se terminer ; aucun nouvel effet ne démarre et aucune publication ne suit. L’annulation reste possible pendant un arrêt global, y compris pour une demande en attente de la levée. Pas de corps de requête ni d’Idempotency-Key.

Paramètres#

NomEmplacementTypeRequisDescription
runIdcheminstring (uuid)ouiIdentifiant de l’exécution (UUID).

Réponses#

CodeDescriptionCorpsEn-têtes
202Arrêt demandé. Location pointe vers l’exécution ; Idempotent-Replayed n’est pas envoyé sur cette route.application/json CancelAcceptedCache-Control, X-Content-Type-Options, Referrer-Policy, Location, Idempotent-Replayed
401Clé absente, mal formée, invalide, expirée ou révoquée, ou compte propriétaire inactif. Vérifiée avant toute validation de paramètre et toute recherche de ressource : la réponse est la même que l’identifiant demandé existe, soit inconnu ou mal formé. (Unauthenticated)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy, WWW-Authenticate
403Scope requis absent de la clé, ou rôle actuel du propriétaire insuffisant sur une ressource visible. (Forbidden)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy
404Ressource inexistante ou hors du périmètre de la clé (projet non sélectionné, accès du propriétaire perdu, dépôt hors du projet, issue jamais reçue, aucune édition de rapport prête). Si l’instance n’active pas les identités, toute route renvoie 404 avec seulement {"error":"not_found"}. (NotFound)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy
422Identifiant mal formé, pagination hors bornes, corps non JSON ou non objet, champ inconnu, valeur invalide, Idempotency-Key absente ou invalide, filtre de période invalide. (InvalidRequest)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy
429Quota de la clé dépassé pour ce projet : fenêtre fixe d’une minute, 120 requêtes par défaut (l’instance peut abaisser cette valeur). Le refus compte dans la fenêtre. (RateLimited)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy, Retry-After
503Service ou capacité temporairement indisponible. Réessayer plus tard. (Unavailable)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy

Exemple de réponse 202 :

json
{
  "id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
  "cancelRequested": true,
  "status": "running",
  "inFlight": "Un appel modèle déjà parti peut se terminer ; aucun nouvel effet ne démarre et aucune publication ne suit.",
  "links": {
    "self": "/api/v1/runs/c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f"
  }
}

Audits#

Audits statiques de dépôt et leurs constats.

GET/api/v1/projects/{projectId}/audits#

Lister les audits d’un projet

operationId listAudits · scope audits:read

Audits du projet triés par identifiant, par pages fixes de 30 ; cette route n’accepte pas limit.

Paramètres#

NomEmplacementTypeRequisDescription
projectIdcheminstring (uuid)ouiIdentifiant du projet (UUID). Valeur mal formée : 422 (après authentification).
afterrequêtestring (uuid)nonCurseur : identifiant du dernier élément de la page précédente (valeur next). Absent : première page.

Réponses#

CodeDescriptionCorpsEn-têtes
200Page d’audits.application/json AuditPageCache-Control, X-Content-Type-Options, Referrer-Policy
401Clé absente, mal formée, invalide, expirée ou révoquée, ou compte propriétaire inactif. Vérifiée avant toute validation de paramètre et toute recherche de ressource : la réponse est la même que l’identifiant demandé existe, soit inconnu ou mal formé. (Unauthenticated)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy, WWW-Authenticate
403Scope requis absent de la clé, ou rôle actuel du propriétaire insuffisant sur une ressource visible. (Forbidden)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy
404Ressource inexistante ou hors du périmètre de la clé (projet non sélectionné, accès du propriétaire perdu, dépôt hors du projet, issue jamais reçue, aucune édition de rapport prête). Si l’instance n’active pas les identités, toute route renvoie 404 avec seulement {"error":"not_found"}. (NotFound)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy
422Identifiant mal formé, pagination hors bornes, corps non JSON ou non objet, champ inconnu, valeur invalide, Idempotency-Key absente ou invalide, filtre de période invalide. (InvalidRequest)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy
429Quota de la clé dépassé pour ce projet : fenêtre fixe d’une minute, 120 requêtes par défaut (l’instance peut abaisser cette valeur). Le refus compte dans la fenêtre. (RateLimited)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy, Retry-After
503Service ou capacité temporairement indisponible. Réessayer plus tard. (Unavailable)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy

Exemple de réponse 200 :

json
{
  "audits": [
    {
      "id": "e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8",
      "status": "complete",
      "repository": "exemple-org/boutique",
      "createdAt": "2026-11-18T14:02:11.000Z",
      "links": {
        "self": "/api/v1/audits/e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8"
      }
    }
  ],
  "next": null
}

POST/api/v1/projects/{projectId}/audits#

Demander un audit statique d’un dépôt

operationId createAudit · scope audits:create

Exécute le plan statique complet : secrets, accessibilité et dépendances. Rôle minimal du propriétaire : opérateur. Lecture seule du dépôt, sans appel au modèle.

Si un audit est déjà en file ou en cours pour ce dépôt, la réponse 202 désigne cet audit au lieu d’en créer un autre.

Pendant l’arrêt global de l’organisation, la demande est acceptée (202) avec waiting: "organization_stop" et l’audit démarre après la levée.

Les contrôles dynamiques (recette) restent soumis à l’accord humain et ne se déclenchent pas par clé.

Paramètres#

NomEmplacementTypeRequisDescription
projectIdcheminstring (uuid)ouiIdentifiant du projet (UUID). Valeur mal formée : 422 (après authentification).
Idempotency-Keyen-têtestring (8 à 128 car. ; motif ^[\x21-\x7e]{8,128}$)ouiObligatoire. 8 à 128 caractères ASCII visibles (0x21 à 0x7E). Unicité par propriétaire, clé API, projet et route. Même valeur et même corps : la première réponse est rejouée pendant 24 h avec Idempotent-Replayed: true. Même valeur et corps différent : 409. Absente ou invalide : 422.

Corps de la requête#

Objet JSON aux seuls champs déclarés ; tout autre champ renvoie 422.

Type application/json, obligatoire. Schéma : AuditRequest.

ChampTypeRequisDescription
repositoryIdstring (uuid)ouiDépôt du projet, actif et rattaché à la GitHub App.
checksarray<string (secrets, accessibility, dependencies)>nonFacultatif. S’il est fourni, il doit contenir exactement les trois contrôles statiques (ordre libre).
json
{
  "repositoryId": "5b7e2c90-1d4f-4e6a-8c3b-9f0a1d2e3c46"
}

Réponses#

CodeDescriptionCorpsEn-têtes
202Demande acceptée. Suivre la ressource indiquée par Location (et links.self dans le corps).application/json AuditAcceptedCache-Control, X-Content-Type-Options, Referrer-Policy, Location, Idempotent-Replayed
401Clé absente, mal formée, invalide, expirée ou révoquée, ou compte propriétaire inactif. Vérifiée avant toute validation de paramètre et toute recherche de ressource : la réponse est la même que l’identifiant demandé existe, soit inconnu ou mal formé. (Unauthenticated)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy, WWW-Authenticate
403Scope requis absent de la clé, ou rôle actuel du propriétaire insuffisant sur une ressource visible. (Forbidden)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy
404Ressource inexistante ou hors du périmètre de la clé (projet non sélectionné, accès du propriétaire perdu, dépôt hors du projet, issue jamais reçue, aucune édition de rapport prête). Si l’instance n’active pas les identités, toute route renvoie 404 avec seulement {"error":"not_found"}. (NotFound)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy
409Conflit : ; dépôt arrêté (reason: repository_stopped) ou non rattaché à la GitHub App (reason: repository_not_bound) ; message indique le réglage à changer ; ; Idempotency-Key déjà utilisée avec un autre corps.application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy
422Identifiant mal formé, pagination hors bornes, corps non JSON ou non objet, champ inconnu, valeur invalide, Idempotency-Key absente ou invalide, filtre de période invalide. (InvalidRequest)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy
429Quota de la clé dépassé pour ce projet : fenêtre fixe d’une minute, 120 requêtes par défaut (l’instance peut abaisser cette valeur). Le refus compte dans la fenêtre. (RateLimited)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy, Retry-After
503Audits désactivés sur l’instance (reason: repository_audits_disabled, renvoyé avant toute validation du corps) ou service indisponible.application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy

Exemple de réponse 202 :

json
{
  "id": "e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8",
  "status": "queued",
  "repositoryId": "5b7e2c90-1d4f-4e6a-8c3b-9f0a1d2e3c46",
  "checks": [
    "accessibility",
    "dependencies",
    "secrets"
  ],
  "links": {
    "self": "/api/v1/audits/e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8"
  }
}

Exemple de réponse 409 — Dépôt arrêté :

json
{
  "error": "conflict",
  "message": "Dépôt arrêté : cocher « Autoriser les travaux sur ce dépôt » dans sa fiche, puis enregistrer.",
  "reason": "repository_stopped"
}

Exemple de réponse 409 — Dépôt non rattaché :

json
{
  "error": "conflict",
  "message": "Dépôt non rattaché à la GitHub App : ouvrir sa fiche et cliquer sur « Vérifier et rattacher ».",
  "reason": "repository_not_bound"
}

Exemple de réponse 503 :

json
{
  "error": "unavailable",
  "message": "Audits de dépôt désactivés sur cette instance : définir MVP_REPOSITORY_AUDITS_ENABLED=true pour le web et le worker (variable de la ressource Coolify), puis redéployer.",
  "reason": "repository_audits_disabled"
}

GET/api/v1/audits/{auditId}#

Lire les contrôles et constats d’un audit

operationId getAudit · scope audits:read

Contrôles statiques, constats (100 au plus, triés par règle) et état de qualification. Les contrôles dynamiques ne sont pas exposés par cette route.

Paramètres#

NomEmplacementTypeRequisDescription
auditIdcheminstring (uuid)ouiIdentifiant de l’audit (UUID).

Réponses#

CodeDescriptionCorpsEn-têtes
200Audit.application/json AuditCache-Control, X-Content-Type-Options, Referrer-Policy
401Clé absente, mal formée, invalide, expirée ou révoquée, ou compte propriétaire inactif. Vérifiée avant toute validation de paramètre et toute recherche de ressource : la réponse est la même que l’identifiant demandé existe, soit inconnu ou mal formé. (Unauthenticated)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy, WWW-Authenticate
403Scope requis absent de la clé, ou rôle actuel du propriétaire insuffisant sur une ressource visible. (Forbidden)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy
404Ressource inexistante ou hors du périmètre de la clé (projet non sélectionné, accès du propriétaire perdu, dépôt hors du projet, issue jamais reçue, aucune édition de rapport prête). Si l’instance n’active pas les identités, toute route renvoie 404 avec seulement {"error":"not_found"}. (NotFound)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy
422Identifiant mal formé, pagination hors bornes, corps non JSON ou non objet, champ inconnu, valeur invalide, Idempotency-Key absente ou invalide, filtre de période invalide. (InvalidRequest)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy
429Quota de la clé dépassé pour ce projet : fenêtre fixe d’une minute, 120 requêtes par défaut (l’instance peut abaisser cette valeur). Le refus compte dans la fenêtre. (RateLimited)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy, Retry-After
503Service ou capacité temporairement indisponible. Réessayer plus tard. (Unavailable)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy

Exemple de réponse 200 :

json
{
  "id": "e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8",
  "projectId": "3f6c1a52-7b0e-4c1d-9a6e-2b8f4d5c6e71",
  "status": "complete",
  "repository": "exemple-org/boutique",
  "baseSha": "9f3c2a1b8e7d6c5b4a39281706f5e4d3c2b1a090",
  "checks": [
    {
      "id": "secrets",
      "state": "complete",
      "durationMs": 412,
      "inspected": 214,
      "skipped": 0
    },
    {
      "id": "accessibility",
      "state": "complete",
      "durationMs": 96,
      "inspected": 18,
      "skipped": 0
    },
    {
      "id": "dependencies",
      "state": "complete",
      "durationMs": 1830,
      "inspected": 1,
      "skipped": 0
    }
  ],
  "finishedAt": "2026-11-18T14:03:40.000Z",
  "pendingQualification": 1,
  "reportAvailable": false,
  "findings": [
    {
      "id": "f5a6b7c8-d9e0-4f1a-b2c3-d4e5f6a7b8c9",
      "rule": "image_alt",
      "location": "public/index.html",
      "line": null,
      "status": "pending",
      "issue": null
    }
  ],
  "links": {
    "self": "/api/v1/audits/e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8",
    "report": "/api/v1/audits/e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8/report"
  }
}

Rapports#

Rapports d’incident (PDF) et rapports finaux d’audit.

GET/api/v1/runs/{runId}/report#

Télécharger le rapport d’incident (PDF) d’une exécution

operationId getRunReport · scope reports:read

Sert à l’identique l’artefact stocké de la dernière édition prête du rapport d’incident, après vérification de son empreinte. L’auteur du PDF est le compte qui a demandé l’édition dans l’interface. 404 si l’exécution est hors périmètre ou si aucune édition prête n’existe (jamais demandée, en file ou refusée : non distingués). Les éditions se demandent dans l’interface, pas par clé.

Paramètres#

NomEmplacementTypeRequisDescription
runIdcheminstring (uuid)ouiIdentifiant de l’exécution (UUID).

Réponses#

CodeDescriptionCorpsEn-têtes
200PDF du rapport d’incident.application/pdf string (binary)Cache-Control, X-Content-Type-Options, Referrer-Policy, Content-Disposition, X-Report-Edition, X-Report-Sha256
401Clé absente, mal formée, invalide, expirée ou révoquée, ou compte propriétaire inactif. Vérifiée avant toute validation de paramètre et toute recherche de ressource : la réponse est la même que l’identifiant demandé existe, soit inconnu ou mal formé. (Unauthenticated)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy, WWW-Authenticate
403Scope requis absent de la clé, ou rôle actuel du propriétaire insuffisant sur une ressource visible. (Forbidden)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy
404Ressource inexistante ou hors du périmètre de la clé (projet non sélectionné, accès du propriétaire perdu, dépôt hors du projet, issue jamais reçue, aucune édition de rapport prête). Si l’instance n’active pas les identités, toute route renvoie 404 avec seulement {"error":"not_found"}. (NotFound)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy
422Identifiant mal formé, pagination hors bornes, corps non JSON ou non objet, champ inconnu, valeur invalide, Idempotency-Key absente ou invalide, filtre de période invalide. (InvalidRequest)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy
429Quota de la clé dépassé pour ce projet : fenêtre fixe d’une minute, 120 requêtes par défaut (l’instance peut abaisser cette valeur). Le refus compte dans la fenêtre. (RateLimited)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy, Retry-After
503Service ou capacité temporairement indisponible. Réessayer plus tard. (Unavailable)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy

GET/api/v1/audits/{auditId}/report#

Lire le rapport final d’un audit (constats acceptés)

operationId getAuditReport · scope reports:read

Mêmes verrous que l’interface : disponible quand l’audit est complete ou partial, qu’aucun constat n’attend de qualification et qu’aucun contrôle dynamique n’est en cours. Seuls les constats acceptés y figurent.

Paramètres#

NomEmplacementTypeRequisDescription
auditIdcheminstring (uuid)ouiIdentifiant de l’audit (UUID).

Réponses#

CodeDescriptionCorpsEn-têtes
200Rapport final.application/json AuditReportCache-Control, X-Content-Type-Options, Referrer-Policy
401Clé absente, mal formée, invalide, expirée ou révoquée, ou compte propriétaire inactif. Vérifiée avant toute validation de paramètre et toute recherche de ressource : la réponse est la même que l’identifiant demandé existe, soit inconnu ou mal formé. (Unauthenticated)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy, WWW-Authenticate
403Scope requis absent de la clé, ou rôle actuel du propriétaire insuffisant sur une ressource visible. (Forbidden)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy
404Ressource inexistante ou hors du périmètre de la clé (projet non sélectionné, accès du propriétaire perdu, dépôt hors du projet, issue jamais reçue, aucune édition de rapport prête). Si l’instance n’active pas les identités, toute route renvoie 404 avec seulement {"error":"not_found"}. (NotFound)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy
409Audit non terminé, constats encore à qualifier ou contrôle dynamique en cours.application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy
422Identifiant mal formé, pagination hors bornes, corps non JSON ou non objet, champ inconnu, valeur invalide, Idempotency-Key absente ou invalide, filtre de période invalide. (InvalidRequest)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy
429Quota de la clé dépassé pour ce projet : fenêtre fixe d’une minute, 120 requêtes par défaut (l’instance peut abaisser cette valeur). Le refus compte dans la fenêtre. (RateLimited)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy, Retry-After
503Service ou capacité temporairement indisponible. Réessayer plus tard. (Unavailable)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy

Exemple de réponse 200 :

json
{
  "id": "e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8",
  "projectId": "3f6c1a52-7b0e-4c1d-9a6e-2b8f4d5c6e71",
  "status": "complete",
  "repository": "exemple-org/boutique",
  "baseSha": "9f3c2a1b8e7d6c5b4a39281706f5e4d3c2b1a090",
  "checks": [
    {
      "id": "secrets",
      "state": "complete",
      "durationMs": 412,
      "inspected": 214,
      "skipped": 0
    },
    {
      "id": "accessibility",
      "state": "complete",
      "durationMs": 96,
      "inspected": 18,
      "skipped": 0
    },
    {
      "id": "dependencies",
      "state": "complete",
      "durationMs": 1830,
      "inspected": 1,
      "skipped": 0
    }
  ],
  "finishedAt": "2026-11-18T14:03:40.000Z",
  "report": "final",
  "findings": [
    {
      "id": "f5a6b7c8-d9e0-4f1a-b2c3-d4e5f6a7b8c9",
      "rule": "image_alt",
      "location": "public/index.html",
      "line": null,
      "status": "accepted",
      "issue": {
        "number": 57,
        "status": "confirmed"
      }
    }
  ],
  "links": {
    "self": "/api/v1/audits/e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8/report"
  }
}

Exemple de réponse 409 :

json
{
  "error": "conflict",
  "message": "Conflit avec l’état actuel ou une requête idempotente différente."
}

Consommation#

Registre d’usage des appels au modèle et coûts connus.

GET/api/v1/projects/{projectId}/usage#

Lire les agrégats et entrées de consommation d’un projet

operationId getProjectUsage · scope usage:read

Compteurs, coûts connus par devise et entrées du registre d’usage sur une période (30 jours par défaut, 366 jours au plus). Entrées triées par date de début, par pages de 100.

Une consommation inconnue (state: unknown), une réservation en cours (state: reserved), une reprise réutilisée (étape reused, aucun jeton facturé) et une consommation nulle restent distinctes : ne pas les additionner comme des zéros.

Paramètres#

NomEmplacementTypeRequisDescription
projectIdcheminstring (uuid)ouiIdentifiant du projet (UUID). Valeur mal formée : 422 (après authentification).
fromrequêtestring (date-time)nonDébut inclus, en UTC au format AAAA-MM-JJTHH:MM:SS[.mmm]Z. Par défaut : to moins 30 jours.
torequêtestring (date-time)nonFin exclue, même format. Par défaut : maintenant. from doit précéder to et l’écart ne pas dépasser 366 jours.
kindrequêtestring (live, evaluation ; défaut "live")nonlive : exécutions de maintenance (défaut). evaluation : exécutions du banc d’essai.
repositoryrequêtestring (uuid)nonLimiter à un dépôt du projet (404 si le dépôt n’appartient pas au projet).
modelrequêtestring (motif ^[a-zA-Z0-9_.:/-]{1,150}$)nonLimiter à un identifiant de modèle.
pullrequêteinteger (1 à …)nonLimiter aux exécutions rattachées à ce numéro de PR brouillon.
afterrequêtestring (motif ^\d{1,15}\.[a-f0-9-]{36}\.\d{1,2}$)nonCurseur opaque : valeur next de la page précédente.

Réponses#

CodeDescriptionCorpsEn-têtes
200Compteurs, coûts connus et entrées.application/json UsageReportCache-Control, X-Content-Type-Options, Referrer-Policy
401Clé absente, mal formée, invalide, expirée ou révoquée, ou compte propriétaire inactif. Vérifiée avant toute validation de paramètre et toute recherche de ressource : la réponse est la même que l’identifiant demandé existe, soit inconnu ou mal formé. (Unauthenticated)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy, WWW-Authenticate
403Scope requis absent de la clé, ou rôle actuel du propriétaire insuffisant sur une ressource visible. (Forbidden)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy
404Ressource inexistante ou hors du périmètre de la clé (projet non sélectionné, accès du propriétaire perdu, dépôt hors du projet, issue jamais reçue, aucune édition de rapport prête). Si l’instance n’active pas les identités, toute route renvoie 404 avec seulement {"error":"not_found"}. (NotFound)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy
422Identifiant mal formé, pagination hors bornes, corps non JSON ou non objet, champ inconnu, valeur invalide, Idempotency-Key absente ou invalide, filtre de période invalide. (InvalidRequest)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy
429Quota de la clé dépassé pour ce projet : fenêtre fixe d’une minute, 120 requêtes par défaut (l’instance peut abaisser cette valeur). Le refus compte dans la fenêtre. (RateLimited)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy, Retry-After
503Service ou capacité temporairement indisponible. Réessayer plus tard. (Unavailable)application/json ErrorCache-Control, X-Content-Type-Options, Referrer-Policy

Exemple de réponse 200 :

json
{
  "kind": "live",
  "period": {
    "from": "2026-11-01T00:00:00.000Z",
    "to": "2026-12-01T00:00:00.000Z"
  },
  "counters": {
    "calls": "5",
    "unknown": "0",
    "pending": "0",
    "unknown_costs": "0",
    "unknown_cached": "0",
    "unknown_reasoning": "0",
    "held": "0",
    "input": "41200",
    "output": "7010",
    "cached": "12000",
    "reasoning": "2100",
    "total": "48210"
  },
  "knownCosts": [
    {
      "currency": "EUR",
      "amount": "0.412300000000"
    }
  ],
  "entries": [
    {
      "runId": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f",
      "sequence": 1,
      "role": "explorer",
      "model": "modele-exemple",
      "kind": "live",
      "repositoryId": "5b7e2c90-1d4f-4e6a-8c3b-9f0a1d2e3c46",
      "issueNumber": 42,
      "pullNumber": 128,
      "state": "known",
      "rate": {
        "model": "modele-exemple",
        "currency": "EUR",
        "input": "0.000003",
        "output": "0.000015",
        "cachedInput": "0.0000003",
        "effectiveFrom": "2026-10-01",
        "source": "contrat"
      },
      "usage": {
        "input": 9200,
        "output": 1400,
        "total": 10600,
        "cached": 3000,
        "reasoning": 400
      },
      "cost": "0.048600000000",
      "reservedTokens": 40000,
      "heldTokens": 0,
      "startedAt": "2026-11-19T09:12:05.000Z"
    }
  ],
  "next": null
}

Réponses communes#

Unauthenticated#

Clé absente, mal formée, invalide, expirée ou révoquée, ou compte propriétaire inactif. Vérifiée avant toute validation de paramètre et toute recherche de ressource : la réponse est la même que l’identifiant demandé existe, soit inconnu ou mal formé.

En-têtes : Cache-Control, X-Content-Type-Options, Referrer-Policy, WWW-Authenticate.

json
{
  "error": "unauthenticated",
  "message": "Clé API absente, invalide, expirée ou révoquée."
}

Forbidden#

Scope requis absent de la clé, ou rôle actuel du propriétaire insuffisant sur une ressource visible.

En-têtes : Cache-Control, X-Content-Type-Options, Referrer-Policy.

json
{
  "error": "forbidden",
  "message": "Droit de la clé ou rôle actuel du propriétaire insuffisant."
}

NotFound#

Ressource inexistante ou hors du périmètre de la clé (projet non sélectionné, accès du propriétaire perdu, dépôt hors du projet, issue jamais reçue, aucune édition de rapport prête). Si l’instance n’active pas les identités, toute route renvoie 404 avec seulement {"error":"not_found"}.

En-têtes : Cache-Control, X-Content-Type-Options, Referrer-Policy.

json
{
  "error": "not_found",
  "message": "Ressource introuvable dans le périmètre de la clé."
}

InvalidRequest#

Identifiant mal formé, pagination hors bornes, corps non JSON ou non objet, champ inconnu, valeur invalide, Idempotency-Key absente ou invalide, filtre de période invalide.

En-têtes : Cache-Control, X-Content-Type-Options, Referrer-Policy.

json
{
  "error": "invalid_request",
  "message": "Données de requête invalides."
}

RateLimited#

Quota de la clé dépassé pour ce projet : fenêtre fixe d’une minute, 120 requêtes par défaut (l’instance peut abaisser cette valeur). Le refus compte dans la fenêtre.

En-têtes : Cache-Control, X-Content-Type-Options, Referrer-Policy, Retry-After.

json
{
  "error": "rate_limited",
  "message": "Quota de requêtes de la clé dépassé pour ce projet."
}

Unavailable#

Service ou capacité temporairement indisponible. Réessayer plus tard.

En-têtes : Cache-Control, X-Content-Type-Options, Referrer-Policy.

json
{
  "error": "unavailable",
  "message": "Service temporairement indisponible."
}

En-têtes#

NomTypeDescription
CacheControlstring (= "no-store")Les réponses de l’API ne sont jamais mises en cache.
XContentTypeOptionsstring (= "nosniff")
ReferrerPolicystring (= "no-referrer")
LocationstringChemin de suivi de la ressource, relatif à l’origine (ex. /api/v1/runs/<runId>).
IdempotentReplayedstring (true, false)true quand la réponse enregistrée d’une requête identique est rejouée, false pour une première exécution.
RetryAfterinteger (1 à 60)Secondes à attendre avant la fin de la fenêtre d’une minute.
WWWAuthenticatestring (= "Bearer realm=\"101maintain\"")Toujours Bearer realm="101maintain".

Schémas#

Error#

Corps de toute réponse d’erreur. Aucun secret ni détail interne n’y figure.

ChampTypeRequisDescription
errorstring (unauthenticated, forbidden, not_found, conflict, invalid_request, rate_limited, unavailable)ouiCode stable, lié au statut HTTP : 401 unauthenticated, 403 forbidden, 404 not_found, 409 conflict, 422 invalid_request, 429 rate_limited, 503 unavailable.
messagestringouiMessage en français destiné à une personne. Peut changer : ne pas l’analyser.
reasonstring (repository_audits_disabled, repository_stopped, repository_not_bound)nonPrérequis manquant pour lancer un audit ; message nomme alors la variable ou le réglage à changer.

RunConflict#

Erreur 409 d’une demande d’exécution, avec l’exécution existante quand la clé peut la lire.

ChampTypeRequisDescription
errorstring (unauthenticated, forbidden, not_found, conflict, invalid_request, rate_limited, unavailable)ouiCode stable, lié au statut HTTP : 401 unauthenticated, 403 forbidden, 404 not_found, 409 conflict, 422 invalid_request, 429 rate_limited, 503 unavailable.
messagestringouiMessage en français destiné à une personne. Peut changer : ne pas l’analyser.
reasonstring (repository_audits_disabled, repository_stopped, repository_not_bound)nonPrérequis manquant pour lancer un audit ; message nomme alors la variable ou le réglage à changer.
existingRunobjectnonDernière tentative de l’issue. Présent seulement si la clé détient aussi runs:read.
existingRun.idstring (uuid)ouiIdentifiant de l’exécution existante.
existingRun.statusRunStatusoui
existingRun.linksobjectoui
existingRun.links.selfstringouiChemin /api/v1/runs/<runId>.
ChampTypeRequisDescription
selfstringouiChemin de la ressource.

Next#

Curseur de la page suivante, à passer dans after ; null en fin de liste.

Type : string ou null.

Project#

ChampTypeRequisDescription
idstring (uuid)ouiIdentifiant du projet.
slugstringouiIdentifiant court du projet.
namestringouiNom du projet.

ProjectPage#

ChampTypeRequisDescription
projectsarray<Project>oui
nextNextoui

Repository#

ChampTypeRequisDescription
idstring (uuid)ouiIdentifiant du dépôt dans 101Maintain.
fullNamestringouiNom GitHub organisation/dépôt.
defaultBranchstringouiBranche de base déclarée.
enabledbooleanoui« Autoriser les travaux sur ce dépôt » : false si le dépôt est arrêté.

RepositoryPage#

ChampTypeRequisDescription
repositoriesarray<Repository>oui
nextNextoui

RunStatus#

État d’une exécution :

  • queued : demandée, pas encore prise par le worker ;
  • running : en cours ;
  • prepared : changement préparé (PR brouillon possible selon la politique) ;
  • needs_input : précisions requises ;
  • refused : refusée par une garde (revue, budget, contexte, arrêt global…) ;
  • failed : échec technique ;
  • unknown : issue incertaine (effet non confirmé) ;
  • canceled : annulée.

Type : string (queued, running, prepared, needs_input, refused, failed, unknown, canceled).

RunRequest#

ChampTypeRequisDescription
repositoryIdstring (uuid)ouiDépôt du projet, actif, rattaché et sous surveillance.
issueNumberinteger (1 à …)ouiNuméro de l’issue GitHub, déjà reçue par le webhook. Doit être un entier JSON (pas une chaîne).

RunSummary#

ChampTypeRequisDescription
idstring (uuid)ouiIdentifiant de l’exécution.
statusRunStatusoui
repositoryIdstring (uuid)ouiDépôt de l’issue.
issueNumberintegerouiNuméro de l’issue GitHub.
startedAtstring ou null (date-time)ouiDébut, null tant que l’exécution n’a pas démarré.
finishedAtstring ou null (date-time)ouiFin, null tant qu’elle n’est pas terminée.
linksSelfLinkoui

RunPage#

ChampTypeRequisDescription
runsarray<RunSummary>oui
nextNextoui

RunAccepted#

ChampTypeRequisDescription
idstring (uuid)ouiIdentifiant de l’exécution créée.
statusstring (= "queued")ouiToujours queued à la création.
waitingstring (= "organization_stop")nonPrésent seulement si le travail attend la levée de l’arrêt global de l’organisation. Il démarre alors une seule fois, avec ses budgets et son idempotence.
repositoryIdstring (uuid)ouiDépôt demandé.
issueNumberintegerouiIssue demandée.
linksSelfLinkoui

RunResult#

Résultat sans contenu de fichier. Les champs présents dépendent de status.

ChampTypeRequisDescription
statusstring (prepared, needs_input, refused, canceled)ouiNature du résultat.
reasonstring (review, invalid, context, budget, stale, global_stop)nonMotif d’un refus : revue défavorable, sortie invalide, contexte insuffisant, budget, issue modifiée entre-temps, arrêt global.
summarystringnonRésumé du changement préparé.
questionsarray<string>nonQuestions posées quand des précisions sont requises.
changedFilesarray<string>nonChemins des fichiers modifiés (8 au plus), sans leur contenu.
testsExecutedboolean (= false)nonToujours false : les tests du dépôt ne sont pas exécutés par la plateforme.

RunStep#

ChampTypeRequisDescription
sequenceinteger (1 à …)ouiRang de l’étape.
rolestring (explorer, analyst, designer, developer, reviewer)ouiAgent : Exploration, Analyse, Conception, Développement, Revue.
statusstring (running, succeeded, refused, unknown)ouiÉtat de l’étape.
reusedbooleanouitrue si le résultat d’une tentative précédente est réutilisé (aucun jeton facturé).

BudgetEnvelope#

Enveloppe de jetons.

ChampTypeRequisDescription
limitintegerouiPlafond de jetons.
usedintegerouiJetons consommés connus.
heldintegerouiJetons réservés pour des appels sans consommation connue.
unknownintegerouiNombre d’appels à consommation inconnue.
remaininginteger ou nullouiJetons restants ; null dès qu’une consommation est inconnue.
warningbooleanouitrue à partir de 80 % du plafond engagé, ou si une consommation est inconnue.

RunBudgets#

Budgets de l’exécution et de l’issue ; null tant que l’exécution n’a pas démarré.

ChampTypeRequisDescription
runBudgetEnvelope ou nullnonPlafond par exécution, null si aucun.
issueBudgetEnvelope ou nullnonBudget cumulé de l’issue, null si aucun.

Publication#

Publication GitHub de l’exécution ; null si aucune.

ChampTypeRequisDescription
statusstring (pending, draft, unknown, published, blocked)ouiÉtat de la publication.
pullNumberinteger ou nullouiNuméro de la PR brouillon, null tant qu’elle n’est pas confirmée.

Run#

Détail d’une exécution, sans contenu de fichier.

ChampTypeRequisDescription
idstring (uuid)ouiIdentifiant de l’exécution.
projectIdstring (uuid)ouiProjet.
statusRunStatusoui
waitingstring (= "organization_stop")nonPrésent seulement si le travail attend la levée de l’arrêt global de l’organisation. Il démarre alors une seule fois, avec ses budgets et son idempotence.
repositoryobjectoui
repository.idstring (uuid)ouiDépôt.
repository.fullNamestringouiorganisation/dépôt.
issueobjectoui
issue.numberintegerouiNuméro de l’issue.
issue.openbooleanouiIssue ouverte sur GitHub au dernier événement reçu.
requestedByobject ou nullouiDemandeur ; null pour une exécution démarrée par le webhook GitHub.
requestedBy.userIdstring (uuid)ouiCompte demandeur (propriétaire de la clé le cas échéant).
requestedBy.apiKeyIdstring ou null (uuid)ouiClé utilisée ; null pour une demande depuis l’interface.
parentRunIdstring ou null (uuid)ouiTentative précédente pour une reprise, sinon null.
startedAtstring ou null (date-time)ouiDébut.
finishedAtstring ou null (date-time)ouiFin.
archivedAtstring ou null (date-time)ouiArchivage dans l’interface.
resultRunResult ou nullouiRésultat ; null tant qu’aucun n’est enregistré.
stepsarray<RunStep>ouiÉtapes des agents.
budgetsRunBudgetsoui
publicationPublicationoui
nextAttemptobject ou nullouiReprise demandée après cette tentative, sinon null.
nextAttempt.idstring (uuid)ouiIdentifiant de la reprise (lisible sur /api/v1/runs/{id}).
nextAttempt.statestring (pending, canceled)ouiÉtat de la demande de reprise.
linksobjectoui
links.selfstringoui
links.cancelstringouiRoute d’annulation.
links.usagestringouiConsommation du projet.

CancelAccepted#

ChampTypeRequisDescription
idstring (uuid)ouiExécution.
cancelRequestedboolean (= true)oui
statusRunStatusouiStatut observé au moment de la demande (avant prise en compte de l’annulation).
inFlightstring ou nullouiAvertissement quand un appel au modèle est en cours, sinon null.
linksSelfLinkoui

AuditRequest#

ChampTypeRequisDescription
repositoryIdstring (uuid)ouiDépôt du projet, actif et rattaché à la GitHub App.
checksarray<string (secrets, accessibility, dependencies)>nonFacultatif. S’il est fourni, il doit contenir exactement les trois contrôles statiques (ordre libre).

AuditStatus#

État d’un audit : queued, running, complete (tous contrôles complets), partial (couverture partielle), refused, failed, unknown.

Type : string (queued, running, complete, partial, refused, failed, unknown).

AuditSummary#

ChampTypeRequisDescription
idstring (uuid)ouiIdentifiant de l’audit.
statusAuditStatusoui
repositorystringouiorganisation/dépôt.
createdAtstring (date-time)ouiDate de la demande.
linksSelfLinkoui

AuditPage#

ChampTypeRequisDescription
auditsarray<AuditSummary>oui
nextNextoui

AuditAccepted#

ChampTypeRequisDescription
idstring (uuid)ouiAudit créé, ou audit déjà en file ou en cours pour ce dépôt.
statusstring (= "queued")oui
waitingstring (= "organization_stop")nonPrésent seulement si le travail attend la levée de l’arrêt global de l’organisation. Il démarre alors une seule fois, avec ses budgets et son idempotence.
repositoryIdstring (uuid)ouiDépôt demandé.
checksarray<string (accessibility, dependencies, secrets)>ouiToujours les trois contrôles statiques.
linksSelfLinkoui

AuditCheck#

ChampTypeRequisDescription
idstring (secrets, accessibility, dependencies)oui
statestring (complete, partial, unavailable)ouiCouverture du contrôle.
durationMsintegerouiDurée en millisecondes.
inspectedintegerouiÉléments inspectés.
skippedintegerouiÉléments ignorés.

AuditFinding#

ChampTypeRequisDescription
idstring (uuid)ouiIdentifiant du constat.
rulestringouiRègle. Contrôles statiques : possible_secret, sensitive_file, image_alt, page_language, missing_npm_lock, dependency_alert. Les contrôles dynamiques ajoutent leurs propres règles.
locationstring ou nullouiChemin du fichier concerné.
lineinteger ou nullouiLigne, si connue.
statusstring (pending, accepted, rejected)ouiQualification : à qualifier, validé, rejeté.
issueobject ou nullouiIssue GitHub ouverte depuis le constat, sinon null.
issue.numberintegeroui
issue.statusstring (queued, attempted, confirmed, blocked, public_hold)oui

AuditBase#

ChampTypeRequisDescription
idstring (uuid)ouiIdentifiant de l’audit.
projectIdstring (uuid)ouiProjet.
statusAuditStatusoui
waitingstring (= "organization_stop")nonPrésent seulement si le travail attend la levée de l’arrêt global de l’organisation. Il démarre alors une seule fois, avec ses budgets et son idempotence.
repositorystringouiorganisation/dépôt.
baseShastring ou nullouiCommit audité.
checksarray<AuditCheck>oui
finishedAtstring ou null (date-time)ouiFin de l’audit.
findingsarray<AuditFinding>oui

Audit#

ChampTypeRequisDescription
idstring (uuid)ouiIdentifiant de l’audit.
projectIdstring (uuid)ouiProjet.
statusAuditStatusoui
waitingstring (= "organization_stop")nonPrésent seulement si le travail attend la levée de l’arrêt global de l’organisation. Il démarre alors une seule fois, avec ses budgets et son idempotence.
repositorystringouiorganisation/dépôt.
baseShastring ou nullouiCommit audité.
checksarray<AuditCheck>oui
finishedAtstring ou null (date-time)ouiFin de l’audit.
findingsarray<AuditFinding>oui
pendingQualificationintegerouiConstats à qualifier.
reportAvailablebooleanouiRapport final lisible.
linksobjectoui
links.selfstringoui
links.reportstringoui

AuditReport#

Rapport final : constats acceptés uniquement.

ChampTypeRequisDescription
idstring (uuid)ouiIdentifiant de l’audit.
projectIdstring (uuid)ouiProjet.
statusAuditStatusoui
waitingstring (= "organization_stop")nonPrésent seulement si le travail attend la levée de l’arrêt global de l’organisation. Il démarre alors une seule fois, avec ses budgets et son idempotence.
repositorystringouiorganisation/dépôt.
baseShastring ou nullouiCommit audité.
checksarray<AuditCheck>oui
finishedAtstring ou null (date-time)ouiFin de l’audit.
findingsarray<AuditFinding>oui
reportstring (= "final")oui
linksSelfLinkoui

TokenUsage#

ChampTypeRequisDescription
inputintegerouiJetons d’entrée.
outputintegerouiJetons de sortie.
totalintegerouiTotal.
cachedintegernonJetons d’entrée en cache, si le fournisseur les donne.
reasoningintegernonJetons de raisonnement, si le fournisseur les donne.

RateSnapshot#

Tarif figé au moment de l’appel (prix par jeton, décimaux en chaîne).

ChampTypeRequisDescription
modelstringoui
currencystring (motif ^[A-Z]{3}$)oui
inputstringoui
outputstringoui
cachedInputstringnon
effectiveFromstringouiDate d’effet.
sourcestringouiOrigine du tarif.

UsageEntry#

ChampTypeRequisDescription
runIdstring (uuid)ouiExécution.
sequenceintegerouiÉtape.
rolestringouiAgent de l’étape.
modelstringouiModèle appelé.
kindstring (live, evaluation)oui
repositoryIdstring (uuid)ouiDépôt.
issueNumberinteger ou nullouiIssue ; null pour le banc d’essai.
pullNumberinteger ou nullouiPR brouillon rattachée.
statestring (reserved, known, unknown)ouiRéservation en cours, consommation connue, consommation inconnue.
rateRateSnapshot ou nulloui
usageTokenUsage ou nulloui
coststring ou nullouiCoût décimal (12 décimales) dans la devise du tarif ; null si inconnu.
reservedTokensinteger ou nullouiJetons réservés avant l’appel.
heldTokensinteger ou nullouiJetons encore retenus : 0 si la consommation est connue.
startedAtstring (date-time)ouiDébut de l’appel.

UsageCounters#

Compteurs sur la période et les filtres, en chaînes décimales entières.

ChampTypeRequisDescription
callsstring (motif ^\d+$)ouiAppels au modèle.
unknownstring (motif ^\d+$)ouiAppels à consommation inconnue.
pendingstring (motif ^\d+$)ouiAppels encore en réservation.
unknown_costsstring (motif ^\d+$)ouiAppels terminés sans coût connu.
unknown_cachedstring (motif ^\d+$)ouiAppels connus sans information de cache.
unknown_reasoningstring (motif ^\d+$)ouiAppels connus sans information de raisonnement.
heldstring (motif ^\d+$)ouiJetons retenus pour les appels non connus.
inputstring (motif ^\d+$)ouiJetons d’entrée connus.
outputstring (motif ^\d+$)ouiJetons de sortie connus.
cachedstring (motif ^\d+$)ouiJetons en cache connus.
reasoningstring (motif ^\d+$)ouiJetons de raisonnement connus.
totalstring (motif ^\d+$)ouiTotal de jetons connus.

UsageReport#

ChampTypeRequisDescription
kindstring (live, evaluation)oui
periodobjectoui
period.fromstring (date-time)ouiDébut inclus.
period.tostring (date-time)ouiFin exclue.
countersUsageCountersoui
knownCostsarray<object>ouiSomme des coûts connus par devise.
knownCosts[].currencystringoui
knownCosts[].amountstringouiMontant décimal (12 décimales).
entriesarray<UsageEntry>oui
nextstring ou nullouiCurseur opaque de la page suivante, à passer dans after.

Actions non exposées#

Extension x-not-exposed : actions volontairement absentes de l’API, réservées aux personnes dans l’interface.

ActionMotif
POST /api/v1/runs/{runId}/reportRefusé : la demande d’édition de rapport est réservée aux personnes. Une édition demandée dans l’interface est ensuite lisible par clé.
Qualification des constatsValider ou rejeter un constat se fait dans l’interface uniquement.
Réponse, reprise, archivage, publicationRépondre aux questions, reprendre, refaire le code, archiver ou publier une exécution : interface (ou commande /answer sur la PR pour répondre).
Contrôles dynamiquesLes contrôles sur la recette exigent un accord humain enregistré ; ils ne sont pas déclenchables ni lisibles par clé.
AdministrationComptes, membres, politiques, intégrations, accords, clés API et arrêt global : aucune route externe.