Retrieve

retrieve is gated by retrieve and is the method most clients use. A single call can drive the server’s entire pipeline — query transform, hybrid recall, fusion, rerank, MMR diversification, recency weighting, metadata filtering, and citation assembly. Every option beyond query/k is optional and honoured only within the advertised retrieve capability.

{
  "jsonrpc": "2.0", "id": 2, "method": "retrieve",
  "params": {
    "query": "transformer attention complexity",
    "k": 5,
    "mode": "hybrid",
    "rerank": { "method": "cross-encoder", "topN": 100 },
    "mmr": { "lambda": 0.5 },
    "filter": { "and": [
      { "field": "lang", "op": "eq", "value": "en" },
      { "field": "year", "op": "gte", "value": 2017 }
    ] },
    "_meta": { "progressToken": "t2" }
  }
}

{
  "jsonrpc": "2.0", "id": 2, "result": {
    "hits": [
      { "id": "arxiv:1706.03762#3", "score": 0.94,
        "text": "Attention is all you need …",
        "citation": { "uri": "https://arxiv.org/abs/1706.03762", "title": "Attention Is All You Need" },
        "meta": { "year": 2017 } }
    ],
    "usage": { "candidates": 100, "reranked": 100, "latencyMs": 42 }
  }
}

Core params

string | Content | Content[]

required

The query — a bare string, or Content block(s) for multimodal retrieval.

integer

default:"10"

The final number of hits to return. Clamped to retrieve.maxK.

"dense" | "sparse" | "hybrid"

Retrieval mode. MUST be one of the advertised retrieve.modes.

"text" | "image" | "audio" | "code" | "multimodal"

default:"text"

The query modality for multimodal engines.

Pipeline params

integer

Recall-stage candidate count before rerank (default server-chosen, e.g. max(k, 100)).

object

{ method: "rrf" | "weighted", weights?, rrfK? } — how to combine dense and sparse lists in hybrid mode.

object | false

{ method, model?, topN? } to rerank inside the call, or false to skip. Needs retrieve.rerankBuiltin.

object

{ lambda: 0.5 } — MMR diversification. lambda 0 = max diversity, 1 = pure relevance.

"rewrite" | "hyde" | "multi-query" | "decompose" | false

Apply a query transform before recall (needs transform).

Assembly params

object

A metadata filter tree. Fields are validated against filter.fields.

float

Drop hits below this score.

object

{ field, halfLifeDays } — exponential recency weighting.

The retrieval granularity to return — a chunk (classic), a whole document (LongRAG), a graph node/triplet/path/subgraph (GraphRAG), a community summary, a RAPTOR tree-node, or a rendered page. Must be in retrieve.units.

integer

Abstraction level in a hierarchical corpus — RAPTOR tree depth or Leiden level. 0 is the leaf/most-specific layer.

integer

Pack top hits until their bodies reach this many tokens instead of a fixed k — long-context readers and the chunk-explosion problem. Needs retrieve.tokenBudget.

string

Opaque token threading this call into an agentic trajectory so the server can dedup already-seen hits and cache trajectory state. Needs session.

boolean

default:"true"

Include the hit body text.

boolean

default:"false"

Include each hit’s stored vector.

integer

Determinism hint — fixes stochastic steps. See below.

string

Pin retrieval to a corpus snapshot. See below.

boolean

default:"true"

If true, an unsupported option is -32005; if false, the server MAY degrade and note it in usage.notes.

string

Opaque pagination cursor (needs pagination).

Result

Hit[]

The ranked results — see the Hit shape below.

string

Opaque cursor for the next page, if any.

string

The corpus snapshot actually served.

object

{ candidates, reranked, latencyMs, notes? } per-request telemetry.

string

The query after a server-side rewrite, if applied.

The Hit shape

{
  "id": "arxiv:1706.03762#3",
  "score": 0.94,
  "confidence": 0.88,
  "text": "Attention is all you need …",
  "content": [{ "type": "image", "mimeType": "image/png", "uri": "…/page-3.png" }],
  "modality": "text",
  "unit": "chunk",
  "level": 0,
  "meta": { "year": 2017 },
  "vector": [0.01, -0.03],
  "scores": { "dense": 0.7, "sparse": 0.3, "rerank": 0.94 },
  "citation": { "source": "…", "uri": "…", "title": "…", "page": 3 },
  "provenance": { "path": ["e:turing", "e:vonneumann"], "leaves": ["doc:42#1"] },
  "trust": { "level": "trusted", "score": 0.98, "injectionSuspected": false },
  "chunk": { "docId": "arxiv:1706.03762", "index": 3, "context": "…" }
}

id is in the server’s identifier space; cross-engine fusion keys on the stringified id.
confidence is a normalised [0,1] relevance/self-eval signal — unlike score it is comparable across calls, so corrective and adaptive clients threshold on it (CRAG buckets, Self-RAG IsRel). Needs retrieve.confidence.
unit/level tell the client the granularity and abstraction level of the hit so it can pack or re-query at the right level.
scores exposes the per-stage contribution (dense/sparse/rerank) for debugging and telemetry.
provenance carries graph/tree lineage (path · nodes · edges · leaves) for auditable, path-level citation (GraphRAG, HippoRAG, RAPTOR).
trust carries provenance and safety signals (injectionSuspected, sanitized) so a downstream LLM can weight or quarantine untrusted content before it enters a prompt.
content/modality carry non-text bodies for visual-document and multimodal retrieval.

Scores are server-scaled

score is the engine’s native relevance number — cosine similarity, a dot product, raw BM25F, whatever the backend emits. Its scale is server-specific, so two servers’ score values are never directly comparable, even if both look like “0.94”. A server MAY advertise retrieve.scoreScale (cosine · dot · bm25 · probability · unbounded) so a client can label or bucket scores — but that is informational, not a comparability promise.

For cross-server ranking or rank fusion, key on rank position (RRF) or the normalised [0,1] confidence field — never raw score. confidence is defined to be comparable across calls precisely so that corrective/adaptive clients (CRAG, Self-RAG) can threshold on it; score is not.

The funnel invariant

The three size knobs form a funnel and MUST satisfy candidateK ≥ rerank.topN ≥ k. The server clamps each to retrieve.maxK / rerank.maxCandidates, SHOULD report effective counts in usage, and MUST NOT return more than k hits.

If a client requests an unsupported mode/method and strict is true (the default), the server returns -32005 (OptionUnsupported) rather than silently degrading. Set strict: false to allow graceful fallback.

Determinism & reproducibility

For evals, regression tests, and audits, two optional handles make a result repeatable:

seed — fix stochastic steps

A client-supplied integer that fixes any stochastic step (ANN exploration, MMR tie-breaking, LLM rerank sampling). A server that honours it MUST return identical results for identical (query, params, seed, indexVersion); one that cannot MUST ignore it (never error) and SHOULD note non-determinism in usage.notes. Advertised via retrieve.deterministic.

indexVersion — pin a corpus snapshot

An opaque token identifying a corpus snapshot. A snapshot-capable server echoes the served snapshot, and when a client pins one MUST either serve it or fail with -32010 if it was garbage-collected — never silently serve a different one. Advertised via retrieve.snapshots.

Stream long retrievals

Attach a progressToken to receive incremental progress and partial hits.

Get Started

Core Concepts

Methods

Features

Operating a Server

Core params

Pipeline params

Assembly params

Result

The Hit shape

Scores are server-scaled

The funnel invariant

Determinism & reproducibility

Stream long retrievals

​Core params

​Pipeline params

​Assembly params

​Result

​The Hit shape

​Scores are server-scaled

​The funnel invariant

​Determinism & reproducibility

Stream long retrievals

Core params

Pipeline params

Assembly params

Result

The Hit shape

Scores are server-scaled

The funnel invariant

Determinism & reproducibility