---
title: "Search Documents"
method: POST
path: "/api/v1/knowledge/documents/search"
tags: ["knowledge-documents"]
---

# Search Documents

`POST /api/v1/knowledge/documents/search`

## Request

- Base URL: `https://api.gnosari.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.gnosari.com/api/v1/knowledge/documents/search`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-AUTH-TOKEN`

Search indexed knowledge documents with mode selection.

Supports three search modes:
- `semantic`: Vector similarity search using embeddings (best for conceptual queries)
- `keyword`: Traditional text-based search (best for exact matches)
- `hybrid`: Combination of both (recommended, default)

**Request Body:**
- `query`: Search query text (required, 1-1000 characters)
- `mode`: Search mode (semantic, keyword, hybrid). Default: hybrid
- `source_ids`: Optional list of source IDs to filter by
- `limit`: Maximum results (1-100). Default: 20
- `offset`: Number of results to skip. Default: 0

**Response:**
- `results`: List of search results with relevance scores
- `total`: Total matching documents
- `mode_used`: The search mode that was used

**Scores:**
Each result includes:
- `score`: Raw relevance score from search engine
- `normalized_score`: Score normalized to 0-100 range (100 = best match)

**Security:**
Search is scoped to the authenticated user's account index.

## Request body

- KnowledgeSearchRequest: Request schema for knowledge search.
  - `query` string, required: Search query text
  - `mode` 'semantic' | 'keyword' | 'hybrid': Search mode for knowledge queries. - semantic: Vector similarity search using embeddings - keyword: Traditional text-based search - hybrid: Combination of semantic and keyword search (recommended)
  - `source_ids` string[], nullable: Filter by source IDs
  - `limit` integer: Maximum results to return
  - `offset` integer: Number of results to skip

## Response `200`

Successful Response

- KnowledgeSearchResponse: Response schema for knowledge search.
  - `results` KnowledgeSearchResultItem[]: List of search results
    - `document_id` string, required: OpenSearch document ID
    - `title` string, required: Document title
    - `content_snippet` string: Relevant content snippet from the document
    - `score` number: Raw relevance score from search engine
    - `normalized_score` integer: Normalized score (0-100)
    - `source_id` string, required: Source ID
  - `total` integer: Total matching documents
  - `mode_used` 'semantic' | 'keyword' | 'hybrid': Search mode for knowledge queries. - semantic: Vector similarity search using embeddings - keyword: Traditional text-based search - hybrid: Combination of semantic and keyword search (recommended)

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/gnosari/apis/gnosari-api.md) · [All operations](https://skmtc.dev/gnosari/apis/gnosari-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gnosari/apis/gnosari-api/revisions/f299cf53ae5f?raw)