# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
This site has an agentic ask interface you may use to query the documentation dynamically by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.knowbase.ai/index.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

---

# Welcome to Knowbase

Everything you need to know about using Knowbase

Knowbase is an AI-powered document intelligence platform. Upload your documents, videos, and audio — then chat with them to find answers instantly.

## What can you do with Knowbase?

* **Chat with your documents** — Ask questions about a single file or search across your entire library
* **Upload anything** — PDFs, Word docs, presentations, audio, video, YouTube links, and websites
* **Deploy AI Assistants** — Create chatbots powered by your knowledge base and embed them on your website
* **Connect your tools** — Search Google Drive, Notion, and Dropbox alongside your uploaded files
* **Share knowledge** — Generate share links so anyone can chat with your documents

## Quick links

| I want to...             | Go to                                                                   |
| ------------------------ | ----------------------------------------------------------------------- |
| Get started from scratch | [Creating Your Account](/getting-started/creating-your-account)         |
| Upload my first file     | [Uploading Your First File](/getting-started/uploading-your-first-file) |
| Chat with my documents   | [Chat with a File](/chat/chat-with-a-file)                              |
| Search my entire library | [Chat All](/chat/chat-all)                                              |
| Build a website chatbot  | [AI Assistants](/ai-assistants/ai-assistants)                           |
| Use the API              | [API Reference](/api-reference/api)                                     |


# Overview

Get up and running with Knowbase in under 5 minutes

New to Knowbase? This section walks you through everything you need to start chatting with your documents.

1. [Create your account](/getting-started/creating-your-account) — sign up and activate your free Pro trial
2. [Upload your first file](/getting-started/uploading-your-first-file) — add a document, video, or audio file
3. [Have your first chat](/getting-started/your-first-chat) — ask a question and get an answer with citations


# Creating Your Account

Sign up for Knowbase and start your free Pro trial

## Sign up

1. Go to [app.knowbase.ai](https://app.knowbase.ai) and click **Get Started**
2. Enter your email and create a password, or sign up with **Google**
3. You're in — every new account gets a **3-day Pro trial** with all features unlocked

## What's included in the trial

During your Pro trial you get access to:

* **2,000 queries/month** and **500 file uploads**
* **Thinking Mode** for deep multi-step analysis
* **AI Assistants** — create and deploy a chatbot
* **Connectors** — Google Drive, Notion, Dropbox
* **Web Search** on custom domains
* **API access**

After the trial ends, you'll switch to the Free plan. You can upgrade anytime from **Account > Plans & Billing**.

## Next step

Now let's [upload your first file](/getting-started/uploading-your-first-file).


# Uploading Your First File

Add your first document, video, or audio file to Knowbase

## How to upload

1. Click the **New File** tab in the top navigation
2. Drag and drop a file onto the upload area, or click to browse your files
3. Wait for processing — the file status will change from "Processing" to "Ready"

## Supported file types

| Category  | Formats                                    |
| --------- | ------------------------------------------ |
| Documents | PDF, DOCX, DOC, TXT, MD, PPTX, PPT         |
| Audio     | MP3, WAV, M4A, AAC, OGG, FLAC              |
| Video     | MP4, MOV, WEBM, AVI, MKV                   |
| Web       | YouTube links, website URLs                |
| Images    | PNG, JPG (within PDFs with Vision enabled) |

{% hint style="info" %}
**Tip:** You can upload up to 50 files at once by selecting multiple files or dragging a batch.
{% endhint %}

## What happens after upload

Knowbase automatically:

* Extracts text from documents and presentations
* Transcribes audio and video files
* Downloads and processes YouTube transcripts
* Creates searchable embeddings so you can chat with the content

## Next step

Your file is ready — let's [ask it a question](/getting-started/your-first-chat).


# Your First Chat

Ask your first question and get an answer with source citations

## Chat with a single file

1. Go to the **Library** tab
2. Click on any file to open it
3. Type a question in the chat input at the bottom
4. Hit Enter or click the send button

Knowbase will return an answer with **source citations** — clickable references that take you to the exact section of the document.

## Chat with your entire library

1. Go to the **Chat** tab in the top navigation
2. Type any question — Knowbase searches across **all your files** at once
3. The answer will include citations from whichever files are most relevant

{% hint style="info" %}
**Tip:** You can also drop specific files into the chat to narrow the search to just those documents.
{% endhint %}

## Follow-up questions

Knowbase remembers the conversation context. Ask follow-up questions naturally — no need to repeat yourself.

## Next steps

* Learn about [Chat All](/chat/chat-all) for library-wide search
* Try [Thinking Mode](/chat/thinking-mode) for complex questions
* Organize your files with [Channels](/knowledge-base/channels)


# Overview

How to build and organize your knowledge base

Your knowledge base is everything you've uploaded to Knowbase — documents, videos, audio, and web pages. This section covers how to add content and keep it organized.

* [Uploading Files](/knowledge-base/uploading-files) — all upload methods, formats, and processing
* [Library](/knowledge-base/library) — browsing, filtering, and managing your files
* [Channels](/knowledge-base/channels) — grouping files into topics or projects
* [Website Import](/knowledge-base/website-import) — importing web pages into your knowledge base


# Uploading Files

All the ways to add content to your knowledge base

## Upload methods

### Drag and drop

Go to the **New File** tab and drag files directly onto the drop zone. You can drop up to 50 files at once.

### YouTube links

Paste a YouTube URL into the upload area. Knowbase downloads the transcript and makes it searchable.

### From connectors

If you've connected Google Drive, Notion, or Dropbox, you can import files directly from those services. See [Connectors](/connectors/connectors).

## Supported formats

| Category  | Formats                            | Max size |
| --------- | ---------------------------------- | -------- |
| Documents | PDF, DOCX, DOC, TXT, MD, PPTX, PPT | 3 GB     |
| Audio     | MP3, WAV, M4A, AAC, OGG, FLAC      | 3 GB     |
| Video     | MP4, MOV, WEBM, AVI, MKV           | 3 GB     |
| Web       | YouTube links                      | —        |

## Processing pipeline

After upload, each file goes through several stages:

1. **Uploaded** — file received
2. **Processing** — text extraction, transcription, or OCR in progress
3. **Ready** — file is searchable and available for chat

{% hint style="warning" %}
**Processing time** depends on the file type. Documents take seconds; long videos may take several minutes for transcription.
{% endhint %}

## Storage limits

Storage depends on your plan:

| Plan    | Storage |
| ------- | ------- |
| Free    | 50 MB   |
| Starter | 2 GB    |
| Pro     | 25 GB   |
| Team    | 100 GB  |

Check your usage in **Account > Plans & Billing**.


# Library

Browse, filter, and manage your uploaded files

The Library is where all your uploaded files live. Go to the **Library** tab to see everything you've added.

## Views

Switch between **Grid view** (cards) and **List view** (table) using the toggle in the top right.

## Filtering

Use the filter chips to narrow by file type:

* All, PDFs, Videos, YouTube, Audio, Documents, Channels, Websites, Presentations

## File actions

Click the **three-dot menu** on any file to:

* **Open** — view the file and chat with it
* **Rename** — change the display name
* **Share** — generate a share link
* **Download** — download the original file
* **Delete** — permanently remove the file

## Opening a file

Click any file to open it. You'll see:

* The file content (document viewer, video player, or transcript)
* A chat panel on the right where you can ask questions about this specific file


# Channels

Organize your files into channels (folders)

Channels let you group related files together — by project, topic, client, or any way that works for you.

## Creating a channel

1. Go to the **Library** tab
2. Click **Create new channel**
3. Give it a name
4. Add files to the channel

## Using channels

* Click a channel in the Library to see its files
* Chat with a channel to search only the files inside it
* Share an entire channel with a single link

## Managing channels

* **Add files** — open the channel and add more files
* **Remove files** — remove individual files from the channel (the file stays in your library)
* **Delete channel** — removes the grouping but does not delete the files

{% hint style="info" %}
**Tip:** Channels are great for organizing knowledge by project or department. Create one channel per project, then share it with your team.
{% endhint %}


# Website Import

Import web pages into your knowledge base

Import web pages to make their content searchable alongside your documents.

## Importing a single page

1. Go to **Library** and click **Import Website**
2. Paste the URL of the page you want to import
3. Knowbase extracts the text content and adds it to your library

## Discovering and importing multiple pages

1. Enter a website URL and click **Discover**
2. Knowbase crawls the site structure and shows available pages
3. Select the pages you want to import
4. Click **Import selected**

## Credits

Website imports use page credits based on your plan:

| Plan    | Pages/month |
| ------- | ----------- |
| Free    | 0           |
| Starter | 50          |
| Pro     | 250         |
| Team    | 1,000       |

## Refreshing content

You can re-crawl imported websites to update the content if the source pages have changed.


# Overview

Ask questions and get AI-powered answers from your documents

Chat is the core of Knowbase. Ask questions in natural language and get answers grounded in your documents, with source citations you can verify.

* [Chat with a File](/chat/chat-with-a-file) — ask questions about a single document
* [Chat All](/chat/chat-all) — search across your entire library at once
* [Thinking Mode](/chat/thinking-mode) — deep analysis for complex questions
* [Attachments & Context](/chat/attachments-and-context) — drop files into chat, control what gets searched
* [Voice Input](/chat/voice-input) — dictate questions with your microphone


# Chat with a File

Open a file and ask questions about it

## How it works

1. Go to the **Library** and click on any file
2. The file opens with a chat panel on the right
3. Type your question and press Enter
4. Knowbase searches the file and returns an answer with **source citations**

## Source citations

Every answer includes numbered citations like **\[1]**, **\[2]**. Click a citation to jump to the exact section of the document where the answer was found.

* **PDFs** — jumps to the page and highlights the text
* **Videos/Audio** — seeks to the timestamp
* **YouTube** — jumps to the moment in the video

## Follow-up questions

The conversation remembers context. You can ask follow-ups without repeating yourself:

> **You:** What are the key findings? **Knowbase:** The study found three main results... \[1]\[2] **You:** Tell me more about the second one.

## Tips

* Be specific — "What was the Q3 revenue?" works better than "Tell me about the finances"
* Use Thinking Mode for questions that require reasoning across multiple sections


# Chat All — Library Search

Search across your entire library at once

## What is Chat All?

The **Chat** tab searches across **all your uploaded files** at once. Instead of opening one file at a time, you can ask a question and Knowbase finds the answer from whichever files are most relevant.

## How to use it

1. Click the **Chat** tab in the top navigation
2. Type your question
3. Knowbase searches your entire library and returns an answer with citations from multiple files

## Narrowing the search

You can control what gets searched:

* **Drop files** into the chat input to search only those specific files
* **Toggle Library** on/off using the library icon in the input bar
* The **context label** above the input shows what's currently being searched

{% hint style="info" %}
**Example:** Drop two quarterly reports into the chat, then ask "Compare Q1 and Q2 performance." Knowbase will only search those two files.
{% endhint %}

## Chat All vs File Chat

| Feature          | Chat All               | File Chat              |
| ---------------- | ---------------------- | ---------------------- |
| Searches         | Entire library         | Single file            |
| Opens from       | Chat tab               | Library > click file   |
| Best for         | Cross-document queries | Deep-dive into one doc |
| File attachments | Yes                    | No                     |


# Thinking Mode

An AI research agent that works through your library step by step

## What is Thinking Mode?

Thinking Mode turns chat into a **research agent**. Instead of answering from a single search, it works through your library the way a careful researcher would — and you watch it happen live:

1. It analyzes your question and plans an approach
2. It searches your documents — and refines its queries based on what comes back
3. When semantic search isn't enough, it looks for **exact matches** (names, numbers, quotes) or **reads entire documents**
4. It can browse your library by filename to locate a document you described
5. When it has solid evidence, it writes the answer with precise citations

The number of steps adapts to the question: a simple lookup finishes in seconds, while a hard cross-document question gets several rounds of research.

## Watch it think

While it works, a live panel shows every step — its reasoning, the exact searches it runs, and what it found:

* *Analyzing your question…*
* *Searching: "brand growth penetration"*
* *Exact match: "09.09.2025"*
* *Reading a full document…*
* *Reviewing 31 passages…*
* *Writing your answer…*

When the answer starts, the panel collapses to a single line — **"Thought for 45s"** — and you can click it anytime to review the full reasoning trail.

## Works across languages

Thinking Mode searches in the language of your **documents**, not just the language of your question. Ask in German about a Ukrainian document (or in English about a Polish one) and it will reformulate its searches in the right language to find the answer.

## Precise citations

Answers cite sources inline with `[N]` markers. Clicking a citation navigates to the exact place the evidence came from — the PDF page, or the exact timestamp in an audio/video recording, which starts playing from that moment.

## Reply to a fragment

Select any part of an answer and click **Reply** — the fragment attaches to your next message as a quote, so the assistant knows exactly which part you're asking about.

## When to use it

* Questions spanning multiple documents or languages
* "Summarize document X" — it reads the whole document, not just fragments
* Finding exact facts: dates, names, figures, specific quotes
* Analysis and comparison tasks where a quick search would miss context

## How to enable it

Thinking Mode is the **default** for library chat (Chat All). Use the **mode selector** in the chat input to switch to Fast Mode when you just need a quick lookup.

## Fast Mode vs Thinking Mode

| Feature      | Fast Mode         | Thinking Mode                                               |
| ------------ | ----------------- | ----------------------------------------------------------- |
| Speed        | Instant           | Seconds to a few minutes — adapts to the question           |
| Search depth | Single pass       | Iterative: search, refine, exact-match, read full documents |
| Languages    | Question language | Searches in your documents' languages                       |
| Reasoning    | Hidden            | Live step-by-step panel, reviewable afterwards              |
| Best for     | Quick lookups     | Deep research, summaries, hard questions                    |

{% hint style="info" %}
**Plan requirement:** Thinking Mode is available on Pro and Team plans. Because it runs multiple rounds of research per question, each Thinking Mode question counts as **5 queries** toward your monthly quota.
{% endhint %}

{% hint style="info" %}
Thinking Mode answers only from your library. If your documents don't cover a topic, it says so and points to the closest related material — it won't improvise an answer from general knowledge.
{% endhint %}


# Attachments & Context

Control what gets searched by attaching files and managing context

## Dropping files into chat

In **Chat All** mode, you can drop files directly into the chat input. This narrows the search to only those files — useful when you want answers from specific documents without searching your entire library.

Files appear as chips above the input. Remove a chip to stop searching that file.

## Context label

The label above the chat input always tells you what's being searched:

* **"Chatting with all"** — searching your entire library
* **"2 dropped files only"** — searching only the files you dropped
* **"2 files + Library"** — dropped files plus your library

## YouTube in chat

Paste a YouTube URL directly into the chat. Knowbase extracts the transcript on the fly so you can ask questions about the video without uploading it to your library first.

## Library toggle

Use the **library icon** in the input bar to include or exclude your uploaded library from the search. This is useful when you only want to search dropped files or connected tools.


# Voice Input

Ask questions using your voice

## How to use it

1. Click the **microphone button** in the chat input
2. Speak your question
3. Knowbase transcribes your voice and sends it as a message

{% hint style="info" %}
Voice input uses your browser's built-in speech recognition. Make sure your browser has microphone permissions enabled.
{% endhint %}

## Supported browsers

Voice input works best in Chrome and Edge. Safari and Firefox have limited support for the Web Speech API.


# Overview

Connect external tools to search alongside your uploaded files

Connectors let you search your external tools — Google Drive, Notion, Dropbox, and custom websites — directly from the Knowbase chat. No need to import everything manually.

* [Google Drive](/connectors/google-drive)
* [Notion](/connectors/notion)
* [Dropbox](/connectors/dropbox)
* [Web Search](/connectors/web-search)

## How connectors work

When you enable a connector in chat, Knowbase searches that service alongside your uploaded files. Results from connectors are extracted on the fly and included in the AI's answer with source citations.

## Setting up connectors

All connectors are managed in **Account > Connectors**.

{% hint style="info" %}
**Plan requirement:** Connectors are available on Starter (1 connector), Pro (unlimited), and Team (unlimited) plans.
{% endhint %}


# Google Drive

Search and import files from Google Drive

## Connecting

1. Go to **Account > Connectors**
2. Click **Connect** next to Google Drive
3. Sign in with your Google account and grant access

## Using in chat

Once connected, toggle the **Google Drive** icon in the chat input bar. When enabled, Knowbase searches your Drive files alongside your library.

## Importing files to library

You can also import files from Google Drive directly into your Knowbase library using the file picker in the Upload page.


# Notion

Search your Notion workspace from Knowbase chat

## Connecting

1. Go to **Account > Connectors**
2. Click **Connect** next to Notion
3. Authorize Knowbase to access your workspace

## Using in chat

Toggle the **Notion** icon in the chat input bar. Knowbase searches your Notion pages and includes relevant content in answers.


# Dropbox

Search your Dropbox files from Knowbase chat

## Connecting

1. Go to **Account > Connectors**
2. Click **Connect** next to Dropbox
3. Sign in and authorize access

## Using in chat

Toggle the **Dropbox** icon in the chat input bar. Knowbase searches your Dropbox files alongside your library.


# Web Search

Search custom website domains from Knowbase chat

Web Search lets you search specific website domains directly from chat — useful for documentation sites, knowledge bases, or internal wikis.

## Setting up

1. Go to **Account > Connectors**
2. Under **Web Search**, click **Add domain**
3. Enter the domain (e.g., `docs.example.com`)

## Using in chat

Toggle the **Web** icon in the chat input bar. Knowbase searches your configured domains and includes relevant web content in answers.

{% hint style="info" %}
**Plan requirement:** Web Search is available on Pro and Team plans.
{% endhint %}


# Overview

Use Knowbase from Claude, ChatGPT, Perplexity and other AI assistants via MCP

Knowbase exposes your document library to external AI assistants through the **Model Context Protocol (MCP)** — an open standard for connecting AI tools to data sources. Once connected, assistants like Claude, ChatGPT, and Perplexity can search and read your library to answer questions, with citations back to your source documents, without you leaving that assistant.

{% hint style="info" %}
**Plan requirement:** MCP access is included with the **Pro** and **Team** plans.
{% endhint %}

## The server URL

Add this remote MCP server URL in your assistant's connector settings:

```
https://mcp.knowbase.ai/mcp
```

You can copy it any time from **Account > MCP** in Knowbase.

The first time you connect, a window opens where you sign in with your Knowbase account and approve access on a consent screen. Your assistant only ever sees the documents in your own library — never your password.

## What the assistant can do

Connecting adds these tools to your assistant:

| Tool                   | What it does                                                                                                        |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `search_library`       | Semantic search — returns the most relevant passages with citations. Can be scoped to specific documents            |
| `grep_library`         | Exact text search (literal or regex) for precise strings — names, IDs, quotes, code — that semantic search may miss |
| `get_document_content` | Returns the full text of a document                                                                                 |
| `ask_knowbase`         | Asks a question and returns a Knowbase-generated answer with sources                                                |
| `list_documents`       | Lists the documents in your library                                                                                 |
| `list_collections`     | Lists your collections and their files                                                                              |

The assistant decides when to call these based on your questions. Try prompts like *"Search my Knowbase library for our refund policy"*.

## Setup guides

* [Claude](/use-knowbase-in-ai-assistants-mcp/claude)
* [ChatGPT](/use-knowbase-in-ai-assistants-mcp/chatgpt)
* [Perplexity](/use-knowbase-in-ai-assistants-mcp/perplexity)

Any assistant that supports remote MCP connectors can use Knowbase — these guides cover the most common ones.


# Claude

Connect Knowbase to Claude (Claude Desktop and claude.ai)

Knowbase works as a custom remote connector in Claude — on **claude.ai** and **Claude Desktop**.

{% hint style="info" %}
Custom connectors are available on Claude's Free, Pro, Max, Team, and Enterprise plans (Free users can add one connector). The feature is currently in beta.
{% endhint %}

## Pro and Max plans

1. In Claude, go to **Customize > Connectors**.
2. Click **"+"**, then **Add custom connector**.
3. Enter the Knowbase MCP server URL:

   ```
   https://mcp.knowbase.ai/mcp
   ```
4. Click **Add**.
5. Click **Connect** on the Knowbase connector. A window opens — sign in with your Knowbase account and click **Allow** on the consent screen.

## Team and Enterprise plans

An organization **Owner** adds the connector first:

1. Go to **Organization settings > Connectors**.
2. Click **Add**, hover over **Custom**, then select **Web**.
3. Enter the server URL `https://mcp.knowbase.ai/mcp` and click **Add**.

**Members** then connect:

1. Go to **Customize > Connectors**.
2. Find the **Knowbase** connector (marked "Custom") and click **Connect** to sign in.

## Using it in a chat

Enable the connector per conversation: click the **"+"** in the lower-left of the chat box, choose **Connectors**, and toggle **Knowbase** on. Then ask something like *"Search my Knowbase library for …"*.


# ChatGPT

Connect Knowbase to ChatGPT using Developer Mode

ChatGPT supports custom remote MCP connectors through **Developer Mode**.

{% hint style="info" %}
Developer Mode is available on ChatGPT's Pro, Plus, Business, Enterprise, and Education plans (web only).
{% endhint %}

## Enable Developer Mode

1. Go to **Settings → Apps** (Connectors).
2. Open **Advanced settings → Developer mode** and toggle it on.

## Add Knowbase

1. In **Apps** settings, click **Create app** (next to Advanced settings — only visible once Developer Mode is on).
2. Enter the Knowbase MCP server URL:

   ```
   https://mcp.knowbase.ai/mcp
   ```
3. Choose **OAuth** authentication, then sign in with your Knowbase account and approve access.
4. Knowbase now appears as a Developer Mode tool in conversations.

## Using it in a chat

Open the **"+" menu → Developer Mode**, select **Knowbase**, then prompt explicitly, for example: *"Use the Knowbase app's search\_library to find …"*.

{% hint style="warning" %}
Developer Mode is powerful — ChatGPT asks you to confirm before any write action. Knowbase's tools are read-only (search and list), so they only ever read from your library.
{% endhint %}


# Perplexity

Connect Knowbase to Perplexity as a custom remote connector

Perplexity supports custom remote MCP connectors that pull live data into your conversations and Computer workflows.

{% hint style="info" %}
Custom connectors are available to Perplexity's **Pro**, **Max**, and **Enterprise** subscribers.
{% endhint %}

## Add Knowbase

1. Go to **Settings → Connectors**.
2. Click **Add custom MCP connector** (or **Add connector → Custom**).
3. Enter the Knowbase MCP server URL:

   ```
   https://mcp.knowbase.ai/mcp
   ```
4. Choose **OAuth** authentication, then sign in with your Knowbase account and approve access.

Once connected, Knowbase is available in your conversations and Computer workflows — ask something like *"Search my Knowbase library for …"*.

{% hint style="info" %}
Enterprise administrators can share the connector across the whole organization and control whether members may add their own.
{% endhint %}


# Overview

Build AI-powered chatbots for your website or intranet

AI Assistants let you turn your knowledge base into a chatbot that anyone can use — on your website, intranet, or via a direct link. No coding required beyond pasting one line of embed code.

## What can assistants do?

* Answer customer questions using your documents
* Collect leads when they can't find an answer
* Reduce support tickets by providing instant self-service
* Track conversations and visitor feedback

## Getting started

1. [Create an assistant](/ai-assistants/creating-an-assistant)
2. [Choose knowledge sources](/ai-assistants/knowledge-sources)
3. [Configure behavior](/ai-assistants/behavior)
4. [Customize appearance](/ai-assistants/appearance)
5. [Deploy](/ai-assistants/deploying)

## Use cases

* **Customer support** — answer FAQs from your documentation
* **Internal knowledge** — help employees find information across company docs
* **Product guides** — let users ask questions about your product
* **Education** — create study assistants from course materials

{% hint style="info" %}
**Plan requirement:** AI Assistants are available on Pro (1 assistant) and Team (5 assistants) plans.
{% endhint %}


# Creating an Assistant

Create your first AI assistant

## Steps

1. Go to the **Assistants** tab in the top navigation
2. Click **Create your first assistant** (or the **+** button in the dropdown if you already have one)
3. Enter a name and pick a color
4. Click **Create**

You'll enter the **setup wizard** which walks you through:

* Sources — what the assistant can search
* Q\&A Pairs — pre-defined answers for specific questions
* Behavior — personality, language, and guardrails
* Appearance — widget colors, greeting, and style
* Deploy — get your embed code

{% hint style="info" %}
**Tip:** You can skip steps and come back to configure them later. Only the name is required to create an assistant.
{% endhint %}


# Knowledge Sources

Choose which documents your assistant can search

## Source modes

Your assistant can search either:

* **Entire library** — searches all your uploaded files. New uploads are automatically included.
* **Specific files** — only searches the files you select.

## Selecting specific files

When you choose "Specific files":

1. Browse your library with search and filters
2. Check the files you want to include
3. Save your selection

{% hint style="info" %}
**Tip:** Use "Entire library" if you want the assistant to always have access to your latest uploads. Use "Specific files" if the assistant should only know about certain documents.
{% endhint %}


# Behavior & Personality

Configure your assistant's personality, language, and boundaries

## System prompt

The system prompt tells your assistant how to behave. Use it to set tone, role, and rules.

**Quick tone presets:** Click "Professional", "Friendly", or "Formal" to add a starting template.

## Response language

Choose whether the assistant:

* **Auto-detects** the visitor's language and responds in the same language
* **Always responds** in a specific language (English, Polish, German, French, Spanish, etc.)

## Topic guardrails

Restrict the assistant to specific topics. Enter a comma-separated list (e.g., "product support, billing, shipping"). Questions outside these topics will be politely declined.

## Follow-up suggestions

When enabled, the assistant suggests follow-up questions after each answer. Helps visitors explore the topic further.

## Fallback email collection

When the assistant can't answer a question, it can ask the visitor for their email. These leads appear in the [Leads](/ai-assistants/leads) tab.

## Document viewing

Toggle whether visitors can click source citations to view the actual document content. Disable this if your documents are confidential.


# Appearance & Widget

Customize how your assistant widget looks

## Widget mode

Choose how the assistant appears on your website:

* **Bubble** — a floating chat button in the corner that expands into a popup
* **Panel** — a slide-in side panel triggered by a bottom bar

## Customization options

| Setting               | Description                                          |
| --------------------- | ---------------------------------------------------- |
| **Color**             | Primary color for the widget header and buttons      |
| **Title**             | Name shown in the chat header                        |
| **Greeting**          | Welcome message displayed when chat opens            |
| **Starter questions** | Suggested questions shown as chips (comma-separated) |

The live preview on the right updates in real time as you make changes.

{% hint style="info" %}
**Changes apply instantly** — once saved, your deployed widget picks up the new appearance without updating the embed code.
{% endhint %}


# Deploying

Get your assistant's embed code and deploy it

## Embed on your website

Copy the embed snippet and paste it into your website's HTML, just before the closing `</body>` tag:

```html
<script src="https://app.knowbase.ai/assets/widget.js"></script>
<script>
  KnowbaseChat.init({ token: 'YOUR_TOKEN' });
</script>
```

That's it — the widget will appear on your website.

### Chat button style

In the **Chat widget** section of the Deploy page you can choose how the button in the corner of your website looks:

* **Pill with text** — icon plus a label (default). Set the label in **Button text**, e.g. "Ask MAO".
* **Icon only** — a round button with just the chat icon.

Both apply instantly to every page where the widget is embedded. The style applies to the *Bubble* mode; the *Side panel* mode keeps its slim bar at the bottom of the page.

### Using your own chat button

If your site already has a "Chat with us" button, you can hide the Knowbase launcher and open the chat from your own element instead:

```html
<script src="https://app.knowbase.ai/assets/widget.js"></script>
<script>
  KnowbaseChat.init({ token: 'YOUR_TOKEN', launcher: false });
</script>

<button onclick="KnowbaseChat.open()">Ask a question</button>
```

Available calls: `KnowbaseChat.open()`, `KnowbaseChat.close()`, `KnowbaseChat.toggle()`.

## Preview

Click **Open demo page** to see your assistant in action before deploying. This opens a test page with the widget loaded.

{% hint style="warning" %}
If your assistant is **hidden** (toggled off on the Overview page), it won't appear in the preview or on your website. Make sure it's set to "Visible on website".
{% endhint %}

## Publishing

If you used the setup wizard, click **Publish** on the last step to set your assistant to "Live" status.

## Updating

All configuration changes (behavior, appearance, sources) **apply instantly** to deployed widgets. No need to update the embed code.


# Conversations

Monitor visitor conversations with your assistant

The Conversations tab shows every chat session visitors have had with your assistant.

## Filtering

Filter conversations by:

* **All** — every conversation
* **Positive** — conversations with thumbs up feedback
* **Negative** — conversations with thumbs down feedback
* **Unanswered** — conversations where the assistant couldn't find an answer

## Viewing a conversation

Click any conversation to see the full message thread on the right. Each message shows:

* Whether it's from the visitor or the bot
* Thumbs up/down feedback (if given)
* "Could not answer" badge on messages where the assistant had no relevant context

## What to do with this data

* Spot questions your documents don't cover → upload more content or add [Q\&A Pairs](/ai-assistants/creating-an-assistant)
* Find negative feedback → improve your system prompt or add guardrails
* Track unanswered questions → add them as Q\&A Pairs for exact answers


# Leads

Collect and manage visitor emails from your assistant

When [fallback email collection](/ai-assistants/behavior) is enabled and your assistant can't answer a question, it asks the visitor for their email. These submissions appear in the **Leads** tab.

## Managing leads

Each lead shows:

* The visitor's email
* The question they asked
* Status: **New**, **Contacted**, or **Resolved**

Click a lead to see details and take action:

* **Reply by email** — opens your email client with the visitor's address
* **View conversation** — see the full chat context
* **Add as Q\&A Pair** — create an exact answer so the assistant can handle this question next time

## Filtering

Filter leads by status:

* **All** — every lead
* **New** — unread leads (with red badge count)
* **Contacted** — leads you've responded to
* **Resolved** — leads that have been handled


# Overview

Share your documents with anyone via link

Share individual files or channels so others can chat with your documents — no Knowbase account required.


# Sharing Files & Channels

Generate share links for files and channels

## How to share

1. Go to the **Library**
2. Click the **three-dot menu** on a file or channel
3. Click **Share**
4. Copy the **share link** or the **iframe embed code**

## What visitors see

Anyone with the link can open a chat interface and ask questions about the shared file or channel. They don't need a Knowbase account.

## Iframe embed

Use the iframe snippet to embed a chat interface directly on your website:

```html
<iframe width="400" height="600" 
  src="https://app.knowbase.ai/iframe-chat/YOUR_TOKEN" 
  title="chat" frameborder="0">
</iframe>
```

## Managing shared links

Go to **Account > Shared Chats** to see all your active share links. You can delete any link to revoke access.

{% hint style="info" %}
**Tip:** For a more customizable experience with branding, lead collection, and analytics, consider using [AI Assistants](/ai-assistants/ai-assistants) instead of simple share links.
{% endhint %}


# Overview

Manage your account, plan, and settings

* [Plans & Billing](/account-and-billing/plans-and-billing) — compare plans, upgrade, track usage
* [Settings](/account-and-billing/settings) — profile, connectors, shared chats


# Plans & Billing

Compare plans, upgrade, and track your usage

## Plans

| Feature            | Free  | Starter ($19/mo)  | Pro ($49/mo) | Team ($99/mo) |
| ------------------ | ----- | ----------------- | ------------ | ------------- |
| Storage            | 50 MB | 2 GB              | 25 GB        | 100 GB        |
| Queries/month      | 10    | 500               | 2,000        | 5,000         |
| Uploads            | 3     | 100               | 500          | Unlimited     |
| AI Assistants      | —     | —                 | 1            | 5             |
| Thinking Mode      | —     | —                 | Yes          | Yes           |
| Connectors         | —     | 1                 | Unlimited    | Unlimited     |
| Web Search         | —     | —                 | Yes          | Yes           |
| API Access         | —     | —                 | Yes          | Yes           |
| OCR (doc scanning) | —     | Basic (100 pages) | Fast (500)   | Fast (2,000)  |
| Website pages      | —     | 50                | 250          | 1,000         |

Yearly billing saves \~20%. Every new account gets a **3-day Pro trial**.

## Upgrading

1. Go to **Account > Plans & Billing** or visit the **Pricing** page
2. Choose a plan and billing interval
3. Complete checkout via Stripe

## Usage tracking

Your current usage is shown in **Account > Plans & Billing**:

* Storage used
* Queries this month
* OCR pages used
* Website pages used

{% hint style="warning" %}
You'll see warning banners at 70%, 90%, and 100% of your limits.
{% endhint %}


# Settings

Profile, connectors, shared chats, and other settings

Access settings from the **user icon** in the top right corner of the app.

## Profile

View your email address and current plan.

## Connectors

Connect and manage external services:

* Google Drive
* Notion
* Dropbox
* Web Search domains

See [Connectors](/connectors/connectors) for setup guides.

## Shared Chats

View all active share links. See message count and last activity for each. Delete links to revoke access.

## API Access

Generate and manage your API key. See [API Reference](/api-reference/api) for documentation.


# Introduction

Knowbase.ai API lets you upload documents, query them with AI, manage collections, and integrate document intelligence into your own applications.

Here you'll find all the documentation you need to get up and running with the Knowbase.ai API.

### Base URL

```
https://api.knowbase.ai/api/v1
```

### Authentication

All API requests require a Bearer token in the `Authorization` header:

```
Authorization: Bearer YOUR_API_TOKEN
```

You can generate your API token from Account Settings in the Knowbase.ai web app, or via the `GET /api/v1/token` endpoint. API access requires a **Pro** or **Team** plan.

### Features

* **File Management** -- Upload, list, get details, delete, and retrieve summaries for documents
* **Collections** -- Group files into named collections for organized querying
* **Chat (Q\&A)** -- Ask questions against your documents with AI-powered answers and source citations
* **Streaming** -- Real-time Server-Sent Events (SSE) streaming for chat responses
* **Thinking Mode** -- Advanced multi-step reasoning for complex questions (Pro and Team)
* **Conversations** -- Persistent chat history with follow-up question support
* **Account Info** -- Check your plan, quotas, and usage

### Supported File Types

* **Documents**: PDF, DOCX, DOC, TXT, MD, PPTX, PPT
* **Audio**: MP3, WAV, M4A, AAC, OGG, FLAC
* **Video**: MP4, MOV, WEBM, AVI, MKV

### Limits

|                 | Pro            | Team           |
| --------------- | -------------- | -------------- |
| **Upload size** | 100 MB         | 100 MB         |
| **Rate limit**  | 20/min, 200/hr | 60/min, 600/hr |
| **Queries**     | 2,000/month    | 5,000/month    |
| **Storage**     | 25 GB          | 100 GB         |
| **Uploads**     | 500            | Unlimited      |

### Error Format

All errors return a consistent JSON format:

```json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable description"
  }
}
```

Common error codes: `INVALID_TOKEN`, `EXPIRED_TOKEN`, `FORBIDDEN`, `NOT_FOUND`, `RATE_LIMIT`, `QUOTA_EXCEEDED`, `INVALID_REQUEST`, `FILE_TOO_LARGE`, `UNSUPPORTED_FILE_TYPE`, `INTERNAL_ERROR`.

### Interactive Docs

Explore and test all endpoints in the interactive Swagger UI:

```
https://api.knowbase.ai/docs
```


# Quick Start

## 1. Get your API token

Your API requests are authenticated using a Bearer token. To obtain your token:

1. Log into [app.knowbase.ai](https://app.knowbase.ai)
2. Go to **Account** > **Manage Account** > **Generate API Key**
3. Copy your API token

You need a **Pro** or **Team** plan to access the API.

### Rate Limits

| Plan | Per Minute | Per Hour | Per Day |
| ---- | ---------- | -------- | ------- |
| Pro  | 20         | 200      | 2,000   |
| Team | 60         | 600      | 5,000   |

## 2. Upload a file

```python
import requests

url = "https://api.knowbase.ai/api/v1/files"
headers = {"Authorization": "Bearer YOUR_API_TOKEN"}
files = {"file": ("report.pdf", open("report.pdf", "rb"), "application/pdf")}

response = requests.post(url, headers=headers, files=files)
data = response.json()
print(data)
# {"message": "File uploaded successfully", "file_id": "abc-123-...", "status": "processing"}
```

## 3. Check file status

Files need processing time (embedding). Poll until status is `success`:

```python
file_id = data["file_id"]
response = requests.get(f"https://api.knowbase.ai/api/v1/files/{file_id}", headers=headers)
print(response.json()["status"])  # "success" when ready
```

## 4. Chat with your documents

```python
import json

response = requests.post(
    "https://api.knowbase.ai/api/v1/chat",
    headers={**headers, "Content-Type": "application/json"},
    json={
        "question": "What are the key findings in this report?",
        "file_ids": [file_id]
    }
)
result = response.json()
print(result["answer"])
print(result["sources"])       # Source citations
print(result["conversation_id"])  # Use for follow-up questions
```

## 5. Follow-up questions

Use the `conversation_id` to ask follow-up questions with context:

```python
response = requests.post(
    "https://api.knowbase.ai/api/v1/chat",
    headers={**headers, "Content-Type": "application/json"},
    json={
        "question": "Can you elaborate on the second point?",
        "file_ids": [file_id],
        "conversation_id": result["conversation_id"]
    }
)
```

## 6. Query your entire library

Omit `file_ids` to search across all your uploaded documents:

```python
response = requests.post(
    "https://api.knowbase.ai/api/v1/chat",
    headers={**headers, "Content-Type": "application/json"},
    json={"question": "What do my documents say about revenue growth?"}
)
```

## 7. Serving multiple users under one account

If you're integrating Knowbase into a product where each of your users has their own chat history, pass a stable `session_id` per user. Same `session_id` continues the same thread; different `session_id`s are fully isolated.

```python
# User A's question
requests.post(f"{BASE}/chat", headers=headers, json={
    "question": "What were the key findings in Q4?",
    "session_id": "usr_42",
})

# User A's follow-up — same session, same thread
requests.post(f"{BASE}/chat", headers=headers, json={
    "question": "Can you elaborate on the second point?",
    "session_id": "usr_42",
})

# User B — fresh, isolated history
requests.post(f"{BASE}/chat", headers=headers, json={
    "question": "Summarize the meeting notes",
    "session_id": "usr_99",
})
```

See [Per-user sessions](/api-reference/chat#per-user-sessions) for the full reference.

## Full workflow example

```python
import requests
import time

TOKEN = "YOUR_API_TOKEN"
BASE = "https://api.knowbase.ai/api/v1"
headers = {"Authorization": f"Bearer {TOKEN}"}

# 1. Upload
files = {"file": ("report.pdf", open("report.pdf", "rb"), "application/pdf")}
upload = requests.post(f"{BASE}/files", headers=headers, files=files).json()
file_id = upload["file_id"]
print(f"Uploaded: {file_id}")

# 2. Wait for processing
while True:
    status = requests.get(f"{BASE}/files/{file_id}", headers=headers).json()["status"]
    if status == "success":
        break
    print(f"Processing... ({status})")
    time.sleep(5)

# 3. Chat
answer = requests.post(f"{BASE}/chat", headers=headers,
    json={"question": "Summarize this document", "file_ids": [file_id]}).json()
print(answer["answer"])

# 4. Clean up
requests.delete(f"{BASE}/files/{file_id}", headers=headers)
print("File deleted")
```


# Upload File

Upload a document to Knowbase for processing and AI-powered querying.

## Upload a document for processing

`POST` `https://api.knowbase.ai/api/v1/files`

Upload a file to your Knowbase library. The file will be automatically processed (embedded) for AI-powered search and chat. Supported types: PDF, DOCX, DOC, TXT, MD, PPTX, PPT, and audio/video files. Maximum size: 100 MB.

#### Headers

| Name            | Type   | Description             |
| --------------- | ------ | ----------------------- |
| Authorization\* | string | `Bearer YOUR_API_TOKEN` |

#### Request Body

| Name   | Type                | Description        |
| ------ | ------------------- | ------------------ |
| file\* | multipart/form-data | The file to upload |

#### Responses

**200: OK** File uploaded successfully

```json
{
  "message": "File uploaded successfully",
  "file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "processing"
}
```

**400: Bad Request** Quota exceeded or unsupported file

```json
{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Upload limit reached (500). Upgrade your plan for more uploads."
  }
}
```

**401: Unauthorized** Invalid or missing token

```json
{
  "error": {
    "code": "INVALID_TOKEN",
    "message": "Invalid API token"
  }
}
```

**429: Too Many Requests** Rate limit exceeded

```json
{
  "error": {
    "code": "RATE_LIMIT",
    "message": "Rate limit exceeded (per minute)"
  }
}
```

### Example

```python
import requests

url = "https://api.knowbase.ai/api/v1/files"
headers = {"Authorization": "Bearer YOUR_API_TOKEN"}
files = {"file": ("document.pdf", open("document.pdf", "rb"), "application/pdf")}

response = requests.post(url, headers=headers, files=files)
print(response.json())
```

```javascript
const form = new FormData();
form.append("file", fs.createReadStream("document.pdf"));

const response = await fetch("https://api.knowbase.ai/api/v1/files", {
  method: "POST",
  headers: { "Authorization": "Bearer YOUR_API_TOKEN" },
  body: form
});
const data = await response.json();
console.log(data.file_id);
```

```bash
curl -X POST https://api.knowbase.ai/api/v1/files \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "file=@document.pdf"
```


# List Files

Retrieve all files in your library with their status and metadata.

## Get all files in your library

`GET` `https://api.knowbase.ai/api/v1/files`

Returns a list of all files in your library with their processing status, size, type, and other metadata.

#### Headers

| Name            | Type   | Description             |
| --------------- | ------ | ----------------------- |
| Authorization\* | string | `Bearer YOUR_API_TOKEN` |

#### Responses

**200: OK** Successfully retrieved files

```json
{
  "files": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "filename": "report.pdf",
      "type": "pdf",
      "status": "success",
      "file_size": 1048576,
      "created_at": "2025-03-15",
      "summary": "This report covers Q4 financial results...",
      "errors": null
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "filename": "meeting.mp3",
      "type": "audio",
      "status": "success",
      "file_size": 5242880,
      "created_at": "2025-03-14",
      "summary": null,
      "errors": null
    }
  ]
}
```

**File status values:**

| Status                    | Meaning                                  |
| ------------------------- | ---------------------------------------- |
| `success`                 | Ready for querying                       |
| `embed_file_started`      | Currently being processed                |
| `transcribe_file_started` | Audio/video being transcribed            |
| `failure`                 | Processing failed (check `errors` field) |

### Example

```python
import requests

url = "https://api.knowbase.ai/api/v1/files"
headers = {"Authorization": "Bearer YOUR_API_TOKEN"}

response = requests.get(url, headers=headers)
for file in response.json()["files"]:
    print(f"{file['filename']} - {file['status']}")
```

```bash
curl https://api.knowbase.ai/api/v1/files \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```


# Get File

Get details and processing status for a specific file.

## Get a file by ID

`GET` `https://api.knowbase.ai/api/v1/files/{file_id}`

Returns details and processing status for a specific file.

#### Headers

| Name            | Type   | Description             |
| --------------- | ------ | ----------------------- |
| Authorization\* | string | `Bearer YOUR_API_TOKEN` |

#### Path Parameters

| Name       | Type   | Description          |
| ---------- | ------ | -------------------- |
| file\_id\* | string | The UUID of the file |

#### Responses

**200: OK**

```json
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "filename": "report.pdf",
  "type": "pdf",
  "status": "success",
  "file_size": 1048576,
  "created_at": "2025-03-15",
  "summary": "This report covers Q4 financial results...",
  "errors": null
}
```

**404: Not Found**

```json
{
  "error": {
    "code": "NOT_FOUND",
    "message": "File not found"
  }
}
```

### Example

```python
import requests

file_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
url = f"https://api.knowbase.ai/api/v1/files/{file_id}"
headers = {"Authorization": "Bearer YOUR_API_TOKEN"}

response = requests.get(url, headers=headers)
print(response.json())
```


# Delete File

Permanently delete a file, its embeddings, and chat history.

## Delete a file by ID

`DELETE` `https://api.knowbase.ai/api/v1/files/{file_id}`

Permanently deletes a file from your library, including its vector embeddings and associated chat history. This action cannot be undone.

#### Headers

| Name            | Type   | Description             |
| --------------- | ------ | ----------------------- |
| Authorization\* | string | `Bearer YOUR_API_TOKEN` |

#### Path Parameters

| Name       | Type   | Description                    |
| ---------- | ------ | ------------------------------ |
| file\_id\* | string | The UUID of the file to delete |

#### Responses

**200: OK**

```json
{
  "message": "File deleted successfully"
}
```

**404: Not Found**

```json
{
  "error": {
    "code": "NOT_FOUND",
    "message": "File not found"
  }
}
```

### Example

```python
import requests

file_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
url = f"https://api.knowbase.ai/api/v1/files/{file_id}"
headers = {"Authorization": "Bearer YOUR_API_TOKEN"}

response = requests.delete(url, headers=headers)
print(response.json())
```

```bash
curl -X DELETE https://api.knowbase.ai/api/v1/files/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```


# File Summary

Get the AI-generated summary for a file.

## Get summary by file ID

`GET` `https://api.knowbase.ai/api/v1/files/{file_id}/summary`

Returns the AI-generated summary for a file. If the summary hasn't been generated yet, returns `status: "processing"`.

#### Headers

| Name            | Type   | Description             |
| --------------- | ------ | ----------------------- |
| Authorization\* | string | `Bearer YOUR_API_TOKEN` |

#### Path Parameters

| Name       | Type   | Description          |
| ---------- | ------ | -------------------- |
| file\_id\* | string | The UUID of the file |

#### Responses

**200: OK** Summary available

```json
{
  "file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "summary": "This document presents the Q4 2024 financial results, highlighting a 15% revenue increase...",
  "status": "ready"
}
```

**200: OK** Summary still processing

```json
{
  "file_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "summary": null,
  "status": "processing"
}
```

### Example

```python
import requests

file_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
url = f"https://api.knowbase.ai/api/v1/files/{file_id}/summary"
headers = {"Authorization": "Bearer YOUR_API_TOKEN"}

response = requests.get(url, headers=headers)
data = response.json()
if data["status"] == "ready":
    print(data["summary"])
else:
    print("Summary is still being generated...")
```


# Collections

Create and manage collections (groups of files) for organized querying.

Collections let you group files together for targeted querying. When you chat with a collection, only the files in that collection are searched.

***

## Create a collection

`POST` `https://api.knowbase.ai/api/v1/collections`

#### Headers

| Name            | Type   | Description             |
| --------------- | ------ | ----------------------- |
| Authorization\* | string | `Bearer YOUR_API_TOKEN` |
| Content-Type\*  | string | `application/json`      |

#### Request Body

| Name        | Type   | Description                        |
| ----------- | ------ | ---------------------------------- |
| name\*      | string | Name of the collection             |
| file\_ids\* | array  | List of file ID strings to include |

```json
{
  "name": "Q4 Reports",
  "file_ids": [
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "b2c3d4e5-f6a7-8901-bcde-f12345678901"
  ]
}
```

#### Response (201: Created)

```json
{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "name": "Q4 Reports",
  "created_at": "2025-03-15",
  "files": [
    {"id": "a1b2c3d4-...", "filename": "report.pdf", "type": "pdf", "status": "success"},
    {"id": "b2c3d4e5-...", "filename": "analysis.docx", "type": "word", "status": "success"}
  ]
}
```

***

## List all collections

`GET` `https://api.knowbase.ai/api/v1/collections`

#### Response (200: OK)

```json
{
  "collections": [
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "name": "Q4 Reports",
      "created_at": "2025-03-15",
      "files": [
        {"id": "a1b2c3d4-...", "filename": "report.pdf", "type": "pdf", "status": "success"}
      ]
    }
  ]
}
```

***

## Get collection details

`GET` `https://api.knowbase.ai/api/v1/collections/{collection_id}`

Returns the collection with its files.

***

## Delete a collection

`DELETE` `https://api.knowbase.ai/api/v1/collections/{collection_id}`

Deletes the collection. **The files inside are NOT deleted** -- they remain in your library.

#### Response (200: OK)

```json
{
  "message": "Collection deleted successfully"
}
```

***

### Example: Create and query a collection

```python
import requests

TOKEN = "YOUR_API_TOKEN"
BASE = "https://api.knowbase.ai/api/v1"
headers = {"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}

# Create a collection
collection = requests.post(f"{BASE}/collections", headers=headers, json={
    "name": "Research Papers",
    "file_ids": ["file-id-1", "file-id-2", "file-id-3"]
}).json()

# Chat with the collection
answer = requests.post(f"{BASE}/chat", headers=headers, json={
    "question": "What are the common themes across these papers?",
    "collection_id": collection["id"]
}).json()

print(answer["answer"])
```


# Chat

Ask questions against your documents with AI-powered answers and source citations.

The chat endpoint is the core of the Knowbase API. Ask questions about your documents and get AI-powered answers with source citations.

***

## Send a query (non-streaming)

`POST` `https://api.knowbase.ai/api/v1/chat`

#### Headers

| Name            | Type   | Description             |
| --------------- | ------ | ----------------------- |
| Authorization\* | string | `Bearer YOUR_API_TOKEN` |
| Content-Type\*  | string | `application/json`      |

#### Request Body

| Name             | Type    | Required | Description                                                                                       |
| ---------------- | ------- | -------- | ------------------------------------------------------------------------------------------------- |
| question         | string  | Yes      | Your question                                                                                     |
| file\_ids        | array   | No       | List of file IDs to query. Omit to search entire library                                          |
| collection\_id   | string  | No       | Collection ID to query (alternative to file\_ids)                                                 |
| conversation\_id | string  | No       | Continue a previous conversation for follow-up questions                                          |
| session\_id      | string  | No       | Stable identifier for one of your end users (see [Per-end-user sessions](#per-end-user-sessions)) |
| thinking\_mode   | boolean | No       | Enable advanced multi-step reasoning (Pro/Team only)                                              |

#### Example request

```json
{
  "question": "What were the key revenue drivers in Q4?",
  "file_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
  "conversation_id": null,
  "thinking_mode": false
}
```

#### Response (200: OK)

```json
{
  "answer": "Based on the Q4 report, the key revenue drivers were:\n\n1. **SaaS subscriptions** grew 23% YoY [1]\n2. **Enterprise deals** contributed $4.2M in new ARR [2]\n3. **International expansion** into APAC markets [1]\n\nThe report highlights that recurring revenue now represents 78% of total revenue [2].",
  "sources": [
    {
      "key": "1",
      "filename": "q4-report.pdf",
      "source": "12",
      "content": "SaaS subscription revenue grew 23% year-over-year...",
      "documentType": "pdf"
    },
    {
      "key": "2",
      "filename": "q4-report.pdf",
      "source": "15",
      "content": "Enterprise segment closed $4.2M in new ARR...",
      "documentType": "pdf"
    }
  ],
  "conversation_id": "d4e5f6a7-b8c9-0123-def0-1234567890ab",
  "session_id": null
}
```

The `sources` array contains numbered references matching the `[1]`, `[2]` citations in the answer. The `source` field indicates the page number (for documents) or timestamp (for audio/video).

***

## Send a query (streaming SSE)

`POST` `https://api.knowbase.ai/api/v1/chat/stream`

Same request body as `/chat`, but returns a **Server-Sent Events** stream for real-time token-by-token output.

#### SSE Events

| Event      | Description                   | Data format                                      |
| ---------- | ----------------------------- | ------------------------------------------------ |
| `sources`  | Source citations (sent first) | `{"sources": [...], "documentType": "pdf"}`      |
| `token`    | Incremental text token        | `{"t": "word "}`                                 |
| `thinking` | Thinking mode progress        | `{"step": "searching", ...}`                     |
| `done`     | Full response complete        | `{"full_text": "...", "conversation_id": "..."}` |
| `error`    | Error occurred                | `{"error": {"code": "...", "message": "..."}}`   |

#### Example: Streaming in Python

```python
import requests
import json

url = "https://api.knowbase.ai/api/v1/chat/stream"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
}
data = {
    "question": "Summarize the main findings",
    "file_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
}

response = requests.post(url, headers=headers, json=data, stream=True)

for line in response.iter_lines():
    line = line.decode("utf-8")
    if line.startswith("event: "):
        event_type = line[7:]
    elif line.startswith("data: "):
        payload = json.loads(line[6:])
        if event_type == "token":
            print(payload["t"], end="", flush=True)
        elif event_type == "sources":
            print(f"\nSources: {len(payload['sources'])} found")
        elif event_type == "done":
            print(f"\n\nDone. Conversation: {payload['conversation_id']}")
```

#### Example: Streaming in JavaScript

```javascript
const response = await fetch("https://api.knowbase.ai/api/v1/chat/stream", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_TOKEN",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    question: "What are the key takeaways?",
    file_ids: ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const text = decoder.decode(value);
  for (const line of text.split("\n")) {
    if (line.startsWith("data: ")) {
      const data = JSON.parse(line.slice(6));
      if (data.t) process.stdout.write(data.t);
    }
  }
}
```

***

## Query scoping

You can control which documents are searched:

| Scope              | How                                      |
| ------------------ | ---------------------------------------- |
| **Entire library** | Omit both `file_ids` and `collection_id` |
| **Specific files** | Set `file_ids: ["id1", "id2"]`           |
| **A collection**   | Set `collection_id: "collection-uuid"`   |

***

## Thinking mode

Set `thinking_mode: true` for complex questions that benefit from multi-step reasoning. The AI will iteratively search, assess confidence, and refine its answer. Available on Pro and Team plans.

```json
{
  "question": "Compare the financial performance across all quarterly reports",
  "thinking_mode": true
}
```

In streaming mode, you'll receive additional `thinking` events showing the AI's reasoning progress.

***

## Per-user sessions

If you're integrating Knowbase into a product that serves multiple end users, pass a stable `session_id` for each user. Same `session_id` continues the same conversation; different `session_id`s under the same API account are fully isolated — no cross-user history leakage.

You don't need to track Knowbase's `conversation_id` on your side; just send your own user identifier as `session_id` and we'll resolve it to the right thread.

#### Example: two users under one API account

```json
// First call for user "usr_42"
POST /api/v1/chat
{
  "question": "What were the key revenue drivers in Q4?",
  "session_id": "usr_42"
}
// → returns { "answer": "...", "conversation_id": "uuid-A", "session_id": "usr_42" }

// Follow-up for the same user — same conversation continues
POST /api/v1/chat
{
  "question": "Can you elaborate on the SaaS growth?",
  "session_id": "usr_42"
}
// → returns { "answer": "...", "conversation_id": "uuid-A", "session_id": "usr_42" }

// Different user — fresh, isolated history
POST /api/v1/chat
{
  "question": "Summarize the meeting notes",
  "session_id": "usr_99"
}
// → returns { "answer": "...", "conversation_id": "uuid-B", "session_id": "usr_99" }
```

#### Notes

* `session_id` is an opaque string of your choice (max 255 chars). We recommend using your product's stable user identifier.
* If you send both `conversation_id` and `session_id`, `conversation_id` wins (back-compat).
* To list a single user's conversations, see [Listing conversations by session](/api-reference/conversations#filter-by-session).
* Quotas and rate limits are enforced **per API account**, not per session. For high-volume integrations, contact us about an Enterprise plan.


# Conversations

List, view, and delete chat conversations.

Conversations are automatically created when you use the `/chat` endpoint. Each conversation has a unique ID and maintains chat history for follow-up questions.

***

## List conversations

`GET` `https://api.knowbase.ai/api/v1/conversations`

Returns all conversations with titles and message counts, ordered by most recent.

#### Query parameters

| Name        | Type   | Required | Description                                                                           |
| ----------- | ------ | -------- | ------------------------------------------------------------------------------------- |
| session\_id | string | No       | Filter to one user's conversations only. See [Filter by session](#filter-by-session). |

#### Response (200: OK)

```json
{
  "conversations": [
    {
      "id": "d4e5f6a7-b8c9-0123-def0-1234567890ab",
      "title": "What were the key revenue drivers...",
      "timestamp": "2025-03-15T14:30:00",
      "message_count": 4
    },
    {
      "id": "e5f6a7b8-c9d0-1234-ef01-234567890abc",
      "title": "Summarize the meeting notes",
      "timestamp": "2025-03-14T10:15:00",
      "message_count": 2
    }
  ]
}
```

### Filter by session

If you serve multiple end users under one API account (see [Per-user sessions](/api-reference/chat#per-user-sessions)), pass `?session_id=...` to fetch a single user's conversations only:

```
GET /api/v1/conversations?session_id=usr_42
```

The response only includes conversations whose messages were sent with that `session_id`. Use this to render a single user's chat history in your UI.

***

## Get conversation messages

`GET` `https://api.knowbase.ai/api/v1/conversations/{conversation_id}`

Returns all messages in a conversation in chronological order.

#### Response (200: OK)

```json
{
  "messages": [
    {
      "id": "msg-uuid-1",
      "question": "What were the key revenue drivers in Q4?",
      "answer": "Based on the Q4 report, the key revenue drivers were...",
      "sources": [...],
      "timestamp": "2025-03-15T14:30:00"
    },
    {
      "id": "msg-uuid-2",
      "question": "Can you elaborate on the SaaS growth?",
      "answer": "The SaaS subscription revenue grew 23% YoY...",
      "sources": [...],
      "timestamp": "2025-03-15T14:31:00"
    }
  ]
}
```

***

## Delete a conversation

`DELETE` `https://api.knowbase.ai/api/v1/conversations/{conversation_id}`

Permanently deletes a conversation and all its messages.

#### Response (200: OK)

```json
{
  "deleted": 4
}
```

### Example

```python
import requests

TOKEN = "YOUR_API_TOKEN"
BASE = "https://api.knowbase.ai/api/v1"
headers = {"Authorization": f"Bearer {TOKEN}"}

# List conversations
convos = requests.get(f"{BASE}/conversations", headers=headers).json()
for c in convos["conversations"]:
    print(f"{c['title']} ({c['message_count']} messages)")

# Get messages for a conversation
messages = requests.get(
    f"{BASE}/conversations/{convos['conversations'][0]['id']}", headers=headers
).json()
for msg in messages["messages"]:
    print(f"Q: {msg['question']}")
    print(f"A: {msg['answer'][:100]}...\n")
```


# Account

Check your subscription tier, quotas, and current usage.

## Get account info

`GET` `https://api.knowbase.ai/api/v1/account`

Returns your subscription tier, quota limits, and current usage.

#### Headers

| Name            | Type   | Description             |
| --------------- | ------ | ----------------------- |
| Authorization\* | string | `Bearer YOUR_API_TOKEN` |

#### Response (200: OK)

```json
{
  "email": "user@example.com",
  "tier": "Pro",
  "quotas": {
    "queries_limit": 2000,
    "queries_used": 342,
    "uploads_limit": 500,
    "uploads_used": 47,
    "storage_limit": "25.00 GB",
    "storage_used": "1.23 GB",
    "storage_remaining": "23.77 GB"
  }
}
```

### Example

```python
import requests

url = "https://api.knowbase.ai/api/v1/account"
headers = {"Authorization": "Bearer YOUR_API_TOKEN"}

response = requests.get(url, headers=headers)
account = response.json()

print(f"Plan: {account['tier']}")
print(f"Queries: {account['quotas']['queries_used']}/{account['quotas']['queries_limit']}")
print(f"Storage: {account['quotas']['storage_used']} / {account['quotas']['storage_limit']}")
```