Knowledge bases

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, or from the Model Context Protocol (MCP) server. Create and manage knowledge bases in the dashboard. 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`

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.

file = client.vector_stores.files.create(
    store.id,
    file="./guide.pdf",
    attributes={"source": "handbook"},
)
print(file.id, file.status)

curl https://api.synapsai.cloud/v1/vector_stores/$VECTOR_STORE_ID/files \
  -H "Authorization: Bearer $SYNAPSAI_API_KEY" \
  -F "[email protected]" \
  -F 'attributes={"source":"handbook"}'

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

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

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)

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
  }'

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.

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.

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. 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.

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

Getting started

Products

Guides

Examples

Manage

Platform

Resources

Support

Legal

Knowledge bases and `vector_store`

Add documents

Connected sources

Search

API reference

Python SDK

Use a knowledge base from other products

​Knowledge bases and vector_store

​Add documents

​Connected sources

​Search

​API reference

​Python SDK

​Use a knowledge base from other products

Knowledge bases and `vector_store`

Add documents

Connected sources

Search

API reference

Python SDK

Use a knowledge base from other products