> ## Documentation Index > Fetch the complete documentation index at: https://dev.marginnote.com.cn/llms.txt > Use this file to discover all available pages before exploring further. # 批量获取卡片 > 按 id 一次读多张卡：标题与预览、文本项、二进制项、样式级别、标签、插件保存的字段、 以及内容的来源。 插件状态记在脑图的卡片上。从文档上摘下来的记录在文档笔记本里，两者不是同一个对象， 用摘录记录的 id 读插件字段只会读到空。 ## OpenAPI ````yaml /openapi/plugin-api.yaml post /notes/batch-get openapi: 3.1.0 info: title: 场景插件 API summary: 场景插件在网页面板里可以调用的接口。 description: > 场景插件的面板是一个网页。页面里向 `/bridge/v1` 发请求，就能读写 MarginNote 里的数据。 请求由 MarginNote 处理，与外部命令行工具共用同一套处理代码。外部工具要带令牌，面板不必带。 面板页面从 `mnpanel://panel/index.html` 加载，因此 `fetch('/bridge/v1' + path)` 属于同源请求。 面板调用受这些条件约束： - 请求不带令牌，本文件也不声明安全方案。 - 页面能调用哪些接口，取决于两份名单。模板里的 `plugins` 名单和沉浸态决定面板能不能建好， 网页面板白名单决定页面能调哪些接口。不在白名单里的请求返回 `403`， 错误码为 `IN_PROCESS_NOT_ALLOWED`。 - `GET /capabilities` 里的 `requiresMax` 只约束外部 Agent。面板的请求在 MarginNote 进程内处理， 不受令牌、订阅状态与跨设备批准的限制，能否调用只看该路径是否在白名单内。 - 写操作里的 `addon`，MarginNote 会改写为当前面板所属插件的 id；`confirm` 由 MarginNote 补上。 页面填的值不会生效。 用 `mn.api(path, opts)` 读取数据。该方法始终将 Response Body 按 JSON 解析，相当于 `fetch('/bridge/v1' + path, opts).then(r => r.json())`。 响应的内容不是 JSON 的接口，改用 `fetch`： - `GET /guide` 返回 Markdown 正文。 - `GET /notes/{noteid}/render` 返回卡片长图或 PDF。 - `GET /documents/{bookmd5}/pages/{index}/content/{contentId}` 返回图片。 - `GET /bundles/{bundleId}/files` 带 `?path=` 时返回该文件的原始字节。 调用失败时 Promise 不会进入 reject。MarginNote 把错误对象 `{"error":{"code":"…","message":"…"}}` 当作 Response Body 返回，因此结果落在 resolve 里。 判断调用结果看响应里是否带 `error`，写操作另看响应里的 `persisted`。 接口清单、各项上限与 Request Body 结构随 MarginNote 的版本变化，运行时以 `GET /capabilities` 与 `GET /guide` 返回的内容为准。 version: '0.91' servers: [] security: [] tags: - name: 能力与状态 description: 读取 MarginNote 的能力、版本与当前上下文。调用其他接口之前先读这组。 - name: 卡片与摘录 description: 卡片的读取与写入、摘录的创建、批注、标签、元数据与留白。 - name: 手写会话 description: 手写层、作答纸、练习准备清单与会话记录的读取与提交。 - name: 学习集与卡组 description: 学习集结构、脑图树、子脑图、色板、快照与复习卡组。 - name: 文档与页面 description: 文档目录、页文本、页内注释面、摘录清单与同步诊断。 - name: 导出与 Anki description: 文档导出计划、导出文件、Anki 导出能力、作业与产物。 - name: 查找 description: 跨库搜索、文件夹列表与学习集列表。 - name: 界面与模板 description: 读取当前界面状态与沉浸模板。 - name: 插件辅助 description: 面板辅助脚本、已配对设备与本机 helper 信息。 - name: 任务包与同步诊断 description: 拆书任务包与旧 CloudKit 同步诊断。 paths: /notes/batch-get: post: tags: - 卡片与摘录 summary: 批量获取卡片 description: | 按 id 一次读多张卡：标题与预览、文本项、二进制项、样式级别、标签、插件保存的字段、 以及内容的来源。 插件状态记在脑图的卡片上。从文档上摘下来的记录在文档笔记本里，两者不是同一个对象， 用摘录记录的 id 读插件字段只会读到空。 operationId: postNotesBatchGet requestBody: required: true content: application/json: schema: type: object required: - noteIds properties: noteIds: type: array maxItems: 200 items: type: string description: 目标卡片。 addons: type: array items: type: string description: 要读的插件字段所属的插件 id。写一个星号表示该卡上所有插件的字段。 comments: type: boolean description: 是否一并返回批注状态。 examples: oneCard: summary: 获取卡片及其插件字段 value: noteIds: - 5880F73A-3A6D-4464-9D6F-88F60285401E addons: - mn.vocab responses: '200': description: 逐张卡的结果。未找到的卡将 `found` 标为 `false`，仍返回 `200`。 content: application/json: schema: $ref: '#/components/schemas/BatchGetResponse' examples: recorded: summary: 真机实录（MarginNote 0.61，2026-09-18 录制）；实录只保留开头部分 value: items: - texts: [] preview: 理工公式对照材料 · 样例 isSubMapRoot: false noteid: CFF32D75-D896-44C3-A1E0-440310573274 found: true metadata: fillIndex: 1 colorIndex: 12 hasInk: false topicid: 77012CA0-48E8-4D29-B5F5-1EEA927AE086 addonValues: {} title: 理工公式对照材料 · 样例 folded: false sourceAnchor: bookmd5: >- 8daef026f17a04db9b325c86366419936de1ef8b454218998990a3cef6f467a7 hasExcerpt: false page: null hasBlank: false parts: - contentId: title noteid: CFF32D75-D896-44C3-A1E0-440310573274 truncated: false excerpt: false text: 理工公式对照材料 · 样例 renderable: false kind: title index: -1 hidden: false kind: card hashtags: [] hashtagPaths: [] reference: isReference: false bridgeApiVersion: '0.61' measured: summary: 实测于 2026-10-07，App 0.91 value: items: - hasBlank: true flashcard: false found: true metadata: fillIndex: 0 colorIndex: 4 preview: 探针改过的正文。 hasInk: false title: '' parts: - ocrText: 探针改过的正文。 index: 0 noteid: D3085422-2CB9-4B68-A78D-DEE351CF9C38 excerpt: true mimeType: image/png width: 1120 contentPath: >- /notes/D3085422-2CB9-4B68-A78D-DEE351CF9C38/content/root-image occlusionSourceFingerprint: >- ecf7386fd34424390c804e594c903e9b3f63b61a20b1c0f22609988524b8c37c contentId: root-image height: 171 occlusionBaseContentPath: >- /notes/D3085422-2CB9-4B68-A78D-DEE351CF9C38/content/root-image?layers=base kind: excerpt_image renderable: true - contentId: sub-1-blank noteid: B2C6E32F-323D-458B-994A-20206B73B730 truncated: false excerpt: false text: '' renderable: false kind: blank index: 1 - index: 1 noteid: 509CC486-1B22-4BD5-8CFF-FC0CC22FF72E excerpt: false mimeType: image/png width: 1120 contentPath: >- /notes/D3085422-2CB9-4B68-A78D-DEE351CF9C38/content/sub-1-blank-image topicid: B1F2A354-125A-4384-A271-C0B829AB9E09 source: blank contentId: sub-1-blank-image height: 292 kind: blank_image composite: true renderable: true - contentId: sub-2-text noteid: '' truncated: false excerpt: false text: 探针写入的批注。 renderable: false kind: text index: 2 hidden: false hashtagPaths: [] reference: sourceNoteId: 48FECCDA-BA29-477F-9B9D-B5B44D5FB051 isReference: true sourceNotebook: topicid: B1F2A354-125A-4384-A271-C0B829AB9E09 title: 'The Quiet Case for Walkable Streets #1' kind: card sourceAnchor: bookmd5: >- ec280b8dbd77594d16b090165fdd4c07ec280b8dbd77594d16b090165fdd4c07 hasExcerpt: true page: 1 noteid: D3085422-2CB9-4B68-A78D-DEE351CF9C38 texts: - noteid: D3085422-2CB9-4B68-A78D-DEE351CF9C38 text: 探针改过的正文。 kind: text excerpt: true index: 0 - noteid: B2C6E32F-323D-458B-994A-20206B73B730 text: '' kind: blank excerpt: false index: 1 - noteid: '' text: 探针写入的批注。 kind: text excerpt: false index: 2 commentsRevision: >- 326148b7724a7e333648e7002da8384280c8ac4af235ed47145d0b9bd3433d02 addonValues: mn.apiprobe: 'n': 3 probe: hello ok: true comments: - collapsed: false index: 1 ownerNoteId: 48FECCDA-BA29-477F-9B9D-B5B44D5FB051 type: LinkNote commentId: null text: '' - collapsed: false index: 2 ownerNoteId: 48FECCDA-BA29-477F-9B9D-B5B44D5FB051 type: TextNote commentId: null text: 探针写入的批注。 topicid: 449C1665-E0DD-4A20-9E67-2B0D451F746D folded: false hashtags: [] isSubMapRoot: false bridgeApiVersion: '0.91' x-codeSamples: - lang: javascript label: 获取卡片 source: | const got = await mn.api('/notes/batch-get', { method: 'POST', body: { noteIds: [noteid], addons: ['*'], comments: true } }); const item = got.items[0]; if (!item.found) { mn.log('该卡已不存在'); return; } // 判断是否为摘录卡看这两处，不要看 sourceAnchor.page const isExcerpt = (item.texts || []).some(t => t.excerpt) || (item.sourceAnchor || {}).hasExcerpt; components: schemas: BatchGetResponse: type: object properties: bridgeApiVersion: type: string description: 响应中的接口版本。 items: type: array items: $ref: '#/components/schemas/BatchGetItem' BatchGetItem: type: object description: 一张卡的读取结果。 properties: noteid: type: string found: type: boolean description: 为 `false` 表示该卡已不存在。 topicid: type: string description: 该卡所属的学习集。 kind: type: string isSubMapRoot: type: boolean description: 该卡是某张子脑图的根。 folded: type: boolean hidden: type: boolean hasInk: type: boolean description: 该卡上存着手写笔迹。 hasBlank: type: boolean description: 该卡下存有留白。 title: type: string description: 完整的显示标题，没有标题时是空串。 preview: type: string description: 显示标题，没有标题时取正文首段。超过 64 个 UTF-16 单位时以省略号结尾，省略号不计入上限。 texts: type: array description: | 卡片上的文本项。该数组是稀疏数组：没有文本的项不出现，但该项原来的位置仍然占号， 所以 `index` 可能不连续。序号 0 是卡片自身正文，从 1 起是各条子笔记。 items: $ref: '#/components/schemas/TextPart' parts: type: array description: 卡片上的二进制项，例如摘录图、插图、手写与音视频。 items: $ref: '#/components/schemas/PartItem' metadata: type: object properties: colorIndex: type: number fillIndex: type: number hashtags: type: array items: type: string hashtagPaths: type: array items: $ref: '#/components/schemas/HashtagPath' addonValues: type: object description: 各插件存在该卡上的字段。键是插件公开 id。只在请求里带 `addons` 时返回。 additionalProperties: true flashcard: type: boolean description: 该卡是一张复习卡。 evernoteid: type: string reference: type: object description: | 该卡与来源保持同步。取值是一个对象，判据在该对象的 `isReference` 上。较早的 MarginNote 在该项上直接给 `1` 与 `0`，因此按真值判断。 properties: isReference: type: - boolean - integer additionalProperties: true sourceAnchor: $ref: '#/components/schemas/SourceAnchor' commentsRevision: type: string description: '批注的版本号，请求里带 `comments: true` 时才给。' comments: type: array description: 批注清单，结构与 `GET /notes/{noteid}/comments` 相同。 items: $ref: '#/components/schemas/CommentItem' TextPart: type: object properties: index: type: number contentId: type: string text: type: string truncated: type: boolean description: 正文超出取回上限时被截断。 renderable: type: boolean excerpt: type: boolean description: 该项表示内容来自文档摘录。 noteid: type: string kind: type: string PartItem: type: object properties: contentId: type: string description: 用 `GET /notes/{noteid}/content/{contentId}` 取回原始内容。 index: type: number kind: type: string noteid: type: string excerpt: type: boolean text: type: string truncated: type: boolean description: 内容超出取回上限时被截断。 renderable: type: boolean contentPath: type: string mimeType: type: string ocrText: type: string field: type: string fieldLabel: type: string occlusion: type: object additionalProperties: true HashtagPath: type: object properties: hashtag: type: string description: 完整路径。 path: type: string name: type: string description: 该层的名字。 segments: type: array items: type: string depth: type: number ancestors: type: array items: type: string SourceAnchor: type: object description: 该卡内容的来源。 properties: hasExcerpt: type: boolean description: 该卡带来自文档摘录的内容。判断一张卡是否为摘录卡依据该字段，或依据 `texts[].excerpt`。 bookmd5: type: string page: type: - number - 'null' description: 页码。以块为单位导入的卡，该项恒为 `null`，因此不要将该字段当作摘录卡的判据。 CommentItem: type: object properties: index: type: number description: 序号，从 1 起。没有文字的条目也占号。 ownerNoteId: type: string commentId: type: - string - 'null' description: 较早的条目可能为 `null`。 collapsed: type: boolean type: type: string text: type: string field: type: string fieldLabel: type: string cardAnnotation: type: boolean description: 该批注是否带卡片批注标记。 annotationVersion: type: number reviewAnnotation: type: object additionalProperties: true createdAt: type: number practice: type: object additionalProperties: true ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.