Skip to main content
POST
Context Retrieval [Cloud-only]

Authorizations

Authorization
string
header
required

API key issued by EverOS, sent as Authorization: Bearer <api_key>.

Body

application/json
user_id
string
required

Required. The user whose memories are searched, matched against the messages' sender_id. agent_id is not accepted (422); use /api/v2/memory/search for agent memories.

Required string length: 1 - 256
query
string
required

The question to gather evidence for. The loop keeps searching until it judges the evidence sufficient to answer it, so a full question works better than a few keywords.

Minimum string length: 1
app_id
string
default:default

Scope to search in, defaulting to "default". Must match the pair used on write.

Maximum string length: 128
project_id
string
default:default

Second half of the scope, defaulting to "default".

Maximum string length: 128
method
string
default:context

Fixed to "context" and may be omitted. Any other value is rejected with 422: this endpoint does not switch retrieval methods, use /api/v2/memory/search for those.

Allowed value: "context"
top_k
integer
default:-1

Maximum number of episodes returned. Either -1 (the default, letting the engine decide) or a value from 1 to 100; anything else is rejected with 422.

min_score
number | null

Not supported here: any value is rejected with 422. Results are ranked by rank fusion over the loop's searches, not by a similarity score, so there is no floor to apply.

Required range: 0 <= x <= 1
include_profile
boolean
default:false

Also return the user's profile alongside the hits, saving a second call.

filters
FilterNode · object | null

Optional filter tree — recursive AND / OR arrays mixed with the scalar conditions being matched.

Response

The episodes the loop found, in the same SearchData shape as /api/v2/memory/search.

request_id
string
required

Request trace id (peer to data)

data
SearchData · object
required

Endpoint-defined business result