api-reference.md

HTTP API Reference

Auto-generated from uteke-server route registry and type schemas. Do not edit manually — run cargo run -p docgen to regenerate.

Base URL: http://localhost:8767 (default)

Auth: Set --auth-token <TOKEN> to require Authorization: Bearer <TOKEN> header.

🏷️ Tags

🟢 GET /tags

List all tags in a namespace. Accepts ?namespace=X query param.

🟡 POST /tags/rename

Rename a tag across all memories.

Request body: TagRenameRequest

🟡 POST /tags/delete

Delete a tag from all memories.

Request body: TagDeleteRequest

📌 Pin (Legacy)

🟡 POST /pin

Pin a memory by ID (legacy — prefer /memory/pin).

Request body: PinRequest

🟡 POST /unpin

Unpin a memory by ID (legacy — prefer /memory/pin with pin=false).

Request body: PinRequest

📝 Other

🟢 GET /guide

Returns the agent-facing memory tools guide for system prompt injection (#1010).

Response: GuideResponse

Related: #1010

🟢 GET /store

Identity of the store this server serves: {"id": "<16 hex digits>"}, the SHA-256 prefix of the store's canonical path (uteke_core::store_identity). The CLI compares it with the store it resolved before routing a command here, so UTEKE_HOME pointing elsewhere is not sent to this server (#1445). The path itself is never returned. Needs the usual token when auth is on.

Related: #1445

🟢 GET /namespaces

List all namespaces in the memory store. ?with_counts=true adds count (total) plus active/deprecated breakdown fields (#1181).

Related: 1181

🟡 POST /namespaces/rename

Rename a namespace ({from, to}). When to already exists this is a merge; the old name vanishes (derived view). Returns {from, to, moved, target_existed} (#1181).

Request body: NamespaceRenameRequest

Related: 1181

🟡 POST /namespaces/delete

Delete a namespace with an explicit strategy for its memories ({name, strategy, target?}): refuse (default — 409 while any memory references the name), merge (move all memories to target), or deprecate (soft-delete — restorable, never hard-deleted) (#1181).

Request body: NamespaceDeleteRequest

Related: 1181

🟢 GET /stats

Get memory statistics (count, etc.) for a namespace. Accepts ?namespace=X query param.

🟡 POST /stats

Get memory statistics via POST body. Accepts {"namespace": "..."}.

Request body: JSON object (see handler source for fields)

Related: #786

🟢 GET /memory

Get a single memory by ID. Accepts ?id=... query param.

Response: Memory

🔵 PUT /memory

Update an existing memory's content and/or metadata.

Request body: MemoryUpdateRequest

🟡 POST /verify

Check vector-index/SQLite consistency: row vs vector counts, mismatch flag (#1266).

Response: VerifyReport

🟡 POST /repair

Rebuild the vector index from stored embeddings to fix recall desync (#1266). SQLite data is untouched.

Response: RepairReport

🟢 GET /graph

Memory graph for visualisation: live memories as nodes, memory_edges (auto-links, supersession) plus explicit graph edges as edges, keyed by memory id. Accepts ?namespace=..., ?node_id=<memory id> (that memory's neighbourhood) and ?limit= (edges, default 500, max 5000); response carries truncated. Derived referenced_by backlinks are omitted.

🟢 GET /provenance

Full provenance report for a memory (#1172): author/source fields, trust tier, source hash at write vs live-recomputed content hash (tamper evidence), and the full timeline event chain with actor + evidence. Accepts ?id=... query param.

Related: 1172

🟢 GET /contradictions

List superseded-but-not-restored memories (#1172) — the auditable contradiction resolution ledger (deprecated rows carrying a live superseded_by edge). Accepts ?namespace=...&limit=....

Related: 1172

🟡 POST /contradictions/undo

Undo a contradiction resolution (#1172): restore the retired memory to active, remove the supersession pair, and record supersession_undone provenance events. Body: {id}.

Request body: ContradictionUndoRequest

Related: 1172

🟡 POST /capture

Queue one raw conversation turn for deferred, budgeted fact extraction. Refused (409) unless [capture] enabled is on.

Request body: CaptureRequest

Related: #1466

🟢 GET /capture/status

Capture queue counts: pending, extracting, done, failed turns and pending sessions.

Related: #1466

🟡 POST /lifecycle/cycle

Run lifecycle aging cycle: deprecate old memories, optionally prune expired ones.

Related: #935

🟡 POST /lifecycle/promote

Restore a deprecated memory back to active status.

Related: #935

🟢 GET /lifecycle/status

Get lifecycle status: active/deprecated counts and current configuration.

Related: #935

🟢 GET /lifecycle/deprecated

List deprecated memories with TTL metadata.

Related: #1007

📦 Import/Export

🟡 POST /import

Import memories from JSONL (or a JSON array) in content. Each row keeps its id, type, importance, pinned flag and slug; the response counts imported, skipped, duplicates_skipped, id_conflicts_skipped and soft_deleted_skipped. A Uteke Cloud export imports whole: type: "document" rows become documents (parent by slug), type: "room" rows become rooms with their doc_slugs linked, both before the memories' rooms, and the manifest line is skipped; the response then adds documents_imported, documents_updated, documents_unchanged, parent_unresolved, rooms_imported, rooms_existing, room_documents_linked and room_documents_missing (each only when non-zero). The body limit of this route is 64 MiB (UTEKE_MAX_IMPORT_SIZE, bytes; other routes keep 10 MB); a larger body gets a 413 that names the limit. Bulk runbook: send defer_embedding: true (rows are stored without a vector and the call returns in seconds; split a large file into several calls under the body limit), then run uteke repair --reembed (add --limit N to spread the work) so /recall finds them.

Request body: ImportRequest

🟢 GET /export

Export all memories as JSON. Accepts ?namespace=... query param.

🟡 POST /importance

Recompute importance scores for all memories.

Request body: ImportanceRequest

🔧 Maintenance

🟡 POST /prune

Remove orphaned memories (no room, no graph edges).

Request body: PruneRequest

🟡 POST /consolidate

Merge similar/duplicate memories automatically.

Request body: ConsolidateRequest

🟡 POST /consolidate/pair

Consolidate a single caller-chosen duplicate pair: keep id_keep, deprecate (or hard-delete) id_remove.

Request body: ConsolidatePairRequest

Related: 1076

🟡 POST /aging

Run aging cleanup — deprioritize or remove old/stale memories.

Request body: AgingRequest

🟡 POST /orphans

List orphaned memories (not in any room, no edges).

Request body: OrphansRequest

🟡 POST /extract

Extract entities and relationships from memory content.

Request body: ExtractRequest

🟡 POST /rebuild-backlinks

Rebuild backlink indices for memory graph.

🔴 Health & Info

🟢 GET /health

Health check — tokenless requests get {status} only; a valid bearer token (or auth-disabled server) returns status, version, memory counts, and update info

Response: HealthResponse

🟢 GET /routes

Machine-readable API route introspection: returns this registry (method, path, tier, description, request/response types) as JSON — the same source of truth that generates docs/api-reference.md (#1289).

Related: #1289

🔵 Documents

🟡 POST /doc/create

Create a new document with slug, title, content, tags.

Request body: DocCreateRequest

🟡 POST /doc/get

Get a document by slug.

Request body: DocGetRequest

🟡 POST /doc/list

List documents with optional namespace/limit/roots_only/parent filters.

Request body: DocListParams

🟡 POST /doc/search

Search documents by query with optional mode/namespace/limit.

Request body: DocSearchRequest

🟡 POST /doc/update

Update an existing document (content, title, tags, parent).

Request body: DocUpdateRequest

🟡 POST /doc/move

Move a document to a different parent.

Request body: DocMoveRequest

🔴 DELETE /doc/delete

Delete a document by slug or ID.

🟡 POST /doc/mem-refs

Get memories that reference a specific document.

Request body: JSON object (see handler source for fields)

🟠 Graph

🟡 POST /graph/edge

Add a directed edge between two memories. Accepts memory IDs (a linked graph node is ensured automatically, #1180) or existing graph node IDs. Returns {ok, source_node, target_node}.

Request body: GraphEdgeRequest

Related: 1180

🔴 DELETE /graph/edge

Remove an edge between two nodes. Accepts memory IDs or graph node IDs via ?source=...&target=... query params (#1180).

Related: 1180

🟢 GET /edges

List all memory_edges of one memory (outgoing and incoming, including derived backlinks). Not an alias of /graph. Accepts ?id=... query param.

🟢 GET /timeline

Get timeline of memory events for a memory. Accepts ?id=... query param.

🟡 Core Memory

🟡 POST /remember

Store a new memory. Accepts content, tags, namespace, type, metadata. Explicit type is honored as-is (no silent normalization, #1302); unknown types are rejected with 400 listing the valid vocabulary. Omit type to auto-infer.

Request body: RememberRequest

Response: Memory

🟡 POST /recall

Semantic search — recall memories by meaning. Returns ranked results. Set explain: true (#1160) to include per-result ranking signals (vector similarity/rank, RRF contributions, boosts); memory-only recall.

Excludes deprecated memories from results.

Request body: RecallRequest

🟡 POST /search

Keyword search — find memories by matching words in content/tags.

Excludes deprecated memories from results.

Request body: SearchRequest

🟡 POST /list

List memories with optional filters (namespace, tags, sort, limit, offset). Set include_meta: true (#1188) for a pagination envelope {memories, total, has_more, next_offset} instead of the bare array (not supported with at).

Excludes deprecated memories from results.

Request body: ListParams

🔴 DELETE /forget

Deprecate a memory by ID. Returns 404 if ID doesn't exist.

🟢 GET /recent

Get recently added memories. Accepts ?limit=N&namespace=X query params.

Excludes deprecated memories from results.

🟢 Rooms

🟡 POST /room/create

Create a new memory room. Accepts {"name": "..."}.

Request body: JSON object (see handler source for fields)

🟡 POST /room/remember

Store a memory linked to a room. Accepts room_id, content, tags, type, author.

Request body: RoomRememberRequest

Response: Memory

Related: #789

🟡 POST /room/recall

Semantic search within a room. Empty query returns all memories chronologically.

Excludes deprecated memories from results.

Request body: RoomRecallRequest

Related: #785

🟡 POST /room/summary

Get room summary with memory clusters and statistics.

Excludes deprecated memories from results.

Request body: JSON object (see handler source for fields)

🟡 POST /room/summary-document

Get room summary focused on document-type memories.

Excludes deprecated memories from results.

Request body: JSON object (see handler source for fields)

🟢 GET /room/list

List all rooms.

🟡 POST /room/consolidate

Plan or execute segment-level LLM consolidation of room memories (#1088). Dry-run by default; apply: true executes with a hard budget cap. Write op — blocked for read-only tokens.

Request body: JSON object (see handler source for fields)

Related: #1088

🟡 POST /room/stats

Get memory count for a room. Includes deprecated memories (known discrepancy vs /room/summary).

Request body: JSON object (see handler source for fields)

Related: #784

🟢 GET /room/memories

List all memories in a room (chronological). Accepts ?room_id=... query param; optional ?author=... and ?namespace=... filters (#1288). Without namespace, returns ALL namespaces that contributed to the room.

Excludes deprecated memories from results.

🔴 DELETE /room/delete

Delete a room (unlink-only): room links are removed, memories and documents are preserved. Response: { deleted, unlinked_memories }. Accepts ?room_id=... query param.

🟡 POST /room/rename

Rename a room: the registry row and every member/document link move in one transaction; title, description, and namespace are preserved (#1202). Accepts { from, to }. Write op — blocked for read-only tokens.

Request body: JSON object (see handler source for fields)

Related: #1202

🟡 POST /room/update

Update a room's title and/or description; omitted fields stay unchanged (#1202). Accepts { room_id, title?, description? }; 404 when the room is missing. Write op — blocked for read-only tokens.

Request body: JSON object (see handler source for fields)

Related: #1202

🟡 POST /room/memory

Add an existing memory to a room without copying it (#1589). Accepts { memory_id, room, author? } (memory_id is a full id or an unambiguous prefix; author defaults to anonymous). Idempotent: linking twice returns already_linked: true and keeps the first link. 404 when the room or the memory does not exist. Write op — blocked for read-only tokens.

Request body: JSON object (see handler source for fields)

Related: #1589

🟡 POST /room/memory/move

Move a memory from one room to another, preserving the link's author/role/joined_at provenance (#1202). Accepts { memory_id, from_room, to_room }; 404 when the memory has no link in from_room. Write op — blocked for read-only tokens.

Request body: JSON object (see handler source for fields)

Related: #1202

🟡 POST /room/document

Store a reference document in a room (large content >500 chars).

Request body: JSON object (see handler source for fields)

🟡 POST /room/document/list

List documents in a room.

Request body: JSON object (see handler source for fields)

🔵 PUT /room/document/add

Add a reference to an existing document in a room.

Request body: JSON object (see handler source for fields)

🔴 DELETE /room/document/remove

Remove a document reference from a room.

Request body: JSON object (see handler source for fields)

🟡 POST /doc/room/list

List rooms that reference a specific document.

Request body: JSON object (see handler source for fields)

🟣 Memory Management

🟡 POST /memory/pin

Pin a memory so it won't be removed by aging/cleanup operations.

Request body: MemoryPinRequest

🟡 POST /memory/importance

Get or set the importance score of a memory.

Request body: MemoryImportanceRequest

🟡 POST /memory/feedback

Submit positive/negative feedback on a memory for ranking signals.

Request body: MemoryFeedbackRequest

🟡 POST /memory/doc-refs

Get documents that reference a specific memory.

Request body: JSON object (see handler source for fields)

🤖 AI Integration

🟡 POST /context

Get context window for a query (for LLM prompt enrichment).

Request body: JSON object (see handler source for fields)

🟡 POST /dream

Generate new memories/insights from existing memory corpus.

Request body: JSON object (see handler source for fields)

🟡 POST /mcp

MCP (Model Context Protocol) bridge endpoint for AI agent tool calls.

Request body: JSON object (see handler source for fields)

Request/Response Schemas

Detailed field definitions for each request type.

AgingRequest

Field	Type	Required	Description
action	string	No
dry_run	boolean	No
max_access_count	any	No	Max access count threshold for preview/cleanup (default: 1).
namespace	any	No
older_than_days	any	No	Days threshold for preview/cleanup (default: warm_days from config, fallback 90).

CaptureRequest

One turn for the capture queue (POST /capture, LAB).

Field	Type	Required	Description
content	string	Yes
namespace	any	No	Namespace the extracted facts are stored in.
role	string	Yes	user, assistant or tool (a tool output keeps its first 2000 characters).
session_id	string	Yes	Conversation the turn belongs to; its turns are extracted together.
source	any	No	Optional source label (e.g. the client name).

ConsolidateRequest

Field	Type	Required	Description
dry_run	boolean	No
namespace	any	No
threshold	number	No

DocCreateRequest

Field	Type	Required	Description
content	string	Yes
parent	any	No
slug	string	Yes
tags	string[]	No
title	any	No

DocGetRequest

Field	Type	Required	Description
id	any	No
slug	any	No

DocMoveRequest

Field	Type	Required	Description
id	any	No
new_parent	any	No
new_sort_order	any	No	Optional sort order for the moved document (#sort-order).
slug	any	No

ErrorResponse

Field	Type	Required	Description
error	string	Yes

ExtractRequest

Field	Type	Required	Description
content	string	Yes
max_facts	any	No	Override max facts per document.
model	any	No	Override extraction model (else config default).
namespace	any	No
tags	string[]	No
type	any	No

GraphEdgeRequest

Field	Type	Required	Description
edge_type	any	No
source	string	Yes
target	string	Yes
weight	any	No

HealthResponse

Field	Type	Required	Description
api_latest	any	No	Latest API version (#737).
api_versions	any	No	Supported API versions (#737).
memories	integer	Yes
namespaces	integer	Yes
status	string	Yes
update_available	any	No	Latest version available on GitHub, if newer than current. Populated from cache (24h TTL) — may be None if cache is stale.
version	string	Yes	Server version (uteke-server crate version), so HTTP clients can gate features on the actual server capability rather than a local CLI probe.

ImportRequest

Field	Type	Required	Description
content	string	Yes	JSONL content to import.
defer_embedding	boolean	No	Store the rows without a vector and return at once (#1634, default false). The rows are keyword-searchable (/search) immediately and found by /recall after uteke repair --reembed adds the vectors. Duplicates are caught by exact content only, not by the cosine check. The response then carries deferred_embedding: the rows waiting for a vector. Use it for bulk imports, which otherwise embed every row before the request returns.
namespace	any	No
tags	string[]	No

ImportanceRequest

Field	Type	Required	Description
namespace	any	No

ListParams

Field	Type	Required	Description
at	any	No	Time-travel: list memories that existed at this RFC3339 timestamp.
include_meta	boolean	No	Pagination metadata (#1188): when true, respond with an envelope {memories, total, has_more, next_offset} instead of the bare array. Default false — the bare-array shape is unchanged for existing clients. Not supported with at (point-in-time listing returns the bare array regardless).
limit	integer	No
namespace	any	No
offset	integer	No
tag	any	No

MemoryFeedbackRequest

Request for memory feedback / trust scoring (#718).

Field	Type	Required	Description
feedback	string	Yes	"helpful" or "unhelpful"
id	string	Yes

MemoryImportanceRequest

Field	Type	Required	Description
id	string	Yes
importance	number	Yes

MemoryPinRequest

Field	Type	Required	Description
id	string	Yes
pinned	boolean	Yes

MemoryUpdateRequest

Field	Type	Required	Description
content	any	No	New content. Triggers embedding regeneration.
id	string	Yes	UUID of the memory to update (required).
importance	any	No	Set importance score (0.0–1.0).
memory_type	any	No	Set memory type (fact, procedure, preference, decision, context, note, insight, reference, event).
metadata	any	No	Replace metadata entirely with this object.
namespace	any	No	Move the memory to this namespace (#1181). Plain column update — no re-embed.
pinned	any	No	Set pinned state.
tags	any	No	Replace tags entirely with this list.

OrphansRequest

Field	Type	Required	Description
limit	integer	No
namespace	any	No
threshold	number	No

PinRequest

Field	Type	Required	Description
id	string	Yes

PruneRequest

Field	Type	Required	Description
dry_run	boolean	No
namespace	any	No
ttl_days	integer	No

RecallRequest

Field	Type	Required	Description
after	any	No	Temporal range filter: only return memories created at or after this RFC3339 timestamp (#902).
at	any	No	Time-travel: query memories that existed at this RFC3339 timestamp.
before	any	No	Temporal range filter: only return memories created at or before this RFC3339 timestamp (#902).
budget_chars	any	No	Character budget for pack (default 4000).
category	any	No	Filter by category metadata.
enrich	boolean	No	Enrich results with cross-entity links (doc↔memory) (#689). When true, populates linked_doc_slugs on memory results and linked_memory_ids on document results.
entity	any	No	Filter by entity metadata.
exclude_ids	any	No	Memory IDs already injected this turn; excluded from pack results (reported as skipped with reason excluded).
explain	boolean	No	Explain mode (#1160): return per-result ranking signals alongside each memory. Memory-only recall — rejected (400) together with search_type/unified, at, before/after.
limit	integer	No
min_score	any	No	Minimum similarity score (0.0-1.0). Results below are filtered. Default: 0.0 (no filtering). Use strict=true for 0.5 default (#995).
namespace	any	No
pack	boolean	No	Budgeted context pack (#1281 Phase 1): return a ContextPack (selected/skipped/budget_used) instead of a bare ranked list. Deterministic, LLM-free, rank-order preserving.
query	string	Yes
search_type	any	No	Search type filter: "all" (default, unified), "memory", or "doc" (#531).
strategy	any	No	Recall strategy: "fusion" (default since 0.16.0), "vector", "fts5", "hybrid", or "graph" (#900, #1034, #1123). When absent, the server falls back to [recall] default_strategy from uteke.toml, then to "fusion" — matching the CLI default. Invalid values return HTTP 400.
strict	boolean	No	Use strict threshold (defaults to 0.5 if min_score not set).
tags	string[]	No

RememberRequest

Field	Type	Required	Description
author	any	No	Who wrote the memory (#1427 phase 2): free text, trimmed, 1 to 128 characters. Optional, with or without a room; returned on the memory.
author_type	any	No	Author type: "human"
category	any	No	Category — stored as metadata key "category".
content	string	Yes
detect_contradiction	boolean	No
entity	any	No	Entity name — stored as metadata key "entity".
metadata	any	No	Extra metadata key=value pairs, merged into the metadata map. Accepts an object (e.g. {"project": "uteke"}).
namespace	any	No
source	any	No	Source provenance — set via set_source() after storage.
source_type	any	No	Source type (defaults to "user").
tags	string[]	No
type	any	No	Memory type — validated against the MemoryType vocabulary and stored as-is (no silent normalization, #1302). Unknown values are rejected with 400 listing the valid types. Omit to let auto-inference decide.
valid_from	any	No
valid_until	any	No

RoomRecallRequest

Field	Type	Required	Description
at	any	No	Time-travel: recall room state as of this RFC3339 timestamp (#1082). Memories created after at (or invalidated before it) are excluded.
author	any	No
limit	integer	No
min_score	any	No
query	any	No	Semantic search query. When None or empty, falls back to chronological recall (equivalent to GET /room/memories) (#785).
room_id	string	Yes

RoomRememberRequest

Field	Type	Required	Description
author	any	No	Author — stored as participant role in room link.
content	string	Yes
metadata	any	No
namespace	any	No
room_id	string	Yes
tags	string[]	No
type	any	No

SearchRequest

Field	Type	Required	Description
limit	integer	No
namespace	any	No
query	string	Yes
tags	string[]	No

TagDeleteRequest

Field	Type	Required	Description
namespace	any	No
tag	string	Yes

TagRenameRequest

Field	Type	Required	Description
namespace	any	No
new	string	Yes
old	string	Yes