---
title: "Search Knowledge Base"
method: POST
path: "/api/v1/knowledge/search"
tags: ["Knowledge Bases"]
---

# Search Knowledge Base

`POST /api/v1/knowledge/search`

Search across one or more knowledge bases. Supports semantic search via query text, tag-based filtering, or a combination of both. Set `searchMode` to `hybrid` to additionally run a full-text keyword leg and fuse it with the semantic results.

## Request body

- object
  - `workspaceId` string, required — The workspace containing the knowledge bases.
  - `knowledgeBaseIds` union, required — Array of knowledge base IDs to search across.
    - string — A single knowledge base ID.
    - string[] — An array of knowledge base IDs to search across.
  - `query` string — Search query text for semantic similarity search. Either query or tagFilters must be provided.
  - `topK` integer — Maximum number of results to return.
  - `tagFilters` TagFilter[] — Tag-based filters. Either query or tagFilters must be provided.
    - `tagName` string, required — Display name of the tag to filter by.
    - `fieldType` 'text' | 'number' | 'date' | 'boolean' — Data type of the tag field.
    - `operator` string — Comparison operator (e.g. eq, neq, gt, lt, gte, lte, contains, between).
    - `value` union, required — Value to filter by.
      - string
      - number
      - boolean
    - `valueTo` union — Upper bound value for 'between' operator.
      - string
      - number
  - `searchMode` 'vector' | 'hybrid' — Retrieval strategy. `vector` ranks purely on embedding similarity. `hybrid` also runs a full-text keyword search and fuses the two rankings by reciprocal rank, which retrieves exact tokens — error codes, ticket keys, identifiers, rare product names — that embeddings alone rank poorly. Ignored when only tagFilters are provided.

## Response `200`

Search results.

- object
  - `success` boolean — Whether the request was successful.
  - `data` object — Response payload containing the search results and metadata.
    - `results` SearchResult[] — Array of search result objects ranked by similarity.
      - `documentId` string — ID of the source document.
      - `documentName` string — Filename of the source document.
      - `sourceUrl` string, nullable — URL to the original source document for connector-synced documents (e.g., a Confluence page, Google Doc, or Notion page). Null for documents without an external source.
      - `content` string — The matched chunk content.
      - `chunkIndex` integer — Index of the chunk within the document.
      - `metadata` object — Tag metadata associated with the chunk (display names mapped to values).
      - `similarity` number — Similarity score (0-1, where 1 is most similar).
    - `query` string — The search query used.
    - `knowledgeBaseIds` string[] — Knowledge base IDs that were searched.
    - `topK` integer — Maximum results requested.
    - `totalResults` integer — Number of results returned.

## Other responses

- `400` — Invalid request parameters. Check the details array for specific validation errors.
- `401` — Invalid or missing API key. Ensure the X-API-Key header is set with a valid key.
- `403` — Access denied. You do not have permission to access this resource. For audit log endpoints, this requires an Enterprise subscription and organization admin/owner role.
- `404` — The requested resource was not found. Verify the ID is correct and belongs to your workspace.
- `429` — Rate limit exceeded. Wait for the duration specified in the Retry-After header before retrying. The X-RateLimit-* headers accompany every response from an authenticated v1 request — success and error alike — and are omitted only when the request fails authentication, since no rate-limit bucket is consulted in that case.

---

[API](https://skmtc.dev/simstudioai/apis/sim-api.md) · [All operations](https://skmtc.dev/simstudioai/apis/sim-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/simstudioai/sim-api/revisions/66a471c5b1df/schema)