# AI RAG Knowledge Base Chat API
Build private document knowledge bases and answer with citations.
## API Overview
- **HTTP Protocol:** HTTPS
- **HTTP Method:** POST
- **HTTP Endpoint:** https://api.gugudata.io/ai/knowledge-bases/default/chat/completions
- **Response Type:** application/json; charset=utf-8
- **DEMO Endpoint:** https://api.gugudata.io/ai/knowledge-bases/default/chat/completions/demo
- **Live Demo:** https://gugudata.io/demo/knowledge-chat
- **Postman:** https://www.postman.com/gugudata/gugudata-io
- **LLM Page:** https://gugudata.io/details/knowledge-chat/llm
- **Raw Markdown:** https://gugudata.io/details/knowledge-chat/llm.md
## Remote MCP
- **MCP Endpoint:** https://mcp.gugudata.io/mcp
- **MCP Guide:** https://gugudata.io/mcp/
- **Authorization:** OAuth authorization opens in the browser; do not paste appkeys into MCP clients.
- **Tool Scope:** MCP clients receive GuGuData API tools available to the authorized account.
## Data & API Features
- Private knowledge bases from five document formats: Upload PDF, TXT, Markdown, HTML, and DOCX files for product guides, policies, support content, and internal documentation.
- Evidence-based answers with citations: Generate answers from the uploaded content and return the supporting document passages for review and display.
- Knowledge bases for each business context: Separate content by product, project, customer, or tenant while using one consistent API contract.
- OpenAI-compatible JSON and real-time SSE: Use familiar chat completion responses for regular requests or stream answer text as it is generated.
- Client-controlled multi-turn context: Send the complete conversation history your application wants the answer to consider on every request.
- Replace and delete documents: Refresh a same-name document safely or remove a document when its content is no longer needed.
## API Request Parameters
| Name | Type | Is Required | Default Value | Remark |
| --- | --- | --- | --- | --- |
| knowledge_base_id | string | true | default | Knowledge base identifier in the URL path. |
| appkey | string | true | YOUR_APPKEY | API key used to authenticate the request. |
| model | string | false | gugudata-knowledge-chat | OpenAI Chat Completions compatible model name. |
| messages | array<object> | true | [{"role":"user","content":"What does the documentation say?"}] | Complete client-managed conversation context with 1 to 20 system, user, or assistant messages. |
| thread_id | string | false | | Optional request correlation identifier; it does not restore server-side history. |
| tenant_id | string | false | default | Customer-defined knowledge base grouping; defaults to default. |
| stream | boolean | false | false | Return real-time Server-Sent Events when true. |
| top_k | integer | false | 6 | Number of retrieved source passages from 1 to 12. |
## API Response Parameters
| Name | Type | Remark |
| --- | --- | --- |
| id | string | Chat completion response identifier. |
| message_id | string | Identifier for the generated answer. |
| object | string | OpenAI-compatible response object type. |
| thread_id | string | Request correlation identifier returned to the client. |
| choices[0].message.content | string | Answer generated from uploaded documents. |
| sources | array<object> | Document passages cited by the answer. |
| usage | object | Usage summary for the request. |
## API Response Status Codes
| Status Code | Explanation of Status Code | Remarks |
| --- | --- | --- |
| 200 | Request processed successfully. | Some endpoints expose a separate application-level status field in the response body, such as `dataStatus.statusCode`. |
| 400 | Invalid request parameters or request format. | Check required fields, data types, and request body format. |
| 401 | Missing or unknown application key. | Provide a valid `appkey` with the request. |
| 403 | The application key is recognized but access is not allowed. | The key may be expired, inactive, or not permitted for the requested API. |
| 429 | Request rate or trial usage limit exceeded. | Reduce request frequency and retry with backoff. If a trial allowance is exhausted, check Trial Keys for remaining requests and subscribe to continue. |
| 500 | Internal service error. | Retry later or contact support if the error persists. |
| 503 | Upstream service unavailable. | Retry later; the requested upstream dependency is temporarily unavailable. |
## cURL Example
```bash
curl --location 'https://api.gugudata.io/ai/knowledge-bases/default/chat/completions?appkey=YOUR_APPKEY' --request POST --header 'Content-Type: application/json' --data '{
"model": "gugudata-knowledge-chat",
"messages": [
{
"role": "user",
"content": "What does the documentation say?"
}
],
"thread_id": "YOUR_VALUE",
"tenant_id": "default",
"stream": false,
"top_k": 6
}'
```