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

# Knowledge bases

> Store documents, sync connected sources, and search them through the OpenAI-compatible vector store API

A **knowledge base** is a private document collection for your account. Upload files or connect a source, and SynapsAI chunks, embeds, and indexes the content so you can search it from the API, from an [agent](/guides/agents), or from the Model Context Protocol (MCP) server.

Create and manage knowledge bases in the [dashboard](https://platform.synapsai.cloud). The same collections are available on the API.

## Knowledge bases and `vector_store`

The product name in the dashboard is **knowledge base**. The public API uses OpenAI's resource name, **`vector_store`**, so existing OpenAI clients keep working if you change the base URL and API key.

A vector store id **is** the knowledge base id. Creating a vector store creates a knowledge base. Searching a vector store searches that knowledge base. There is no separate vector-store product.

| Dashboard | API |
| - | - |
| Knowledge base | `vector_store` |
| Knowledge base id | `vector_store_id` |
| File / document | `vector_store.file` |

```python theme={null}
from synapsai import SynapsAI

client = SynapsAI()

store = client.vector_stores.create(
    name="Product docs",
    description="Public handbook",
)
# store.id is the knowledge base id
```

## Add documents

Upload a file with multipart form data, or attach a document that is already in the knowledge base by id. Send **either** `file` **or** `file_id`, not both.

Supported uploads include PDF, Office documents (`.doc`, `.docx`, `.ppt`, `.pptx`, `.xls`, `.xlsx`), text and markup (`.txt`, `.md`, `.html`, `.csv`, `.tsv`, `.json`), and common source files such as `.py` and `.ts`. Each file can be up to 512 MB.

<CodeGroup>
  ```python title="Python" theme={null}
  file = client.vector_stores.files.create(
      store.id,
      file="./guide.pdf",
      attributes={"source": "handbook"},
  )
  print(file.id, file.status)
  ```

  ```bash title="cURL" theme={null}
  curl https://api.synapsai.cloud/v1/vector_stores/$VECTOR_STORE_ID/files \
    -H "Authorization: Bearer $SYNAPSAI_API_KEY" \
    -F "file=@guide.pdf" \
    -F 'attributes={"source":"handbook"}'
  ```
</CodeGroup>

`status` is `in_progress` while the file is being parsed, then `completed` or `failed`. Poll retrieve until it finishes, then read the parsed text:

```python theme={null}
content = client.vector_stores.files.content(store.id, file.id)
for part in content.data:
    print(part.text)
```

## Connected sources

From the knowledge base page you can connect:

* Google Drive
* OneDrive and SharePoint
* Dropbox
* Notion
* Amazon S3

SynapsAI polls the source and ingests new or changed files, and removes documents that were deleted at the source. You can pause sync (for a number of minutes, or until you resume it), retry a failed document, or delete documents from the dashboard. Connector setup uses OAuth where the provider requires it.

Google Docs, Sheets, and Slides are exported and ingested. Notion pages are ingested as text.

## Search

<CodeGroup>
  ```python title="Python" theme={null}
  results = client.vector_stores.search(
      store.id,
      query="How do I rotate API keys?",
      max_num_results=10,
  )
  for item in results.data:
      print(item.score, item.filename, item.content)
  ```

  ```bash title="cURL" theme={null}
  curl https://api.synapsai.cloud/v1/vector_stores/$VECTOR_STORE_ID/search \
    -H "Authorization: Bearer $SYNAPSAI_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "How do I rotate API keys?",
      "max_num_results": 10
    }'
  ```
</CodeGroup>

`query` may be a string or a list of strings. Optional `filters` follow the OpenAI comparison and compound filter shape (`eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`, `and`, `or`). `ranking_options.score_threshold` drops hits below that score. `max_num_results` is between 1 and 50 (default 10).

Each hit includes `file_id`, `filename`, `score`, `attributes`, and `content` (text chunks).

## API reference

All routes are on `https://api.synapsai.cloud` and use your [API key](/manage/api-keys).

| Method | Path | Action |
| - | - | - |
| `GET` | `/v1/vector_stores` | List knowledge bases |
| `POST` | `/v1/vector_stores` | Create a knowledge base (`name`, `description`) |
| `GET` | `/v1/vector_stores/{vector_store_id}` | Retrieve one, including file counts |
| `POST` | `/v1/vector_stores/{vector_store_id}` | Rename or update the description |
| `DELETE` | `/v1/vector_stores/{vector_store_id}` | Delete the knowledge base |
| `POST` | `/v1/vector_stores/{vector_store_id}/search` | Search passages |
| `GET` | `/v1/vector_stores/{vector_store_id}/files` | List files (`limit`, `order`, `after`, `before`, `filter`) |
| `POST` | `/v1/vector_stores/{vector_store_id}/files` | Upload a file or attach a `file_id` |
| `GET` | `/v1/vector_stores/{vector_store_id}/files/{file_id}` | Retrieve a file |
| `POST` | `/v1/vector_stores/{vector_store_id}/files/{file_id}` | Update `attributes` |
| `DELETE` | `/v1/vector_stores/{vector_store_id}/files/{file_id}` | Delete a file |
| `GET` | `/v1/vector_stores/{vector_store_id}/files/{file_id}/content` | Read parsed text |

List endpoints return an OpenAI-style page: `object`, `data`, `first_id`, `last_id`, and `has_more`. `limit` is 1–100 (default 20). `order` is `asc` or `desc`.

Your API key needs vector-store permissions. A key scoped to a single knowledge base can upload files to that knowledge base only.

## Python SDK

`pip install --upgrade synapsai-python`. `client.vector_stores` and `client.vector_stores.files` call `https://api.synapsai.cloud/v1`. They create, list, update, delete, and search knowledge bases, and upload or attach files. The SDK uses the name `vector_store` because the HTTP API does.

```python theme={null}
from synapsai import SynapsAI

client = SynapsAI()

store = client.vector_stores.create(name="Product docs", description="Public handbook")
uploaded = client.vector_stores.files.upload_paths(store.id, ["./docs", "./README.md"])
results = client.vector_stores.search(store.id, query="How do I rotate API keys?")
```

`upload_paths` walks directories recursively. `AsyncSynapsAI` has the same methods. The CLI uploads files with `synapsai upload-vector-store-files`.

## Use a knowledge base from other products

* **Agents.** Assign one or more knowledge bases when you deploy an [agent](/guides/agents). The agent can search them and load a full document. Those tools are attached automatically; you do not add them to the tool list.
* **MCP.** SynapsAI runs an MCP server mounted at `/mcp`. Send `Authorization: Bearer` with your API key. The tools are `search_knowledge_base` (`kb_id`, `query`) and `retrieve_knowledge_base_content` (`kb_id`, `document_id`). `document_id` is the file id returned by search.

<Note>
  Deleting a knowledge base fails if an agent still references it. Remove it from those agents first.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.