{
  "openapi": "3.1.0",
  "info": {
    "title": "101Maintain API",
    "version": "1.0.0",
    "summary": "API externe de 101Maintain : déclencher et suivre des exécutions et des audits.",
    "description": "API externe authentifiée par **clé personnelle**. Chaque appel est attribué à la clé et au compte qui l’a créée.\nLes 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.\n\nCette 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.\n\nDocumentation lisible : chapitre « Intégration API » du site de documentation.",
    "license": {
      "name": "Propriétaire",
      "identifier": "LicenseRef-101Maintain"
    },
    "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."
    ]
  },
  "servers": [
    {
      "url": "https://{instance}",
      "description": "Instance 101Maintain de votre organisation.",
      "variables": {
        "instance": {
          "default": "maintain.example"
        }
      }
    }
  ],
  "externalDocs": {
    "description": "Chapitre « Intégration API » de la documentation 101Maintain",
    "url": "/07-integration-api/01-vue-d-ensemble.html"
  },
  "tags": [
    {
      "name": "Contrat",
      "description": "Document OpenAPI servi par l’instance."
    },
    {
      "name": "Projets",
      "description": "Projets et dépôts accessibles à la clé."
    },
    {
      "name": "Exécutions",
      "description": "Demandes d’exécution de maintenance sur des issues suivies."
    },
    {
      "name": "Audits",
      "description": "Audits statiques de dépôt et leurs constats."
    },
    {
      "name": "Rapports",
      "description": "Rapports d’incident (PDF) et rapports finaux d’audit."
    },
    {
      "name": "Consommation",
      "description": "Registre d’usage des appels au modèle et coûts connus."
    }
  ],
  "security": [
    {
      "personalKey": []
    }
  ],
  "paths": {
    "/api/v1/openapi.json": {
      "get": {
        "operationId": "getOpenApiDocument",
        "tags": [
          "Contrat"
        ],
        "summary": "Contrat OpenAPI servi par l’instance",
        "description": "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.",
        "security": [],
        "x-required-scope": null,
        "responses": {
          "200": {
            "description": "Document OpenAPI 3.1 (JSON).",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/projects": {
      "get": {
        "security": [
          {
            "personalKey": []
          }
        ],
        "x-required-scope": "projects:read",
        "operationId": "listProjects",
        "tags": [
          "Projets"
        ],
        "summary": "Lister les projets de la clé encore accessibles au propriétaire",
        "description": "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.",
        "parameters": [
          {
            "$ref": "#/components/parameters/After"
          }
        ],
        "responses": {
          "200": {
            "description": "Page de projets.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              },
              "X-Content-Type-Options": {
                "$ref": "#/components/headers/XContentTypeOptions"
              },
              "Referrer-Policy": {
                "$ref": "#/components/headers/ReferrerPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProjectPage"
                },
                "example": {
                  "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
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "x-agent-hints": [
          "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."
        ]
      }
    },
    "/api/v1/projects/{projectId}/repositories": {
      "get": {
        "security": [
          {
            "personalKey": []
          }
        ],
        "x-required-scope": "repositories:read",
        "operationId": "listRepositories",
        "tags": [
          "Projets"
        ],
        "summary": "Lister les dépôts d’un projet",
        "description": "Dépôts du projet triés par identifiant, par pages de `limit` éléments.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProjectId"
          },
          {
            "$ref": "#/components/parameters/After"
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ],
        "responses": {
          "200": {
            "description": "Page de dépôts.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              },
              "X-Content-Type-Options": {
                "$ref": "#/components/headers/XContentTypeOptions"
              },
              "Referrer-Policy": {
                "$ref": "#/components/headers/ReferrerPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RepositoryPage"
                },
                "example": {
                  "repositories": [
                    {
                      "id": "5b7e2c90-1d4f-4e6a-8c3b-9f0a1d2e3c46",
                      "fullName": "exemple-org/boutique",
                      "defaultBranch": "main",
                      "enabled": true
                    }
                  ],
                  "next": null
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "x-agent-hints": [
          "`enabled: false` signifie que le dépôt est arrêté : aucune exécution ni audit ne pourra y démarrer."
        ]
      }
    },
    "/api/v1/projects/{projectId}/runs": {
      "get": {
        "security": [
          {
            "personalKey": []
          }
        ],
        "x-required-scope": "runs:read",
        "operationId": "listRuns",
        "tags": [
          "Exécutions"
        ],
        "summary": "Lister les exécutions d’un projet",
        "description": "Exécutions (originales et reprises) du projet triées par identifiant, par pages de `limit` éléments.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProjectId"
          },
          {
            "$ref": "#/components/parameters/After"
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ],
        "responses": {
          "200": {
            "description": "Page d’exécutions.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              },
              "X-Content-Type-Options": {
                "$ref": "#/components/headers/XContentTypeOptions"
              },
              "Referrer-Policy": {
                "$ref": "#/components/headers/ReferrerPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RunPage"
                },
                "example": {
                  "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
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      },
      "post": {
        "security": [
          {
            "personalKey": []
          }
        ],
        "x-required-scope": "runs:create",
        "operationId": "createRun",
        "tags": [
          "Exécutions"
        ],
        "summary": "Demander une exécution sur une issue déjà suivie",
        "description": "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.\n\nConditions : 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.\n\nPendant 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.\n\nLa 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.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProjectId"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Objet JSON aux seuls champs déclarés ; tout autre champ renvoie 422.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RunRequest"
              },
              "example": {
                "repositoryId": "5b7e2c90-1d4f-4e6a-8c3b-9f0a1d2e3c46",
                "issueNumber": 42
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Demande acceptée. Suivre la ressource indiquée par `Location` (et `links.self` dans le corps).",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              },
              "X-Content-Type-Options": {
                "$ref": "#/components/headers/XContentTypeOptions"
              },
              "Referrer-Policy": {
                "$ref": "#/components/headers/ReferrerPolicy"
              },
              "Location": {
                "$ref": "#/components/headers/Location"
              },
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RunAccepted"
                },
                "example": {
                  "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"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Conflit :\n- issue fermée, ou dépôt inactif, non rattaché ou non surveillé (`error: conflict`, sans détail) ;\n- 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 ;\n- `Idempotency-Key` déjà utilisée avec un autre corps.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              },
              "X-Content-Type-Options": {
                "$ref": "#/components/headers/XContentTypeOptions"
              },
              "Referrer-Policy": {
                "$ref": "#/components/headers/ReferrerPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RunConflict"
                },
                "examples": {
                  "existingRun": {
                    "summary": "Exécution existante, lisible par la clé",
                    "value": {
                      "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"
                        }
                      }
                    }
                  },
                  "generic": {
                    "summary": "Conflit générique",
                    "value": {
                      "error": "conflict",
                      "message": "Conflit avec l’état actuel ou une requête idempotente différente."
                    }
                  }
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "x-agent-hints": [
          "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."
        ]
      }
    },
    "/api/v1/runs/{runId}": {
      "get": {
        "security": [
          {
            "personalKey": []
          }
        ],
        "x-required-scope": "runs:read",
        "operationId": "getRun",
        "tags": [
          "Exécutions"
        ],
        "summary": "Lire l’état d’une exécution",
        "description": "É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.",
        "parameters": [
          {
            "$ref": "#/components/parameters/RunId"
          }
        ],
        "responses": {
          "200": {
            "description": "Exécution.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              },
              "X-Content-Type-Options": {
                "$ref": "#/components/headers/XContentTypeOptions"
              },
              "Referrer-Policy": {
                "$ref": "#/components/headers/ReferrerPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Run"
                },
                "example": {
                  "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"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "x-agent-hints": [
          "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."
        ]
      }
    },
    "/api/v1/runs/{runId}/cancel": {
      "post": {
        "security": [
          {
            "personalKey": []
          }
        ],
        "x-required-scope": "runs:cancel",
        "operationId": "cancelRun",
        "tags": [
          "Exécutions"
        ],
        "summary": "Demander l’arrêt d’une exécution (idempotent)",
        "description": "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`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/RunId"
          }
        ],
        "responses": {
          "202": {
            "description": "Arrêt demandé. `Location` pointe vers l’exécution ; `Idempotent-Replayed` n’est pas envoyé sur cette route.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              },
              "X-Content-Type-Options": {
                "$ref": "#/components/headers/XContentTypeOptions"
              },
              "Referrer-Policy": {
                "$ref": "#/components/headers/ReferrerPolicy"
              },
              "Location": {
                "$ref": "#/components/headers/Location"
              },
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CancelAccepted"
                },
                "example": {
                  "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"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/api/v1/runs/{runId}/report": {
      "get": {
        "security": [
          {
            "personalKey": []
          }
        ],
        "x-required-scope": "reports:read",
        "operationId": "getRunReport",
        "tags": [
          "Rapports"
        ],
        "summary": "Télécharger le rapport d’incident (PDF) d’une exécution",
        "description": "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é.",
        "parameters": [
          {
            "$ref": "#/components/parameters/RunId"
          }
        ],
        "responses": {
          "200": {
            "description": "PDF du rapport d’incident.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              },
              "X-Content-Type-Options": {
                "$ref": "#/components/headers/XContentTypeOptions"
              },
              "Referrer-Policy": {
                "$ref": "#/components/headers/ReferrerPolicy"
              },
              "Content-Disposition": {
                "description": "Toujours `attachment; filename=\"<nom>.pdf\"`.",
                "schema": {
                  "type": "string",
                  "examples": [
                    "attachment; filename=\"rapport.pdf\""
                  ]
                }
              },
              "X-Report-Edition": {
                "description": "Identifiant de l’édition servie.",
                "schema": {
                  "type": "string",
                  "format": "uuid"
                }
              },
              "X-Report-Sha256": {
                "description": "Empreinte SHA-256 (hexadécimal) du PDF servi, à comparer après téléchargement.",
                "schema": {
                  "type": "string",
                  "pattern": "^[a-f0-9]{64}$"
                }
              }
            },
            "content": {
              "application/pdf": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "x-agent-hints": [
          "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."
        ]
      }
    },
    "/api/v1/projects/{projectId}/audits": {
      "get": {
        "security": [
          {
            "personalKey": []
          }
        ],
        "x-required-scope": "audits:read",
        "operationId": "listAudits",
        "tags": [
          "Audits"
        ],
        "summary": "Lister les audits d’un projet",
        "description": "Audits du projet triés par identifiant, par pages fixes de 30 ; cette route n’accepte pas `limit`.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProjectId"
          },
          {
            "$ref": "#/components/parameters/After"
          }
        ],
        "responses": {
          "200": {
            "description": "Page d’audits.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              },
              "X-Content-Type-Options": {
                "$ref": "#/components/headers/XContentTypeOptions"
              },
              "Referrer-Policy": {
                "$ref": "#/components/headers/ReferrerPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditPage"
                },
                "example": {
                  "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
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      },
      "post": {
        "security": [
          {
            "personalKey": []
          }
        ],
        "x-required-scope": "audits:create",
        "operationId": "createAudit",
        "tags": [
          "Audits"
        ],
        "summary": "Demander un audit statique d’un dépôt",
        "description": "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.\n\nSi 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.\n\nPendant 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.\n\nLes contrôles dynamiques (recette) restent soumis à l’accord humain et ne se déclenchent pas par clé.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProjectId"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "description": "Objet JSON aux seuls champs déclarés ; tout autre champ renvoie 422.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AuditRequest"
              },
              "example": {
                "repositoryId": "5b7e2c90-1d4f-4e6a-8c3b-9f0a1d2e3c46"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Demande acceptée. Suivre la ressource indiquée par `Location` (et `links.self` dans le corps).",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              },
              "X-Content-Type-Options": {
                "$ref": "#/components/headers/XContentTypeOptions"
              },
              "Referrer-Policy": {
                "$ref": "#/components/headers/ReferrerPolicy"
              },
              "Location": {
                "$ref": "#/components/headers/Location"
              },
              "Idempotent-Replayed": {
                "$ref": "#/components/headers/IdempotentReplayed"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditAccepted"
                },
                "example": {
                  "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"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Conflit :\n- dépôt arrêté (`reason: repository_stopped`) ou non rattaché à la GitHub App (`reason: repository_not_bound`) ; `message` indique le réglage à changer ;\n- `Idempotency-Key` déjà utilisée avec un autre corps.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              },
              "X-Content-Type-Options": {
                "$ref": "#/components/headers/XContentTypeOptions"
              },
              "Referrer-Policy": {
                "$ref": "#/components/headers/ReferrerPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "stopped": {
                    "summary": "Dépôt arrêté",
                    "value": {
                      "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"
                    }
                  },
                  "notBound": {
                    "summary": "Dépôt non rattaché",
                    "value": {
                      "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"
                    }
                  }
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "description": "Audits désactivés sur l’instance (`reason: repository_audits_disabled`, renvoyé avant toute validation du corps) ou service indisponible.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              },
              "X-Content-Type-Options": {
                "$ref": "#/components/headers/XContentTypeOptions"
              },
              "Referrer-Policy": {
                "$ref": "#/components/headers/ReferrerPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "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"
                }
              }
            }
          }
        },
        "x-agent-hints": [
          "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."
        ]
      }
    },
    "/api/v1/audits/{auditId}": {
      "get": {
        "security": [
          {
            "personalKey": []
          }
        ],
        "x-required-scope": "audits:read",
        "operationId": "getAudit",
        "tags": [
          "Audits"
        ],
        "summary": "Lire les contrôles et constats d’un audit",
        "description": "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.",
        "parameters": [
          {
            "$ref": "#/components/parameters/AuditId"
          }
        ],
        "responses": {
          "200": {
            "description": "Audit.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              },
              "X-Content-Type-Options": {
                "$ref": "#/components/headers/XContentTypeOptions"
              },
              "Referrer-Policy": {
                "$ref": "#/components/headers/ReferrerPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Audit"
                },
                "example": {
                  "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"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "x-agent-hints": [
          "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."
        ]
      }
    },
    "/api/v1/audits/{auditId}/report": {
      "get": {
        "security": [
          {
            "personalKey": []
          }
        ],
        "x-required-scope": "reports:read",
        "operationId": "getAuditReport",
        "tags": [
          "Rapports"
        ],
        "summary": "Lire le rapport final d’un audit (constats acceptés)",
        "description": "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.",
        "parameters": [
          {
            "$ref": "#/components/parameters/AuditId"
          }
        ],
        "responses": {
          "200": {
            "description": "Rapport final.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              },
              "X-Content-Type-Options": {
                "$ref": "#/components/headers/XContentTypeOptions"
              },
              "Referrer-Policy": {
                "$ref": "#/components/headers/ReferrerPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditReport"
                },
                "example": {
                  "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"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Audit non terminé, constats encore à qualifier ou contrôle dynamique en cours.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              },
              "X-Content-Type-Options": {
                "$ref": "#/components/headers/XContentTypeOptions"
              },
              "Referrer-Policy": {
                "$ref": "#/components/headers/ReferrerPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "conflict",
                  "message": "Conflit avec l’état actuel ou une requête idempotente différente."
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/api/v1/projects/{projectId}/usage": {
      "get": {
        "security": [
          {
            "personalKey": []
          }
        ],
        "x-required-scope": "usage:read",
        "operationId": "getProjectUsage",
        "tags": [
          "Consommation"
        ],
        "summary": "Lire les agrégats et entrées de consommation d’un projet",
        "description": "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.\n\nUne 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.",
        "parameters": [
          {
            "$ref": "#/components/parameters/ProjectId"
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Début inclus, en UTC au format `AAAA-MM-JJTHH:MM:SS[.mmm]Z`. Par défaut : `to` moins 30 jours.",
            "schema": {
              "type": "string",
              "format": "date-time",
              "examples": [
                "2026-11-01T00:00:00Z"
              ]
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Fin exclue, même format. Par défaut : maintenant. `from` doit précéder `to` et l’écart ne pas dépasser 366 jours.",
            "schema": {
              "type": "string",
              "format": "date-time",
              "examples": [
                "2026-12-01T00:00:00Z"
              ]
            }
          },
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "description": "`live` : exécutions de maintenance (défaut). `evaluation` : exécutions du banc d’essai.",
            "schema": {
              "type": "string",
              "enum": [
                "live",
                "evaluation"
              ],
              "default": "live"
            }
          },
          {
            "name": "repository",
            "in": "query",
            "required": false,
            "description": "Limiter à un dépôt du projet (404 si le dépôt n’appartient pas au projet).",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "model",
            "in": "query",
            "required": false,
            "description": "Limiter à un identifiant de modèle.",
            "schema": {
              "type": "string",
              "pattern": "^[a-zA-Z0-9_.:/-]{1,150}$"
            }
          },
          {
            "name": "pull",
            "in": "query",
            "required": false,
            "description": "Limiter aux exécutions rattachées à ce numéro de PR brouillon.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "after",
            "in": "query",
            "required": false,
            "description": "Curseur opaque : valeur `next` de la page précédente.",
            "schema": {
              "type": "string",
              "pattern": "^\\d{1,15}\\.[a-f0-9-]{36}\\.\\d{1,2}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Compteurs, coûts connus et entrées.",
            "headers": {
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControl"
              },
              "X-Content-Type-Options": {
                "$ref": "#/components/headers/XContentTypeOptions"
              },
              "Referrer-Policy": {
                "$ref": "#/components/headers/ReferrerPolicy"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UsageReport"
                },
                "example": {
                  "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
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/InvalidRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        },
        "x-agent-hints": [
          "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."
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "personalKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "101m_<keyId>.<secret>",
        "description": "Clé personnelle créée depuis l’écran **Mes clés API** (`/account/api-keys`) de l’instance.\nFormat : `101m_` + identifiant public (UUID) + `.` + secret de 43 caractères base64url. Durée de 1 à 90 jours, 20 projets au plus, scopes explicites.\nSeul l’en-tête `Authorization: Bearer …` est accepté ; un cookie de session ou un jeton dans l’URL n’authentifie rien."
      }
    },
    "parameters": {
      "ProjectId": {
        "name": "projectId",
        "in": "path",
        "required": true,
        "description": "Identifiant du projet (UUID). Valeur mal formée : 422 (après authentification).",
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      },
      "RunId": {
        "name": "runId",
        "in": "path",
        "required": true,
        "description": "Identifiant de l’exécution (UUID).",
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      },
      "AuditId": {
        "name": "auditId",
        "in": "path",
        "required": true,
        "description": "Identifiant de l’audit (UUID).",
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      },
      "After": {
        "name": "after",
        "in": "query",
        "required": false,
        "description": "Curseur : identifiant du dernier élément de la page précédente (valeur `next`). Absent : première page.",
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      },
      "Limit": {
        "name": "limit",
        "in": "query",
        "required": false,
        "description": "Taille de page, de 1 à 50 (défaut 50). Hors bornes : 422.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 50,
          "default": 50
        }
      },
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": true,
        "description": "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.",
        "schema": {
          "type": "string",
          "minLength": 8,
          "maxLength": 128,
          "pattern": "^[\\x21-\\x7e]{8,128}$"
        },
        "example": "issue-42-2026-11-19"
      }
    },
    "headers": {
      "CacheControl": {
        "description": "Les réponses de l’API ne sont jamais mises en cache.",
        "schema": {
          "type": "string",
          "const": "no-store"
        }
      },
      "XContentTypeOptions": {
        "schema": {
          "type": "string",
          "const": "nosniff"
        }
      },
      "ReferrerPolicy": {
        "schema": {
          "type": "string",
          "const": "no-referrer"
        }
      },
      "Location": {
        "description": "Chemin de suivi de la ressource, relatif à l’origine (ex. `/api/v1/runs/<runId>`).",
        "schema": {
          "type": "string"
        }
      },
      "IdempotentReplayed": {
        "description": "`true` quand la réponse enregistrée d’une requête identique est rejouée, `false` pour une première exécution.",
        "schema": {
          "type": "string",
          "enum": [
            "true",
            "false"
          ]
        }
      },
      "RetryAfter": {
        "description": "Secondes à attendre avant la fin de la fenêtre d’une minute.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 60
        }
      },
      "WWWAuthenticate": {
        "description": "Toujours `Bearer realm=\"101maintain\"`.",
        "schema": {
          "type": "string",
          "const": "Bearer realm=\"101maintain\""
        }
      }
    },
    "responses": {
      "Unauthenticated": {
        "description": "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é.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          },
          "X-Content-Type-Options": {
            "$ref": "#/components/headers/XContentTypeOptions"
          },
          "Referrer-Policy": {
            "$ref": "#/components/headers/ReferrerPolicy"
          },
          "WWW-Authenticate": {
            "$ref": "#/components/headers/WWWAuthenticate"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "unauthenticated",
              "message": "Clé API absente, invalide, expirée ou révoquée."
            }
          }
        }
      },
      "Forbidden": {
        "description": "Scope requis absent de la clé, ou rôle actuel du propriétaire insuffisant sur une ressource visible.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          },
          "X-Content-Type-Options": {
            "$ref": "#/components/headers/XContentTypeOptions"
          },
          "Referrer-Policy": {
            "$ref": "#/components/headers/ReferrerPolicy"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "forbidden",
              "message": "Droit de la clé ou rôle actuel du propriétaire insuffisant."
            }
          }
        }
      },
      "NotFound": {
        "description": "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\"}`.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          },
          "X-Content-Type-Options": {
            "$ref": "#/components/headers/XContentTypeOptions"
          },
          "Referrer-Policy": {
            "$ref": "#/components/headers/ReferrerPolicy"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "not_found",
              "message": "Ressource introuvable dans le périmètre de la clé."
            }
          }
        }
      },
      "InvalidRequest": {
        "description": "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.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          },
          "X-Content-Type-Options": {
            "$ref": "#/components/headers/XContentTypeOptions"
          },
          "Referrer-Policy": {
            "$ref": "#/components/headers/ReferrerPolicy"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "invalid_request",
              "message": "Données de requête invalides."
            }
          }
        }
      },
      "RateLimited": {
        "description": "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.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          },
          "X-Content-Type-Options": {
            "$ref": "#/components/headers/XContentTypeOptions"
          },
          "Referrer-Policy": {
            "$ref": "#/components/headers/ReferrerPolicy"
          },
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "rate_limited",
              "message": "Quota de requêtes de la clé dépassé pour ce projet."
            }
          }
        }
      },
      "Unavailable": {
        "description": "Service ou capacité temporairement indisponible. Réessayer plus tard.",
        "headers": {
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControl"
          },
          "X-Content-Type-Options": {
            "$ref": "#/components/headers/XContentTypeOptions"
          },
          "Referrer-Policy": {
            "$ref": "#/components/headers/ReferrerPolicy"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "unavailable",
              "message": "Service temporairement indisponible."
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "description": "Corps de toute réponse d’erreur. Aucun secret ni détail interne n’y figure.",
        "required": [
          "error",
          "message"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Code stable, lié au statut HTTP : 401 `unauthenticated`, 403 `forbidden`, 404 `not_found`, 409 `conflict`, 422 `invalid_request`, 429 `rate_limited`, 503 `unavailable`.",
            "enum": [
              "unauthenticated",
              "forbidden",
              "not_found",
              "conflict",
              "invalid_request",
              "rate_limited",
              "unavailable"
            ]
          },
          "message": {
            "type": "string",
            "description": "Message en français destiné à une personne. Peut changer : ne pas l’analyser."
          },
          "reason": {
            "type": "string",
            "description": "Prérequis manquant pour lancer un audit ; `message` nomme alors la variable ou le réglage à changer.",
            "enum": [
              "repository_audits_disabled",
              "repository_stopped",
              "repository_not_bound"
            ]
          }
        }
      },
      "RunConflict": {
        "description": "Erreur 409 d’une demande d’exécution, avec l’exécution existante quand la clé peut la lire.",
        "allOf": [
          {
            "$ref": "#/components/schemas/Error"
          },
          {
            "type": "object",
            "properties": {
              "existingRun": {
                "type": "object",
                "description": "Dernière tentative de l’issue. Présent seulement si la clé détient aussi `runs:read`.",
                "required": [
                  "id",
                  "status",
                  "links"
                ],
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Identifiant de l’exécution existante."
                  },
                  "status": {
                    "$ref": "#/components/schemas/RunStatus"
                  },
                  "links": {
                    "type": "object",
                    "required": [
                      "self"
                    ],
                    "properties": {
                      "self": {
                        "type": "string",
                        "description": "Chemin `/api/v1/runs/<runId>`."
                      }
                    }
                  }
                }
              }
            }
          }
        ]
      },
      "SelfLink": {
        "type": "object",
        "required": [
          "self"
        ],
        "properties": {
          "self": {
            "type": "string",
            "description": "Chemin de la ressource."
          }
        }
      },
      "Next": {
        "type": [
          "string",
          "null"
        ],
        "description": "Curseur de la page suivante, à passer dans `after` ; `null` en fin de liste."
      },
      "Project": {
        "type": "object",
        "required": [
          "id",
          "slug",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Identifiant du projet."
          },
          "slug": {
            "type": "string",
            "description": "Identifiant court du projet."
          },
          "name": {
            "type": "string",
            "description": "Nom du projet."
          }
        }
      },
      "ProjectPage": {
        "type": "object",
        "required": [
          "projects",
          "next"
        ],
        "properties": {
          "projects": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "$ref": "#/components/schemas/Project"
            }
          },
          "next": {
            "$ref": "#/components/schemas/Next"
          }
        }
      },
      "Repository": {
        "type": "object",
        "required": [
          "id",
          "fullName",
          "defaultBranch",
          "enabled"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Identifiant du dépôt dans 101Maintain."
          },
          "fullName": {
            "type": "string",
            "description": "Nom GitHub `organisation/dépôt`."
          },
          "defaultBranch": {
            "type": "string",
            "description": "Branche de base déclarée."
          },
          "enabled": {
            "type": "boolean",
            "description": "« Autoriser les travaux sur ce dépôt » : `false` si le dépôt est arrêté."
          }
        }
      },
      "RepositoryPage": {
        "type": "object",
        "required": [
          "repositories",
          "next"
        ],
        "properties": {
          "repositories": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "$ref": "#/components/schemas/Repository"
            }
          },
          "next": {
            "$ref": "#/components/schemas/Next"
          }
        }
      },
      "RunStatus": {
        "type": "string",
        "description": "État d’une exécution :\n- `queued` : demandée, pas encore prise par le worker ;\n- `running` : en cours ;\n- `prepared` : changement préparé (PR brouillon possible selon la politique) ;\n- `needs_input` : précisions requises ;\n- `refused` : refusée par une garde (revue, budget, contexte, arrêt global…) ;\n- `failed` : échec technique ;\n- `unknown` : issue incertaine (effet non confirmé) ;\n- `canceled` : annulée.",
        "enum": [
          "queued",
          "running",
          "prepared",
          "needs_input",
          "refused",
          "failed",
          "unknown",
          "canceled"
        ]
      },
      "RunRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "repositoryId",
          "issueNumber"
        ],
        "properties": {
          "repositoryId": {
            "type": "string",
            "format": "uuid",
            "description": "Dépôt du projet, actif, rattaché et sous surveillance."
          },
          "issueNumber": {
            "type": "integer",
            "minimum": 1,
            "description": "Numéro de l’issue GitHub, déjà reçue par le webhook. Doit être un entier JSON (pas une chaîne)."
          }
        }
      },
      "RunSummary": {
        "type": "object",
        "required": [
          "id",
          "status",
          "repositoryId",
          "issueNumber",
          "startedAt",
          "finishedAt",
          "links"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Identifiant de l’exécution."
          },
          "status": {
            "$ref": "#/components/schemas/RunStatus"
          },
          "repositoryId": {
            "type": "string",
            "format": "uuid",
            "description": "Dépôt de l’issue."
          },
          "issueNumber": {
            "type": "integer",
            "description": "Numéro de l’issue GitHub."
          },
          "startedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Début, `null` tant que l’exécution n’a pas démarré."
          },
          "finishedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Fin, `null` tant qu’elle n’est pas terminée."
          },
          "links": {
            "$ref": "#/components/schemas/SelfLink"
          }
        }
      },
      "RunPage": {
        "type": "object",
        "required": [
          "runs",
          "next"
        ],
        "properties": {
          "runs": {
            "type": "array",
            "maxItems": 50,
            "items": {
              "$ref": "#/components/schemas/RunSummary"
            }
          },
          "next": {
            "$ref": "#/components/schemas/Next"
          }
        }
      },
      "RunAccepted": {
        "type": "object",
        "required": [
          "id",
          "status",
          "repositoryId",
          "issueNumber",
          "links"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Identifiant de l’exécution créée."
          },
          "status": {
            "type": "string",
            "const": "queued",
            "description": "Toujours `queued` à la création."
          },
          "waiting": {
            "type": "string",
            "const": "organization_stop",
            "description": "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": {
            "type": "string",
            "format": "uuid",
            "description": "Dépôt demandé."
          },
          "issueNumber": {
            "type": "integer",
            "description": "Issue demandée."
          },
          "links": {
            "$ref": "#/components/schemas/SelfLink"
          }
        }
      },
      "RunResult": {
        "type": "object",
        "description": "Résultat sans contenu de fichier. Les champs présents dépendent de `status`.",
        "required": [
          "status"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "prepared",
              "needs_input",
              "refused",
              "canceled"
            ],
            "description": "Nature du résultat."
          },
          "reason": {
            "type": "string",
            "enum": [
              "review",
              "invalid",
              "context",
              "budget",
              "stale",
              "global_stop"
            ],
            "description": "Motif d’un refus : revue défavorable, sortie invalide, contexte insuffisant, budget, issue modifiée entre-temps, arrêt global."
          },
          "summary": {
            "type": "string",
            "description": "Résumé du changement préparé."
          },
          "questions": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Questions posées quand des précisions sont requises."
          },
          "changedFiles": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Chemins des fichiers modifiés (8 au plus), sans leur contenu."
          },
          "testsExecuted": {
            "type": "boolean",
            "const": false,
            "description": "Toujours `false` : les tests du dépôt ne sont pas exécutés par la plateforme."
          }
        }
      },
      "RunStep": {
        "type": "object",
        "required": [
          "sequence",
          "role",
          "status",
          "reused"
        ],
        "properties": {
          "sequence": {
            "type": "integer",
            "minimum": 1,
            "description": "Rang de l’étape."
          },
          "role": {
            "type": "string",
            "enum": [
              "explorer",
              "analyst",
              "designer",
              "developer",
              "reviewer"
            ],
            "description": "Agent : Exploration, Analyse, Conception, Développement, Revue."
          },
          "status": {
            "type": "string",
            "enum": [
              "running",
              "succeeded",
              "refused",
              "unknown"
            ],
            "description": "État de l’étape."
          },
          "reused": {
            "type": "boolean",
            "description": "`true` si le résultat d’une tentative précédente est réutilisé (aucun jeton facturé)."
          }
        }
      },
      "BudgetEnvelope": {
        "type": "object",
        "description": "Enveloppe de jetons.",
        "required": [
          "limit",
          "used",
          "held",
          "unknown",
          "remaining",
          "warning"
        ],
        "properties": {
          "limit": {
            "type": "integer",
            "description": "Plafond de jetons."
          },
          "used": {
            "type": "integer",
            "description": "Jetons consommés connus."
          },
          "held": {
            "type": "integer",
            "description": "Jetons réservés pour des appels sans consommation connue."
          },
          "unknown": {
            "type": "integer",
            "description": "Nombre d’appels à consommation inconnue."
          },
          "remaining": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Jetons restants ; `null` dès qu’une consommation est inconnue."
          },
          "warning": {
            "type": "boolean",
            "description": "`true` à partir de 80 % du plafond engagé, ou si une consommation est inconnue."
          }
        }
      },
      "RunBudgets": {
        "type": [
          "object",
          "null"
        ],
        "description": "Budgets de l’exécution et de l’issue ; `null` tant que l’exécution n’a pas démarré.",
        "properties": {
          "run": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/BudgetEnvelope"
              },
              {
                "type": "null"
              }
            ],
            "description": "Plafond par exécution, `null` si aucun."
          },
          "issue": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/BudgetEnvelope"
              },
              {
                "type": "null"
              }
            ],
            "description": "Budget cumulé de l’issue, `null` si aucun."
          }
        }
      },
      "Publication": {
        "type": [
          "object",
          "null"
        ],
        "description": "Publication GitHub de l’exécution ; `null` si aucune.",
        "required": [
          "status",
          "pullNumber"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "draft",
              "unknown",
              "published",
              "blocked"
            ],
            "description": "État de la publication."
          },
          "pullNumber": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Numéro de la PR brouillon, `null` tant qu’elle n’est pas confirmée."
          }
        }
      },
      "Run": {
        "type": "object",
        "description": "Détail d’une exécution, sans contenu de fichier.",
        "required": [
          "id",
          "projectId",
          "status",
          "repository",
          "issue",
          "requestedBy",
          "parentRunId",
          "startedAt",
          "finishedAt",
          "archivedAt",
          "result",
          "steps",
          "budgets",
          "publication",
          "nextAttempt",
          "links"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Identifiant de l’exécution."
          },
          "projectId": {
            "type": "string",
            "format": "uuid",
            "description": "Projet."
          },
          "status": {
            "$ref": "#/components/schemas/RunStatus"
          },
          "waiting": {
            "type": "string",
            "const": "organization_stop",
            "description": "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": {
            "type": "object",
            "required": [
              "id",
              "fullName"
            ],
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid",
                "description": "Dépôt."
              },
              "fullName": {
                "type": "string",
                "description": "`organisation/dépôt`."
              }
            }
          },
          "issue": {
            "type": "object",
            "required": [
              "number",
              "open"
            ],
            "properties": {
              "number": {
                "type": "integer",
                "description": "Numéro de l’issue."
              },
              "open": {
                "type": "boolean",
                "description": "Issue ouverte sur GitHub au dernier événement reçu."
              }
            }
          },
          "requestedBy": {
            "type": [
              "object",
              "null"
            ],
            "description": "Demandeur ; `null` pour une exécution démarrée par le webhook GitHub.",
            "required": [
              "userId",
              "apiKeyId"
            ],
            "properties": {
              "userId": {
                "type": "string",
                "format": "uuid",
                "description": "Compte demandeur (propriétaire de la clé le cas échéant)."
              },
              "apiKeyId": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "uuid",
                "description": "Clé utilisée ; `null` pour une demande depuis l’interface."
              }
            }
          },
          "parentRunId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "Tentative précédente pour une reprise, sinon `null`."
          },
          "startedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Début."
          },
          "finishedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Fin."
          },
          "archivedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Archivage dans l’interface."
          },
          "result": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/RunResult"
              },
              {
                "type": "null"
              }
            ],
            "description": "Résultat ; `null` tant qu’aucun n’est enregistré."
          },
          "steps": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/RunStep"
            },
            "description": "Étapes des agents."
          },
          "budgets": {
            "$ref": "#/components/schemas/RunBudgets"
          },
          "publication": {
            "$ref": "#/components/schemas/Publication"
          },
          "nextAttempt": {
            "type": [
              "object",
              "null"
            ],
            "description": "Reprise demandée après cette tentative, sinon `null`.",
            "required": [
              "id",
              "state"
            ],
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid",
                "description": "Identifiant de la reprise (lisible sur `/api/v1/runs/{id}`)."
              },
              "state": {
                "type": "string",
                "enum": [
                  "pending",
                  "canceled"
                ],
                "description": "État de la demande de reprise."
              }
            }
          },
          "links": {
            "type": "object",
            "required": [
              "self",
              "cancel",
              "usage"
            ],
            "properties": {
              "self": {
                "type": "string"
              },
              "cancel": {
                "type": "string",
                "description": "Route d’annulation."
              },
              "usage": {
                "type": "string",
                "description": "Consommation du projet."
              }
            }
          }
        }
      },
      "CancelAccepted": {
        "type": "object",
        "required": [
          "id",
          "cancelRequested",
          "status",
          "inFlight",
          "links"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Exécution."
          },
          "cancelRequested": {
            "type": "boolean",
            "const": true
          },
          "status": {
            "allOf": [
              {
                "$ref": "#/components/schemas/RunStatus"
              }
            ],
            "description": "Statut observé au moment de la demande (avant prise en compte de l’annulation)."
          },
          "inFlight": {
            "type": [
              "string",
              "null"
            ],
            "description": "Avertissement quand un appel au modèle est en cours, sinon `null`."
          },
          "links": {
            "$ref": "#/components/schemas/SelfLink"
          }
        }
      },
      "AuditRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "repositoryId"
        ],
        "properties": {
          "repositoryId": {
            "type": "string",
            "format": "uuid",
            "description": "Dépôt du projet, actif et rattaché à la GitHub App."
          },
          "checks": {
            "type": "array",
            "description": "Facultatif. S’il est fourni, il doit contenir exactement les trois contrôles statiques (ordre libre).",
            "minItems": 3,
            "maxItems": 3,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": [
                "secrets",
                "accessibility",
                "dependencies"
              ]
            }
          }
        }
      },
      "AuditStatus": {
        "type": "string",
        "description": "État d’un audit : `queued`, `running`, `complete` (tous contrôles complets), `partial` (couverture partielle), `refused`, `failed`, `unknown`.",
        "enum": [
          "queued",
          "running",
          "complete",
          "partial",
          "refused",
          "failed",
          "unknown"
        ]
      },
      "AuditSummary": {
        "type": "object",
        "required": [
          "id",
          "status",
          "repository",
          "createdAt",
          "links"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Identifiant de l’audit."
          },
          "status": {
            "$ref": "#/components/schemas/AuditStatus"
          },
          "repository": {
            "type": "string",
            "description": "`organisation/dépôt`."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "Date de la demande."
          },
          "links": {
            "$ref": "#/components/schemas/SelfLink"
          }
        }
      },
      "AuditPage": {
        "type": "object",
        "required": [
          "audits",
          "next"
        ],
        "properties": {
          "audits": {
            "type": "array",
            "maxItems": 30,
            "items": {
              "$ref": "#/components/schemas/AuditSummary"
            }
          },
          "next": {
            "$ref": "#/components/schemas/Next"
          }
        }
      },
      "AuditAccepted": {
        "type": "object",
        "required": [
          "id",
          "status",
          "repositoryId",
          "checks",
          "links"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Audit créé, ou audit déjà en file ou en cours pour ce dépôt."
          },
          "status": {
            "type": "string",
            "const": "queued"
          },
          "waiting": {
            "type": "string",
            "const": "organization_stop",
            "description": "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": {
            "type": "string",
            "format": "uuid",
            "description": "Dépôt demandé."
          },
          "checks": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "accessibility",
                "dependencies",
                "secrets"
              ]
            },
            "description": "Toujours les trois contrôles statiques."
          },
          "links": {
            "$ref": "#/components/schemas/SelfLink"
          }
        }
      },
      "AuditCheck": {
        "type": "object",
        "required": [
          "id",
          "state",
          "durationMs",
          "inspected",
          "skipped"
        ],
        "properties": {
          "id": {
            "type": "string",
            "enum": [
              "secrets",
              "accessibility",
              "dependencies"
            ]
          },
          "state": {
            "type": "string",
            "enum": [
              "complete",
              "partial",
              "unavailable"
            ],
            "description": "Couverture du contrôle."
          },
          "durationMs": {
            "type": "integer",
            "description": "Durée en millisecondes."
          },
          "inspected": {
            "type": "integer",
            "description": "Éléments inspectés."
          },
          "skipped": {
            "type": "integer",
            "description": "Éléments ignorés."
          }
        }
      },
      "AuditFinding": {
        "type": "object",
        "required": [
          "id",
          "rule",
          "location",
          "line",
          "status",
          "issue"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Identifiant du constat."
          },
          "rule": {
            "type": "string",
            "description": "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.",
            "examples": [
              "image_alt"
            ]
          },
          "location": {
            "type": [
              "string",
              "null"
            ],
            "description": "Chemin du fichier concerné."
          },
          "line": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Ligne, si connue."
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "accepted",
              "rejected"
            ],
            "description": "Qualification : à qualifier, validé, rejeté."
          },
          "issue": {
            "type": [
              "object",
              "null"
            ],
            "description": "Issue GitHub ouverte depuis le constat, sinon `null`.",
            "required": [
              "number",
              "status"
            ],
            "properties": {
              "number": {
                "type": "integer"
              },
              "status": {
                "type": "string",
                "enum": [
                  "queued",
                  "attempted",
                  "confirmed",
                  "blocked",
                  "public_hold"
                ]
              }
            }
          }
        }
      },
      "AuditBase": {
        "type": "object",
        "required": [
          "id",
          "projectId",
          "status",
          "repository",
          "baseSha",
          "checks",
          "finishedAt",
          "findings"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Identifiant de l’audit."
          },
          "projectId": {
            "type": "string",
            "format": "uuid",
            "description": "Projet."
          },
          "status": {
            "$ref": "#/components/schemas/AuditStatus"
          },
          "waiting": {
            "type": "string",
            "const": "organization_stop",
            "description": "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": {
            "type": "string",
            "description": "`organisation/dépôt`."
          },
          "baseSha": {
            "type": [
              "string",
              "null"
            ],
            "description": "Commit audité."
          },
          "checks": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AuditCheck"
            }
          },
          "finishedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Fin de l’audit."
          },
          "findings": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/AuditFinding"
            }
          }
        }
      },
      "Audit": {
        "allOf": [
          {
            "$ref": "#/components/schemas/AuditBase"
          },
          {
            "type": "object",
            "required": [
              "pendingQualification",
              "reportAvailable",
              "links"
            ],
            "properties": {
              "pendingQualification": {
                "type": "integer",
                "description": "Constats à qualifier."
              },
              "reportAvailable": {
                "type": "boolean",
                "description": "Rapport final lisible."
              },
              "links": {
                "type": "object",
                "required": [
                  "self",
                  "report"
                ],
                "properties": {
                  "self": {
                    "type": "string"
                  },
                  "report": {
                    "type": "string"
                  }
                }
              }
            }
          }
        ]
      },
      "AuditReport": {
        "description": "Rapport final : constats acceptés uniquement.",
        "allOf": [
          {
            "$ref": "#/components/schemas/AuditBase"
          },
          {
            "type": "object",
            "required": [
              "report",
              "links"
            ],
            "properties": {
              "report": {
                "type": "string",
                "const": "final"
              },
              "links": {
                "$ref": "#/components/schemas/SelfLink"
              }
            }
          }
        ]
      },
      "TokenUsage": {
        "type": "object",
        "required": [
          "input",
          "output",
          "total"
        ],
        "properties": {
          "input": {
            "type": "integer",
            "description": "Jetons d’entrée."
          },
          "output": {
            "type": "integer",
            "description": "Jetons de sortie."
          },
          "total": {
            "type": "integer",
            "description": "Total."
          },
          "cached": {
            "type": "integer",
            "description": "Jetons d’entrée en cache, si le fournisseur les donne."
          },
          "reasoning": {
            "type": "integer",
            "description": "Jetons de raisonnement, si le fournisseur les donne."
          }
        }
      },
      "RateSnapshot": {
        "type": "object",
        "description": "Tarif figé au moment de l’appel (prix par jeton, décimaux en chaîne).",
        "required": [
          "model",
          "currency",
          "input",
          "output",
          "effectiveFrom",
          "source"
        ],
        "properties": {
          "model": {
            "type": "string"
          },
          "currency": {
            "type": "string",
            "pattern": "^[A-Z]{3}$"
          },
          "input": {
            "type": "string"
          },
          "output": {
            "type": "string"
          },
          "cachedInput": {
            "type": "string"
          },
          "effectiveFrom": {
            "type": "string",
            "description": "Date d’effet."
          },
          "source": {
            "type": "string",
            "description": "Origine du tarif."
          }
        }
      },
      "UsageEntry": {
        "type": "object",
        "required": [
          "runId",
          "sequence",
          "role",
          "model",
          "kind",
          "repositoryId",
          "issueNumber",
          "pullNumber",
          "state",
          "rate",
          "usage",
          "cost",
          "reservedTokens",
          "heldTokens",
          "startedAt"
        ],
        "properties": {
          "runId": {
            "type": "string",
            "format": "uuid",
            "description": "Exécution."
          },
          "sequence": {
            "type": "integer",
            "description": "Étape."
          },
          "role": {
            "type": "string",
            "description": "Agent de l’étape."
          },
          "model": {
            "type": "string",
            "description": "Modèle appelé."
          },
          "kind": {
            "type": "string",
            "enum": [
              "live",
              "evaluation"
            ]
          },
          "repositoryId": {
            "type": "string",
            "format": "uuid",
            "description": "Dépôt."
          },
          "issueNumber": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Issue ; `null` pour le banc d’essai."
          },
          "pullNumber": {
            "type": [
              "integer",
              "null"
            ],
            "description": "PR brouillon rattachée."
          },
          "state": {
            "type": "string",
            "enum": [
              "reserved",
              "known",
              "unknown"
            ],
            "description": "Réservation en cours, consommation connue, consommation inconnue."
          },
          "rate": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/RateSnapshot"
              },
              {
                "type": "null"
              }
            ]
          },
          "usage": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/TokenUsage"
              },
              {
                "type": "null"
              }
            ]
          },
          "cost": {
            "type": [
              "string",
              "null"
            ],
            "description": "Coût décimal (12 décimales) dans la devise du tarif ; `null` si inconnu."
          },
          "reservedTokens": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Jetons réservés avant l’appel."
          },
          "heldTokens": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Jetons encore retenus : 0 si la consommation est connue."
          },
          "startedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Début de l’appel."
          }
        }
      },
      "UsageCounters": {
        "type": "object",
        "description": "Compteurs sur la période et les filtres, en chaînes décimales entières.",
        "required": [
          "calls",
          "unknown",
          "pending",
          "unknown_costs",
          "unknown_cached",
          "unknown_reasoning",
          "held",
          "input",
          "output",
          "cached",
          "reasoning",
          "total"
        ],
        "properties": {
          "calls": {
            "type": "string",
            "pattern": "^\\d+$",
            "description": "Appels au modèle."
          },
          "unknown": {
            "type": "string",
            "pattern": "^\\d+$",
            "description": "Appels à consommation inconnue."
          },
          "pending": {
            "type": "string",
            "pattern": "^\\d+$",
            "description": "Appels encore en réservation."
          },
          "unknown_costs": {
            "type": "string",
            "pattern": "^\\d+$",
            "description": "Appels terminés sans coût connu."
          },
          "unknown_cached": {
            "type": "string",
            "pattern": "^\\d+$",
            "description": "Appels connus sans information de cache."
          },
          "unknown_reasoning": {
            "type": "string",
            "pattern": "^\\d+$",
            "description": "Appels connus sans information de raisonnement."
          },
          "held": {
            "type": "string",
            "pattern": "^\\d+$",
            "description": "Jetons retenus pour les appels non connus."
          },
          "input": {
            "type": "string",
            "pattern": "^\\d+$",
            "description": "Jetons d’entrée connus."
          },
          "output": {
            "type": "string",
            "pattern": "^\\d+$",
            "description": "Jetons de sortie connus."
          },
          "cached": {
            "type": "string",
            "pattern": "^\\d+$",
            "description": "Jetons en cache connus."
          },
          "reasoning": {
            "type": "string",
            "pattern": "^\\d+$",
            "description": "Jetons de raisonnement connus."
          },
          "total": {
            "type": "string",
            "pattern": "^\\d+$",
            "description": "Total de jetons connus."
          }
        }
      },
      "UsageReport": {
        "type": "object",
        "required": [
          "kind",
          "period",
          "counters",
          "knownCosts",
          "entries",
          "next"
        ],
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "live",
              "evaluation"
            ]
          },
          "period": {
            "type": "object",
            "required": [
              "from",
              "to"
            ],
            "properties": {
              "from": {
                "type": "string",
                "format": "date-time",
                "description": "Début inclus."
              },
              "to": {
                "type": "string",
                "format": "date-time",
                "description": "Fin exclue."
              }
            }
          },
          "counters": {
            "$ref": "#/components/schemas/UsageCounters"
          },
          "knownCosts": {
            "type": "array",
            "description": "Somme des coûts connus par devise.",
            "items": {
              "type": "object",
              "required": [
                "currency",
                "amount"
              ],
              "properties": {
                "currency": {
                  "type": "string"
                },
                "amount": {
                  "type": "string",
                  "description": "Montant décimal (12 décimales)."
                }
              }
            }
          },
          "entries": {
            "type": "array",
            "maxItems": 100,
            "items": {
              "$ref": "#/components/schemas/UsageEntry"
            }
          },
          "next": {
            "type": [
              "string",
              "null"
            ],
            "description": "Curseur opaque de la page suivante, à passer dans `after`."
          }
        }
      }
    }
  },
  "x-scopes": {
    "projects:read": {
      "label": "Lire les projets",
      "minimumRole": "reader"
    },
    "repositories:read": {
      "label": "Lire les dépôts",
      "minimumRole": "reader"
    },
    "runs:read": {
      "label": "Lire les exécutions",
      "minimumRole": "reader"
    },
    "runs:create": {
      "label": "Démarrer une exécution",
      "minimumRole": "operator"
    },
    "runs:cancel": {
      "label": "Annuler une exécution",
      "minimumRole": "operator"
    },
    "audits:read": {
      "label": "Lire les audits",
      "minimumRole": "reader"
    },
    "audits:create": {
      "label": "Demander un audit",
      "minimumRole": "operator"
    },
    "reports:read": {
      "label": "Lire les rapports",
      "minimumRole": "reader"
    },
    "usage:read": {
      "label": "Lire la consommation",
      "minimumRole": "reader"
    }
  },
  "x-not-exposed": {
    "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."
  }
}
