Study Sets

参数、Schema、多语言示例、Try-it 见各端点交互页（左侧 StudySets 分组）。本页只保留判据与陷阱。

文档归属

GET /study-sets/{id}/documents（免 Max）

交互式

• 含 sourceState（normal/missing_file）与主文档。挑 normal 的打开（否则 422）。

POST /study-sets/{id}/documents（需 Max + confirm）

交互式

• 文档须已在库。首次加成主文档（becameMainDocument:true），再加为 addedToBooklist；重复加幂等。空集完整链路：建集（验 isStudySet）→ 加文档（验 becameMainDocument）→ outline → prepare → submit。

POST /study-sets/{id}/documents/{docId}/delete（需 Max + confirm）

交互式

• 文档留库，该书有锚卡片失回源（startpage 清空、改指主文档）。先不带 confirm 打一次看失回源卡数，告知后再 confirm。
• 主文档可移除（newMainDocumentAfter 预告上位者）；移除最后一个退回占位符。自动打快照（存上下文并告知；快照失败则无撤销，须明说）。removed:false = 未生效，勿报成功。

POST /study-sets/{id}/open（免 Max，无 confirm）

交互式

• 不给 bookmd5 即主文档。可临时打开非本集文档（tempOpen:true，如实告知非「已加入」）。异步，事后 /context 对账。会抢屏，仅用户要求时用。

结构

GET /study-sets/{id}/tree（免 Max）

交互式

• 扁平 nodes[]，父子靠 parent 拼（非嵌套 children）。subMapId 为归属标签（住在哪张子脑图里，非拥有）；depth>0 子脑图可嵌套。
• noteCount（库记录，摘录亦算）与 tree 节点数口径不同，对不上正常。标题超 64 截断，完整走 batch-get。
• ?root= 读单张子脑图。

GET /study-sets/{id}/sub-maps（免 Max）

交互式

• 顺序同 App。

GET /study-sets/{id}/notebooks（免 Max）

交互式

• 该集引用了哪些文档笔记本。

快照与删除

GET /study-sets/{id}/snapshots（免 Max）／POST /study-sets/{id}/snapshots（需 Max）

交互式 · 交互式 · 危险纪律

• description 不加 Agent: 前缀。无变化复用既有版本点（0.18+ 回 created:false + warnings；更旧无此字段时回读列表核条数）。批量写前必打。回退见 Snapshots 章。

POST /study-sets/{id}/delete（需 Max + confirm，最重）

交互式

• expectedTitle 必填且须完全一致（否则 409 + actualTitle）；调用前读出标题卡数展示获同意。
• 默认保守（卡隐藏、划线保留、自动打快照）；彻底清才显式 false（不可恢复）。
• 语义为不再满足学习集判据（removedFromLibrary 回读自证）。preDeleteSnapshotId 为后悔药（可能复用既有快照，描述未必是删除前备份，内容一致即有效）。
• 卡组删除走同一端点（keepHighlights:false 才真干净，默认仍在 GET /decks）。

标签与色板

GET /study-sets/{id}/hashtags（免 Max）

交互式

• directCardCount 仅直存；cardCount 含后代；derived:true 为推导层。

GET /study-sets/{id}/note-palette（免 Max）

交互式

• 16 项。拆书 [style:] 与 notes/metadata 选色前必读，禁硬编码颜色名。fillIndex 语义与 /capabilities.fillIndexSemantics 同源（0 非无填充，「不填色」选 2）。

脑图打印（0.49+，免 Max，无 confirm）

交互式 · 交互式

• preview 为规划入口，不落文件。CLI 不自算分页。export 传保存的 plan 执行，不重算。输出到 MindMapExports。与文档导出共享 EXPORT_BUSY。CLI 推荐预览 → 用户确认 → 执行。