Vue d'ensemble de l'API
L'API externe permet à un outil tiers (CI, script, tableau de bord, agent IA) de déclencher et de suivre des exécutions et des audits. Elle agit toujours au nom du compte qui a créé la clé, avec ses droits actuels.
Qui peut le faire : tout compte actif peut créer une clé personnelle. La clé ne donne jamais plus que les droits de son propriétaire sur le projet : un Lecteur obtient une clé de lecture, un Opérateur peut aussi démarrer et annuler. Voir Rôles et droits.
Ce que vous pouvez faire#
| Besoin | Route | Droit de la clé |
|---|---|---|
| Lister les projets accessibles | GET /api/v1/projects | Lire les projets |
| Lister les dépôts d'un projet | GET /api/v1/projects/<projectId>/repositories | Lire les dépôts |
| Lister les exécutions d'un projet | GET /api/v1/projects/<projectId>/runs | Lire les exécutions |
| Demander une exécution sur une issue | POST /api/v1/projects/<projectId>/runs | Démarrer une exécution |
| Suivre une exécution | GET /api/v1/runs/<runId> | Lire les exécutions |
| Annuler une exécution | POST /api/v1/runs/<runId>/cancel | Annuler une exécution |
| Télécharger le rapport d'incident (PDF) | GET /api/v1/runs/<runId>/report | Lire les rapports |
| Lister les audits d'un projet | GET /api/v1/projects/<projectId>/audits | Lire les audits |
| Demander un audit statique | POST /api/v1/projects/<projectId>/audits | Demander un audit |
| Lire un audit et ses constats | GET /api/v1/audits/<auditId> | Lire les audits |
| Lire le rapport final d'un audit | GET /api/v1/audits/<auditId>/report | Lire les rapports |
| Lire la consommation d'un projet | GET /api/v1/projects/<projectId>/usage | Lire la consommation |
Toutes les routes sont décrites champ par champ dans la référence de l'API. Le contrat machine est publié au format OpenAPI 3.1 sur le site de documentation (voir Ressources pour agents IA). Votre instance sert aussi son propre contrat, plus succinct, à https://maintain.example/api/v1/openapi.json, sans authentification.
Ce que l'API ne permet pas#
Certaines décisions restent réservées aux personnes, dans l'interface :
- qualifier un constat (valider ou rejeter) et demander une édition PDF d'un rapport ;
- répondre aux questions d'une exécution, la reprendre, refaire le code, l'archiver ou la publier ;
- lancer des contrôles dynamiques sur une recette (ils exigent un accord de recette) ;
- gérer les comptes, les membres, les politiques des dépôts, les intégrations, les clés API ou l'arrêt global.
Le contrat OpenAPI liste ces refus sous l'extension x-not-exposed.
Principes de fonctionnement#
- Une clé, un propriétaire. Chaque appel est inscrit au journal des actions avec le compte propriétaire et la clé utilisée. Voir Clés API personnelles.
- Droits relus à chaque appel. Un rôle retiré, un projet ôté de la clé, un compte suspendu ou une clé révoquée bloquent immédiatement les appels suivants. Voir Authentification et scopes.
- Créations asynchrones. Une demande d'exécution ou d'audit répond
202 Acceptedavec l'adresse de suivi dans l'en-têteLocation. Vous interrogez ensuite cette adresse. - Réessais sans doublon. Chaque création exige un en-tête
Idempotency-Key. Voir Idempotence, pagination et quotas. - Erreurs uniformes. Toute erreur renvoie un corps JSON
{ "error": "…", "message": "…" }. Voir Erreurs. - Aucun rappel sortant. La plateforme n'appelle pas votre outil : c'est à lui d'interroger l'état.
Un premier appel#
curl -sS https://maintain.example/api/v1/projects \
-H "Authorization: Bearer $MAINTAIN_API_KEY"Réponse :
{
"projects": [
{ "id": "3f6c1a52-7b0e-4c1d-9a6e-2b8f4d5c6e71", "slug": "boutique", "name": "Boutique en ligne" }
],
"next": null
}Pour continuer#
Créez votre première clé : Clés API personnelles.