Outline RESTful API 实战指南如何完成文档读、写、状态流转与检索【免费下载链接】outlineThe fastest knowledge base for growing teams. Beautiful, realtime collaborative, feature packed, and markdown compatible.项目地址: https://gitcode.com/GitHub_Trending/ou/outline如果你要把团队知识库接入自动化流程——同步 Wiki、生成报告、做文档中台——那么 Outline RESTful API 就是你需要的入口。Outline 是一个实时协作、Markdown 兼容的开源知识库The fastest knowledge base for growing teams它把整套文档能力开放成了统一格式的 HTTP 接口一个基础地址、一种认证方式、一套响应约定之后所有操作读、写、归档、搜索、授权都遵循同一套规则。上手准备十分钟跑通第一个请求所有接口都是POST方法路径形如/api/documents.list——冒号后面是资源.动作没有 GET/PUT/DELETE 的分法全部用请求体传参。你只需要先搞清三件事怎么发请求、怎么带凭证、怎么读响应。约定项说明基础地址部署根路径下的/api接口名形如documents.list、collections.create认证方式Authorization: Bearer token。token 可以是 API 密钥长期集成首选、OAuth access token 或会话 JWT请求格式Content-Type: application/json参数放 JSON 请求体响应结构固定三段pagination列表接口才有、data业务数据、policies当前用户对返回资源的权限位限流响应头触发限流时返回429并带Retry-After等待秒数、RateLimit-Limit、RateLimit-Remaining、RateLimit-Reset公共请求头只声明这一次后文所有示例默认都已带上不再重复# 公共请求头认证 JSON 内容类型 -H Authorization: Bearer $API_KEY -H Content-Type: application/json拿到凭证后用collections.list集合列表或documents.list发第一个探活请求只要返回data数组而不是 401链路就通了。认证与限流的具体实现可以分别看 认证中间件 和 限流中间件。读先 list 再 info把文档拿回来读接口分两层list类接口负责找到文档info负责拿全文。先列表、后详情是最省配额的路径。documents.list按条件列出文档作用分页返回文档列表支持按集合、创建者、父文档、状态等条件过滤。请求要点sortdirection控制排序可选createdAt/updatedAt/title等字段collectionId、userId、parentDocumentId做范围过滤statusFilter传published/draft/archived的组合offset/limit控制分页。参数用途sort/direction排序字段与方向ASC/DESCcollectionId/parentDocumentId/backlinkDocumentId按集合、父文档、反向链接筛选userId/template按创建者或是否模板筛选statusFilter状态过滤数组offset/limit分页游标与页大小响应要点data是文档摘要数组id、title、icon、updatedAt 等不含正文全文policies按文档 id 给出canRead/canUpdate/canDelete等权限位——渲染操作按钮前先看这里能省掉一批 403。示例curl -s $HOST/api/documents.list \ -H Authorization: Bearer $API_KEY -H Content-Type: application/json \ -d {sort:updatedAt,direction:DESC,collectionId:col-uuid,limit:20}documents.info取回单篇全文作用按 id 取回完整文档含 ProseMirror 格式的正文、版本、附件引用。请求要点id必需shareId用于匿名走分享链接访问apiVersion可选 1/2。该接口允许未认证auth({ optional: true })是少数支持公开分享场景的读接口。响应要点data.document为完整文档对象policies给出该文档下你可执行的操作集合。示例curl -s $HOST/api/documents.info \ -H Authorization: Bearer $API_KEY -H Content-Type: application/json \ -d {id:doc-uuid,apiVersion:2}同族接口还有documents.drafts我的草稿、documents.archived归档清单、documents.viewed最近浏览参数形态与list类似按场景替换即可。写create 与 update正文用 ProseMirror JSON写接口的关键认知只有一条text不是纯文本字符串而是 ProseMirrorProseMirror协作编辑器状态格式JSON。标题、加粗、列表都编码在文档结构里。如果你手里只有 Markdown 或 HTML先走导入接口见检索与导入一节别手工拼 JSON。documents.create新建一篇文档作用在指定集合可选父文档下创建文档可当场发布。请求要点参数用途title/text标题与正文ProseMirror JSONcollectionId/parentDocumentId归属集合与父节点publish是否立即发布false 则落为草稿icon/color侧边栏图标与颜色template/fullWidth是否模板、是否通栏createdAt可选回写创建时间用于迁移保序响应要点data为新建文档完整对象policies即刻可用创建者天然有全部写权限。示例curl -s $HOST/api/documents.create \ -H Authorization: Bearer $API_KEY -H Content-Type: application/json \ -d {title:周报 2026-08,text:{type:doc,content:[]},collectionId:col-uuid,publish:true}documents.update原地改文档作用更新标题、正文、图标等字段支持编辑会话语义。请求要点id必需title/text只传要改的字段append: true表示追加而非覆盖正文done: true表示本次编辑会话结束服务端会据此落版本collectionId可顺带把文档挪到别的集合。响应要点返回更新后的文档摘要含新的updatedAt。示例curl -s $HOST/api/documents.update \ -H Authorization: Bearer $API_KEY -H Content-Type: application/json \ -d {id:doc-uuid,title:周报已修订,done:true}状态流转归档、删除、恢复、发布文档的生命周期由四个接口驱动全部以id为入参操作互逆、可回溯documents.archive / documents.unpublish作用archive把已发布文档移入归档侧边栏不再出现unpublish撤回发布状态可选detach同时从集合中脱离。请求要点archive只传idunpublish传id 可选detach。响应要点分别回写archivedAt/publishedAt: null。documents.delete 与 documents.restore作用delete进回收站permanent: true则物理删除不可逆慎用restore从回收站恢复可选revisionId恢复到某个历史版本。请求要点都只需idrestore可带collectionId指定恢复位置。响应要点deletedAt置空即恢复成功。documents.duplicate 与 documents.move作用duplicate复制文档recursive: true连同子树一起复制可换title、换集合、指定是否发布move调整文档在树中的位置目标collectionIdparentDocumentIdindex。请求要点move的index是分位索引不确定位置时先list看相邻文档的排序值。响应要点都返回目标文档的最新定位信息可直接用于前端刷新。# 把文档归档一行命令完成状态流转 curl -s $HOST/api/documents.archive \ -H Authorization: Bearer $API_KEY -H Content-Type: application/json \ -d {id:doc-uuid}检索与导入search 找内容import 换格式documents.search全文搜索作用按关键词在权限可见范围内搜正文返回命中摘要。请求要点query必需collectionId/documentId收窄范围dateFilterday/week/month/year按更新时间过滤snippetMinWords/snippetMaxWords控制摘要长短shareId支持分享上下文搜索。响应要点data含匹配片段注意它是全文检索慢且吃配额别拿它当 list 用。documents.search_titles标题快速搜索作用只匹配标题用于下拉联想类场景。请求要点与search同参响应更快适合前端实时建议。示例curl -s $HOST/api/documents.search_titles \ -H Authorization: Bearer $API_KEY -H Content-Type: application/json \ -d {query:周报,limit:10}documents.import / documents.export进出 Outline作用import接受multipart/form-data文件HTML、Markdown 等交给队列异步转换后落库export按Accept头返回 HTML / Markdown / PDF 文件流。请求要点import用publish/collectionId/parentDocumentId指定落地位置export用Accept: text/markdown这类请求头挑格式。响应要点import返回任务信息异步需轮询任务状态export直接是文件下载不是 JSON。授权把文档借给特定人或组权限位藏在每个列表接口的policies里而改权限本身也有专门接口核心是两条加与撤。documents.add_user / documents.add_group作用给单个用户或整个组授予文档权限。请求要点id文档userId或groupIdpermissionread只读 /read_write可编辑。响应要点返回新建立的关联对象含permission字段。documents.remove_user / documents.remove_group作用撤销对应主体对文档的授权。请求要点iduserId/groupId无第三参。响应要点成功即返回空数据或关联删除确认无需轮询。# 给组授予编辑权限 curl -s $HOST/api/documents.add_group \ -H Authorization: Bearer $API_KEY -H Content-Type: application/json \ -d {id:doc-uuid,groupId:group-uuid,permission:read_write}端到端实战从凭证到落库的一条调用链下面这段脚本演示一条真实链路探活 → 建文档 → 追加内容 → 取全文 → 归档每一步都校验了上一步的产出。把它贴进终端替换$HOST与$API_KEY就能跑。HOSThttps://kb.example.com API_KEYsk_test_... # 1. 探活确认凭证有效拿到目标集合 COLL$(curl -s $HOST/api/collections.list \ -H Authorization: Bearer $API_KEY -H Content-Type: application/json \ -d {} | jq -r .data[0].id) # 2. 创建并发布文档 DOC$(curl -s $HOST/api/documents.create \ -H Authorization: Bearer $API_KEY -H Content-Type: application/json \ -d {\title\:\自动化接入示例\,\text\:{\type\:\doc\,\content\:[]},\collectionId\:\$COLL\,\publish\:true} \ | jq -r .data.id) # 3. 追加一段正文并标记编辑会话结束落版本 curl -s $HOST/api/documents.update \ -H Authorization: Bearer $API_KEY -H Content-Type: application/json \ -d {\id\:\$DOC\,\text\:{\type\:\doc\,\content\:[]},\append\:true,\done\:true} /dev/null # 4. 取回全文校验 curl -s $HOST/api/documents.info \ -H Authorization: Bearer $API_KEY -H Content-Type: application/json \ -d {\id\:\$DOC\} | jq .data.document.title # 5. 归档进入生命周期下一态 curl -s $HOST/api/documents.archive \ -H Authorization: Bearer $API_KEY -H Content-Type: application/json \ -d {\id\:\$DOC\} | jq .data.archivedAt这条链路覆盖了 API 的典型用法list 找位置 → create 建对象 → update 改内容 → info 读结果 → archive 管状态。批量场景下把 2/3 步替换成batch接口批处理路由可以显著减少往返。排障手册错误码与限流怎么查遇到非 200 别慌Outline 的错误响应结构是统一的{ error: { name: ValidationError, message: Invalid input provided, status: 422, details: [{ path: [title], message: Title is required }] } }排查时先看status定位类别再看details定位字段。状态码含义排查动作400请求本身非法检查请求体是否为合法 JSON、接口名拼写documents.list不是/list401未认证或凭证失效确认Authorization: Bearer token格式检查 token 是否过期、API key 是否被停用403权限不足响应里的policies会告诉你缺哪个权限位用add_user/add_group补授权后重试404资源不存在确认 id 属于当前 team注意文档在回收站后多数接口仍 404需走restore422参数校验失败逐条对照details[].path修字段text必须是 ProseMirror JSON 而不是字符串429触发限流读Retry-After头等待把高频 list 换成search_titles或加缓存500服务端异常重试一次持续出现则查服务端日志错误处理入口见 错误定义关于限流默认开启窗口与配额由RATE_LIMITER_ENABLED、RATE_LIMITER_REQUESTS默认 1000 次/60 秒窗口等环境变量控制且支持按路由单独加码如搜索类接口会挂更严格的 limiter。被限流时响应头里会带RateLimit-Limit/RateLimit-Remaining/RateLimit-Reset把这三个值打进你的监控日志比等 429 再处理要主动得多。实现细节见 RateLimiter 工具。下一步往哪看本文只覆盖了documents.*这条主线。要继续深入按这条线走效率最高全部接口定义都在 路由目录每个资源一个子目录documents的完整实现是 documents.ts入参 zod schema 在同目录schema.ts命令层create/update/delete 的真实逻辑在 server/commands/比如documentCreator.ts、documentMover.ts权限判定policies从哪来在 server/policies/更多资源——集合、组、评论、附件、分享——遵循与文档完全相同的动作命名 统一响应约定照这套模式迁移即可掌握这套一个基础地址、一种凭证、六个动作域的心智模型后Outline 的 API 对你就只剩搬砖的功夫了——去把知识库接进你的流水线吧。【免费下载链接】outlineThe fastest knowledge base for growing teams. Beautiful, realtime collaborative, feature packed, and markdown compatible.项目地址: https://gitcode.com/GitHub_Trending/ou/outline创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考