REST API
KaaS 后端在配置的监听地址（默认 http://localhost:8080）暴露 REST API。除特殊说明外，所有端点使用 JSON 请求/响应体。
基础 URL
http://<host>:<port>/api内容提交
POST /api/submit
提交文本内容以编译到知识库。
- Content-Type:
application/json - 请求体上限: 10 MiB
| 字段 | 类型 | 说明 |
|---|---|---|
content | string | 待编译的原始文本 |
source_url | string | （可选）内容的来源 URL |
响应: 201 Created — 返回创建的任务对象。
POST /api/submit/files
上传一个或多个文件用于编译。使用 multipart/form-data。
- Content-Type:
multipart/form-data
| 字段 | 类型 | 说明 |
|---|---|---|
files | file(s) | 一个或多个待上传文件 |
文件大小和数量限制由上传配置控制（见 GET /api/upload/config）。
响应: 201 Created — 返回创建的任务对象。
GET /api/upload/config
获取当前上传限制配置。
响应: 200 OK
{
"max_file_size": 10485760,
"max_files": 10,
"allowed_extensions": [".md", ".txt", ".pdf"]
}任务管理
GET /api/tasks
列出编译任务，支持分页。
| 查询参数 | 类型 | 说明 | 默认值 |
|---|---|---|---|
page | int | 页码 | 1 |
page_size | int | 每页条数 | 20 |
status | string | 按状态过滤 | — |
响应: 200 OK — 返回分页任务列表。
GET /api/tasks/{id}
根据 ID 获取单个任务。
| 路径参数 | 类型 | 说明 |
|---|---|---|
id | string | 任务 ID |
响应: 200 OK — 返回任务对象。
错误: 404 Not Found — 任务不存在。
GET /api/tasks/{id}/content
获取任务的源内容（原始提交的文本或文件内容）。
| 路径参数 | 类型 | 说明 |
|---|---|---|
id | string | 任务 ID |
响应: 200 OK — 返回任务内容。
错误: 404 Not Found — 任务不存在。
DELETE /api/tasks/{id}
删除任务及其关联数据。
| 路径参数 | 类型 | 说明 |
|---|---|---|
id | string | 任务 ID |
响应: 204 No Content
错误: 404 Not Found — 任务不存在。
Wiki
GET /api/wiki
以树形结构列出所有 wiki 文章。
响应: 200 OK — 返回 wiki 树（目录和文件）。
GET /api/wiki/file
获取单个 wiki 文件的内容。
| 查询参数 | 类型 | 说明 |
|---|---|---|
path | string | wiki 文件的相对路径 |
响应: 200 OK — 返回文件内容（Markdown）。
错误: 404 Not Found — 文件不存在。
聊天
POST /api/chat
发起基于编译 wiki 的流式聊天。响应为 SSE（Server-Sent Events） 流。
- Content-Type:
application/json - 响应 Content-Type:
text/event-stream
| 字段 | 类型 | 说明 |
|---|---|---|
query | string | 用户的问题 |
session_id | string | （可选）会话 ID，用于保持对话历史 |
model | string | （可选）模型覆盖 |
SSE 事件类型：
| 事件类型 | 说明 |
|---|---|
status | 处理状态更新（如 "retrieving"、"generating"） |
delta | 增量答案文本片段 |
done | 最终事件，含元数据（来源、费用） |
error | 处理过程中发生错误 |
会话管理
GET /api/sessions
列出所有聊天会话，按最近更新时间排序。
响应: 200 OK — 返回会话对象数组。
POST /api/sessions
创建新聊天会话。
- Content-Type:
application/json
| 字段 | 类型 | 说明 |
|---|---|---|
title | string | （可选）会话标题 |
响应: 201 Created — 返回创建的会话对象。
PATCH /api/sessions/{id}
更新会话（如重命名）。
| 路径参数 | 类型 | 说明 |
|---|---|---|
id | string | 会话 ID |
| 字段 | 类型 | 说明 |
|---|---|---|
title | string | 新会话标题 |
响应: 200 OK — 返回更新后的会话对象。
DELETE /api/sessions/{id}
删除会话及其所有消息。
| 路径参数 | 类型 | 说明 |
|---|---|---|
id | string | 会话 ID |
响应: 204 No Content
GET /api/sessions/{id}/messages
列出会话中的消息。
| 路径参数 | 类型 | 说明 |
|---|---|---|
id | string | 会话 ID |
响应: 200 OK — 返回消息对象数组。
健康检查
GET /healthz
容器编排的存活探针。不访问数据库或 AI 引擎。
响应: 200 OK
{"status": "ok"}MCP 端点
/mcp
MCP（Model Context Protocol）streamable-http 端点。仅在配置中 [ai.mcp] enabled = true（或环境变量 KAAS_MCP_ENABLED=true）时可用。
- 认证: 当设置了
KAAS_MCP_TOKEN时需要 Bearer token。 - 协议: MCP streamable-http 传输
详见 MCP 服务器 了解工具规格。