Retrieve API

POST `/v1/users/:user_id/streams/:stream_id/retrieve`

Run hybrid retrieval for one user and stream.

What This Route Is For

This is the main recall route for the runtime. It merges multiple retrieval signals instead of relying on a single search path. Signals can include:

semantic similarity
text retrieval
graph expansion
time filtering
organization knowledge
multimodal query input

Request

POST /v1/users/dylan/streams/11111111-1111-1111-1111-111111111111/retrieve
Authorization: Bearer <token>
Content-Type: application/json

{
  "org_id": "default",
  "agent_id": "coding-assistant",
  "query": "What does Dylan prefer for systems work?",
  "limit": 10,
  "enable_arbitration": false,
  "min_score": 0.2,
  "graph_depth": 1,
  "start_time": "2026-03-01T00:00:00Z",
  "end_time": "2026-03-31T23:59:59Z",
  "as_of": "2026-03-25T12:00:00Z"
}

Request Fields

Field	Type	Required	Description
`query`	string	Yes	Retrieval query text
`limit`	number	No	Max results, capped server-side
`enable_arbitration`	boolean	No	Enable API-level arbitrated retrieval behavior. This is separate from server-side `[reranker] type = "arbitrator"`.
`min_score`	number	No	Minimum score cutoff
`graph_depth`	number	No	Graph expansion depth
`start_time`	ISO8601	No	Valid-time lower bound
`end_time`	ISO8601	No	Valid-time upper bound
`as_of`	ISO8601	No	Transaction-time point-in-time filter
`org_id`	string	No	Include organization knowledge scope
`agent_id`	string	No	Filter toward one agent’s procedural memory
`image`	string	No	Base64 image for cross-modal retrieval
`audio`	string	No	Base64 audio for cross-modal retrieval
`video`	string	No	Base64 video for cross-modal retrieval

Response

{
  "stream_id": "11111111-1111-1111-1111-111111111111",
  "query": "What does Dylan prefer for systems work?",
  "results": [
    {
      "unit": {
        "id": "9db1d859-0a32-4c33-8b94-8cab9f8e0d16",
        "memory_type": "factual",
        "content": "Dylan prefers Rust for systems work.",
        "keywords": ["rust", "systems"],
        "level": 1
      },
      "score": 0.94
    }
  ],
  "query_time_ms": 8
}

Response Fields

Field	Meaning
`stream_id`	The stream used for this retrieval request
`query`	The final text query that was embedded and searched
`results[].unit`	The matched memory unit view
`results[].score`	Final ranking score after retrieval fusion
`query_time_ms`	Server-side retrieval latency

Practical Notes

Query text is always required, even for multimodal retrieval.
Shared organization knowledge can enter the result set when org_id is provided.
graph_depth lets retrieval expand through graph-linked neighbors instead of staying on direct matches only.
agent_id is useful when you want to bias toward one agent’s procedural memory.

​Retrieve API

​POST /v1/users/:user_id/streams/:stream_id/retrieve

​What This Route Is For

​Request

​Request Fields

​Response

​Response Fields

​Practical Notes

​Related Pages

Retrieve API

POST `/v1/users/:user_id/streams/:stream_id/retrieve`

What This Route Is For

Request

Request Fields

Response

Response Fields

Practical Notes

Related Pages