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.
| Scope | Libellé dans l’interface | Rôle minimal |
|---|---|---|
projects:read | Lire les projets | Lecteur |
repositories:read | Lire les dépôts | Lecteur |
runs:read | Lire les exécutions | Lecteur |
runs:create | Démarrer une exécution | Opérateur |
runs:cancel | Annuler une exécution | Opérateur |
audits:read | Lire les audits | Lecteur |
audits:create | Demander un audit | Opérateur |
reports:read | Lire les rapports | Lecteur |
usage:read | Lire la consommation | Lecteur |
Sommaire des opérations#
| Méthode | Route | Résumé | Scope |
|---|---|---|---|
GET | undefined | Contrat OpenAPI servi par l’instance | public |
GET | undefined | Lister les projets de la clé encore accessibles au propriétaire | projects:read |
GET | undefined | Lister les dépôts d’un projet | repositories:read |
GET | undefined | Lister les exécutions d’un projet | runs:read |
POST | undefined | Demander une exécution sur une issue déjà suivie | runs:create |
GET | undefined | Lire l’état d’une exécution | runs:read |
POST | undefined | Demander l’arrêt d’une exécution (idempotent) | runs:cancel |
GET | undefined | Télécharger le rapport d’incident (PDF) d’une exécution | reports:read |
GET | undefined | Lister les audits d’un projet | audits:read |
POST | undefined | Demander un audit statique d’un dépôt | audits:create |
GET | undefined | Lire les contrôles et constats d’un audit | audits:read |
GET | undefined | Lire le rapport final d’un audit (constats acceptés) | reports:read |
GET | undefined | Lire les agrégats et entrées de consommation d’un projet | usage: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#
| Code | Description | Corps | En-têtes |
|---|---|---|---|
200 | Document OpenAPI 3.1 (JSON). | application/json object | Cache-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#
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
after | requête | string (uuid) | non | Curseur : identifiant du dernier élément de la page précédente (valeur next). Absent : première page. |
Réponses#
| Code | Description | Corps | En-têtes |
|---|---|---|---|
200 | Page de projets. | application/json ProjectPage | Cache-Control, X-Content-Type-Options, Referrer-Policy |
401 | 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é. (Unauthenticated) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy, WWW-Authenticate |
403 | Scope requis absent de la clé, ou rôle actuel du propriétaire insuffisant sur une ressource visible. (Forbidden) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
404 | 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"}. (NotFound) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
422 | 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. (InvalidRequest) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
429 | 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. (RateLimited) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy, Retry-After |
503 | Service ou capacité temporairement indisponible. Réessayer plus tard. (Unavailable) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
Exemple de réponse 200 :
{
"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#
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
projectId | chemin | string (uuid) | oui | Identifiant du projet (UUID). Valeur mal formée : 422 (après authentification). |
after | requête | string (uuid) | non | Curseur : identifiant du dernier élément de la page précédente (valeur next). Absent : première page. |
limit | requête | integer (1 à 50 ; défaut 50) | non | Taille de page, de 1 à 50 (défaut 50). Hors bornes : 422. |
Réponses#
| Code | Description | Corps | En-têtes |
|---|---|---|---|
200 | Page de dépôts. | application/json RepositoryPage | Cache-Control, X-Content-Type-Options, Referrer-Policy |
401 | 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é. (Unauthenticated) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy, WWW-Authenticate |
403 | Scope requis absent de la clé, ou rôle actuel du propriétaire insuffisant sur une ressource visible. (Forbidden) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
404 | 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"}. (NotFound) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
422 | 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. (InvalidRequest) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
429 | 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. (RateLimited) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy, Retry-After |
503 | Service ou capacité temporairement indisponible. Réessayer plus tard. (Unavailable) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
Exemple de réponse 200 :
{
"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#
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
projectId | chemin | string (uuid) | oui | Identifiant du projet (UUID). Valeur mal formée : 422 (après authentification). |
after | requête | string (uuid) | non | Curseur : identifiant du dernier élément de la page précédente (valeur next). Absent : première page. |
limit | requête | integer (1 à 50 ; défaut 50) | non | Taille de page, de 1 à 50 (défaut 50). Hors bornes : 422. |
Réponses#
| Code | Description | Corps | En-têtes |
|---|---|---|---|
200 | Page d’exécutions. | application/json RunPage | Cache-Control, X-Content-Type-Options, Referrer-Policy |
401 | 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é. (Unauthenticated) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy, WWW-Authenticate |
403 | Scope requis absent de la clé, ou rôle actuel du propriétaire insuffisant sur une ressource visible. (Forbidden) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
404 | 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"}. (NotFound) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
422 | 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. (InvalidRequest) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
429 | 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. (RateLimited) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy, Retry-After |
503 | Service ou capacité temporairement indisponible. Réessayer plus tard. (Unavailable) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
Exemple de réponse 200 :
{
"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#
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
projectId | chemin | string (uuid) | oui | Identifiant du projet (UUID). Valeur mal formée : 422 (après authentification). |
Idempotency-Key | en-tête | string (8 à 128 car. ; motif ^[\x21-\x7e]{8,128}$) | oui | Obligatoire. 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.
| Champ | Type | Requis | Description |
|---|---|---|---|
repositoryId | string (uuid) | oui | Dépôt du projet, actif, rattaché et sous surveillance. |
issueNumber | integer (1 à …) | oui | Numéro de l’issue GitHub, déjà reçue par le webhook. Doit être un entier JSON (pas une chaîne). |
{
"repositoryId": "5b7e2c90-1d4f-4e6a-8c3b-9f0a1d2e3c46",
"issueNumber": 42
}Réponses#
| Code | Description | Corps | En-têtes |
|---|---|---|---|
202 | Demande acceptée. Suivre la ressource indiquée par Location (et links.self dans le corps). | application/json RunAccepted | Cache-Control, X-Content-Type-Options, Referrer-Policy, Location, Idempotent-Replayed |
401 | 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é. (Unauthenticated) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy, WWW-Authenticate |
403 | Scope requis absent de la clé, ou rôle actuel du propriétaire insuffisant sur une ressource visible. (Forbidden) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
404 | 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"}. (NotFound) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
409 | Conflit : ; 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 RunConflict | Cache-Control, X-Content-Type-Options, Referrer-Policy |
422 | 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. (InvalidRequest) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
429 | 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. (RateLimited) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy, Retry-After |
503 | Service ou capacité temporairement indisponible. Réessayer plus tard. (Unavailable) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
Exemple de réponse 202 :
{
"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é :
{
"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 :
{
"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#
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
runId | chemin | string (uuid) | oui | Identifiant de l’exécution (UUID). |
Réponses#
| Code | Description | Corps | En-têtes |
|---|---|---|---|
200 | Exécution. | application/json Run | Cache-Control, X-Content-Type-Options, Referrer-Policy |
401 | 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é. (Unauthenticated) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy, WWW-Authenticate |
403 | Scope requis absent de la clé, ou rôle actuel du propriétaire insuffisant sur une ressource visible. (Forbidden) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
404 | 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"}. (NotFound) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
422 | 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. (InvalidRequest) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
429 | 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. (RateLimited) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy, Retry-After |
503 | Service ou capacité temporairement indisponible. Réessayer plus tard. (Unavailable) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
Exemple de réponse 200 :
{
"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#
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
runId | chemin | string (uuid) | oui | Identifiant de l’exécution (UUID). |
Réponses#
| Code | Description | Corps | En-têtes |
|---|---|---|---|
202 | Arrêt demandé. Location pointe vers l’exécution ; Idempotent-Replayed n’est pas envoyé sur cette route. | application/json CancelAccepted | Cache-Control, X-Content-Type-Options, Referrer-Policy, Location, Idempotent-Replayed |
401 | 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é. (Unauthenticated) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy, WWW-Authenticate |
403 | Scope requis absent de la clé, ou rôle actuel du propriétaire insuffisant sur une ressource visible. (Forbidden) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
404 | 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"}. (NotFound) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
422 | 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. (InvalidRequest) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
429 | 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. (RateLimited) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy, Retry-After |
503 | Service ou capacité temporairement indisponible. Réessayer plus tard. (Unavailable) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
Exemple de réponse 202 :
{
"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#
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
projectId | chemin | string (uuid) | oui | Identifiant du projet (UUID). Valeur mal formée : 422 (après authentification). |
after | requête | string (uuid) | non | Curseur : identifiant du dernier élément de la page précédente (valeur next). Absent : première page. |
Réponses#
| Code | Description | Corps | En-têtes |
|---|---|---|---|
200 | Page d’audits. | application/json AuditPage | Cache-Control, X-Content-Type-Options, Referrer-Policy |
401 | 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é. (Unauthenticated) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy, WWW-Authenticate |
403 | Scope requis absent de la clé, ou rôle actuel du propriétaire insuffisant sur une ressource visible. (Forbidden) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
404 | 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"}. (NotFound) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
422 | 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. (InvalidRequest) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
429 | 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. (RateLimited) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy, Retry-After |
503 | Service ou capacité temporairement indisponible. Réessayer plus tard. (Unavailable) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
Exemple de réponse 200 :
{
"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#
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
projectId | chemin | string (uuid) | oui | Identifiant du projet (UUID). Valeur mal formée : 422 (après authentification). |
Idempotency-Key | en-tête | string (8 à 128 car. ; motif ^[\x21-\x7e]{8,128}$) | oui | Obligatoire. 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.
| Champ | Type | Requis | Description |
|---|---|---|---|
repositoryId | string (uuid) | oui | Dépôt du projet, actif et rattaché à la GitHub App. |
checks | array<string (secrets, accessibility, dependencies)> | non | Facultatif. S’il est fourni, il doit contenir exactement les trois contrôles statiques (ordre libre). |
{
"repositoryId": "5b7e2c90-1d4f-4e6a-8c3b-9f0a1d2e3c46"
}Réponses#
| Code | Description | Corps | En-têtes |
|---|---|---|---|
202 | Demande acceptée. Suivre la ressource indiquée par Location (et links.self dans le corps). | application/json AuditAccepted | Cache-Control, X-Content-Type-Options, Referrer-Policy, Location, Idempotent-Replayed |
401 | 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é. (Unauthenticated) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy, WWW-Authenticate |
403 | Scope requis absent de la clé, ou rôle actuel du propriétaire insuffisant sur une ressource visible. (Forbidden) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
404 | 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"}. (NotFound) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
409 | Conflit : ; 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 Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
422 | 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. (InvalidRequest) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
429 | 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. (RateLimited) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy, Retry-After |
503 | Audits désactivés sur l’instance (reason: repository_audits_disabled, renvoyé avant toute validation du corps) ou service indisponible. | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
Exemple de réponse 202 :
{
"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é :
{
"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é :
{
"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 :
{
"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#
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
auditId | chemin | string (uuid) | oui | Identifiant de l’audit (UUID). |
Réponses#
| Code | Description | Corps | En-têtes |
|---|---|---|---|
200 | Audit. | application/json Audit | Cache-Control, X-Content-Type-Options, Referrer-Policy |
401 | 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é. (Unauthenticated) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy, WWW-Authenticate |
403 | Scope requis absent de la clé, ou rôle actuel du propriétaire insuffisant sur une ressource visible. (Forbidden) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
404 | 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"}. (NotFound) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
422 | 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. (InvalidRequest) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
429 | 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. (RateLimited) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy, Retry-After |
503 | Service ou capacité temporairement indisponible. Réessayer plus tard. (Unavailable) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
Exemple de réponse 200 :
{
"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#
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
runId | chemin | string (uuid) | oui | Identifiant de l’exécution (UUID). |
Réponses#
| Code | Description | Corps | En-têtes |
|---|---|---|---|
200 | PDF du rapport d’incident. | application/pdf string (binary) | Cache-Control, X-Content-Type-Options, Referrer-Policy, Content-Disposition, X-Report-Edition, X-Report-Sha256 |
401 | 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é. (Unauthenticated) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy, WWW-Authenticate |
403 | Scope requis absent de la clé, ou rôle actuel du propriétaire insuffisant sur une ressource visible. (Forbidden) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
404 | 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"}. (NotFound) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
422 | 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. (InvalidRequest) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
429 | 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. (RateLimited) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy, Retry-After |
503 | Service ou capacité temporairement indisponible. Réessayer plus tard. (Unavailable) | application/json Error | Cache-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#
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
auditId | chemin | string (uuid) | oui | Identifiant de l’audit (UUID). |
Réponses#
| Code | Description | Corps | En-têtes |
|---|---|---|---|
200 | Rapport final. | application/json AuditReport | Cache-Control, X-Content-Type-Options, Referrer-Policy |
401 | 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é. (Unauthenticated) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy, WWW-Authenticate |
403 | Scope requis absent de la clé, ou rôle actuel du propriétaire insuffisant sur une ressource visible. (Forbidden) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
404 | 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"}. (NotFound) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
409 | Audit non terminé, constats encore à qualifier ou contrôle dynamique en cours. | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
422 | 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. (InvalidRequest) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
429 | 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. (RateLimited) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy, Retry-After |
503 | Service ou capacité temporairement indisponible. Réessayer plus tard. (Unavailable) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
Exemple de réponse 200 :
{
"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 :
{
"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#
| Nom | Emplacement | Type | Requis | Description |
|---|---|---|---|---|
projectId | chemin | string (uuid) | oui | Identifiant du projet (UUID). Valeur mal formée : 422 (après authentification). |
from | requête | string (date-time) | non | Début inclus, en UTC au format AAAA-MM-JJTHH:MM:SS[.mmm]Z. Par défaut : to moins 30 jours. |
to | requête | string (date-time) | non | Fin exclue, même format. Par défaut : maintenant. from doit précéder to et l’écart ne pas dépasser 366 jours. |
kind | requête | string (live, evaluation ; défaut "live") | non | live : exécutions de maintenance (défaut). evaluation : exécutions du banc d’essai. |
repository | requête | string (uuid) | non | Limiter à un dépôt du projet (404 si le dépôt n’appartient pas au projet). |
model | requête | string (motif ^[a-zA-Z0-9_.:/-]{1,150}$) | non | Limiter à un identifiant de modèle. |
pull | requête | integer (1 à …) | non | Limiter aux exécutions rattachées à ce numéro de PR brouillon. |
after | requête | string (motif ^\d{1,15}\.[a-f0-9-]{36}\.\d{1,2}$) | non | Curseur opaque : valeur next de la page précédente. |
Réponses#
| Code | Description | Corps | En-têtes |
|---|---|---|---|
200 | Compteurs, coûts connus et entrées. | application/json UsageReport | Cache-Control, X-Content-Type-Options, Referrer-Policy |
401 | 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é. (Unauthenticated) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy, WWW-Authenticate |
403 | Scope requis absent de la clé, ou rôle actuel du propriétaire insuffisant sur une ressource visible. (Forbidden) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
404 | 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"}. (NotFound) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
422 | 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. (InvalidRequest) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
429 | 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. (RateLimited) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy, Retry-After |
503 | Service ou capacité temporairement indisponible. Réessayer plus tard. (Unavailable) | application/json Error | Cache-Control, X-Content-Type-Options, Referrer-Policy |
Exemple de réponse 200 :
{
"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.
{
"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.
{
"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.
{
"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.
{
"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.
{
"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.
{
"error": "unavailable",
"message": "Service temporairement indisponible."
}En-têtes#
| Nom | Type | Description |
|---|---|---|
CacheControl | string (= "no-store") | Les réponses de l’API ne sont jamais mises en cache. |
XContentTypeOptions | string (= "nosniff") | |
ReferrerPolicy | string (= "no-referrer") | |
Location | string | Chemin de suivi de la ressource, relatif à l’origine (ex. /api/v1/runs/<runId>). |
IdempotentReplayed | string (true, false) | true quand la réponse enregistrée d’une requête identique est rejouée, false pour une première exécution. |
RetryAfter | integer (1 à 60) | Secondes à attendre avant la fin de la fenêtre d’une minute. |
WWWAuthenticate | string (= "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.
| Champ | Type | Requis | Description |
|---|---|---|---|
error | string (unauthenticated, forbidden, not_found, conflict, invalid_request, rate_limited, unavailable) | oui | Code stable, lié au statut HTTP : 401 unauthenticated, 403 forbidden, 404 not_found, 409 conflict, 422 invalid_request, 429 rate_limited, 503 unavailable. |
message | string | oui | Message en français destiné à une personne. Peut changer : ne pas l’analyser. |
reason | string (repository_audits_disabled, repository_stopped, repository_not_bound) | non | Pré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.
| Champ | Type | Requis | Description |
|---|---|---|---|
error | string (unauthenticated, forbidden, not_found, conflict, invalid_request, rate_limited, unavailable) | oui | Code stable, lié au statut HTTP : 401 unauthenticated, 403 forbidden, 404 not_found, 409 conflict, 422 invalid_request, 429 rate_limited, 503 unavailable. |
message | string | oui | Message en français destiné à une personne. Peut changer : ne pas l’analyser. |
reason | string (repository_audits_disabled, repository_stopped, repository_not_bound) | non | Prérequis manquant pour lancer un audit ; message nomme alors la variable ou le réglage à changer. |
existingRun | object | non | Dernière tentative de l’issue. Présent seulement si la clé détient aussi runs:read. |
existingRun.id | string (uuid) | oui | Identifiant de l’exécution existante. |
existingRun.status | RunStatus | oui | |
existingRun.links | object | oui | |
existingRun.links.self | string | oui | Chemin /api/v1/runs/<runId>. |
SelfLink#
| Champ | Type | Requis | Description |
|---|---|---|---|
self | string | oui | Chemin de la ressource. |
Next#
Curseur de la page suivante, à passer dans after ; null en fin de liste.
Type : string ou null.
Project#
| Champ | Type | Requis | Description |
|---|---|---|---|
id | string (uuid) | oui | Identifiant du projet. |
slug | string | oui | Identifiant court du projet. |
name | string | oui | Nom du projet. |
ProjectPage#
Repository#
| Champ | Type | Requis | Description |
|---|---|---|---|
id | string (uuid) | oui | Identifiant du dépôt dans 101Maintain. |
fullName | string | oui | Nom GitHub organisation/dépôt. |
defaultBranch | string | oui | Branche de base déclarée. |
enabled | boolean | oui | « Autoriser les travaux sur ce dépôt » : false si le dépôt est arrêté. |
RepositoryPage#
| Champ | Type | Requis | Description |
|---|---|---|---|
repositories | array<Repository> | oui | |
next | Next | oui |
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#
| Champ | Type | Requis | Description |
|---|---|---|---|
repositoryId | string (uuid) | oui | Dépôt du projet, actif, rattaché et sous surveillance. |
issueNumber | integer (1 à …) | oui | Numéro de l’issue GitHub, déjà reçue par le webhook. Doit être un entier JSON (pas une chaîne). |
RunSummary#
| Champ | Type | Requis | Description |
|---|---|---|---|
id | string (uuid) | oui | Identifiant de l’exécution. |
status | RunStatus | oui | |
repositoryId | string (uuid) | oui | Dépôt de l’issue. |
issueNumber | integer | oui | Numéro de l’issue GitHub. |
startedAt | string ou null (date-time) | oui | Début, null tant que l’exécution n’a pas démarré. |
finishedAt | string ou null (date-time) | oui | Fin, null tant qu’elle n’est pas terminée. |
links | SelfLink | oui |
RunPage#
| Champ | Type | Requis | Description |
|---|---|---|---|
runs | array<RunSummary> | oui | |
next | Next | oui |
RunAccepted#
| Champ | Type | Requis | Description |
|---|---|---|---|
id | string (uuid) | oui | Identifiant de l’exécution créée. |
status | string (= "queued") | oui | Toujours queued à la création. |
waiting | string (= "organization_stop") | non | Pré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. |
repositoryId | string (uuid) | oui | Dépôt demandé. |
issueNumber | integer | oui | Issue demandée. |
links | SelfLink | oui |
RunResult#
Résultat sans contenu de fichier. Les champs présents dépendent de status.
| Champ | Type | Requis | Description |
|---|---|---|---|
status | string (prepared, needs_input, refused, canceled) | oui | Nature du résultat. |
reason | string (review, invalid, context, budget, stale, global_stop) | non | Motif d’un refus : revue défavorable, sortie invalide, contexte insuffisant, budget, issue modifiée entre-temps, arrêt global. |
summary | string | non | Résumé du changement préparé. |
questions | array<string> | non | Questions posées quand des précisions sont requises. |
changedFiles | array<string> | non | Chemins des fichiers modifiés (8 au plus), sans leur contenu. |
testsExecuted | boolean (= false) | non | Toujours false : les tests du dépôt ne sont pas exécutés par la plateforme. |
RunStep#
| Champ | Type | Requis | Description |
|---|---|---|---|
sequence | integer (1 à …) | oui | Rang de l’étape. |
role | string (explorer, analyst, designer, developer, reviewer) | oui | Agent : Exploration, Analyse, Conception, Développement, Revue. |
status | string (running, succeeded, refused, unknown) | oui | État de l’étape. |
reused | boolean | oui | true si le résultat d’une tentative précédente est réutilisé (aucun jeton facturé). |
BudgetEnvelope#
Enveloppe de jetons.
| Champ | Type | Requis | Description |
|---|---|---|---|
limit | integer | oui | Plafond de jetons. |
used | integer | oui | Jetons consommés connus. |
held | integer | oui | Jetons réservés pour des appels sans consommation connue. |
unknown | integer | oui | Nombre d’appels à consommation inconnue. |
remaining | integer ou null | oui | Jetons restants ; null dès qu’une consommation est inconnue. |
warning | boolean | oui | true à 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é.
| Champ | Type | Requis | Description |
|---|---|---|---|
run | BudgetEnvelope ou null | non | Plafond par exécution, null si aucun. |
issue | BudgetEnvelope ou null | non | Budget cumulé de l’issue, null si aucun. |
Publication#
Publication GitHub de l’exécution ; null si aucune.
| Champ | Type | Requis | Description |
|---|---|---|---|
status | string (pending, draft, unknown, published, blocked) | oui | État de la publication. |
pullNumber | integer ou null | oui | Numé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.
| Champ | Type | Requis | Description |
|---|---|---|---|
id | string (uuid) | oui | Identifiant de l’exécution. |
projectId | string (uuid) | oui | Projet. |
status | RunStatus | oui | |
waiting | string (= "organization_stop") | non | Pré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. |
repository | object | oui | |
repository.id | string (uuid) | oui | Dépôt. |
repository.fullName | string | oui | organisation/dépôt. |
issue | object | oui | |
issue.number | integer | oui | Numéro de l’issue. |
issue.open | boolean | oui | Issue ouverte sur GitHub au dernier événement reçu. |
requestedBy | object ou null | oui | Demandeur ; null pour une exécution démarrée par le webhook GitHub. |
requestedBy.userId | string (uuid) | oui | Compte demandeur (propriétaire de la clé le cas échéant). |
requestedBy.apiKeyId | string ou null (uuid) | oui | Clé utilisée ; null pour une demande depuis l’interface. |
parentRunId | string ou null (uuid) | oui | Tentative précédente pour une reprise, sinon null. |
startedAt | string ou null (date-time) | oui | Début. |
finishedAt | string ou null (date-time) | oui | Fin. |
archivedAt | string ou null (date-time) | oui | Archivage dans l’interface. |
result | RunResult ou null | oui | Résultat ; null tant qu’aucun n’est enregistré. |
steps | array<RunStep> | oui | Étapes des agents. |
budgets | RunBudgets | oui | |
publication | Publication | oui | |
nextAttempt | object ou null | oui | Reprise demandée après cette tentative, sinon null. |
nextAttempt.id | string (uuid) | oui | Identifiant de la reprise (lisible sur /api/v1/runs/{id}). |
nextAttempt.state | string (pending, canceled) | oui | État de la demande de reprise. |
links | object | oui | |
links.self | string | oui | |
links.cancel | string | oui | Route d’annulation. |
links.usage | string | oui | Consommation du projet. |
CancelAccepted#
| Champ | Type | Requis | Description |
|---|---|---|---|
id | string (uuid) | oui | Exécution. |
cancelRequested | boolean (= true) | oui | |
status | RunStatus | oui | Statut observé au moment de la demande (avant prise en compte de l’annulation). |
inFlight | string ou null | oui | Avertissement quand un appel au modèle est en cours, sinon null. |
links | SelfLink | oui |
AuditRequest#
| Champ | Type | Requis | Description |
|---|---|---|---|
repositoryId | string (uuid) | oui | Dépôt du projet, actif et rattaché à la GitHub App. |
checks | array<string (secrets, accessibility, dependencies)> | non | Facultatif. 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#
| Champ | Type | Requis | Description |
|---|---|---|---|
id | string (uuid) | oui | Identifiant de l’audit. |
status | AuditStatus | oui | |
repository | string | oui | organisation/dépôt. |
createdAt | string (date-time) | oui | Date de la demande. |
links | SelfLink | oui |
AuditPage#
| Champ | Type | Requis | Description |
|---|---|---|---|
audits | array<AuditSummary> | oui | |
next | Next | oui |
AuditAccepted#
| Champ | Type | Requis | Description |
|---|---|---|---|
id | string (uuid) | oui | Audit créé, ou audit déjà en file ou en cours pour ce dépôt. |
status | string (= "queued") | oui | |
waiting | string (= "organization_stop") | non | Pré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. |
repositoryId | string (uuid) | oui | Dépôt demandé. |
checks | array<string (accessibility, dependencies, secrets)> | oui | Toujours les trois contrôles statiques. |
links | SelfLink | oui |
AuditCheck#
| Champ | Type | Requis | Description |
|---|---|---|---|
id | string (secrets, accessibility, dependencies) | oui | |
state | string (complete, partial, unavailable) | oui | Couverture du contrôle. |
durationMs | integer | oui | Durée en millisecondes. |
inspected | integer | oui | Éléments inspectés. |
skipped | integer | oui | Éléments ignorés. |
AuditFinding#
| Champ | Type | Requis | Description |
|---|---|---|---|
id | string (uuid) | oui | Identifiant du constat. |
rule | string | oui | Rè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. |
location | string ou null | oui | Chemin du fichier concerné. |
line | integer ou null | oui | Ligne, si connue. |
status | string (pending, accepted, rejected) | oui | Qualification : à qualifier, validé, rejeté. |
issue | object ou null | oui | Issue GitHub ouverte depuis le constat, sinon null. |
issue.number | integer | oui | |
issue.status | string (queued, attempted, confirmed, blocked, public_hold) | oui |
AuditBase#
| Champ | Type | Requis | Description |
|---|---|---|---|
id | string (uuid) | oui | Identifiant de l’audit. |
projectId | string (uuid) | oui | Projet. |
status | AuditStatus | oui | |
waiting | string (= "organization_stop") | non | Pré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. |
repository | string | oui | organisation/dépôt. |
baseSha | string ou null | oui | Commit audité. |
checks | array<AuditCheck> | oui | |
finishedAt | string ou null (date-time) | oui | Fin de l’audit. |
findings | array<AuditFinding> | oui |
Audit#
| Champ | Type | Requis | Description |
|---|---|---|---|
id | string (uuid) | oui | Identifiant de l’audit. |
projectId | string (uuid) | oui | Projet. |
status | AuditStatus | oui | |
waiting | string (= "organization_stop") | non | Pré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. |
repository | string | oui | organisation/dépôt. |
baseSha | string ou null | oui | Commit audité. |
checks | array<AuditCheck> | oui | |
finishedAt | string ou null (date-time) | oui | Fin de l’audit. |
findings | array<AuditFinding> | oui | |
pendingQualification | integer | oui | Constats à qualifier. |
reportAvailable | boolean | oui | Rapport final lisible. |
links | object | oui | |
links.self | string | oui | |
links.report | string | oui |
AuditReport#
Rapport final : constats acceptés uniquement.
| Champ | Type | Requis | Description |
|---|---|---|---|
id | string (uuid) | oui | Identifiant de l’audit. |
projectId | string (uuid) | oui | Projet. |
status | AuditStatus | oui | |
waiting | string (= "organization_stop") | non | Pré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. |
repository | string | oui | organisation/dépôt. |
baseSha | string ou null | oui | Commit audité. |
checks | array<AuditCheck> | oui | |
finishedAt | string ou null (date-time) | oui | Fin de l’audit. |
findings | array<AuditFinding> | oui | |
report | string (= "final") | oui | |
links | SelfLink | oui |
TokenUsage#
| Champ | Type | Requis | Description |
|---|---|---|---|
input | integer | oui | Jetons d’entrée. |
output | integer | oui | Jetons de sortie. |
total | integer | oui | Total. |
cached | integer | non | Jetons d’entrée en cache, si le fournisseur les donne. |
reasoning | integer | non | Jetons de raisonnement, si le fournisseur les donne. |
RateSnapshot#
Tarif figé au moment de l’appel (prix par jeton, décimaux en chaîne).
| Champ | Type | Requis | Description |
|---|---|---|---|
model | string | oui | |
currency | string (motif ^[A-Z]{3}$) | oui | |
input | string | oui | |
output | string | oui | |
cachedInput | string | non | |
effectiveFrom | string | oui | Date d’effet. |
source | string | oui | Origine du tarif. |
UsageEntry#
| Champ | Type | Requis | Description |
|---|---|---|---|
runId | string (uuid) | oui | Exécution. |
sequence | integer | oui | Étape. |
role | string | oui | Agent de l’étape. |
model | string | oui | Modèle appelé. |
kind | string (live, evaluation) | oui | |
repositoryId | string (uuid) | oui | Dépôt. |
issueNumber | integer ou null | oui | Issue ; null pour le banc d’essai. |
pullNumber | integer ou null | oui | PR brouillon rattachée. |
state | string (reserved, known, unknown) | oui | Réservation en cours, consommation connue, consommation inconnue. |
rate | RateSnapshot ou null | oui | |
usage | TokenUsage ou null | oui | |
cost | string ou null | oui | Coût décimal (12 décimales) dans la devise du tarif ; null si inconnu. |
reservedTokens | integer ou null | oui | Jetons réservés avant l’appel. |
heldTokens | integer ou null | oui | Jetons encore retenus : 0 si la consommation est connue. |
startedAt | string (date-time) | oui | Début de l’appel. |
UsageCounters#
Compteurs sur la période et les filtres, en chaînes décimales entières.
| Champ | Type | Requis | Description |
|---|---|---|---|
calls | string (motif ^\d+$) | oui | Appels au modèle. |
unknown | string (motif ^\d+$) | oui | Appels à consommation inconnue. |
pending | string (motif ^\d+$) | oui | Appels encore en réservation. |
unknown_costs | string (motif ^\d+$) | oui | Appels terminés sans coût connu. |
unknown_cached | string (motif ^\d+$) | oui | Appels connus sans information de cache. |
unknown_reasoning | string (motif ^\d+$) | oui | Appels connus sans information de raisonnement. |
held | string (motif ^\d+$) | oui | Jetons retenus pour les appels non connus. |
input | string (motif ^\d+$) | oui | Jetons d’entrée connus. |
output | string (motif ^\d+$) | oui | Jetons de sortie connus. |
cached | string (motif ^\d+$) | oui | Jetons en cache connus. |
reasoning | string (motif ^\d+$) | oui | Jetons de raisonnement connus. |
total | string (motif ^\d+$) | oui | Total de jetons connus. |
UsageReport#
| Champ | Type | Requis | Description |
|---|---|---|---|
kind | string (live, evaluation) | oui | |
period | object | oui | |
period.from | string (date-time) | oui | Début inclus. |
period.to | string (date-time) | oui | Fin exclue. |
counters | UsageCounters | oui | |
knownCosts | array<object> | oui | Somme des coûts connus par devise. |
knownCosts[].currency | string | oui | |
knownCosts[].amount | string | oui | Montant décimal (12 décimales). |
entries | array<UsageEntry> | oui | |
next | string ou null | oui | Curseur 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.
| Action | Motif |
|---|---|
| POST /api/v1/runs/{runId}/report | Refusé : 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 constats | Valider ou rejeter un constat se fait dans l’interface uniquement. |
| Réponse, reprise, archivage, publication | Ré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 dynamiques | Les contrôles sur la recette exigent un accord humain enregistré ; ils ne sont pas déclenchables ni lisibles par clé. |
| Administration | Comptes, membres, politiques, intégrations, accords, clés API et arrêt global : aucune route externe. |