Skip to main content

REST API

The server serves REST, A2A and MCP on one port (API_PORT, default 3001). Bodies and responses are JSON, and errors are always {"error": "<message>"}.

Authentication. In the default AUTH_MODE=local no credential is needed (the server only listens on loopback). In AUTH_MODE=jwt every route except /health and /ready needs Authorization: Bearer <token>. The examples below leave the header out; add it for a shared deployment. See Authentication and tenancy.

StatusMeaning
200, 201, 204success
400invalid input
401missing or invalid credential (jwt mode)
403credential is valid but outside its scope
404not found, or owned by someone your credential cannot see
409conflict (for example an operation ID reused with another payload)
500 / 503server or storage failure / temporarily unavailable

Health​

Method and pathPurpose
GET /healthliveness; static
GET /readyreadiness: storage, ledger, coordinator, tokenizer, model_executor, search_index; 503 when the database handle is unavailable

Memory​

Base path /api/v1/memory.

Method and pathPurpose
POST /add a memory
GET /list one page; filter with ?user_id=&agent_id=&session_id=, page with limit, cursor, include_embeddings
DELETE /delete every memory matching the same filters
GET /{id}fetch one
PUT /{id}replace its content (re-embeds, bumps version)
DELETE /{id}delete one
GET /{id}/historythe change history
# Add
curl -s -X POST http://127.0.0.1:3001/api/v1/memory -H 'content-type: application/json' \
-d '{"content":"Alice prefers dark mode","user_id":"alice","agent_id":"claude-code",
"session_id":"s-42","categories":["preference"]}'

# List one user's memories, one page at a time
curl -s 'http://127.0.0.1:3001/api/v1/memory?user_id=alice&limit=5'
curl -s 'http://127.0.0.1:3001/api/v1/memory?user_id=alice&limit=5&cursor=memory:0b6c4d1e-1f2a-4c3b-9d8e-7f6a5b4c3d2e'

# Update, then read the history
curl -s -X PUT http://127.0.0.1:3001/api/v1/memory/memory:949ae93e-62b2-467a-8937-51739d240d9a \
-H 'content-type: application/json' -d '{"content":"Alice prefers dark mode and large fonts"}'
curl -s http://127.0.0.1:3001/api/v1/memory/memory:949ae93e-62b2-467a-8937-51739d240d9a/history

POST requires content. Everything else is optional: user_id, agent_id, session_id, categories. Adding text that is a near-duplicate (cosine similarity at or above 0.92) of a memory in the same scope updates that memory instead of creating another. A missing scope field widens the check to every value of it, so set user_id and agent_id when you want the check to stay narrow.

DELETE / with no filters deletes every memory in the tenant. Always pass a scope. It deletes in bounded batches of record IDs, expired and archived memories included, and returns {"deleted": n}. It stops at the first memory it cannot delete, and the error states how many were deleted before it. Sending the same request again deletes the rest only once the cause is resolved (for example a transient database error, or a row that cannot be read); until then a rerun stops at the same memory.

Listing is paged​

Breaking change (issue #62): GET / returns one page object, not a bare array of every memory:

{ "memories": [ { "id": "memory:…", "content": "…", "embedding": null, "…": "…" } ],
"next_cursor": "memory:0b6c4d1e-1f2a-4c3b-9d8e-7f6a5b4c3d2e",
"has_more": true }

Pass next_cursor back as cursor until it is null (has_more is then false). Treat a cursor as opaque. A cursor that is not of the form memory:<key> is a 400; any memory:<key> is accepted as a starting position, and the owner filters and the caller's scope still decide what is returned.

ParameterDefaultLimit
limit50 (25 with include_embeddings)200; 25 with include_embeddings
cursorfirst pagea previous page's next_cursor
include_embeddingsfalse—

A limit of 0 or above the maximum is a 400, never silently reduced. Each page is also capped at 1 MiB of encoded memories: a page may hold fewer than limit memories while has_more is true, and a single memory larger than that is returned alone. Embeddings are omitted (null) unless requested.

Pages are ordered by record ID and are not a snapshot. A memory that exists for the whole iteration is returned exactly once; a memory added during it may be missed; a memory deleted or expired during it does not appear afterwards. The owner filters and the caller's verified scope apply to every page, so a cursor cannot reveal another scope's memories. Expired and archived memories never appear.

POST /api/v1/search runs hybrid search (BM25 and HNSW merged by reciprocal rank fusion).

FieldDefaultMeaning
queryrequiredthe search text
user_id, agent_id, session_idnonescope filters
categoriesnoneany-match filter, applied to both legs
limit10maximum results
vector_weight / bm25_weight0.7 / 0.3the blend
include_embeddingsfalseembeddings are large and omitted unless asked for
curl -s -X POST http://127.0.0.1:3001/api/v1/search -H 'content-type: application/json' \
-d '{"query":"editor theme","user_id":"alice","categories":["preference"],"limit":5}'

Knowledge graph​

Base path /api/v1/entities.

Method and pathPurpose
POST / · POST /batchcreate entities
GET /read the whole graph
GET /search?q=…search entities
DELETE /{name}delete an entity
POST /{name}/observationsadd observations
GET /{name}/neighbors?depth=&limit=neighbors up to a depth
GET /{name}/related?relation_type=&direction=&limit=related entities
GET /{name}/path/{to}?max_depth=shortest path
POST /relations · POST /relations/batchcreate relations
curl -s -X POST http://127.0.0.1:3001/api/v1/entities -H 'content-type: application/json' \
-d '{"name":"Alice","entity_type":"person","observations":["Prefers dark mode"]}'

curl -s -X POST http://127.0.0.1:3001/api/v1/entities/relations -H 'content-type: application/json' \
-d '{"from":"Alice","to":"Acme","relation_type":"works_at"}'

TaskStreams​

Base path /api/v1/taskstreams.

Method and pathPurpose
POST / · GET /create · list
GET /{name} · DELETE /{name}fetch · delete
POST /{name}/archive · POST /{name}/pauselifecycle
POST /{name}/memoriesadd a memory to the stream
GET /{name}/contexttoken-budgeted context window
POST /{name}/summarizecompress the stream
curl -s -X POST http://127.0.0.1:3001/api/v1/taskstreams -H 'content-type: application/json' \
-d '{"name":"release-1-12","description":"Cut the 1.12 release","agent_id":"claude-code",
"model_id":"gpt-4o","auto_summarize":true}'

Mindmaps​

Base path /api/v1/mindmaps.

Method and pathPurpose
POST / · GET /create · list
GET /{name} · DELETE /{name}fetch · delete
POST /{name}/nodes · DELETE /{name}/nodes/{node_id}nodes
POST /{name}/edgesadd an edge
GET /{name}/exportexport
POST /generate/persona · POST /generate/ideationgenerate

Keep mindmaps under 500 nodes; see MCP tools.

Durable operations​

Base path /api/v2/operations. See Durable operations.

Method and pathPurpose
POST /submit an operation
GET /{id}the authoritative receipt
GET /{id}/events?after=Nordered state events (server-sent events)
GET /statscounts per state, oldest unfinished operation, query cache
POST /{id}/retryre-drive now (operator)
POST /{id}/rejectdead-letter, body {"reason":"…"} (operator)

Memory Palace (palace feature)​

Base path /api/v1/palace: GET /wake, GET /recall, POST /search, POST /ingest, DELETE /drawer/{id}, GET /status, POST /hybrid-search.

A2A​

Method and pathPurpose
GET /agent.jsonthe agent card; advertises bearer authentication
POST /a2a/tasks/sendcreate a task: {"skill_id": "…", "input": {…}}
GET /a2a/tasks/{id}task status

MCP over HTTP​

PathTransport
/mcp/httpstreamable HTTP (current standard)
/mcp/sse and POST /mcp/messages?sessionId=…legacy SSE

Sessions are bound to the principal that opened them. See MCP tools for the tools and example calls.