Référence API (OpenAPI et exemples)

English version: ../../en/guides/api-reference.md

Cette page est le point d'entrée de la référence API de la Navin Platform. Elle présente les deux API, où se trouve leur référence sur le site de documentation et dans le dépôt, comment s'authentifier, et comment fonctionnent les erreurs, les pages, les reprises et les traces. Qui : développeurs et intégrateurs.

Les deux API

API	Ce qu'elle sert	Préfixe	Identifiant	Référence sur le site de documentation	Source de la référence
API du Control Plane	tenants et projets, identités et accès, agents et exécutions, modèles et passerelle LLM, connaissances, outils et MCP, gouvernance, sécurité, FinOps ; chaque écran du portail, SDK et commande CLI passe par elle	`/v1`	jeton OIDC, session du portail ou clé d'API `eai_...`	`/api/control-plane`	`docs/api/openapi-v1.json`
API du Navin Manager	l'infrastructure de la plateforme : hôtes, clusters, services, haute disponibilité, sauvegardes, restaurations et reprise après sinistre	`/api/v1` du Navin Manager	jeton d'API du manager `nmt_...`	`/api/manager`	`navin-manager/docs/api/manager-openapi.json`

Sur le site de documentation, ouvrez /api/control-plane pour l'API du Control Plane et /api/manager pour l'API du Navin Manager. Dans ce dépôt, lisez l'API du Control Plane route par route et les SDK et CLI du Navin Manager pour l'API du Navin Manager. Dans le portail, Portail développeur > Référence API pointe vers /docs, /redoc et /openapi.json de votre Control Plane et affiche sa version.

remarque

Quand la documentation est activée sur un serveur du Control Plane, le serveur sert lui-même la référence sur /redoc, la console interactive sur /docs et le contrat machine sur /openapi.json.

Sources de vérité

Le schéma OpenAPI publié est docs/api/openapi-v1.json, généré depuis l'application FastAPI par services/control-plane/src/eai/api_openapi.py (un changement cassant est refusé). La surface des requêtes est docs/api/control-plane-v1.requests.json et la description route par route docs/api/control-plane-v1.md. Les contrats JSON Schema sont dans contracts/v1.

cd services/control-plane
.venv/bin/python -m eai.api_openapi --check
.venv/bin/python -m eai.api_surface --check

Le schéma du Navin Manager navin-manager/docs/api/manager-openapi.json est écrit depuis le serveur par tools/manager/openapi.py, et ses clients Python, TypeScript et Go en sont générés par tools/manager/gen_sdks.py.

Authentification

Le tenant d'un appel au Control Plane vient toujours de l'identifiant, jamais du corps de la requête.

Identifiant	En-tête	Appelant type
Jeton d'accès OIDC émis par Keycloak	`Authorization: Bearer <token>`	utilisateurs du portail, des SDK et de la CLI après connexion
Session du portail `eais_...` ouverte par POST /v1/auth/login	`Authorization: Bearer eais_...`	comptes locaux
Clé d'API `eai_...`	`X-API-Key: eai_...` ou `Authorization: Bearer eai_...`	scripts, chaînes CI, services back end
Jeton d'API du Navin Manager `nmt_...`	`Authorization: Bearer nmt_...` sur l'API du Navin Manager	automatisation de l'infrastructure

Le Navin Manager accepte aussi X-NM-On-Behalf-Of: <user> d'un jeton qui détient auth:delegate ; tout autre appelant reçoit 403 on_behalf_of_forbidden.

Exemples

Lister les contrats (GET /v1/contracts), valider un manifeste (POST /v1/contracts/{name}/validate), démarrer un run (POST /v1/agents/{agent_id}/runs) et lire ses étapes (GET /v1/runs/{run_id}/steps).

curl -H "X-API-Key: $EAI_API_KEY" https://ai.acme.example/v1/contracts
curl -X POST -H "X-API-Key: $EAI_API_KEY" -H 'Content-Type: application/json' \
  -d @agent.json https://ai.acme.example/v1/contracts/agent-manifest/validate

Premiers appels

Vérifier qui vous êtes. La réponse prouve que l'identifiant fonctionne et montre le tenant, les rôles et les droits que le serveur en a tirés.
```
curl -H "X-API-Key: $EAI_API_KEY" https://ai.acme.example/v1/me
```
Résultat attendu : 200 avec votre principal.

En cas d'échec : 401 unauthenticated (aucun identifiant), 401 invalid_api_key ou 401 api_key_revoked.
Vérifier la version de l'API. GET /v1/meta donne la version du serveur et la version de l'API ; un client écrit pour /v1 attend v1.
```
curl -H "X-API-Key: $EAI_API_KEY" https://ai.acme.example/v1/meta
```
Résultat attendu : api_version vaut v1.

En cas d'échec : une autre valeur signale que le serveur et votre client ne parlent pas la même version majeure.
Lire une liste page par page. Les routes de liste renvoient {"items": [...], "next_cursor": "..."} ; envoyez limit (50 par défaut, 500 au plus) et cursor=<next_cursor> pour la page suivante, jusqu'à ce que next_cursor vaille null.
```
curl -H "X-API-Key: $EAI_API_KEY" "https://ai.acme.example/v1/runs?limit=50"
```
Résultat attendu : une page d'exécutions et un next_cursor.

En cas d'échec : 400 invalid_cursor signale un curseur abîmé ; ne le décodez ni ne le fabriquez jamais.
Relancer une création sans risque. Envoyez un en-tête Idempotency-Key (1 à 200 caractères) : une reprise avec la même clé et le même corps renvoie la réponse enregistrée avec Idempotency-Replayed: true. Les créations longues renvoient aussi Operation-Id et Operation-Location, suivies avec GET /v1/operations/{operation_id}.

Résultat attendu : une seule ressource créée, quel que soit le nombre de reprises.

En cas d'échec : 409 idempotency_conflict (même clé, autre corps) ou 409 operation_in_progress (la première requête tourne encore).
Corréler un appel. Envoyez votre propre X-Request-Id et un traceparent W3C ; la réponse porte X-Request-Id, l'enveloppe d'erreur le répète et les événements d'audit portent le même identifiant de trace.

Résultat attendu : GET /v1/audit/correlations retrouve chaque événement de la chaîne d'appels.

En cas d'échec : un X-Request-Id avec des caractères hors lettres, chiffres et . _ : - est remplacé par un identifiant généré req_<hex>.

Erreurs

Toute erreur suit l'enveloppe error avec code, message, message_i18n (en, fr), details et request_id ; les SDK la traduisent en erreurs typées (voir les guides SDK Python, TypeScript, Go).

{"error": {"code": "forbidden", "message": "...", "message_i18n": {"en": "...", "fr": "..."},
           "details": {"required_roles": ["tenant_admin"]}, "request_id": "req_..."}}

La langue de message suit l'en-tête Accept-Language (en ou fr, en par défaut). L'API du Navin Manager garde la même enveloppe {error: {code, message, message_i18n, details}}.

Dépannage

Statut	Code	Cause	Correction
400	`invalid_request`	valeur invalide	lisez `details`, corrigez la valeur
400	`invalid_cursor`	curseur de pagination abîmé	repartez de la première page
401	`unauthenticated`	aucun identifiant	envoyez un jeton ou une clé d'API
401	`invalid_api_key`, `api_key_revoked`	clé fausse ou révoquée	créez ou renouvelez la clé (POST /v1/api-keys/{key_id}/rotate)
403	`forbidden`	rôle ou droit manquant	demandez le rôle de `details.required_roles`
404	`not_found`	ressource absente ou dans un autre tenant	vérifiez l'identifiant et l'identité utilisée
409	`conflict`, `idempotency_conflict`, `operation_in_progress`	doublon, clé réutilisée ou conflit d'état	lisez `details`, relancez avec une nouvelle clé ou plus tard
413	`payload_too_large`	corps au-delà de la limite	envoyez au plus `details.max_bytes`
422	`validation_error`	corps ou paramètres non conformes au schéma	lisez `details.errors` (`loc`, `msg`, `type`)
429	`rate_limited`	limite de débit atteinte	attendez `Retry-After` secondes
502	`authz_backend_error`	le moteur d'autorisation n'a pas pu répondre (échec fermé)	vérifiez OpenFGA et OPA
503	`service_unavailable`	une dépendance est arrêtée	vérifiez l'état de la plateforme

Étapes suivantes

API du Control Plane : chaque route, avec sa requête et sa réponse.
SDK et CLI du Navin Manager : l'API du Navin Manager depuis Python, TypeScript, Go et la CLI.
Référence ExecutionContext et Référence ActionContext.
Portail développeur : la documentation vivante dans le portail.

Les deux API​

Sources de vérité​

Authentification​

Exemples​

Premiers appels​

Erreurs​

Dépannage​

Étapes suivantes​