> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knowledgestack.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Semantic Search

> Search your documents using natural language. Knowledge Stack converts your query into a vector embedding and finds the most relevant content across your knowledge base.

## How it works

When you search, Knowledge Stack:

1. Converts your query text into a vector embedding.
2. Finds the most similar document chunks using vector similarity.
3. Filters results by your specified scope and metadata.
4. Enforces authorization — you only see results you have permission to read.
5. Returns ranked results with similarity scores.

## Search endpoint

```
POST /chunks/search
```

### Request

```bash theme={null}
curl -X POST https://your-instance.example.com/api/v1/chunks/search \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "query": "What is the deployment architecture?",
    "top_k": 10,
    "score_threshold": 0.4
  }'
```

### Parameters

| Parameter         | Type          | Default                   | Description                                                                |
| ----------------- | ------------- | ------------------------- | -------------------------------------------------------------------------- |
| `query`           | string        | *(required)*              | Your search query in natural language.                                     |
| `top_k`           | integer       | 5                         | Number of results to return (1-50).                                        |
| `score_threshold` | float         | 0.3                       | Minimum similarity score (0.0-1.0). Results below this score are excluded. |
| `parent_path_ids` | list of UUIDs | tenant's `/shared` folder | Restrict search to specific folders or documents by their path part IDs.   |
| `chunk_type`      | string        | all types                 | Filter by content type: `TEXT`, `TABLE`, `IMAGE`, or `UNKNOWN`.            |
| `updated_at`      | datetime      | none                      | Only return chunks updated after this timestamp.                           |

### Response

The response is a list of matching chunks, sorted by relevance (highest score first). Each result includes:

* **Content** — The actual text of the chunk.
* **Score** — A similarity score between 0 and 1.
* **Path info** — Where this chunk lives in the document hierarchy.
* **Metadata** — Additional context like bounding boxes for PDF content and S3 URLs for images.

## Understanding scores

Scores represent how similar a chunk is to your query:

| Score range | Meaning                                 |
| ----------- | --------------------------------------- |
| 0.7 - 1.0   | Highly relevant — strong semantic match |
| 0.4 - 0.7   | Moderately relevant — related content   |
| 0.3 - 0.4   | Loosely relevant — tangential match     |
| Below 0.3   | Excluded by default (below threshold)   |

Adjust `score_threshold` based on your use case. Lower it for broader recall, raise it for higher precision.

## Scoping your search

### Search within specific folders

Pass `parent_path_ids` to restrict search to specific parts of your knowledge base:

```bash theme={null}
curl -X POST https://your-instance.example.com/api/v1/chunks/search \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "query": "quarterly revenue",
    "parent_path_ids": ["folder-path-part-id-1", "folder-path-part-id-2"],
    "top_k": 10
  }'
```

If you don't specify `parent_path_ids`, the search defaults to your tenant's `/shared` folder.

### Filter by content type

Search only specific types of content:

```bash theme={null}
curl -X POST https://your-instance.example.com/api/v1/chunks/search \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "query": "revenue breakdown",
    "chunk_type": "TABLE",
    "top_k": 5
  }'
```

## Authorization and search

Search results are always filtered by your permissions. You will only see chunks from documents you have read access to.

* **Owners and Admins** can see results from anywhere in the tenant.
* **Users** only see results within their authorized paths.

If your requested search scope and your permissions don't overlap, the search returns an empty list (not an error).

| Your search scope       | Your permissions                                   | What you see                         |
| ----------------------- | -------------------------------------------------- | ------------------------------------ |
| `/shared/docs/projectA` | Read access to `/shared/docs`                      | Results from `/shared/docs/projectA` |
| `/shared`               | Read access to `/shared/docs` and `/shared/images` | Results from both folders            |
| `/shared/docs`          | Read access to `/users/abc` only                   | Empty list (no overlap)              |