API — Référence canonique

Cette page est la carte humaine de l'API Aurora Nexus. Le contrat exhaustif des payloads, réponses et codes de validation reste le snapshot openapi.json. Le guide AURORA_NEXUS_API.md présente les parcours généraux d'authentification, query et ingestion.

État du contrat

API publique : https://nexus.auroramind.fr/openapi.json.
Swagger d'une installation : <API_BASE>/api/docs.
Snapshot versionné : openapi.json, généré par python3 ops/generate_openapi.py dans un environnement qui possède toutes les dépendances de api/requirements.txt.
Une fonction présente seulement dans le snapshot local n'est pas considérée comme déployée tant que l'OpenAPI public ne la contient pas.

Depuis Nexus 1.0.23, le champ facultatif retrieval_mode est présent dans le snapshot versionné et dans le contrat public pour les requêtes RAG normales et streaming. Les familles Media V1, Integration Scopes, Domain Projections, Knowledge Graph workspace, Nexus WebUI et Optimizer restent également visibles dans l'OpenAPI public.

Carte des familles

Famille	Préfixe ou endpoint	Audience	Autorité / accès	Référence
Query RAG	`POST /api/query`, `POST /api/query/stream`	apps clientes	session/OIDC, scope et ACL du corpus	`AURORA_NEXUS_API.md`
Ingestion	`/api/ingest/*`	apps et workers	`nexus.ingest` + `can_write`	`AURORA_NEXUS_API.md`
Documents	`/api/documents/*`	apps, UI et ops	ACL `source_app` et tenant	`AURORA_NEXUS_API.md`
Intégration M2M V1	`/api/v1/integration-scopes/*`	backends partenaires	principal machine lié au `caller_app`	API Intégrations M2M V1
Media V1	`/api/v1/media/*`	backends partenaires autorisés	scope opaque actif ; adaptation actuelle Narrélia	API Intégrations M2M V1
Projections domaine	`/api/v1/domain-projections/*`	backends partenaires	idempotence, versions, scope opaque	API Intégrations M2M V1
KG workspace	`/api/v1/knowledge-graph/*`	backends partenaires	graphe strictement borné au workspace résolu	API Intégrations M2M V1 et Knowledge Graph
Compatibilité Narrélia	`/api/narrelia/media/*`	backend Narrélia	client M2M Narrélia uniquement	API Intégrations M2M V1
Nexus WebUI	`/api/nexus-webui/*`	Nexus WebUI / OpenWebUI	utilisateur authentifié, `nexus.query`, ACL read	API Nexus WebUI
Context packs	`POST /api/context-packs`	Nexus Intelligence	lecture bornée, `caller_app` contrôlé	`AURORA_NEXUS_API.md`
Optimizer	`/api/optimizer/*`	admin Nexus	rôle admin ; tâches asynchrones	Vue étendue
Administration	`/api/admin/*`	UI et ops Nexus	rôle/scopes admin	OpenAPI et guides Configuration/Ops
Meta KG applicatif	`/api/meta-kg/*`	outils code/doc KG	contrôles Nexus dédiés	Spécification Meta KG

Les routes /api/optimizer/* font partie du runtime de production. Une génération locale sans Celery est incomplète et doit échouer au lieu de mettre à jour le snapshot officiel.

Principes communs

Ne jamais transmettre de secret client, token ou cookie dans un payload ou un log applicatif.
tenant_id, les ACL et le corpus autorisé sont résolus et contrôlés par Nexus.
Un workspace, un project, un external_scope_id ou un document_id ne permet jamais d'élargir les droits du principal.
Les erreurs de ressource hors périmètre privilégient une réponse non énumérable (404) lorsque le contrat le prévoit.
Les écritures M2M utilisent des clés d'idempotence et/ou versions optimistes lorsque leur contrat l'exige.

Authentik M2M

Les intégrations serveur utilisent OAuth2 client_credentials. Le secret reste exclusivement dans le coffre du backend client. Le détail des claims, audiences, bindings caller_app -> client_id et scopes est dans 24-Contrat-Auth-OIDC-Nexus.md.

Le contrôle de diagnostic recommandé est GET /api/auth/oidc/me; il doit retourner un principal machine attendu sans que le JWT brut soit copié dans une preuve ou un ticket.

Documents et réaffectation de corpus

La réaffectation en masse utilise :

POST /api/documents/bulk-relocation/preview pour produire un périmètre et un preview_token ;
POST /api/documents/bulk-relocation/execute pour appliquer la mutation validée, synchroniser les payloads Qdrant et journaliser l'opération.

Le runbook détaillé est 36-Document-Bulk-Relocation.md.

Règle de mise à jour

Toute création, suppression ou modification d'endpoint doit mettre à jour dans le même lot : le modèle/route, les tests, openapi.json, cette carte si la famille change, le guide spécialisé concerné et l'index si une nouvelle page est créée. La projection Fumadocs est ensuite régénérée avec bash ops/sync_docs_to_aurora_docs.sh.