Intégration API

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#

BesoinRouteDroit de la clé
Lister les projets accessiblesGET /api/v1/projectsLire les projets
Lister les dépôts d'un projetGET /api/v1/projects/<projectId>/repositoriesLire les dépôts
Lister les exécutions d'un projetGET /api/v1/projects/<projectId>/runsLire les exécutions
Demander une exécution sur une issuePOST /api/v1/projects/<projectId>/runsDémarrer une exécution
Suivre une exécutionGET /api/v1/runs/<runId>Lire les exécutions
Annuler une exécutionPOST /api/v1/runs/<runId>/cancelAnnuler une exécution
Télécharger le rapport d'incident (PDF)GET /api/v1/runs/<runId>/reportLire les rapports
Lister les audits d'un projetGET /api/v1/projects/<projectId>/auditsLire les audits
Demander un audit statiquePOST /api/v1/projects/<projectId>/auditsDemander un audit
Lire un audit et ses constatsGET /api/v1/audits/<auditId>Lire les audits
Lire le rapport final d'un auditGET /api/v1/audits/<auditId>/reportLire les rapports
Lire la consommation d'un projetGET /api/v1/projects/<projectId>/usageLire 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 Accepted avec l'adresse de suivi dans l'en-tête Location. 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#

bash
curl -sS https://maintain.example/api/v1/projects \
  -H "Authorization: Bearer $MAINTAIN_API_KEY"

Réponse :

json
{
  "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.