Retrieval
Retrieval

Query Retrieval

post/v2/retrieval/query

Request

  • Base URL: https://api.knowhereto.ai/api
  • URL: https://api.knowhereto.ai/api/v2/retrieval/query
  • Auth: none declared

Headers

authorizationstring nullable

Bearer <token> OR internal signature auth

Request body

namespacestring nullable

Effective namespace; defaults to default

querystring required
top_kinteger
include_document_idsstring[] nullable

Document allowlist: null means unrestricted, [] means empty; exclusions win.

exclude_document_idsstring[]

Documents excluded from every retrieval path. Exclusions override include_document_ids.

data_typeinteger

Chunk type filter: 1=all, 2=text, 3=image, 4=table, 5=text+image, 6=text+table, 7=page, 8=text+image+table

chunk_typesstring[] nullable

Allowed chunk types for retrieval. Options: text, image, table, page. None or empty means all types. Overrides data_type if provided.

signal_pathsstring[]

Path keywords for include/exclude filtering

filter_mode'delete' | 'keep'

Signal path filter mode

rerankboolean

Enable LLM reranking after RRF fusion

thresholdnumber

Minimum RRF score threshold

internal_recall_kinteger nullable

Override per-channel recall count

use_agenticboolean nullable

Turns agent retrieval on or off. False uses classic map-unit BM25. Unset or true turns agent retrieval on; AGENT_EXPLORE_HARNESS then selects Cursor (cursor_sdk) or Knowhere's own harness (openai).

agent_explore_modelstring nullable

Optional Cursor model when agent retrieval is on and AGENT_EXPLORE_HARNESS=cursor_sdk. Omit or leave empty to use AGENT_EXPLORE_CURSOR_MODEL (default composer-2.5). Ignored when agent retrieval is off or the harness is openai.

conversation_idstring nullable

Caller-supplied conversation identifier, threaded through for retrieval tracing. Does not affect caching or result content.

Response

Successful Response

namespacestring required
querystring required
router_usedstring required
evidenceobject[]

Grouped evidence blocks. Each group starts with [E1] [§ source_file_name / parent_path]. Text and table HTML stay as text parts; images stay as image parts at their placeholder positions.

evidence_textstring

DEPRECATED. Always empty. Knowhere no longer projects evidence into a string. Use evidence.

answer_textstring

DEPRECATED. Always empty; KNOWHERE no longer generates answers. Use evidence and synthesize answers downstream.

referenced_chunksobject[]
resultsobject[]

Raw path chunks for debug. Content keeps placeholders; composed parts live on evidence.

stop_reasonstring nullable
failure_reasonstring nullable
decision_traceobject[] nullable

Per-step agentic retrieval trace. Each entry follows the observation/decision/result schema.

Changes

No recorded changes to this operation across all 1 revision of this API.