Primary surfaces of the FastAPI app (kazma_ui). Auth is default-deny for /api/* unless listed open. HITL danger applies to tool execution, not every HTTP route.
| Method | Path | Auth | Description |
|---|
| GET | /health | Open | Liveness |
| GET | /health/live | Open | Process live |
| GET | /health/ready | Open | Readiness (DB ping when configured) |
| Method | Path | Auth scope | Description |
|---|
| GET/POST | /login | Public page | Multi-mode login (user / secret / OIDC) |
| POST | /api/auth/* | Varies | Login, logout, session (see auth.py, saas_api.py) |
| GET | /api/saas/* | Admin / operator | Tenants, platform users (RBAC) |
| Method | Path | Auth | HITL | Description |
|---|
| POST | /api/chat/stream | Session/secret | Graph interrupt on danger tools | SSE chat stream |
| POST | /api/approve/{thread_id} | Session | Resumes graph HITL | Approve danger tool |
| * | Session CRUD under /api/sessions* | Session | — | Thread list / history (session_manager) |
| Method | Path | Auth | HITL | Description |
|---|
| * | /api/ide/* | Session | Via tool registry | Files, apply_patch, codebase search, LSP (GET/POST /lsp), run, git, swarm send (ide_api.py) |
| GET | /ide | Session | — | IDE page |
| Method | Path | Auth | Description |
|---|
| * | /api/swarm/* | Session / RBAC | Workers, dispatch, tasks, metrics |
| GET | SSE swarm events | Session | Live task stream (swarm_sse) |
| GET | /swarm | Session | Swarm panel page |
| * | /api/replay/* | Session | Time travel: threads, snapshots, restore, fork, compare, clear (replay_routes.py) |
| GET | /replay | Session | Time Travel panel page |
| * | /api/research/* | Session | Research: list, detail, compare, export, archive, unarchive (research_panel/routes.py) |
| POST | /api/research/sessions | Session | Start deep research session (background pipeline) |
| GET | /api/research/sessions | Session | List durable research sessions |
| GET | /api/research/sessions/{id} | Session | Session status / log / report path |
| GET | /api/research/sessions/{id}/stream | Session | SSE progress (snapshot / progress / done) |
| GET | /api/research/eval | Session | Structural rubric for ?path= or ?session_id= |
| POST | /api/memory/v2/eval/golden | Session | Run golden memory recall cases (pass rate) |
| GET | /research | Session | Research panel page (start form + live progress) |
| Method | Path | Auth | Description |
|---|
| GET | /api/system/status | Session | Memory health board + embedder/layer probes (build_memory_health) |
| GET | /api/memory/graph | Session | Property graph JSON (nodes/edges); optional ?q= filter |
| GET | /api/memory/graph/stats | Session | Node/edge counts + backend path |
| GET | /api/memory/graph/search | Session | FTS search over graph nodes (?q=&limit=) |
| POST | /api/memory/graph/clear | Session | Bi-temporal invalidate of active V2 beliefs for one tenant (?tenant= defaults to default; no all-tenants mode). Tombstones the PG mirror, deletes Neo4j edges, writes a graph_clear audit row. UI confirms. |
| * | /api/system/memory/* | Session | Backup / restore / maintenance of memory stores |
Active when memory.v2.use_new_stack is true. All routes return shaped JSON
on error (never a bare 500); non-numeric params yield a FastAPI 422.
| Method | Path | Auth | Description |
|---|
| GET | /api/memory/v2/health | Session | V2 health snapshot — active/superseded/archived belief counts, episode/entity/procedural stats, queue depth. Drives the dashboard KPI grid (pollV2Health, 5s cadence). |
| GET | /api/memory/v2/beliefs | Session | Active beliefs list. ?q= FTS filter, ?limit= (default 50, clamped 1–200). |
| GET | /api/memory/v2/beliefs/{id} | Session | Belief detail + supersede chain. |
| POST | /api/memory/v2/beliefs/{id}/invalidate | Session | Soft-invalidate one belief (+ best-effort Neo4j edge delete). |
| POST | /api/memory/v2/beliefs/invalidate-batch | Session | Soft-invalidate many ({ "ids": [...] }). |
| PATCH | /api/memory/v2/beliefs/{id} | Session | Operator edit of active triple: optional subject, predicate, object, predicate_type. Sets extraction_method=user_explicit; clears embedding if object changes. |
| GET | /api/memory/v2/graph | Session | Belief graph {nodes, links, stats, groups} for the canvas. Bi-temporal + filter params: ?at=<unix_ts> (point-in-time scrub; superseded beliefs marked superseded=true), ?type= (functional/set/state predicate_type), ?entity_type= (person/tool/concept/…), ?limit= (default 200), ?source=neo4j (optional probe). stats.total_links vs stats.links is the slicing delta shown on the truncation banner. Invariants: unique node ids; no virtual fact node when object text equals an entity id; no dangling links; hub node id=user with display name from entities.user (self person shells collapsed onto hub); payload-object subjects carry a hub related_to anchor. |
| GET | /api/memory/v2/entities | Session | Entity list for /memory ops. Flags: empty, isolated, protected, is_self, graph_id (self shells → "user"). Query: ?q=, ?empty_only=, ?isolated_only=, ?limit=. |
| POST | /api/memory/v2/entities/{id}/rename | Session | Display rename only ({ "name": "…" }). Id stable; aliases preserved. Self/person User shells also upsert hub entities.user. Returns hub_synced, graph_id. |
| POST | /api/memory/v2/entities/merge | Session | Merge source into target (beliefs rewired, aliases union). |
| POST | /api/memory/v2/entities/link | Session | Create belief edge (subject, predicate, object). |
| DELETE | /api/memory/v2/entities/{id} | Session | Delete entity shell (blocked for protected ids: user, assistant, …). Copies matching entity_merges rows to entity_merges_archive before dropping live ledger rows (FK). |
| GET | /api/memory/v2/admin/summary | Session | Counts for ops chips (live/invalidated beliefs, empty/isolated entities). |
| GET/POST | /api/memory/v2/hygiene/* | Session | Preview + run empty purge / near-dup invalidate / archive. |
| GET/POST | /api/memory/v2/entity-merges* | Session | Quarantine merge list + approve/reject. |
| GET/POST/DELETE | /api/memory/v2/graph/groups* | Session | View-only groupings (list/create/delete/move/tier). Never mutates beliefs. Canvas poll uses groups on GET /graph; Ungroup is DELETE …/groups/{id}. |
| GET | /api/memory/v2/graph/export | Session | On-demand JSON or GraphML (?format=json|graphml). |
| POST | /api/memory/v2/probe | Session | Recall dry-run (explain chips). |
| POST | /api/memory/v2/federated-search | Session | Memory + KB labeled search. |
| POST | /api/memory/v2/eval/golden | Session | Golden recall suite. |
Page: GET /memory (HTML admin). Guide: Memory & RAG · Memory best path.
| Method | Path | Auth | Description |
|---|
| * | /api/settings*, config export | Admin/operator | ConfigStore-backed settings UI |
| GET/PUT | /api/settings/agent/nonstop | Session / Admin | Non-Stop & Self-Healing watchdog/failover/ledger settings |
| * | Workspace routes /api/workspaces* | Session | WorkspaceStore CRUD |
Mounted from documents_api.py at /api/documents/*. Thin transport over the
shared DocumentIngestionService (no parallel parser path). Tenant/actor come
from request context — clients never supply trusted paths for remote intake.
Guide: Document Intelligence ·
Ops: Document processing ·
Security: Document security.
| Method | Path | Auth | Description |
|---|
| POST | /api/documents | Session | Streamed upload intake (bounded; 413 on overflow) |
| POST | /api/documents/import | Session | Workspace-safe local file intake |
| POST | /api/documents/generate | Session | Generate + durably ingest (payload ≤ 1 MiB) |
| GET | /api/documents | Session | List documents (tenant/actor scoped) |
| GET | /api/documents/health | Session | Parser/OCR/renderer readiness + worker status |
| POST | /api/documents/merge | Session | Merge several documents’ PDFs by opaque IDs |
| GET | /api/documents/{document_id} | Session | Detail (versions + jobs + artifacts) |
| GET | /api/documents/{document_id}/versions | Session | Version list |
| GET | /api/documents/{document_id}/content | Session | Paged normalized/fenced content |
| GET | /api/documents/{document_id}/artifacts | Session | Derived artifacts for a document |
| GET | /api/documents/artifacts/{artifact_id}/download | Session | Download artifact by opaque ID |
| POST | /api/documents/{document_id}/convert | Session | Convert current version to target format |
| GET | /api/documents/{document_id}/pdf-info | Session | Structural PDF report |
| POST | /api/documents/{document_id}/split | Session | Split page range from PDF version |
| POST | /api/documents/{document_id}/fill-form | Session | Fill AcroForm fields |
| POST | /api/documents/{document_id}/redact | Session | Physical redact terms → new artifact (no UI confirm on API) |
| POST | /api/documents/{document_id}/index | Session | Publish current version to a Knowledge library |
| POST | /api/documents/{document_id}/unindex | Session | Remove from a library |
| POST | /api/documents/search | Session | Library search (fenced hits) |
| GET | /api/documents/jobs/{job_id} | Session | Job status |
| GET | /api/documents/jobs/{job_id}/events | Session | Append-only job event history |
| POST | /api/documents/jobs/{job_id}/cancel | Session | Cooperative cancel |
| POST | /api/documents/jobs/{job_id}/retry | Session | Re-enqueue dead-letter/rejected job |
| POST | /api/documents/{document_id}/delete | Session | Tombstone / delete document |
| Method | Path | Auth | Description |
|---|
| GET | /api/documents/ops/metrics | Session | Content-free metrics snapshot |
| GET | /api/documents/ops/capacity | Session | Backpressure snapshot + degraded_reasons |
| GET | /api/documents/ops/readiness | Session | Multi-replica honesty (metadata_single_replica, jobs backend) |
| GET | /api/documents/ops/retention | Session | Live retention/GC policy view |
| GET | /api/documents/ops/audit | Session | Keyset-paged operational audit (?limit=&before_id=) |
| POST | /api/documents/ops/maintenance/dry-run | Admin | GC dry-run report |
| POST | /api/documents/ops/maintenance/run | Admin | GC run after dry-run/confirm in UI |
HTML page: GET /documents (session). TUI Documents tab uses the same coordinator.
| Method | Path | Auth | Description |
|---|
| GET | /api/email/status | Session | Active provider, auth modes, presets summary |
| GET | /api/email/accounts | Session | Multi-account aliases (env) |
| GET | /api/email/presets | Session | Gmail/Microsoft IMAP/POP host presets |
| POST | /api/email/protocol/connect | Session | Save IMAP/POP for gmail|microsoft|generic |
| POST | /api/email/protocol/disconnect | Session | Clear protocol + OAuth tokens for provider |
| POST | /api/email/gmail/connect | Session | Gmail app-password → IMAP |
| POST | /api/email/gmail/disconnect | Session | Clear Gmail creds |
| POST | /api/email/oauth/gmail/client | Session | Save Google OAuth client id/secret |
| GET | /api/email/oauth/gmail/start · start.json | Session | Browser OAuth redirect / JSON |
| GET | /api/email/oauth/gmail/callback | Open (OAuth) | Token exchange; redirects to Settings |
| POST | /api/email/oauth/microsoft/client | Session | Save Azure app id/secret |
| GET | /api/email/oauth/microsoft/start · start.json | Session | Browser OAuth |
| GET | /api/email/oauth/microsoft/callback | Open (OAuth) | Token exchange |
| POST | /api/email/oauth/microsoft/device/start · …/poll | Session | Device-code fallback |
| POST | /api/email/oauth/microsoft/disconnect | Session | Clear Microsoft tokens |
Agent mail ops use tools (email_list, …), not these HTTP routes. Guide: Email integration.
| Method | Path | Auth | Description |
|---|
| GET | /x | Session | X Studio page (composer + X-only planner). |
| GET | /api/x/status | Session | Configured?, handle, caps. Never returns secrets. |
| POST | /api/x/preview | Session | Dry-run ToU policy (evaluate_post). No network, no ledger. |
| GET | /api/x/drafts | Session | Flattened save_proposal items for the Studio inbox. |
| GET | /api/x/audit | Session | Recent x_audit.db rows (?action=&limit=). |
| POST | /api/x/post | Session + CSRF | Immediate post (publish_x_post). Operator click is the approval. Optional reply_to_id, proposal_id (stored text wins). |
| POST | /api/x/delete | Session + CSRF | Delete a live tweet (delete_x_post). Operator click is the approval. |
| POST | /api/x/credentials | Session + CSRF | Save four OAuth 1.0a keys (vaulted) + handle + caps. |
| POST | /api/x/test | Session + CSRF | GET /2/users/me with stored keys. |
| POST | /api/x/disconnect | Session + CSRF | Delete keys, disable posting. |
Chat tweets still go through x_post (always HITL + proposal_id). Guide: X publisher.
| Method | Path | Auth | Description |
|---|
| GET | /scheduled | Session | Mixed clock page (cron jobs and X posts). |
| GET | /api/scheduled/tasks | Session | Combined upcoming list. |
| POST | /api/scheduled/cron | Session + CSRF | Create a cron job. |
| PUT | /api/scheduled/cron/{job_id} | Session + CSRF | Reschedule a cron job. |
| DELETE | /api/scheduled/cron/{job_id} | Session + CSRF | Cancel a cron job. |
| POST | /api/scheduled/x | Session + CSRF | Book an X post (book_x_post). Optional reply_to_id, proposal_id. |
| PUT | /api/scheduled/x/{post_id} | Session + CSRF | Reschedule a pending X post. |
| DELETE | /api/scheduled/x/{post_id} | Session + CSRF | Cancel a pending X post (releases reserved quota). |
X Studio’s All clocks link is this page. The Studio planner itself is X-only.
| Method | Path | Auth | Description |
|---|
| Webhooks | Telegram/Discord/Slack callbacks | Adapter secrets | Inbound messages + HITL buttons |
| * | /api/gateway/* | Session | Gateway status/control from CLI |
| Method | Path | Auth | Description |
|---|
| WS | Voice routes | Session | routes_voice_ws.py |
| * | Chaos routes | KAZMA_CHAOS_ENABLED | Dev only |
| Static | /, /chat, /settings, /x, /scheduled, … | Cookie/session | HTML pages |
Exact route lists evolve with routers mounted in app.py. For extension points see API & Extension Points.
| Mode | When |
|---|
| Shared secret cookie / header | Single-operator |
| Opaque web session | Multi-user default |
| Platform RBAC (viewer/operator/admin) | SaaS APIs |
| OIDC PKCE | SSO login |
| API token / JWT | Programmatic (where enabled) |
See Multi-user SaaS and Environment variables.
