# Chat 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.md#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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.knowbase.ai/api-reference/chat.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.