# Référence API

La définition complète, lisible par machine de l'API Maetra vit dans `openapi.yaml` (OpenAPI 3.1). Il couvre Govern, Secure, Task Guard, Agents, et les opérations du système.

> **Note**
> **Câblage des spécifications dans GitBook.** Ajouter le fichier OpenAPI comme source de référence de l'API : **Paramètres de l'organisation → Intégrations → OpenAPI**, téléchargement `openapi.yaml` (ou pointer à une URL hébergée), puis insérer un **Bloc OpenAPI** sur cette page.


### Opérations

Tous les paramètres sont fournis à partir de `https://api.maetra.io` et nécessitent une [Clé API du porteur](https://maetra.io/fr/docs/getting-started/authentication) sauf indication contraire.

#### Govern

| Méthode | Voie | Portée | Docteurs |
| ------ | --------------------------- | -------------------------- | ----------------------------------------- |
| `POST` | `/v1/checkpoints` | `govern:checkpoints:write` | [Points de contrôle](https://maetra.io/fr/docs/govern-api/checkpoints) |
| `GET` | `/v1/checkpoints/{id}` | `govern:checkpoints:read` | [Points de contrôle](https://maetra.io/fr/docs/govern-api/checkpoints) |
| `GET` | `/v1/checkpoints/{id}/wait` | `govern:checkpoints:read` | [Points de contrôle](https://maetra.io/fr/docs/govern-api/checkpoints) |
| `GET` | `/v1/policies/active` | `govern:policies:read` | [Politiques](https://maetra.io/fr/docs/govern-api/policies) |

#### Secure

| Méthode | Voie | Portée | Docteurs |
| ------- | ----------------------- | ----------------------- | --------------------------------------------------- |
| `GET` | `/v1/secure/rules` | `secure:rules:read` | [Règles](https://maetra.io/fr/docs/secure-api/rules) |
| `POST` | `/v1/secure/rules` | `secure:rules:write` | [Règles](https://maetra.io/fr/docs/secure-api/rules) |
| `PATCH` | `/v1/secure/rules/{id}` | `secure:rules:write` | [Règles](https://maetra.io/fr/docs/secure-api/rules) |
| `POST` | `/v1/secure/scan` | `secure:scan:write` | [Analyse du contenu](https://maetra.io/fr/docs/secure-api/scanning-content) |
| `GET` | `/v1/secure/incidents` | `secure:incidents:read` | [Événements](https://maetra.io/fr/docs/secure-api/incidents) |

#### Agents

| Méthode | Voie | Portée | Docteurs |
| ------ | ------------ | ---------------------- | -------------------- |
| `GET` | `/v1/agents` | `discover:agents:read` | [Agents](https://maetra.io/fr/docs/agents) |

#### Task Guard

| Méthode | Voie | Portée | Docteurs |
| ------ | ---- | ----- | ---- |
| `POST` | `/v1/task-guard/tools/{tool}` | Dépend de l'outil | [API Task Guard](https://maetra.io/fr/docs/task-guard-api) |
| `POST` | `/v1/task-guard/sessions` | `task_guard:tasks:write` | [Tâches et contexte](https://maetra.io/fr/docs/task-guard-api/tasks-and-context) |
| `POST` | `/v1/task-guard/tasks` | `task_guard:tasks:write` | [Tâches et contexte](https://maetra.io/fr/docs/task-guard-api/tasks-and-context) |
| `POST` | `/v1/task-guard/sessions/{sessionId}/user-events` | `task_guard:confirmations:write` + justificatif de confiance | [Tâches et contexte](https://maetra.io/fr/docs/task-guard-api/tasks-and-context) |
| `GET` | `/v1/task-guard/tasks/{taskId}` | `task_guard:tasks:read` | [Tâches et contexte](https://maetra.io/fr/docs/task-guard-api/tasks-and-context) |
| `GET` | `/v1/task-guard/tasks/{taskId}/context` | `task_guard:tasks:read` | [Tâches et contexte](https://maetra.io/fr/docs/task-guard-api/tasks-and-context) |
| `POST` | `/v1/task-guard/tasks/{taskId}/progress` | `task_guard:tasks:write` | [Tâches et contexte](https://maetra.io/fr/docs/task-guard-api/tasks-and-context) |
| `POST` | `/v1/task-guard/tasks/{taskId}/pause` | `task_guard:tasks:write` | [Tâches et contexte](https://maetra.io/fr/docs/task-guard-api/tasks-and-context) |
| `POST` | `/v1/task-guard/tasks/{taskId}/resume` | `task_guard:tasks:write` | [Tâches et contexte](https://maetra.io/fr/docs/task-guard-api/tasks-and-context) |
| `POST` | `/v1/task-guard/tasks/{taskId}/cancel` | `task_guard:tasks:write` | [Tâches et contexte](https://maetra.io/fr/docs/task-guard-api/tasks-and-context) |
| `POST` | `/v1/task-guard/tasks/{taskId}/complete` | `task_guard:tasks:write` | [Tâches et contexte](https://maetra.io/fr/docs/task-guard-api/tasks-and-context) |
| `POST` | `/v1/task-guard/tasks/{taskId}/checks` | `task_guard:checks:write` | [Alignement et effets](https://maetra.io/fr/docs/task-guard-api/alignment-and-effects) |
| `POST` | `/v1/task-guard/tasks/{taskId}/changes` | `task_guard:checks:write` | [Alignement et effets](https://maetra.io/fr/docs/task-guard-api/alignment-and-effects) |
| `POST` | `/v1/task-guard/checks/{checkId}/explanation` | `task_guard:checks:write` | [Alignement et effets](https://maetra.io/fr/docs/task-guard-api/alignment-and-effects) |
| `POST` | `/v1/task-guard/checks/{checkId}/effects` | `task_guard:effects:write` | [Alignement et effets](https://maetra.io/fr/docs/task-guard-api/alignment-and-effects) |
| `POST` | `/v1/task-guard/changes/{proposalId}/confirmation` | `task_guard:confirmations:write` + justificatif de confiance | [Alignement et effets](https://maetra.io/fr/docs/task-guard-api/alignment-and-effects) |
| `POST` | `/v1/task-guard/alignment/verify` | `task_guard:checks:write` | [Alignement et effets](https://maetra.io/fr/docs/task-guard-api/alignment-and-effects) |

#### Système

| Méthode | Voie | Resp.: Ministère de l'Agriculture | Docteurs |
| ------ | ------------------------ | ------------- | ---------------------------------------------------- |
| `GET` | `/v1/ping` | Toute clé valide | [Authentification](https://maetra.io/fr/docs/getting-started/authentication) |
| `GET` | `/.well-known/jwks.json` | Aucune | [Jetons de décision](https://maetra.io/fr/docs/govern-api/decision-tokens) |