通用鉴权与 Base URL 见 HTTP API 总览。
上传见 上传文件，删除见 删除文档 / 空间。
列出文档
GET /v1/knowledge-bases/{kb_id}/documents
Authorization: Bearer <token>
| 查询参数 | 说明 |
|---|---|
path | 可选。按目录精确匹配，如 path=/ 或 path=/wiki/。省略则返回该空间未归档文档。 |
include_scaffold | 可选，默认 false。为 true 时包含建库脚手架：overview.md / log.md / index.json / .keep。 |
成功：200，文档对象数组。默认不含 archived=true，也不含上述脚手架文件（与空间「文件数」一致）。元素字段见下方「文档对象」。
文档对象
列表与 GET /v1/documents/{doc_id} 共用同一结构（节选）：
| 字段 | 说明 |
|---|---|
id | 文档 UUID |
knowledge_base_id | 所属空间 UUID |
filename / path / title | 文件名、目录、标题 |
file_type / file_size | 类型与字节数 |
status | 如 pending（解析中）、ready（可检索）、失败时见 error_message |
page_count | 页数（若有） |
tags | 字符串数组（知识库科目等） |
document_number | 空间内编号（若有） |
version | 内容版本号 |
archived | 是否已归档 |
created_at / updated_at | 时间 |
单篇元数据
GET /v1/documents/{doc_id}
Authorization: Bearer <token>
成功：200，单个文档对象。
失败：404（不存在或无权）。
单篇正文
GET /v1/documents/{doc_id}/content
Authorization: Bearer <token>
成功：200
{
"id": "<doc-uuid>",
"content": "# 标题\n…",
"version": 1
}
content 在尚未解析完成时可能为 null。
预览 / 下载 URL
GET /v1/documents/{doc_id}/url
Authorization: Bearer <token>
成功：200，{ "url": "<预签名或存储 URL>" }。
依赖对象存储；未配置时可能 501。部分 Office 仅文本解析、无 PDF 预览时返回 404。
更新正文
PUT /v1/documents/{doc_id}/content
Authorization: Bearer <token>
Content-Type: application/json
{ "content": "# 新正文\n…" }
成功：200，返回 { "id", "content", "version" }（version 递增）；服务端会重建检索分块。
更新元数据
PATCH /v1/documents/{doc_id}
Authorization: Bearer <token>
Content-Type: application/json
{ "title": "新标题", "tags": ["综述"], "path": "/wiki/" }
可更新字段包括：filename、path、title、tags 等。
成功：200，完整文档对象。
整理到知识页（仅知识库）
将已 ready、且不在 /wiki/ 下的资料整理为 /wiki/concepts/ 知识页，并更新 overview / log。
POST /v1/knowledge-bases/{kb_id}/documents/{doc_id}/compile
Authorization: Bearer <token>
| 查询参数 | 说明 |
|---|---|
force | true 时已有知识页也强制重新生成 |
成功：200
{
"status": "ready",
"source_id": "<原资料 doc id>",
"wiki_id": "<知识页 doc id>",
"wiki_path": "/wiki/concepts/….md",
"wiki_title": "标题",
"reused": false
}
reused: true 表示沿用已有知识页（未传 force）。
需 API 侧配置 DASHSCOPE_API_KEY；未配置时 503。产品说明见 知识库。