---
title: Vue d'ensemble de l'API
description: Ce que l'API externe de 101Maintain permet de faire avec une clé personnelle, et ce qu'elle ne permet pas.
---

# 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](../01-prise-en-main/03-roles-et-droits.md).

## 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](reference-api.md). Le contrat machine est publié au format OpenAPI 3.1 sur le site de documentation (voir [Ressources pour agents IA](07-agent-ia.md)). 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](02-cles-api-personnelles.md).
- **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](03-authentification-et-scopes.md).
- **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](04-idempotence-et-quotas.md).
- **Erreurs uniformes.** Toute erreur renvoie un corps JSON `{ "error": "…", "message": "…" }`. Voir [Erreurs](05-erreurs.md).
- **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
}
```

> [!TIP]
> Conservez la clé dans un gestionnaire de secrets et passez-la par une variable d'environnement, comme `$MAINTAIN_API_KEY` dans tous les exemples de ce chapitre.

## Pour continuer

Créez votre première clé : [Clés API personnelles](02-cles-api-personnelles.md).
