MuseCanto

导出你名下某一知识库中的全部有效文档。响应包含元数据、纯文本正文，以及可选的 HTML 渲染结果，适用于备份、检索索引与下游 ETL。

鉴权方式与 Open API 前缀见开发者文档首页。若要新建文档，请参阅导入文档。

接口

GET /api/v1/open/books/{bookSlug}/docs
Authorization: Bearer YOUR_API_KEY

项	说明
方法	`GET`
鉴权	`Authorization: Bearer` + 完整 API 密钥
路径参数	`bookSlug` — 知识库 slug（`x_book.slug`）
默认范围	仅有效文档（`status = 1`）
权限	密钥须属于该知识库所有者

查询参数

参数	默认值	说明
`excludeCategories`	`true`	为 `true` 时排除文件夹节点（`type === "category"`）；设为 `false` 可包含
`includeContentHtml`	`true`	为 `true` 时在每条文档中返回 `contentHtml`；设为 `false` 可减小响应体积（字段仍为 `null`）

包含分类节点并省略 HTML 正文的示例：

GET /api/v1/open/books/my-library/docs?excludeCategories=false&includeContentHtml=false

请求示例

将 YOUR_API_KEY、BOOK_SLUG 替换为实际值；非本地环境请将 https://your-domain.com 换成你的站点地址。

curl -sS \
  -H "Authorization: Bearer YOUR_API_KEY" \
  "https://your-domain.com/api/v1/open/books/BOOK_SLUG/docs"

$headers = @{ Authorization = "Bearer YOUR_API_KEY" }
Invoke-RestMethod `
  -Uri "https://your-domain.com/api/v1/open/books/BOOK_SLUG/docs" `
  -Headers $headers

成功响应

状态码： 200 OK

{
  "success": true,
  "book": {
    "id": "…",
    "slug": "BOOK_SLUG",
    "name": "产品笔记",
    "description": "团队内部知识库",
    "coverImage": "https://cdn.example.com/book-cover.png",
    "createdAt": "2026-04-01T08:00:00.000Z",
    "updatedAt": "2026-05-21T10:00:00.000Z"
  },
  "documents": [
    {
      "id": "…",
      "slug": "doc-slug",
      "name": "需求整理",
      "type": "document",
      "parentId": null,
      "orderKey": "a",
      "description": null,
      "emojiInfo": null,
      "cover": { "url": "https://cdn.example.com/doc-cover.png", "position": "center" },
      "tags": ["guide"],
      "themeId": "default",
      "backgroundThemeId": "transparent",
      "bodyFontSize": "default",
      "updatedAt": "2026-05-21T09:00:00.000Z",
      "createdAt": "2026-05-20T08:00:00.000Z",
      "contentStr": "可用的纯文本正文",
      "contentHtml": "<p>渲染后的 HTML 正文</p>"
    }
  ],
  "meta": { "count": 1 }
}

响应字段

`book`

字段	类型	说明
`id`	string	知识库 ID
`slug`	string	知识库 slug
`name`	string	名称
`description`	string \| null	简介
`coverImage`	string \| null	封面图 URL
`createdAt`	string (ISO 8601)	创建时间
`updatedAt`	string (ISO 8601)	最近更新时间

`documents[]`

字段	类型	说明
`id`	string	文档 ID
`slug`	string	文档 slug
`name`	string	标题
`type`	string	`document`、`category` 等
`parentId`	string \| null	父节点 ID（目录树）
`orderKey`	string	同级排序键
`description`	string \| null	摘要
`emojiInfo`	string \| null	图标信息
`cover`	object \| null	封面头图：`{ url, position }`（`url` 已按媒体代理解析；`position` 为 CSS `object-position`，未设置时为 `center`）
`tags`	string[] \| null	标签
`themeId`	string	编辑器排版主题（未设置时为 `default`）
`backgroundThemeId`	string	编辑器背景主题（未设置时为 `transparent`）
`bodyFontSize`	string	正文字号预设：`default`、`14` 或 `12`
`createdAt`	string (ISO 8601)	创建时间
`updatedAt`	string (ISO 8601)	最近更新时间
`contentStr`	string \| null	纯文本正文
`contentHtml`	string \| null	渲染后的 HTML 正文（`includeContentHtml=false` 时为 `null`）。其中的相对图片/附件 URL 会拼接与编辑器相同的 CDN 代理前缀（`config.storage.proxyUrls.cmsFile`），导出的 `<img src="...">` 可直接访问。

说明：

默认返回 contentStr 与 contentHtml；知识库很大时响应体积可能较大，可通过 includeContentHtml=false 仅拉取纯文本。
不返回 contentYjs、contentJson 等编辑器内部格式。
文档按知识库内 orderKey 排序。

错误响应

所有错误统一使用扁平信封：

{ "success": false, "code": "<机器可读 code>", "message": "<人类可读描述>" }

HTTP	`code`	场景
`401`	`INVALID_API_KEY`	缺少请求头、密钥无效、过期或已删除
`404`	`BOOK_NOT_FOUND`	slug 不存在，或不属于该密钥用户
`429`	`RATE_LIMITED`	触发 API 密钥校验速率限制
`500`	`EXPORT_FAILED`	服务端未预期错误（详细原因记录在服务端日志，不回显）

示例：

{
  "success": false,
  "code": "BOOK_NOT_FOUND",
  "message": "Knowledge base not found"
}

为何用 404 而非 403

非本人知识库统一返回 404，避免通过状态码推断 slug 是否存在。

当前版本限制

只读：不支持更新或删除文档。
无分页；一次返回全部匹配文档。
无按密钥绑定知识库白名单（知晓 slug 即可访问名下任意库）。
无法访问他人公开/密码保护的知识库。

导出知识库文档

接口