mnapis
接口参考

接口总览（72 路由）

72 路由总表：方法、路径、Max 与 confirm 速查

下表是 72 路由速查。每个端点的交互式文档（参数 Schema、多语言代码示例）见侧边栏「交互式 API」分组（按 Tag 分组，如从 system/get-status 开始）。 发即执行的端点先读危险端点纪律。

来源：运行时 GET /capabilities（Bridge API v0.49 / App 4.5.0 / routeCount 72）。 Max = requiresMax（有效 token 下是否另需 MarginNote Max）；Cfm = 是否需 confirm:true（JSON body；upload 例外，走 query confirm=1，见脚注①）。 无 Cfm 标记即无 confirm 门，发即执行（prepare/submit/focus/discard、打快照、ui-state/apply、install/code 等）。 Cfm ✅ 中仅六个重动词为真 dry-run（不带回 422 + 已验事实），其余仅门控，须用只读端点自核。 详情见各分域页与危险端点纪律；契约原文见 运行时能力。

方法路径MaxCfm说明
GET/status——探活（免鉴权唯一）
GET/capabilities——运行时能力清单
GET/guide——运行时规程 Markdown
GET/context——用户此刻上下文
GET/install——安装脚本（?code= 一次性）
POST/install/code——安装辅助
POST/mcp——MCP 通道（GET 未实现）
GET/library/study-sets——列学习集
POST/library/study-sets✅✅新建空学习集
POST/library/documents/upload✅①上传文档（字节+query，confirm=1）
POST/library/documents/{id}/delete✅✅删资料库文档（仅干净撤销）
GET/library/folders——列文档文件夹
GET/study-sets/{id}/documents——列集内文档
POST/study-sets/{id}/documents✅✅集内加文档
POST/study-sets/{id}/documents/{id}/delete✅✅集内移除文档（失回源警告）
POST/study-sets/{id}/open——打开学习集
GET/study-sets/{id}/tree——脑图树（扁平 nodes）
GET/study-sets/{id}/sub-maps——列子脑图
GET/study-sets/{id}/snapshots——列快照
POST/study-sets/{id}/snapshots✅—打快照
POST/study-sets/{id}/delete✅✅删学习集（最重）
GET/study-sets/{id}/notebooks——集引用的文档笔记本
GET/study-sets/{id}/hashtags——集标签树
GET/study-sets/{id}/note-palette——16 色摘录色板
POST/study-sets/{id}/mindmap-print/preview——脑图打印计划
POST/study-sets/{id}/mindmap-print/export——按计划导出脑图 PDF
GET/documents/{id}/outline——目录（segments）
GET/documents/{id}/pages——页文本（&blocks=1 探针）
GET/documents/{id}/pages/{index}/parts——页视觉注释面
GET/documents/{id}/pages/{index}/content/{id}——页手写/留白图
GET/documents/{id}/toc-candidates——AI 目录标题候选
POST/documents/{id}/toc✅✅写/切 AI 目录
POST/documents/{id}/locate——按原文找位置
POST/documents/{id}/export——导出扁平 PDF
GET/documents/{id}/sync-status——单文档同步对账
POST/notes/batch-get——批量读卡（≤200）
POST/notes/hashtags✅✅写 hashtag
POST/notes/metadata✅✅改样式
POST/notes/move✅✅移动（≤50）
POST/notes/copy✅✅复制分支（≤50 根）
POST/notes/delete✅✅删卡（≤50，同集）
POST/notes/fold✅✅折叠（≤200）
GET/notes/{id}/content/{id}——卡二进制项
GET/notes/{id}/render——整卡渲染
POST/notes/{id}/image-occlusions✅✅原生图片挖空
POST/notes/{id}/title✅✅改标题
POST/notes/{id}/text✅✅改正文
POST/notes/{id}/comments✅✅追加评论
POST/notes/{id}/comments/{index}✅✅改写评论（1..N）
POST/notes/{id}/comments/{index}/delete✅✅删除评论
POST/notes/{id}/merge-branch✅✅合并分支
POST/notes/{id}/fold-into-sub-map✅✅折成子脑图/展回
POST/notes/{id}/focus——定位到卡
GET/decks——列复习卡组
POST/decks✅✅建卡组
GET/decks/{id}/cards——列复习卡
POST/decks/{id}/cards✅✅加复习卡（≤50）
POST/decks/{id}/open——打开卡组
POST/bundles/prepare——准备任务包
GET/bundles——列包/作业
GET/bundles/{id}/files——列包文件/取单文件
POST/bundles/{id}/submit✅—提交导入（无 confirm 门）
POST/bundles/{id}/focus——聚焦结果
POST/bundles/{id}/discard——删包/取消
POST/snapshots/{id}/restore✅✅回退快照
GET/search——全库搜索
GET/sync/legacy/status——旧同步诊断
GET/sync/legacy/events——旧同步增量事件
POST/sync/legacy/recheck——旧同步安全重核
POST/sync/legacy/inventory——旧同步只读盘点
GET/ui-state——读界面状态
POST/ui-state/apply✅—应用界面状态（差量）

① upload 的 confirm=1 走 query，不是 JSON body 的 confirm:true。

错误处理与纪律

状态码速查、confirm 门清单、鉴权与订阅

危险端点纪律

submit、快照、安装辅助、界面状态、目录写入的 confirm 与调用纪律