---
title: "Search"
method: POST
path: "/api/kb/search"
tags: ["kb"]
---

# Search

`POST /api/kb/search`

Search documents in the knowledge base.

Args:
    collection: Target collection to search within.
    query_text: Query text to search for.
    embedding_model_id: Embedding model ID (required for dense/hybrid search).
    search_type: Search strategy (dense, sparse, or hybrid).
    top_k: Maximum number of results to return.
    filters: Optional filters for search.
    fusion_config: Optional fusion configuration for hybrid search.
    rerank_model_id: Optional rerank model for result reordering.
    rerank_top_k: Override for rerank result count.
    readonly: Whether to avoid index modifications.
    nprobes: Number of partitions to probe for ANN search.
    refine_factor: Refine factor for ANN search re-ranking.
    fallback_to_sparse: Allow hybrid search to fallback to sparse.

## Response `200`

Successful Response

- SearchPipelineResult — Unified response payload for document search pipeline.
  - `status` string, required — Pipeline status: success|partial_success|error
  - `search_type` 'dense' | 'sparse' | 'hybrid', required — Unified search types for the document search pipeline.
  - `results` SearchResult[] — Search results (possibly reranked)
    - `doc_id` string, required — Document ID
    - `chunk_id` string, required — Chunk ID within the document
    - `text` string, required — Text content of the chunk
    - `score` number, required — Similarity score (0-1, higher is better); must be between 0 and 1 inclusive
    - `parse_hash` string, required — Parse version hash
    - `model_tag` string, required — Embedding model identifier
    - `created_at` string, date-time — Chunk creation timestamp
    - `metadata` object, nullable — Additional metadata for the chunk (page_number, section, source, etc.)
    - `vector_score` number, nullable — Original vector search score (before rerank/fusion)
    - `fts_score` number, nullable — Original FTS search score (before rerank/fusion)
    - `vector_rank` integer, nullable — Original rank in vector search results (1-based)
    - `fts_rank` integer, nullable — Original rank in FTS search results (1-based)
  - `result_count` integer, required — Number of results returned
  - `warnings` string[] — Non-fatal warnings and fallback messages
  - `message` string, required — Human-readable pipeline outcome message
  - `used_rerank` boolean — Whether rerank model was applied to the results

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/xorbitsai/apis/xagent.md) · [All operations](https://skmtc.net/xorbitsai/apis/xagent/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/xorbitsai/xagent/revisions/33e4ba4936ad/schema)