Retrieval Query

Query published documents in a namespace and receive cited evidence for downstream agents.

POST /v2/retrieval/query

v2 endpoint

This is a v2 endpoint. Optional llm_config (BYOK) is supported here only — not on POST /v1/retrieval/query.

Request Body

Parameter	Type	Required	Description
query	string	Yes	Natural-language retrieval query.
namespace	string	No	Isolation namespace. Defaults to "default". Max 255 chars.
top_k	integer	No	Maximum number of results to return. Default: 10.
use_agentic	boolean | null	No	When true, enables agentic retrieval (LLM document selection + section navigation). Default (null/false) uses classic 3-channel top-K.
chunk_types	string[]	No	Allowed chunk types: "text", "image", "table", "page". Empty or omitted means all types. Overrides data_type when provided.
data_type	integer	No	Deprecated. Legacy chunk-type filter (1–8). Prefer chunk_types. Default: 1 (all).
signal_paths	string[]	No	Path keywords for include/exclude filtering.
filter_mode	string	No	Signal-path filter mode: "delete" (default) or "keep".
channels	string[]	No	Lexical channels to run: "path", "content", "term". Empty means all.
channel_weights	object	No	Per-channel weight overrides (keys: path, content, term).
rerank	boolean	No	Enable LLM reranking after RRF fusion. Default: false.
threshold	number	No	Minimum RRF score threshold. Default: 0.0.
internal_recall_k	integer	No	Override per-channel recall count.
exclude_document_ids	string[]	No	Document IDs to exclude from results.
exclude_sections	object[]	No	Section exclusions. Each item: { "document_id": string, "section_path": string }.
llm_config	object	No	Bring-your-own-key (BYOK) OpenAI-compatible LLM credentials. Flat {api_key, model, base_url} applies to both channels; models picks per-channel model ids on the same endpoint; text / vision objects replace a channel entirely. When omitted, server defaults are used.
llm_config.api_key	string	Conditional	Required with base_url plus model and/or models. Provider API key.
llm_config.model	string	Conditional	Default model for both channels (overridden by models.*).
llm_config.base_url	string	Conditional	Required with api_key plus model and/or models. OpenAI-compatible base URL.
llm_config.models	object	No	Per-channel model ids sharing root api_key / base_url.
llm_config.models.text	string	No	Text / planning model id.
llm_config.models.vision	string	No	Vision / VLM model id.
llm_config.text	object	No	Text / planning LLM provider config (replaces root for text).
llm_config.text.api_key	string	Conditional	Required when text is present. Provider API key.
llm_config.text.model	string	Conditional	Required when text is present. Model identifier.
llm_config.text.base_url	string	Conditional	Required when text is present. OpenAI-compatible base URL.
llm_config.vision	object	No	Vision / VLM provider config (replaces root for vision).
llm_config.vision.api_key	string	Conditional	Required when vision is present. Provider API key.
llm_config.vision.model	string	Conditional	Required when vision is present. Model identifier.
llm_config.vision.base_url	string	Conditional	Required when vision is present. OpenAI-compatible base URL.

Response

Status: 200 OK

{
  "namespace": "default",
  "query": "What are the key findings on AI security?",
  "router_used": "agentic",
  "evidence_text": "# AI_Security_Report.docx\n## 1. Overview\n...",
  "answer_text": "",
  "referenced_chunks": [
    {
      "chunk_id": "d88e4c47-3c48-5bdf-b849-693c00453021",
      "document_id": "doc_abc123def456",
      "chunk_type": "text",
      "section_path": "AI_Security_Report.docx / 1. Overview / 1.1 Key Findings",
      "source_chunk_path": "kb/AI_Security_Report.docx/1. Overview/1.1 Key Findings",
      "file_path": null,
      "asset_url": null,
      "metadata": null
    }
  ],
  "results": [
    {
      "chunk_id": "d88e4c47-3c48-5bdf-b849-693c00453021",
      "chunk_type": "text",
      "content": "Key findings include...",
      "score": 0.42,
      "source_chunk_path": "kb/AI_Security_Report.docx/1. Overview/1.1 Key Findings",
      "file_path": null,
      "asset_url": null,
      "metadata": null,
      "source": {
        "document_id": "doc_abc123def456",
        "source_file_name": "AI_Security_Report.docx",
        "section_path": "AI_Security_Report.docx / 1. Overview / 1.1 Key Findings"
      }
    }
  ],
  "stop_reason": null,
  "failure_reason": null,
  "decision_trace": null
}

Response Fields

Field	Type	Description
namespace	string	Effective namespace used for the query.
query	string	Echo of the request query.
router_used	string	Retrieval route taken (e.g. classic RRF or agentic).
evidence_text	string	Hierarchical evidence text. Primary output for downstream agents.
answer_text	string	Deprecated. Always empty; KNOWHERE does not synthesize answers. Use evidence_text and synthesize downstream.
referenced_chunks	object[]	Structured chunk citations (especially useful after agentic retrieval).
referenced_chunks[].chunk_id	string	Content-hash chunk identifier.
referenced_chunks[].document_id	string	Parent document ID.
referenced_chunks[].chunk_type	string	"text", "image", "table", or "page".
referenced_chunks[].section_path	string	Human-readable section path.
referenced_chunks[].source_chunk_path	string | null	Original parser path.
referenced_chunks[].file_path	string | null	Asset path for images/tables.
referenced_chunks[].asset_url	string | null	Presigned asset URL when available.
results	object[]	Ranked chunk results with scores and source citations.
results[].chunk_id	string | null	Chunk identifier.
results[].chunk_type	string	Chunk type.
results[].content	string	Chunk content (text or HTML).
results[].score	number | null	Relevance score.
results[].source	object	Citation: document_id, source_file_name, section_path.
stop_reason	string | null	Why agentic retrieval stopped (when applicable).
failure_reason	string | null	Failure detail when retrieval could not complete normally.
decision_trace	object[] | null	Per-step agentic observation/decision/result trace.

Examples

Basic Query

cURL

curl -X POST https://api.knowhereto.ai/v2/retrieval/query \
  -H "Authorization: Bearer $KNOWHERE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the key findings on AI security?",
    "namespace": "default",
    "top_k": 10
  }'

Python

import requests

response = requests.post(
    "https://api.knowhereto.ai/v2/retrieval/query",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "query": "What are the key findings on AI security?",
        "namespace": "default",
        "top_k": 10
    }
)

data = response.json()
print(data["evidence_text"])
print(f"Results: {len(data['results'])}")

Node.js

const response = await fetch('https://api.knowhereto.ai/v2/retrieval/query', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'What are the key findings on AI security?',
    namespace: 'default',
    top_k: 10
  })
});

const data = await response.json();
console.log(data.evidence_text);
console.log(`Results: ${data.results.length}`);

Agentic Retrieval

cURL

curl -X POST https://api.knowhereto.ai/v2/retrieval/query \
  -H "Authorization: Bearer $KNOWHERE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Summarize supply-side recommendations from the security report",
    "namespace": "default",
    "use_agentic": true,
    "chunk_types": ["text", "table"],
    "top_k": 10
  }'

Python

import requests

response = requests.post(
    "https://api.knowhereto.ai/v2/retrieval/query",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "query": "Summarize supply-side recommendations from the security report",
        "namespace": "default",
        "use_agentic": True,
        "chunk_types": ["text", "table"],
        "top_k": 10
    }
)

data = response.json()
print(data["evidence_text"])
for chunk in data["referenced_chunks"]:
    print(chunk["document_id"], chunk["section_path"])

Node.js

const response = await fetch('https://api.knowhereto.ai/v2/retrieval/query', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'Summarize supply-side recommendations from the security report',
    namespace: 'default',
    use_agentic: true,
    chunk_types: ['text', 'table'],
    top_k: 10
  })
});

const data = await response.json();
console.log(data.evidence_text);
for (const chunk of data.referenced_chunks) {
  console.log(chunk.document_id, chunk.section_path);
}

With Custom LLM (BYOK)

OpenAI-compatible providers only.

• Flat {api_key, model, base_url} → both text and vision (multimodal shorthand)
• {api_key, base_url, models: {text, vision}} → same endpoint, different model ids
• text / vision objects → fully replace that channel (set both for different endpoints)
• a channel with no resolved model keeps the server default

cURL

curl -X POST https://api.knowhereto.ai/v2/retrieval/query \
  -H "Authorization: Bearer $KNOWHERE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the key findings on AI security?",
    "namespace": "default",
    "use_agentic": true,
    "llm_config": {
      "api_key": "sk-...",
      "model": "gpt-4.1",
      "base_url": "https://api.openai.com/v1"
    }
  }'

Python

import requests

response = requests.post(
    "https://api.knowhereto.ai/v2/retrieval/query",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    },
    json={
        "query": "What are the key findings on AI security?",
        "namespace": "default",
        "use_agentic": True,
        "llm_config": {
            "api_key": "sk-...",
            "model": "gpt-4.1",
            "base_url": "https://api.openai.com/v1"
        }
    }
)

data = response.json()
print(data["evidence_text"])

Node.js

const response = await fetch('https://api.knowhereto.ai/v2/retrieval/query', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'What are the key findings on AI security?',
    namespace: 'default',
    use_agentic: true,
    llm_config: {
      api_key: 'sk-...',
      model: 'gpt-4.1',
      base_url: 'https://api.openai.com/v1'
    }
  })
});

const data = await response.json();
console.log(data.evidence_text);

Errors

Code	HTTP Status	Description
INVALID_ARGUMENT	400	Missing or invalid parameters (e.g. empty query, invalid llm_config)
UNAUTHENTICATED	401	Invalid API key
RESOURCE_EXHAUSTED	429	Rate limit exceeded

Example Error Response

{
  "success": false,
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "llm_config requires root credentials and/or text/vision overrides",
    "request_id": "req_abc123",
    "details": {
      "field": "llm_config"
    }
  }
}

Next Steps

• Create Job - Ingest documents before querying
• API Overview - Full endpoint list
• Error Handling - Handle all error cases