Actor API surface
Every actor generated from the kaboum template mounts the same base routers
in create_app(). The surface below is the cross-actor contract: /agent/invoke,
/health, /ready and /metrics are required by the platform; the rest
are recommended and present in every kaboum actor.
| Endpoint | Purpose | Consumed by |
|---|---|---|
POST /agent/invoke |
Chat with the actor. Request: user_identifier, session_id, message, optional role/metadata/attachments. |
Platform (chat relay), kreator (local testing, external API chat operation) |
GET /health |
Liveness/startup. Always 200 while the process lives; reports status: degraded when Postgres is missing. |
Kubernetes probe |
GET /ready |
Readiness. 503 when not ready to serve. Declared when declare_readiness_probe=true (the default). |
Kubernetes probe |
GET /metrics |
Prometheus text metrics. | Platform / ops monitoring |
GET /stats and GET /stats/{tenant_id} |
Kompanion-wide cumulative and per-tenant stats. | Platform (reconciliation cron) |
PUT /settings |
Runtime config update. | kreator (local/ops) — the platform path refuses it with 403 |
GET /api/actor/metadata |
Short marketplace card for the actor. | Marketplace / platform |
GET /api/actor/kaoohi-config |
Serves the baked src/kaoohi/config.json — the canonical actor config. |
Platform, kreator |
Also mounted, conditionally
Section titled “Also mounted, conditionally”| Endpoint | Condition |
|---|---|
GET /settings/schema |
Always present — the settings JSON Schema (docs 04 lists it; the template code is ground truth). |
GET /oauth/authorize, GET /oauth/callback |
Always present — OAuth flow for external services. |
GET /panel/<slug> (+ /data, /action) |
Only when include_panel — owner-facing panel served through the Kaoohi panel relay. |
GET /api/<domain>/_peer_check + peer reads |
Only when fleet_mesh — mesh sibling reads, guarded by the group mesh key. |
/n8n/* proxy |
Only when integration_type=n8n. |
The legacy /api/actor/configuration-schema endpoint has been retired in
favour of /api/actor/kaoohi-config.
Auth posture
Section titled “Auth posture”- Pods run auth-off. On the platform, an actor pod trusts its callers; Kaoohi is the authorization boundary. Never add your own auth layer inside the actor — the platform provisions, exposes and protects the pod.
- Standalone/local runs can enable API key auth (
API_KEY_ENABLED=true,X-API-Keyheader)./health,/ready,/metricsand the OpenAPI docs bypass it. - External API edge: each kompanion can get a public URL
(
https://<PLATFORM_URL>/api/v1/k/<ref>/...) with a per-kompanion API key, over REST and MCP. Only idempotent operations are exposable (chat,status,health); settings and OAuth are never eligible. This is on by default for kaboum actors (kaoohi_expose_external_api).
Where the detail lives
Section titled “Where the detail lives”For request/response schemas, curl examples and error codes, see the
reference doc of record:
kaboum documentation/04-api-reference.md.
The platform-side view of the same contract is the kaoohi repo’s
documentation/30-actor-platform/actor-contract.md
(note: that page is marked draft; the template code is ground truth).
Sources: kaboum facts pack §3 (template/src/main.py.jinja @ 7b2e11e and the
per-router api modules), kaoohi actor-contract.md @ 6742875be.