Knowledge and Explore API¶

Knowledge APIs manage semantic models and the sources that make content searchable. Explore APIs manage question sessions, selected data sources, messages, and feedback. A source being present in a model does not mean it is already indexed and searchable.

Semantic models¶

Method and route	Purpose
`GET /newmoi/semantic-models`	List semantic models
`POST /newmoi/semantic-models`	Create a semantic model
`GET /newmoi/semantic-models/:model_id`	Read a model
`PUT /newmoi/semantic-models/:model_id`	Update a model
`DELETE /newmoi/semantic-models/:model_id`	Delete a model
`POST .../:model_id/validate`	Validate model semantics
`POST .../:model_id/import`	Import a model definition
`GET .../:model_id/export`	Export a model definition

Entries are managed below /newmoi/semantic-models/:model_id/entries with list, create, update, and delete operations. Treat entry kinds and specifications as contract-defined values; do not invent a free-form kind.

Sources, documents, and segments¶

The source lifecycle includes selection preview, existence checks, append, list, removal, document read, and governance. Local-file upload is available through /newmoi/semantic-models/local-files/upload and the model-scoped variant. Source jobs can be read through .../:model_id/source-jobs and reconciled through .../source-jobs/reconcile.

Document sources expose segment operations below:

/newmoi/semantic-models/:model_id/sources/:source_row_id/segments

The contract covers initial import, create, edit, enable/disable, delete, re-embedding, and selecting a current segment version. Table sources have different governance behavior; do not apply document segment operations to a table merely because both appear in the same knowledge base.

After adding or changing a source, follow its source job until processing and reconciliation complete. If retrieval remains empty, check source enablement, the current segment version, embedding configuration, and caller permission before submitting the source again.

Explore sessions¶

Method and route	Purpose
`POST /newmoi/sessions`	Create a session
`POST /newmoi/sessions/list`	List sessions
`POST /newmoi/sessions/pinned/list`	List pinned sessions
`POST /newmoi/sessions/unpinned/list`	List unpinned sessions
`GET /newmoi/sessions/:id`	Read a session
`PUT /newmoi/sessions/:id`	Update a session
`PUT` or `DELETE /newmoi/sessions/:id/pin`	Pin or unpin
`DELETE /newmoi/sessions/:id`	Delete a session

Message APIs list session messages, obtain the latest message ID, read/delete a message, and submit like/dislike feedback. Message-list operations require the identifier shape documented by the deployed endpoint; do not coerce an opaque session ID to an integer unless the contract requires it.

Querying selected data¶

Explore source discovery uses /newmoi/table/overview, /newmoi/table/database/tables, and /newmoi/table/columns. Build the query source selection from server-returned catalog, database, table, and semantic model IDs. Do not choose a source only by display name when multiple matches exist.

Explore answers can be streamed as SSE/A2A-style events containing planning, source, and answer updates. Parse events by their protocol type, preserve citations as structured data, and stop at the terminal event. An interrupted stream can have created a session or partial message; read the session before retrying the question.

Agent-bound knowledge use is described in Agents and A2A. Model provider and embedding setup is described in Models and providers.