MuseCanto

使用用户 API 密钥 POST，从 Markdown、HTML 或 ProseMirror JSON 向名下知识库新建文档。

在你名下的知识库中新建一篇文档。服务端从 Markdown、HTML 或 ProseMirror JSON 解析正文，创建文档并初始化协作状态（collabVersion 从 0 开始）。

鉴权方式与 Open API 前缀见开发者文档首页。若要拉取已有文档，请参阅导出知识库文档。

接口

POST /api/v1/open/books/{bookSlug}/docs/import
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

项	说明
方法	`POST`
鉴权	`Authorization: Bearer` + 完整 API 密钥
路径参数	`bookSlug` — 目标知识库 slug
Content-Type	`application/json`
权限	密钥须属于该知识库所有者

请求体

字段	类型	必填	说明
`title`	string	是	文档标题，去除首尾空格后长度 1–150
`format`	`"markdown"` \| `"html"` \| `"json"`	是	正文格式
`content`	string \| object	是	正文。`markdown` / `html` 须为非空字符串；`json` 可为字符串或 ProseMirror 文档对象（`type: "doc"`）
`description`	string	否	摘要，最长 150
`parentId`	string	否	父节点 ID；省略则置于知识库根级。须为同一知识库内的有效节点

格式说明

`format`	`content` 要求
`markdown`	非空 Markdown 字符串
`html`	非空 HTML 字符串
`json`	ProseMirror 文档 JSON（`{ "type": "doc", "content": [...] }`）或同等结构的 JSON 字符串

请求示例

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

curl -sS -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "title": "导入的文档",
        "format": "markdown",
        "content": "# 标题\n\n正文段落。"
      }' \
  "https://your-domain.com/api/v1/open/books/BOOK_SLUG/docs/import"

$headers = @{ Authorization = "Bearer YOUR_API_KEY" }
$body = @{
  title   = "导入的文档"
  format  = "markdown"
  content = "# 标题`n`n正文段落。"
} | ConvertTo-Json
Invoke-RestMethod -Method Post `
  -Uri "https://your-domain.com/api/v1/open/books/BOOK_SLUG/docs/import" `
  -Headers $headers -ContentType "application/json" -Body $body

成功响应

状态码： 201 Created

{
  "success": true,
  "doc": {
    "id": "…",
    "slug": "doc-slug",
    "name": "导入的文档",
    "type": "document",
    "collabVersion": 0
  },
  "links": {
    "editor": "/app/books/BOOK_SLUG/doc-slug"
  }
}

响应字段

字段	类型	说明
`doc.id`	string	新文档 ID
`doc.slug`	string	新文档 slug
`doc.name`	string	标题
`doc.type`	string	固定为 `document`
`doc.collabVersion`	number	协作版本号，新建为 `0`
`links.editor`	string	浏览器内编辑器相对路径

错误响应

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

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

HTTP	`code`	场景
`400`	`INVALID_CONTENT`	正文为空或无法按 `format` 解析为有效文档
`400`	`INVALID_PARENT`	`parentId` 不存在或不属于该知识库
`401`	`INVALID_API_KEY`	缺少请求头、密钥无效、过期或已删除
`404`	`BOOK_NOT_FOUND`	slug 不存在，或不属于该密钥用户
`500`	`IMPORT_FAILED`	服务端未预期错误（详细原因记录在服务端日志，不回显）

为何用 404 而非 403

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

当前版本限制

仅支持新建：不支持更新或删除已有文档。
无按密钥绑定知识库白名单（知晓 slug 即可向名下任意库导入）。
无法向他人公开/密码保护的知识库导入。

导入文档

接口

请求体