# L'API

> Ce que vous pouvez appeler par programme aujourd'hui : vérification de la barrière de livraison pour la CI, avec une clé API, et clés publiques des dossiers de preuves. L'API est limitée en bêta.

Source: https://aicodeops.dev/fr/docs/api

AI CodeOps s'utilise dans le navigateur. Pendant la bêta ouverte, l'API par programme est volontairement réduite : un point de terminaison pour la CI, plus les clés publiques qui permettent à chacun de vérifier un dossier de preuves. Tout le reste de la console nécessite une session de navigateur connectée et n'est pas une API prise en charge.

## Clés API de l'espace de travail

Créez une clé sous **Configure → API Keys**. Donnez-lui un nom ; le secret (il commence par `sk-`) n'est affiché qu'une fois, copiez-le donc à ce moment-là. AI CodeOps ne stocke qu'une empreinte.

- Une clé agit au nom du membre qui l'a créée, avec le rôle actuel de ce membre. Si le membre est retiré ou si son rôle perd une permission, la clé la perd aussi.
- Les rôles Owner, Admin, Developer et Member peuvent créer des clés. Le rôle Viewer ne le peut pas.
- Les Admins voient toutes les clés de l'espace de travail ; les autres voient les leurs.
- **Delete** révoque une clé immédiatement. Les intégrations qui l'utilisent cessent de fonctionner aussitôt.

Lorsque votre offre inclut la limitation du périmètre des clés, un administrateur peut choisir **Scope** pour limiter une clé à une liste d'adresses IP autorisées (plages CIDR), à une limite de débit par minute, à une date d'expiration et à ce pour quoi elle peut être utilisée : les appels à la passerelle de modèles, la vérification de la barrière de livraison, ou les deux (la valeur par défaut).

Envoyez la clé comme Bearer token :

```http
Authorization: Bearer sk-...
```

## Vérification de la barrière de livraison

`POST /api/release/check` répond à une question pour votre CI : cette pull request ou ce commit peut-il être livré ? Il applique les mêmes contrôles que les [barrières qualité](https://aicodeops.dev/fr/docs/quality-gates) sur l'ensemble des sessions qui ont touché au changement. La clé nécessite la permission `workspace:read`.

```bash
curl -sf -X POST "https://console.aicodeops.dev/api/release/check" \
  -H "Authorization: Bearer $WORKSPACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pullRequestURL":"https://github.com/acme/api/pull/42"}'
```

Utilisez le même hôte que celui sur lequel vous ouvrez la console. [Barrière de livraison dans la CI](https://aicodeops.dev/fr/docs/release-gate-ci) propose des jobs à copier pour GitHub Actions, GitLab CI, Bitbucket Pipelines, et Forgejo et Gitea Actions.

### Champs de la requête

| Champ                 | Type                                                                                             | Valeur par défaut                       |
| --------------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------- |
| `pullRequestURL`      | URL                                                                                              | l'un de ces deux champs est obligatoire |
| `commitSHA`           | chaîne, 7 caractères ou plus                                                                     |                                         |
| `blockingSeverity`    | `critical`, `high`, `medium`, `low`, `info`                                                      | `high`                                  |
| `blockOnTestFailure`  | booléen : des tests en échec bloquent, tout comme un changement de code sans résultat de test    | `true`                                  |
| `blockOnBuildFailure` | booléen : un build du dépôt qui n'a pas réussi bloque                                            | `true`                                  |
| `minCoveragePct`      | nombre de 0 à 100 : un seuil de couverture ; refuse si aucune couverture n'a été indiquée        | non contrôlé                            |
| `requiredWorkflows`   | tableau de chaînes                                                                               | aucun                                   |
| `disallowedLicenses`  | tableau de chaînes, vérifié par rapport au SBOM du projet                                        | aucun                                   |
| `requireDeployedTo`   | nom d'environnement, p. ex. `staging`                                                            | aucun                                   |
| `blockOnInFlight`     | booléen : refuser tant qu'une exécution est encore en cours                                      | `false`                                 |
| `lookbackMs`          | jusqu'où remonter dans le temps, en millisecondes                                                | 14 jours                                |
| `workspaceID`         | identifiant de l'espace de travail : uniquement lorsque vous appelez avec une session de console | l'espace de travail de la clé API       |

`GET /api/release/check` accepte les mêmes noms comme paramètres de requête (listes séparées par des virgules).

**Preuve par les tests.** Avec `blockOnTestFailure` activé, ce qui est la valeur par défaut, chaque session qui a modifié du code dans un projet a besoin d'un résultat de test avec des décomptes. Si aucun test ne s'est exécuté pour elle, ou si la commande de test s'est exécutée sans indiquer de décomptes, la vérification refuse : « The test command ran but reported no test counts, so nothing shows a test passed. Check the project's test command ». Une absence de preuve n'est pas une réussite. Pour un projet sans suite de tests, activez **Don't run tests for this project** dans les réglages du projet, sous **Plan → Projects** ; la vérification ne demande alors aucun résultat de test. La règle ne s'applique pas non plus à une session qui n'a modifié aucun code, ni lorsque vous envoyez `"blockOnTestFailure": false`.

**Seuil de couverture.** Lorsque `minCoveragePct` est défini, l'exécution de tests la plus récente ayant indiqué une couverture doit l'atteindre. Si aucune exécution de tests sur le changement n'a indiqué de couverture, la vérification refuse : « Coverage wasn't reported, so the 80% floor can't be checked ». Un seuil qui ne peut pas être vérifié ne passe pas. Faites en sorte que la commande de test du projet affiche un résumé de couverture avant de définir un seuil. Omettez `minCoveragePct` et la couverture n'est pas contrôlée.

**Appeler avec une session de console.** Une clé API porte son espace de travail : la CI n'envoie donc pas de `workspaceID`. Une session de console connectée peut aussi appeler le point de terminaison, et elle doit nommer l'espace de travail : ajoutez `?workspaceID=<id>` à l'URL, ou placez `workspaceID` dans le corps JSON d'un `POST`. Sans cela, la réponse est `400`. L'identifiant est la partie qui suit `/workspace/` dans l'adresse de la console.

### Réponse

Le point de terminaison renvoie `200` dans les deux cas. Lisez `allowed` :

- `allowed` : `true` ou `false`
- `summary` et `reasons` : des explications en anglais simple
- `blockingFindings`, `testFailures`, `testEvidenceMissing`, `coverageShortfall`, `coverageNotReported`, `licenseViolations`, `licenseEvidenceMissing` : les détails qui motivent un refus (`licenseEvidenceMissing` liste les projets sans SBOM à vérifier lorsque vous transmettez `disallowedLicenses`)
- `testEvidenceMissing` : un `{ "workflowRunID", "reason" }` pour chaque session qui a modifié du code et n'a pas de résultat de test avec des décomptes ; une liste vide lorsque rien ne manque
- `coverageNotReported` : `{ "required": 80 }` lorsque vous définissez un seuil et qu'aucune exécution de tests n'a indiqué de couverture ; `null` lorsqu'un chiffre de couverture existe ou qu'aucun seuil n'est défini
- `runsConsidered` : les sessions sur lesquelles le verdict s'est fondé

Un changement sans session correspondante est refusé (« No workflow runs found for … »). Il en va de même pour un changement de code sans résultat de test, comme décrit sous Preuve par les tests ci-dessus. Si l'évaluation échoue, vous obtenez `allowed: false` avec le résumé « Evaluation failed », de sorte qu'une vérification défaillante ne valide jamais un changement.

### Erreurs

| Statut | Signification                                                                                                                                                                           |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400    | JSON invalide ou champs invalides. Avec une session de console : `workspaceID` est manquant, et le message l'indique                                                                    |
| 401    | Ni clé API ni session de console, ou la clé n'est pas valide                                                                                                                            |
| 403    | Le périmètre de la clé ou le rôle de son créateur ne le permet pas, ou la clé appartient à un autre espace de travail. Avec une session : vous n'êtes pas membre de l'espace de travail |
| 429    | Plus de 60 vérifications par minute pour l'espace de travail ; voir `Retry-After`                                                                                                       |

La même vérification se trouve dans la console sous **Review & Gate → Release gate**, avec un job de CI à copier.

## Clés des dossiers de preuves

`GET /api/evidence?action=keys` est public et ne nécessite aucune clé. Il renvoie les clés publiques Ed25519 qui signent les [dossiers de preuves](https://aicodeops.dev/fr/docs/evidence-packs), ce qui vous permet de vérifier un dossier hors ligne. Télécharger un dossier nécessite un membre connecté ayant l'accès à l'audit ; ce n'est pas possible avec une clé API.

## Référence de l'API

Une page par point de terminaison, générée à partir de la [spécification OpenAPI](https://aicodeops.dev/docs/api/openapi.json) :

- [Vérifier si une pull request ou un commit peut être livré](https://aicodeops.dev/docs/api/release-check)
- [Les clés qui signent les dossiers de preuves](https://aicodeops.dev/docs/api/evidence-keys)
- [Vérifier un dossier de preuves](https://aicodeops.dev/docs/api/evidence-verify)
- [Liveness et readiness](https://aicodeops.dev/docs/api/health)
- [État des composants](https://aicodeops.dev/docs/api/status)

## Étapes suivantes

- [Barrière de livraison dans la CI](https://aicodeops.dev/fr/docs/release-gate-ci)
- [Barrières qualité](https://aicodeops.dev/fr/docs/quality-gates)
- [Membres et rôles](https://aicodeops.dev/fr/docs/members)
- [Dépannage](https://aicodeops.dev/fr/docs/troubleshooting)

## Questions fréquentes

### Existe-t-il une API REST complète pour les sessions et les projets ?

Pas encore. Pendant la bêta ouverte, la console est le moyen d'exécuter des sessions et de gérer des projets. Les points de terminaison de cette page sont ceux qui acceptent un accès par programme.

### Les clés API expirent-elles ?

Pas par défaut. Une clé fonctionne jusqu'à ce qu'elle soit supprimée, que son créateur quitte l'espace de travail ou qu'une date d'expiration définie dans son périmètre soit dépassée.
