Skip to main content
POST
/
api
/
kb
/
search
Search
curl --request POST \
  --url https://api.example.com/api/kb/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data 'collection=<string>' \
  --data 'query_text=<string>' \
  --data embedding_model_id=text-embedding-v4 \
  --data search_type=dense \
  --data top_k=50 \
  --data 'filters={}' \
  --data 'fusion_config={}' \
  --data 'rerank_model_id=<string>' \
  --data rerank_top_k=123 \
  --data readonly=true \
  --data nprobes=123 \
  --data refine_factor=123 \
  --data fallback_to_sparse=true
{
  "status": "<string>",
  "search_type": "dense",
  "result_count": 123,
  "message": "<string>",
  "results": [
    {
      "doc_id": "<string>",
      "chunk_id": "<string>",
      "text": "<string>",
      "score": 0.5,
      "parse_hash": "<string>",
      "model_tag": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "metadata": {},
      "vector_score": 123,
      "fts_score": 123,
      "vector_rank": 2,
      "fts_rank": 2
    }
  ],
  "warnings": [
    "<string>"
  ],
  "used_rerank": false
}

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/x-www-form-urlencoded
collection
string
required

Target collection to search within

query_text
string
required

Query text to search for

embedding_model_id
string
default:text-embedding-v4

Embedding model ID (default: text-embedding-v4)

search_type
enum<string> | null

Search strategy: dense, sparse, or hybrid (default: hybrid)

Available options:
dense,
sparse,
hybrid
top_k
integer | null

Maximum number of results to return (default: 5)

Required range: 1 <= x <= 100
filters
Filters · object

Optional filters to apply during search (LanceDB format)

fusion_config
Fusion Config · object

Optional fusion configuration for hybrid search

rerank_model_id
string | null

Optional rerank model ID for result reordering

rerank_top_k
integer | null

Optional override for rerank result count

readonly
boolean | null

Avoid index modifications (default: False)

nprobes
integer | null

Number of partitions to probe for ANN search

refine_factor
integer | null

Refine factor for ANN search re-ranking

fallback_to_sparse
boolean | null

Allow hybrid search to fallback to sparse (default: True)

Response

Successful Response

Unified response payload for document search pipeline.

status
string
required

Pipeline status: success|partial_success|error

search_type
enum<string>
required

Actual search strategy executed (post-fallback if any)

Available options:
dense,
sparse,
hybrid
result_count
integer
required

Number of results returned

message
string
required

Human-readable pipeline outcome message

results
SearchResult · object[]

Search results (possibly reranked)

warnings
string[]

Non-fatal warnings and fallback messages

used_rerank
boolean
default:false

Whether rerank model was applied to the results