Low-level UI API (/api/ui)

The UI API exposes direct graph operations intended for interactive editing, migrations, and tooling. Unlike /v1, it does not enforce ingest placement semantics.

Endpoint groups

Group Endpoints Notes
Model and graph payload GET /api/ui/datamodel, GET /api/ui/graph Model diagram source and graph snapshot for visual clients.
Topic CRUD POST/GET/PATCH/DELETE /api/ui/topics... Create, list, fetch, patch, and delete topics directly.
Relationships POST/DELETE /api/ui/topics/{id}/relationships Direct RELATED management.
Fields POST/GET/DELETE /api/ui/topics/{id}/fields... Field history append/read/delete and ref updates.

Graph snapshot details

GET /api/ui/graph returns:

  • nodes[] with topic metadata, summarized fields, and community cluster id.
  • edges[] with both related and field_ref edge types.

Community ids are computed by blending structural links (RELATED + refs) with embedding-similarity neighborhoods.

Field operations behavior

  • POST /fields appends history and can create missing fields.
  • GET /fields/{name} can return full history (with_history=true) or current snapshot only.
  • PUT /fields/{name}/ref sets or clears ref_topic_id.
  • Field operations update topic salience via field-average synchronization.

Low-level flow diagram

UI client request -> /api/ui handler
  -> GraphStore direct method call
  -> Kuzu update/read
  -> optional graph snapshot normalization
  -> JSON response (no Executor placement layer)

When to use this surface

  • Interactive editors that need immediate, precise control over graph shape.
  • Migration and repair tooling.
  • Debugging or inspection scripts that need direct topic/field endpoints.
For product-facing ingestion/query behavior, prefer /v1. The UI API intentionally exposes lower-level primitives and fewer guardrails.