Retrieval

Retrieve

Retrieve relevant chunks via hybrid search (vector + full-text), with filtering on built-in or user-defined metadata.

post/api/v1/retrieval/retrieve

Query parameters

project_idstring uuid nullable

organization_idstring uuid nullable

sessionstring nullable

index_idstring required

ID of the index to retrieve against.

querystring required

Natural-language query to retrieve relevant chunks.

top_kinteger nullable

Maximum number of results to return.

num_candidatesinteger nullable

Number of candidates for approximate nearest neighbor search.

vector_pipeline_weightnumber nullable

Weight of the vector search pipeline (0-1).

full_text_pipeline_weightnumber nullable

Weight of the full-text search pipeline (0-1).

score_thresholdnumber nullable

Minimum score threshold for returned results.

custom_filtersobject nullable

Filters on user-defined metadata fields.

{
  "index_id": "idx-abc123",
  "query": "What are the key findings?",
  "top_k": 10,
  "rerank": {
    "top_n": 5
  }
}

Successful Response

Changed in 4 of the 33 revisions of this API.16

Jun 9, 2026b17341164de94See the full diff
- ○
  added the optional property detail/items/ctx to the response with the 422 status
  response-optional-property-added
- ○
  added the optional property detail/items/input to the response with the 422 status
  response-optional-property-added
- ○
  added MetadataDict to the results/items/metadata response property anyOf list for the response status 200
  response-property-any-of-added
- ○
  removed subschema #1 from the results/items/metadata response property anyOf list for the response status 200
  response-property-any-of-removed
This revision also has 5 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
May 23, 202634da5826db1c1See the full diff
- ○
  endpoint added
  endpoint-added
May 21, 2026fb63fb8d662c1See the full diff
- ▲
  api path removed without deprecation
  api-path-removed-without-deprecation
This revision also has 46 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
May 19, 202664b8ab5b0a0a1See the full diff
- ○
  endpoint added
  endpoint-added