API Reference

External clients call the gateway at http://localhost:8080. The gateway handles authentication, admin path guards, tenant/user header stamping, correlation IDs, turn context, and service routing.

Gateway Routes

Prefix	Backend
/v1/chat, /v1/chat/*	Agent Runtime
/v1/agents, /v1/agents/*	Agent Runtime
/v1/sessions, /v1/sessions/*	Agent Runtime
/v1/connectors, /v1/workflows, /v1/overview	Agent Runtime
/v1/admin/mission-control	Agent Runtime
/v1/admin/users	Agent Runtime
/v1/admin/mcp-servers/*, /v1/user/mcp-servers/*	Agent Runtime
/v1/admin/agentops/*	Agent Runtime
/v1/admin/approvals/*, /v1/user/approvals/*	Agent Runtime
/v1/user/secrets/*, /v1/user/profile, /v1/user/integrations/status	Agent Runtime
/v1/guard/*	Guardrail
/v1/memory, /v1/memory/*	Memory
/v1/knowledge/*	Knowledge
/v1/sandbox/*	Code Sandbox, prefix stripped before forwarding
/v1/models, /v1/routes	Inference Router
/v1/audit, /v1/admin/audit/*	Audit
/v1/receipts/*	Audit
/v1/admin/observability/*	Observability
/v1/admin/sso/idps/*	Gateway Keycloak admin integration when enabled
/v1/auth/verify	Gateway auth check used by protected upstream surfaces

/webhook and /v1/turns/* exist on their owning services for direct development/internal access, but the gateway does not currently expose /v1/webhook or proxy /v1/turns/*.

Common Headers

Header	Direction	Notes
Authorization: Bearer ...	Client to gateway	Required when auth is enabled.
X-Correlation-ID	Gateway downstream	Generated if absent.
X-Tenant-ID	Gateway downstream	Derived from JWT tenant or sub; inbound values are stripped.
X-User-ID, X-User-Email, X-User-Roles	Gateway downstream	Derived from verified JWT claims.
X-Aibox-Principal	Gateway downstream	HMAC-signed canonical principal.
X-Aibox-Turn-Id, X-Aibox-Cap-Token	Gateway downstream	Per-request turn context and short-lived capability token.

Chat

Synchronous

curl http://localhost:8080/v1/chat \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "What is 2 + 2?"}
    ],
    "session_id": "s1",
    "tenant_id": "default",
    "user_id": "alice",
    "agent_id": "default"
  }'

Response:

{
  "message": {
    "role": "assistant",
    "content": "4",
    "receipt": {
      "id": "01J...",
      "turn_id": "01J...",
      "tier": "attestable",
      "status": "pending",
      "sealed": false,
      "receipt_url": "/v1/receipts/01J...",
      "proof_url": "/v1/receipts/01J.../proof"
    }
  },
  "session_id": "s1",
  "agent_id": "default",
  "receipt": {
    "id": "01J...",
    "turn_id": "01J...",
    "tier": "attestable",
    "status": "pending",
    "sealed": false,
    "receipt_url": "/v1/receipts/01J...",
    "proof_url": "/v1/receipts/01J.../proof"
  }
}

Streaming

curl -N http://localhost:8080/v1/chat/stream \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "Explain transformers"}],
    "tenant_id": "default",
    "user_id": "alice",
    "session_id": "s1"
  }'

Current SSE event types include:

Event	Data
session_created	{"session_id": "..."}
thinking	Reasoning text when the model emits it.
token	{"content": "..."}
tool_call	Tool name, arguments, optional call ID.
tool_result	Tool name, truncated result, optional call ID.
artifact	Sandbox-generated file/chart/table metadata.
approval_required	User approval requests for gated actions.
trace_update	Late processing-trace patch.
blocked	Guardrail block reason.
retract	Output retraction after a late output guardrail block.
done	Session, agent, routing, and receipt metadata.
error	Error message.

Receipts

curl "http://localhost:8080/v1/receipts/$TURN_ID" \
  -H "Authorization: Bearer $TOKEN"

curl "http://localhost:8080/v1/receipts/$TURN_ID/proof" \
  -H "Authorization: Bearer $TOKEN"

Receipt detail is available only after the turn envelope has sealed.

Direct Service Docs

When using the dev compose override, some direct service OpenAPI pages are exposed on localhost. Production deployments should use the gateway and ingress policy instead.