Surface d'API de l'acteur

Chaque acteur généré depuis le template kaboum monte les mêmes routeurs de base dans create_app(). La surface ci-dessous est le contrat entre acteurs : /agent/invoke, /health, /ready et /metrics sont requis par la plateforme ; le reste est recommandé et présent dans chaque acteur kaboum.

Endpoint	Rôle	Consommé par
POST /agent/invoke	Discuter avec l’acteur. Requête : user_identifier, session_id, message, role/metadata/attachments optionnels.	Plateforme (relais de chat), kreator (tests locaux, opération chat de l’API externe)
GET /health	Vie/démarrage. Toujours 200 tant que le processus vit ; rapporte status: degraded quand Postgres manque.	Sonde Kubernetes
GET /ready	Disponibilité. 503 quand l’acteur n’est pas prêt à servir. Déclaré quand declare_readiness_probe=true (valeur par défaut).	Sonde Kubernetes
GET /metrics	Métriques au format texte Prometheus.	Plateforme / supervision ops
GET /stats et GET /stats/{tenant_id}	Statistiques cumulées du kompanion et par tenant.	Plateforme (cron de réconciliation)
PUT /settings	Mise à jour de configuration à l’exécution.	kreator (local/ops) — le chemin plateforme la refuse avec 403
GET /api/actor/metadata	Fiche marketplace courte de l’acteur.	Marketplace / plateforme
GET /api/actor/kaoohi-config	Sert le src/kaoohi/config.json cuit — la configuration canonique de l’acteur.	Plateforme, kreator

Également monté, conditionnellement

Endpoint	Condition
GET /settings/schema	Toujours présent — le JSON Schema des réglages (la doc 04 le liste ; le code du template fait foi).
GET /oauth/authorize, GET /oauth/callback	Toujours présent — flux OAuth pour les services externes.
GET /panel/<slug> (+ /data, /action)	Seulement si include_panel — panneau côté propriétaire, servi via le relais de panneau Kaoohi.
GET /api/<domain>/_peer_check + lectures peer	Seulement si fleet_mesh — lectures des siblings mesh, gardées par la clé mesh de groupe.
Proxy /n8n/*	Seulement si integration_type=n8n.

L’endpoint hérité /api/actor/configuration-schema a été retiré au profit de /api/actor/kaoohi-config.

Posture d’authentification

• Les pods tournent sans auth. Sur la plateforme, un pod d’acteur fait confiance à ses appelants ; Kaoohi est la frontière d’autorisation. N’ajoutez jamais votre propre couche d’authentification dans l’acteur — la plateforme provisionne, expose et protège le pod.
• Les exécutions autonomes/locales peuvent activer l’authentification par clé API (API_KEY_ENABLED=true, en-tête X-API-Key). /health, /ready, /metrics et la documentation OpenAPI la contournent.
• Edge d’API externe : chaque kompanion peut recevoir une URL publique (https://<PLATFORM_URL>/api/v1/k/<ref>/...) avec une clé API par kompanion, sur REST et MCP. Seules les opérations idempotentes sont exposables (chat, status, health) ; les réglages et OAuth ne le sont jamais. C’est actif par défaut pour les acteurs kaboum (kaoohi_expose_external_api).

Où vit le détail

Pour les schémas de requête/réponse, les exemples curl et les codes d’erreur, voir le document de référence officiel : kaboum documentation/04-api-reference.md. La vue côté plateforme du même contrat est le documentation/30-actor-platform/actor-contract.md du dépôt kaoohi (à noter : cette page est marquée draft ; le code du template fait foi).

Sources : pack de faits kaboum §3 (template/src/main.py.jinja @ 7b2e11e et les modules API par routeur), kaoohi actor-contract.md @ 6742875be.