HTTP endpoint index

Complete endpoint map for all MemState API surfaces, including auth behavior and module ownership.

Auth summary

  • When MEMSTATE_API_KEY is set, protected JSON routes require X-API-Key: <key> or Authorization: Bearer <key>.
  • MEMSTATE_ADMIN_KEY (falls back to MEMSTATE_API_KEY) gates updates to an existing system context — send it as X-Admin-Key on PUT /api/ui/system-context.
  • /health, /health/graph, /health/falkordb, and the static /ui mount remain unauthenticated.

Core routes

Method Path Auth Module Description
GET /Noapi.main Redirect to /ui/.
GET /healthNoapi.main Process liveness.
GET /health/graphNoapi.main Kuzu store open and basic read check.
GET /health/falkordbNoapi.main Compatibility alias for /health/graph.
POST /v1/ingestYes*api.main Observation-shaped topic ingestion through Executor (placement fields in current contract).
POST /v1/queryYes*api.main Staged semantic/structural/temporal retrieval through Executor.

UI API routes /api/ui

Method Path Description
GET /api/ui/datamodel Returns the canonical Mermaid data-model diagram source string.
GET /api/ui/graph Graph snapshot with nodes, edges, and community IDs for the visual explorer.
GET /api/ui/system-context Returns the configured fixed system role and runtime context, if any.
PUT /api/ui/system-context Sets or updates system context. Requires X-Admin-Key when a config already exists.
POST /api/ui/topics Create a new topic.
GET /api/ui/topics List all topic IDs. Accepts include_archived query param.
GET /api/ui/topics/{topic_id} Fetch full topic data including fields and history.
PATCH /api/ui/topics/{topic_id} Partially update topic metadata (title, summary, kind, salience, archived).
DELETE /api/ui/topics/{topic_id} Delete a topic and its edges.
POST /api/ui/topics/{from_id}/relationships Add a typed RELATED edge between two topics.
DELETE /api/ui/topics/{from_id}/relationships Remove a RELATED edge (to_topic_id and kind as query params).
POST /api/ui/topics/{topic_id}/fields Append a history entry to a field (creates field if absent).
GET /api/ui/topics/{topic_id}/fields/{field_name} Read a field with optional full history (with_history param, default true).
DELETE /api/ui/topics/{topic_id}/fields/{field_name} Delete a field and its history.
PUT /api/ui/topics/{topic_id}/fields/{field_name}/ref Set or clear ref_topic_id on a field without appending a history entry.
POST /api/ui/topics/{topic_id}/promote-nested Move a set of fields into a new child topic and add a RELATED edge.
POST /api/ui/topics/{topic_id}/undo-nested Reverse a promote-nested: move child fields back into the parent and remove the edge.
POST /api/ui/topics/{topic_id}/nest-fields Group existing fields under a nested key within fields_json.
POST /api/ui/topics/{topic_id}/unnest-fields Flatten a nested field group back to the top level.
POST /api/ui/transcribe Speech-to-text via Groq Whisper. Alias for /api/llm/transcribe, used by the graph UI client.

LLM routes /api/llm

Method Path Description
POST /api/llm/chat Intent-routed chat with Ollama or Groq, tool loops, and optional two-phase Study ingest pipeline.
POST /api/llm/transcribe Speech-to-text via Groq Whisper. Requires GROQ_API_KEY; independent of chat provider.

Static UI mount

/ui/* serves files from src/memstate/api/static/ui/ when the directory exists. The mount is set up at startup and is not a router endpoint.

Cross-reference