---
title: "Search knowledge base"
method: POST
path: "/v2/knowledge/{knowledge_id}/search"
tags: ["Knowledge Bases"]
---

# Search knowledge base

`POST /v2/knowledge/{knowledge_id}/search`

Search a Knowledge Base and return the most similar chunks, along with their search and rerank scores. Note that all configuration changes made in the API will override the settings in the UI.

## Path parameters

- `knowledge_id` string, required

## Request body

- SearchKnowledgeRequest — SearchKnowledgeRequest mirrors the existing public search body and adds the internal retrieval configuration override used by the knowledge testing UI.
  - `query` string, required — The query to use to search the knowledge base
  - `top_k` integer — The number of results to return. If not provided, will default to the knowledge base configured `top_k`.
  - `threshold` number, double — The threshold to apply to the search. If not provided, will default to the knowledge base configured `threshold`
  - `search_type` 'vector_search' | 'keyword_search' | 'hybrid_search'
  - `filter_by` union — The metadata filter to apply to the search. Check the [Searching a Knowledge Base](https://docs.orq.ai/docs/knowledge/api#knowledge-base-search) for more information.
    - object
    - object — And
      - `and` object[], required
    - object — Or
      - `or` object[], required
  - `search_options` SearchOptions
    - `include_vectors` boolean — Whether to include the vector in the chunk
    - `include_metadata` boolean — Whether to include the metadata in the chunk
    - `include_scores` boolean — Whether to include the scores in the chunk
  - `rerank_config` SearchRerankConfig
    - `model` string, required — The name of the rerank model to use. Refer to the [model list](https://docs.orq.ai/docs/proxy#/rerank-models).
    - `threshold` number, double — The threshold value used to filter the rerank results, only documents with a relevance score greater than the threshold will be returned
    - `top_k` integer — The number of top results to return after reranking. If not provided, will default to the knowledge base configured `top_k`.
  - `agentic_rag_config` union — Override the agentic RAG configuration for this search. If not provided, will use the knowledge base configured agentic RAG settings.
    - object — Represents a dynamically typed value which can be either null, a number, a string, a boolean, a recursive struct value, or a list of values.
    - object — Represents a dynamically typed value which can be either null, a number, a string, a boolean, a recursive struct value, or a list of values.
  - `retrieval_config` SearchRetrievalConfig — SearchRetrievalConfig mirrors RetrievalConfigInDatabaseSchema. Type remains optional because external knowledge bases use the same base configuration without a retrieval strategy discriminator.
    - `type` 'vector_search' | 'keyword_search' | 'hybrid_search'
    - `top_k` integer
    - `threshold` number, double
    - `rerank_config` object, nullable — Override reranking for this retrieval configuration. Omit to inherit stored settings or set to null to disable reranking.
      - `enabled` boolean
      - `provider` string
      - `top_k` integer
      - `model` string
      - `model_db_id` string
      - `model_type` 'rerank'
      - `model_parameters` object
        - `threshold` number
      - `integration_id` string, nullable

## Response `200`

Search knowledge base

- SearchKnowledgeResponse
  - `matches` SearchKnowledgeMatch[], required — Matching chunks. The response codec must emit this field even when empty.
    - `id` string, required
    - `text` string, required
    - `vector` number[] — The service maps the internal embedding field to this public name. Empty repeated fields are omitted by proto JSON, preserving optional vectors.
    - `metadata` object — Arbitrary chunk metadata, omitted unless requested.
    - `scores` SearchKnowledgeScores
      - `rerank_score` number, double
      - `search_score` number, double

---

[API](https://skmtc.net/orq-ai/apis/orq-ai-api.md) · [All operations](https://skmtc.net/orq-ai/apis/orq-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/orq-ai/orq-ai-api/revisions/9a63ca712c8b/schema)