接口参考
Notes
批量读卡、标签样式、移动复制删除、评论标题正文、合并折叠、挖空
参数、Schema、多语言示例、Try-it 见各端点交互页（左侧 Notes 分组）。本页只保留跨参数的纪律：判据、陷阱与调用顺序。
POST /notes/batch-get（免 Max，≤200/次）
texts[]是对象数组{index,text,excerpt,noteid,kind}，不是字符串数组。index0=卡正文，1..N=子笔记（评论接口用此号）；稀疏（无文本条目占号但不出场）；空留白亦返回（kind:blank，noteid为留白实体 id，写内容走同一text端点）。parts[]为视觉顺序全量；texts空先看parts，勿断言卡为空。hashtagPaths存值为完整叶路径，祖先为派生，勿写回。
POST /notes/hashtags（需 Max + confirm，≤200 卡）
- 标签须完整路径。
remove默认精确（删#医学不碰#医学/心血管；连子一起删才includeDescendants:true，仅 remove 合法）。replace空数组=清空（须展示获同意）。 - 禁 text 接口伪造（422
HASHTAG_ROUTE_REQUIRED）。比较不分大小写，保留首次拼写。 - 整批一撤销组；
persisted:true才成功。批量改前打快照；写完回读batch-get.hashtags（批量对账集hashtags）。
POST /notes/metadata（需 Max + confirm，≤200）
colorIndex0..15、fillIndex-1..2（语义见色板页）；选色前读note-palette，禁硬编码颜色名。- 独立 context 回读一致才
persisted:true；SAVE_FAILED非成功。collapsed/子脑图/标题正文走专用端点。
POST /notes/move（需 Max + confirm，≤50/次）
- 同集改父子，不删不改内容，整批一撤销组。先展示逐卡方案获同意。
- 不调兄弟顺序/坐标（无此能力，如实告知）。批量先打快照，方案靠 tree+batch-get。
POST /notes/copy（需 Max + confirm，真 dry-run，≤50 根）
reference（引用卡，内容同步）/clone（独立克隆，分支内链接重映射）二选一。- 复制所选根整棵分支（当时快照，不随源树后续调整同步）；祖先后代同选后代
covered_by_selected_ancestor跳过；目标须已存在普通脑图卡；源禁隐藏/复习卡；可跨集（源文档按规则入目标集，同集不改归属）。 - 不带 confirm 回 422 +
wouldCopy/skipped。persisted:true才成功。
POST /notes/delete（需 Max + confirm，真 dry-run，≤50/次，同集）
- 只删点名卡，子卡按
childrenReattachedTo接祖父（grandparent）或升顶层重排（topLevel，位置会跳，CLI 固有限制）。合并子笔记随卡消失；虚拟卡断引用转独立；闪卡复制体级联。 - 回收站默认关，先打快照。流程：打点 → tree 看子节点 → 展示标题+子卡去向获同意 → 带 confirm → 转告
orphanedChildren/descendants/trashEnabled+ 逐条outcome（deleted真消失 /hidden仅隐藏划线保留）。顶层卡额外提醒重排。
POST /notes/fold（需 Max + confirm，≤200）
- 最轻写动词。叶子 skip（
no_children）。脑图开着可能需重进。
GET /notes/{id}/content/{contentId}（免 Max）
- 摘录/插图/手写回合成图；音视频回原始二进制。代价中：先 parts 定位必要项再取。
GET /notes/{id}/render（免 Max）
- 整卡合成长图/PDF。超 3600 万像素拒绝。代价高：看整卡/视觉校对专用，不代批量文本读取。
POST /notes/{id}/image-occlusions（需 Max + confirm，真 dry-run）
- 只给已存在图片/PDF 摘录笔记增/替原生遮罩（不建卡，不写
complexQuestion）。 - 1..200 框；
add同页同矩形同组去重；replace替换该源图已有遮罩。禁视觉模型直写：先读 batch-get + 底图出候选并叠框预览。 - dry-run 与确认都带
expectedSourceFingerprint；确认另带expectedMaskFingerprint。变了回 409（重读重预览）。persisted:true才成功。 existingReviewCardCount>0须转告：已有复习卡为快照，不自动改写，重建才进复习/Anki。
POST /notes/{id}/title、/text（需 Max + confirm）
expectedPrefix（空传""）。编辑会话前打点；改写/删除展示原文→改后获同意。- 判摘录卡：
texts[].excerpt任一 true 或sourceAnchor.hasExcerpt（勿用sourceAnchor.page判 block 包）。摘录卡改文致脱钩（回源不受影响），须告知。
POST /notes/{id}/comments（需 Max + confirm）
- 追加。整条为
marginnote4app://note/…URL 时成真双链（整理回链旧卡用此，勿塞正文链接文本）。
POST /notes/{id}/comments/{index}、/{index}/delete（需 Max + confirm）
index为texts[].index的 1..N（0 为卡正文，传 0 422）。先读最新；409COMMENT_CHANGED重读再来。
POST /notes/{id}/merge-branch（需 Max + confirm）
- 默认直接子卡；
recursive:true整 subtree（Agent 默认收窄防爆）。先 dry-run 念willMerge[]；合不了留树；摘要卡/子脑图根卡跳过。一 undo 组。合并（对方消失），非链接。
POST /notes/{id}/fold-into-sub-map（需 Max + confirm）
- 折子脑图须有子节点（否则 422
NO_CHILDREN）；undo:true展回。「放进子脑图」= move 为其子节点，无需新端点。
POST /notes/{id}/focus（免 Max，无 confirm）
- 多集引用同一卡时用
topicid指定集。抢屏，仅用户要求时用；异步，事后/context对账。