---
title: Référence de l'API
description: "Toutes les opérations de 101Maintain API 1.0.0, générées depuis le contrat OpenAPI 3.1.0."
---

# 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](/openapi.json) et [openapi.yaml](/openapi.yaml). Les agents IA trouveront les autres ressources dans [Ressources pour agents IA](07-agent-ia.md).

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 |

> [!TIP]
> **Consignes pour agents IA** (extension `x-agent-hints`) :
>
> - Envoyer la clé uniquement dans `Authorization: Bearer 101m_<keyId>.<secret>` ; jamais dans l’URL.
> - Toute création (POST …/runs, POST …/audits) exige un en-tête `Idempotency-Key` stable pour une même intention ; réutiliser la même valeur pour réessayer après une erreur réseau.
> - Les créations sont asynchrones (202) : interroger `Location` ou `links.self` jusqu’à un statut terminal, en espaçant les appels (quota par clé et par projet, 120 requêtes par minute au plus).
> - Sur 429, attendre `Retry-After` secondes avant de réessayer. Sur 503, réessayer plus tard avec un délai croissant. Ne jamais réessayer automatiquement un 401, 403, 404, 409 ou 422 sans changer la requête.
> - Un 404 signifie aussi « hors du périmètre de la clé » : ne pas en déduire que la ressource n’existe pas.
> - Paginer avec `after` = valeur `next` de la page précédente, jusqu’à `next: null`.
> - Les identifiants sont des UUID en minuscules ; les chemins de suivi sont relatifs à l’origine de l’instance.

## Sommaire des opérations

| Méthode | Route | Résumé | Scope |
| --- | --- | --- | --- |
| `GET` | [`/api/v1/openapi.json`](#op-getopenapidocument) | Contrat OpenAPI servi par l’instance | public |
| `GET` | [`/api/v1/projects`](#op-listprojects) | Lister les projets de la clé encore accessibles au propriétaire | `projects:read` |
| `GET` | [`/api/v1/projects/{projectId}/repositories`](#op-listrepositories) | Lister les dépôts d’un projet | `repositories:read` |
| `GET` | [`/api/v1/projects/{projectId}/runs`](#op-listruns) | Lister les exécutions d’un projet | `runs:read` |
| `POST` | [`/api/v1/projects/{projectId}/runs`](#op-createrun) | Demander une exécution sur une issue déjà suivie | `runs:create` |
| `GET` | [`/api/v1/runs/{runId}`](#op-getrun) | Lire l’état d’une exécution | `runs:read` |
| `POST` | [`/api/v1/runs/{runId}/cancel`](#op-cancelrun) | Demander l’arrêt d’une exécution (idempotent) | `runs:cancel` |
| `GET` | [`/api/v1/runs/{runId}/report`](#op-getrunreport) | Télécharger le rapport d’incident (PDF) d’une exécution | `reports:read` |
| `GET` | [`/api/v1/projects/{projectId}/audits`](#op-listaudits) | Lister les audits d’un projet | `audits:read` |
| `POST` | [`/api/v1/projects/{projectId}/audits`](#op-createaudit) | Demander un audit statique d’un dépôt | `audits:create` |
| `GET` | [`/api/v1/audits/{auditId}`](#op-getaudit) | Lire les contrôles et constats d’un audit | `audits:read` |
| `GET` | [`/api/v1/audits/{auditId}/report`](#op-getauditreport) | Lire le rapport final d’un audit (constats acceptés) | `reports:read` |
| `GET` | [`/api/v1/projects/{projectId}/usage`](#op-getprojectusage) | 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 {#op-getopenapidocument}

**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 {#op-listprojects}

**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](#schema-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](#reponse-unauthenticated)) | `application/json` [Error](#schema-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](#reponse-forbidden)) | `application/json` [Error](#schema-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](#reponse-notfound)) | `application/json` [Error](#schema-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](#reponse-invalidrequest)) | `application/json` [Error](#schema-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](#reponse-ratelimited)) | `application/json` [Error](#schema-error) | `Cache-Control`, `X-Content-Type-Options`, `Referrer-Policy`, `Retry-After` |
| `503` | Service ou capacité temporairement indisponible. Réessayer plus tard. ([Unavailable](#reponse-unavailable)) | `application/json` [Error](#schema-error) | `Cache-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
}
```

> [!TIP]
> **Pour les agents IA**
>
> - Point de départ : récupérer ici les `projectId` utilisables par la clé.
> - 403 signifie que la clé n’a pas le scope `projects:read` ; les autres routes restent utilisables avec un `projectId` connu.

### GET /api/v1/projects/{projectId}/repositories {#op-listrepositories}

**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](#schema-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](#reponse-unauthenticated)) | `application/json` [Error](#schema-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](#reponse-forbidden)) | `application/json` [Error](#schema-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](#reponse-notfound)) | `application/json` [Error](#schema-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](#reponse-invalidrequest)) | `application/json` [Error](#schema-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](#reponse-ratelimited)) | `application/json` [Error](#schema-error) | `Cache-Control`, `X-Content-Type-Options`, `Referrer-Policy`, `Retry-After` |
| `503` | Service ou capacité temporairement indisponible. Réessayer plus tard. ([Unavailable](#reponse-unavailable)) | `application/json` [Error](#schema-error) | `Cache-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
}
```

> [!TIP]
> **Pour les agents IA**
>
> - `enabled: false` signifie que le dépôt est arrêté : aucune exécution ni audit ne pourra y démarrer.

## Exécutions

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

### GET /api/v1/projects/{projectId}/runs {#op-listruns}

**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](#schema-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](#reponse-unauthenticated)) | `application/json` [Error](#schema-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](#reponse-forbidden)) | `application/json` [Error](#schema-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](#reponse-notfound)) | `application/json` [Error](#schema-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](#reponse-invalidrequest)) | `application/json` [Error](#schema-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](#reponse-ratelimited)) | `application/json` [Error](#schema-error) | `Cache-Control`, `X-Content-Type-Options`, `Referrer-Policy`, `Retry-After` |
| `503` | Service ou capacité temporairement indisponible. Réessayer plus tard. ([Unavailable](#reponse-unavailable)) | `application/json` [Error](#schema-error) | `Cache-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 {#op-createrun}

**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](#schema-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). |

```json
{
  "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](#schema-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](#reponse-unauthenticated)) | `application/json` [Error](#schema-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](#reponse-forbidden)) | `application/json` [Error](#schema-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](#reponse-notfound)) | `application/json` [Error](#schema-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](#schema-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](#reponse-invalidrequest)) | `application/json` [Error](#schema-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](#reponse-ratelimited)) | `application/json` [Error](#schema-error) | `Cache-Control`, `X-Content-Type-Options`, `Referrer-Policy`, `Retry-After` |
| `503` | Service ou capacité temporairement indisponible. Réessayer plus tard. ([Unavailable](#reponse-unavailable)) | `application/json` [Error](#schema-error) | `Cache-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."
}
```

> [!TIP]
> **Pour les agents IA**
>
> - Dériver `Idempotency-Key` de l’intention (par exemple `issue-<numéro>-<date>`) et la réutiliser pour chaque nouvel essai de la même demande.
> - 404 : dépôt hors du projet ou issue jamais reçue par le webhook (la plateforme ne crée pas d’issue).
> - Sur 409 avec `existingRun`, suivre `existingRun.links.self` au lieu de redemander.

### GET /api/v1/runs/{runId} {#op-getrun}

**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](#schema-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](#reponse-unauthenticated)) | `application/json` [Error](#schema-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](#reponse-forbidden)) | `application/json` [Error](#schema-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](#reponse-notfound)) | `application/json` [Error](#schema-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](#reponse-invalidrequest)) | `application/json` [Error](#schema-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](#reponse-ratelimited)) | `application/json` [Error](#schema-error) | `Cache-Control`, `X-Content-Type-Options`, `Referrer-Policy`, `Retry-After` |
| `503` | Service ou capacité temporairement indisponible. Réessayer plus tard. ([Unavailable](#reponse-unavailable)) | `application/json` [Error](#schema-error) | `Cache-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"
  }
}
```

> [!TIP]
> **Pour les agents IA**
>
> - Statuts terminaux : `prepared`, `needs_input`, `refused`, `failed`, `unknown`, `canceled`. `queued` et `running` sont transitoires.
> - `waiting: "organization_stop"` avec `queued` : l’organisation est en arrêt global ; l’exécution démarrera après la levée, inutile de redemander.
> - `needs_input` : les questions sont dans `result.questions` ; y répondre se fait dans l’interface ou par la commande `/answer` sur la PR, pas par l’API.
> - `result.testsExecuted` vaut toujours `false` : la plateforme n’exécute pas les tests du dépôt.
> - Si `nextAttempt` n’est pas nul, suivre `/api/v1/runs/{nextAttempt.id}` pour la reprise.

### POST /api/v1/runs/{runId}/cancel {#op-cancelrun}

**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](#schema-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](#reponse-unauthenticated)) | `application/json` [Error](#schema-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](#reponse-forbidden)) | `application/json` [Error](#schema-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](#reponse-notfound)) | `application/json` [Error](#schema-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](#reponse-invalidrequest)) | `application/json` [Error](#schema-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](#reponse-ratelimited)) | `application/json` [Error](#schema-error) | `Cache-Control`, `X-Content-Type-Options`, `Referrer-Policy`, `Retry-After` |
| `503` | Service ou capacité temporairement indisponible. Réessayer plus tard. ([Unavailable](#reponse-unavailable)) | `application/json` [Error](#schema-error) | `Cache-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 {#op-listaudits}

**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](#schema-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](#reponse-unauthenticated)) | `application/json` [Error](#schema-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](#reponse-forbidden)) | `application/json` [Error](#schema-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](#reponse-notfound)) | `application/json` [Error](#schema-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](#reponse-invalidrequest)) | `application/json` [Error](#schema-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](#reponse-ratelimited)) | `application/json` [Error](#schema-error) | `Cache-Control`, `X-Content-Type-Options`, `Referrer-Policy`, `Retry-After` |
| `503` | Service ou capacité temporairement indisponible. Réessayer plus tard. ([Unavailable](#reponse-unavailable)) | `application/json` [Error](#schema-error) | `Cache-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 {#op-createaudit}

**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](#schema-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). |

```json
{
  "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](#schema-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](#reponse-unauthenticated)) | `application/json` [Error](#schema-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](#reponse-forbidden)) | `application/json` [Error](#schema-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](#reponse-notfound)) | `application/json` [Error](#schema-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](#schema-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](#reponse-invalidrequest)) | `application/json` [Error](#schema-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](#reponse-ratelimited)) | `application/json` [Error](#schema-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](#schema-error) | `Cache-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"
}
```

> [!TIP]
> **Pour les agents IA**
>
> - Omettre `checks` : la v1 exécute toujours les trois contrôles statiques.
> - Sur 409 ou 503 avec `reason`, transmettre `message` à une personne : il nomme le réglage à corriger ; réessayer ne changera rien.

### GET /api/v1/audits/{auditId} {#op-getaudit}

**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](#schema-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](#reponse-unauthenticated)) | `application/json` [Error](#schema-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](#reponse-forbidden)) | `application/json` [Error](#schema-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](#reponse-notfound)) | `application/json` [Error](#schema-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](#reponse-invalidrequest)) | `application/json` [Error](#schema-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](#reponse-ratelimited)) | `application/json` [Error](#schema-error) | `Cache-Control`, `X-Content-Type-Options`, `Referrer-Policy`, `Retry-After` |
| `503` | Service ou capacité temporairement indisponible. Réessayer plus tard. ([Unavailable](#reponse-unavailable)) | `application/json` [Error](#schema-error) | `Cache-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"
  }
}
```

> [!TIP]
> **Pour les agents IA**
>
> - Statuts terminaux : `complete`, `partial`, `refused`, `failed`, `unknown`.
> - La qualification des constats (valider, rejeter) se fait dans l’interface. `reportAvailable` passe à `true` quand plus aucun constat n’attend.

## Rapports

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

### GET /api/v1/runs/{runId}/report {#op-getrunreport}

**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](#reponse-unauthenticated)) | `application/json` [Error](#schema-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](#reponse-forbidden)) | `application/json` [Error](#schema-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](#reponse-notfound)) | `application/json` [Error](#schema-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](#reponse-invalidrequest)) | `application/json` [Error](#schema-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](#reponse-ratelimited)) | `application/json` [Error](#schema-error) | `Cache-Control`, `X-Content-Type-Options`, `Referrer-Policy`, `Retry-After` |
| `503` | Service ou capacité temporairement indisponible. Réessayer plus tard. ([Unavailable](#reponse-unavailable)) | `application/json` [Error](#schema-error) | `Cache-Control`, `X-Content-Type-Options`, `Referrer-Policy` |

> [!TIP]
> **Pour les agents IA**
>
> - Vérifier l’intégrité du fichier en comparant son SHA-256 à `X-Report-Sha256`.
> - Un 404 peut signifier « aucune édition prête » : demander à une personne de générer l’édition PDF dans l’interface.

### GET /api/v1/audits/{auditId}/report {#op-getauditreport}

**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](#schema-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](#reponse-unauthenticated)) | `application/json` [Error](#schema-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](#reponse-forbidden)) | `application/json` [Error](#schema-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](#reponse-notfound)) | `application/json` [Error](#schema-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](#schema-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](#reponse-invalidrequest)) | `application/json` [Error](#schema-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](#reponse-ratelimited)) | `application/json` [Error](#schema-error) | `Cache-Control`, `X-Content-Type-Options`, `Referrer-Policy`, `Retry-After` |
| `503` | Service ou capacité temporairement indisponible. Réessayer plus tard. ([Unavailable](#reponse-unavailable)) | `application/json` [Error](#schema-error) | `Cache-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 {#op-getprojectusage}

**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](#schema-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](#reponse-unauthenticated)) | `application/json` [Error](#schema-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](#reponse-forbidden)) | `application/json` [Error](#schema-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](#reponse-notfound)) | `application/json` [Error](#schema-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](#reponse-invalidrequest)) | `application/json` [Error](#schema-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](#reponse-ratelimited)) | `application/json` [Error](#schema-error) | `Cache-Control`, `X-Content-Type-Options`, `Referrer-Policy`, `Retry-After` |
| `503` | Service ou capacité temporairement indisponible. Réessayer plus tard. ([Unavailable](#reponse-unavailable)) | `application/json` [Error](#schema-error) | `Cache-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
}
```

> [!TIP]
> **Pour les agents IA**
>
> - Les compteurs sont des chaînes décimales (entiers potentiellement grands) : les convertir avec une arithmétique entière exacte.
> - `cost` et `knownCosts[].amount` sont des montants décimaux en chaîne (12 décimales) : ne pas les convertir en flottant pour des totaux comptables.
> - `cost: null` signifie coût inconnu (tarif absent ou usage inconnu), jamais gratuit.

## Réponses communes

### Unauthenticated {#reponse-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 {#reponse-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 {#reponse-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 {#reponse-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 {#reponse-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 {#reponse-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

| 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 {#schema-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 {#schema-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](#schema-runstatus) | oui |  |
| `existingRun.links` | object | oui |  |
| `existingRun.links.self` | string | oui | Chemin `/api/v1/runs/<runId>`. |

### SelfLink {#schema-selflink}

| Champ | Type | Requis | Description |
| --- | --- | --- | --- |
| `self` | string | oui | Chemin de la ressource. |

### Next {#schema-next}

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

Type : string ou null.

### Project {#schema-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 {#schema-projectpage}

| Champ | Type | Requis | Description |
| --- | --- | --- | --- |
| `projects` | array<[Project](#schema-project)> | oui |  |
| `next` | [Next](#schema-next) | oui |  |

### Repository {#schema-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 {#schema-repositorypage}

| Champ | Type | Requis | Description |
| --- | --- | --- | --- |
| `repositories` | array<[Repository](#schema-repository)> | oui |  |
| `next` | [Next](#schema-next) | oui |  |

### RunStatus {#schema-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 {#schema-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 {#schema-runsummary}

| Champ | Type | Requis | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | oui | Identifiant de l’exécution. |
| `status` | [RunStatus](#schema-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](#schema-selflink) | oui |  |

### RunPage {#schema-runpage}

| Champ | Type | Requis | Description |
| --- | --- | --- | --- |
| `runs` | array<[RunSummary](#schema-runsummary)> | oui |  |
| `next` | [Next](#schema-next) | oui |  |

### RunAccepted {#schema-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](#schema-selflink) | oui |  |

### RunResult {#schema-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 {#schema-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 {#schema-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 {#schema-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](#schema-budgetenvelope) ou null | non | Plafond par exécution, `null` si aucun. |
| `issue` | [BudgetEnvelope](#schema-budgetenvelope) ou null | non | Budget cumulé de l’issue, `null` si aucun. |

### Publication {#schema-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 {#schema-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](#schema-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](#schema-runresult) ou null | oui | Résultat ; `null` tant qu’aucun n’est enregistré. |
| `steps` | array<[RunStep](#schema-runstep)> | oui | Étapes des agents. |
| `budgets` | [RunBudgets](#schema-runbudgets) | oui |  |
| `publication` | [Publication](#schema-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 {#schema-cancelaccepted}

| Champ | Type | Requis | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | oui | Exécution. |
| `cancelRequested` | boolean (= `true`) | oui |  |
| `status` | [RunStatus](#schema-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](#schema-selflink) | oui |  |

### AuditRequest {#schema-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 {#schema-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 {#schema-auditsummary}

| Champ | Type | Requis | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | oui | Identifiant de l’audit. |
| `status` | [AuditStatus](#schema-auditstatus) | oui |  |
| `repository` | string | oui | `organisation/dépôt`. |
| `createdAt` | string (date-time) | oui | Date de la demande. |
| `links` | [SelfLink](#schema-selflink) | oui |  |

### AuditPage {#schema-auditpage}

| Champ | Type | Requis | Description |
| --- | --- | --- | --- |
| `audits` | array<[AuditSummary](#schema-auditsummary)> | oui |  |
| `next` | [Next](#schema-next) | oui |  |

### AuditAccepted {#schema-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](#schema-selflink) | oui |  |

### AuditCheck {#schema-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 {#schema-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 {#schema-auditbase}

| Champ | Type | Requis | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | oui | Identifiant de l’audit. |
| `projectId` | string (uuid) | oui | Projet. |
| `status` | [AuditStatus](#schema-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](#schema-auditcheck)> | oui |  |
| `finishedAt` | string ou null (date-time) | oui | Fin de l’audit. |
| `findings` | array<[AuditFinding](#schema-auditfinding)> | oui |  |

### Audit {#schema-audit}

| Champ | Type | Requis | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | oui | Identifiant de l’audit. |
| `projectId` | string (uuid) | oui | Projet. |
| `status` | [AuditStatus](#schema-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](#schema-auditcheck)> | oui |  |
| `finishedAt` | string ou null (date-time) | oui | Fin de l’audit. |
| `findings` | array<[AuditFinding](#schema-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 {#schema-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](#schema-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](#schema-auditcheck)> | oui |  |
| `finishedAt` | string ou null (date-time) | oui | Fin de l’audit. |
| `findings` | array<[AuditFinding](#schema-auditfinding)> | oui |  |
| `report` | string (= `"final"`) | oui |  |
| `links` | [SelfLink](#schema-selflink) | oui |  |

### TokenUsage {#schema-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 {#schema-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 {#schema-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](#schema-ratesnapshot) ou null | oui |  |
| `usage` | [TokenUsage](#schema-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 {#schema-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 {#schema-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](#schema-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](#schema-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. |
