Référence de l'API¶
Guide d'usage : API. Le contrat complet (schémas d'entrée de chaque opération) est servi par l'instance : GET /api/v1/openapi.json (153 opérations du socle, sans authentification ; avec un jeton, s'y ajoutent les opérations de plugins accessibles à ce jeton).
Enveloppe¶
{"ok": true, "result": {}}
{"ok": false, "error": {"code": "denied", "message": "…"}}
Routes fixes¶
Toute opération est appelée par POST /api/v1/ops/<nom> (corps JSON = arguments).
| Méthode | Chemin | Rôle |
|---|---|---|
| GET | /api/v1/chat/runs/{run_id}/events |
Flux SSE d'un run de chat |
| POST | /api/v1/chat/{agent} |
Envoyer un message à un agent (chat web) |
| GET | /api/v1/cli/manifest |
Manifeste de la CLI (identique à la liste des ops) |
| GET | /api/v1/events |
Flux d'événements (SSE) |
| POST | /api/v1/files |
Déposer un fichier |
| GET | /api/v1/files/{file_id} |
Lire un fichier déposé |
| GET | /api/v1/logs |
Journaux de l'instance |
| GET | /api/v1/notifications |
Mes notifications |
| GET | /api/v1/openapi.json |
Ce document |
| GET | /api/v1/ops |
Opérations que l'appelant peut appeler |
| GET | /api/v1/ops/{name} |
Décrire une op |
| POST | /api/v1/ops/{name} |
Appeler une op (forme générique) |
| POST | /api/v1/runs/{run_id}/token |
Renouveler le jeton d'un run en cours |
| GET | /api/v1/whoami |
Identité de l'appelant |
Erreurs¶
| HTTP | Code | Sens |
|---|---|---|
| 202 | pending_confirmation |
Action acceptée mais en attente d'approbation hors bande (confirmation_id). |
| 400 | invalid_json / invalid_input |
Corps non JSON, ou arguments refusés par le schéma de l'op. |
| 401 | unauthenticated |
Aucune authentification valide (jeton absent, expiré, révoqué, IP non autorisée). |
| 403 | denied / reauth_required |
Permission refusée par le PDP, ou ré-authentification humaine récente exigée. |
| 404 | NotFound |
Op ou objet inconnu (un refus de lecture est indiscernable d'une absence). |
| 409 | conflict |
L'objet existe déjà. |
| 500 | internal |
Erreur interne ; l'identifiant de requête (X-Request-Id) permet de la retrouver. |