Upload

通用鉴权与 Base URL 见 HTTP API 总览。
上传前需已有空间 kb_id，见 空间（创建 / 列表 / 详情）。

支持两种方式：

1. 二进制文件（PDF / Word 等）：走 TUS 可断点续传（/v1/uploads）
2. Markdown 笔记：直接创建笔记接口（无需 TUS）

TUS 上传（PDF、Office、图片等）

协议版本：Tus-Resumable: 1.0.0
单文件上限：100 MB
允许扩展名：.pdf .pptx .ppt .docx .doc .png .jpg .jpeg .webp .gif .xlsx .xls .csv .html .htm

1. 创建上传会话

POST /v1/uploads
Authorization: Bearer <token>
Tus-Resumable: 1.0.0
Upload-Length: <文件字节数>
Upload-Metadata: filename <base64(文件名)>,knowledge_base_id <base64(空间UUID)>

说明：

• Upload-Metadata 为 TUS 标准：键值用逗号分隔，值为 Base64 编码的 UTF-8 字符串
• 必须提供 filename 与 knowledge_base_id
• 空间必须属于当前登录用户，否则 403

成功：201，响应头 Location: /v1/uploads/{upload_id}

查询服务能力（可选）：

OPTIONS /v1/uploads

2. 分片上传内容

PATCH /v1/uploads/{upload_id}
Authorization: Bearer <token>
Tus-Resumable: 1.0.0
Content-Type: application/offset+octet-stream
Upload-Offset: <已上传字节偏移，从 0 开始>

请求体为原始二进制分片。可多次 PATCH，直到偏移等于 Upload-Length。

成功：204，响应头含最新 Upload-Offset。
全部传完后，服务端落库并触发解析，响应头额外返回：

• X-Document-Id：新建文档的 UUID

文档初始 status 为 pending，解析完成后变为 ready（失败见文档字段 error_message）。

PDF 解析后端由环境变量 PDF_BACKEND 控制：默认 pdf_oxide（本地抽文本）。可选 mistral。

3. 查询进度（可选）

HEAD /v1/uploads/{upload_id}
Authorization: Bearer <token>

响应头：Upload-Offset、Upload-Length。

创建 Markdown 笔记

无需上传二进制，直接写入文本：

POST /v1/knowledge-bases/{kb_id}/documents/note
Authorization: Bearer <token>
Content-Type: application/json

{
  "filename": "notes.md",
  "path": "/",
  "content": "# 标题\n正文…"
}

成功：201，返回文档对象；内容会立刻分块入库，可供检索。

相关

• 文档（列表 / 读写）（含列出文档）
• 删除文档 / 空间