Local API 参考

语言版本： English

相关文档：总览 · 快速开始 · 插件开发指南

基础信息

协议：HTTP
默认地址：http://127.0.0.1:29467
API 前缀：/api/v1
数据格式：application/json; charset=utf-8
API 支持方法：GET、POST、PUT、OPTIONS
写入能力：可选，默认因 Read-Only Mode 处于开启状态而关闭；只有在 Settings → Local API 中关闭 Read-Only Mode 后才可用。PUT /api/v1/papers/{uuid}/pdf 还要求 /status.capabilities 中包含 pdf-upload
插件静态资源托管位于 /plugins/{name}/...，不属于 /api/v1

通用约定

成功响应

正常业务端点返回 200 OK
创建文献成功时返回 201 Created
预检请求返回 204 No Content

错误响应

大多数错误响应至少包含：

{
  "error": "错误说明"
}

有些错误响应会额外携带字段：

{
  "error": "Duplicate paper found",
  "existingPaperID": "550E8400-E29B-41D4-A716-446655440000"
}

{
  "error": "Library limit reached",
  "currentCount": 50,
  "limit": 50
}

常见状态码

状态码	含义	常见原因
`200`	成功	请求正常完成
`201`	已创建	`POST /api/v1/papers` 成功创建文献，或 `PUT /api/v1/papers/{uuid}/pdf` 成功上传字节
`204`	无内容	`OPTIONS` 预检
`400`	参数错误	请求格式错误、JSON 非法、标题为空、`paperType` 非法、`strategy` 非法、metadata 查询参数缺失，或 PDF 请求形状不合法
`403`	禁止访问	非本机请求、来源不被允许，或公开写接口仍处于只读
`404`	未找到	端点不存在，或文献 / metadata 结果 / 插件资源不存在
`405`	方法不允许	使用了 `PATCH`、`DELETE` 等不支持的方法，或当前路径不支持该方法组合
`409`	冲突	创建文献时检测到重复项，或上传 PDF 时已有附件且未强制覆盖检查
`422`	无法处理	免费版文献数量已达到上限
`413`	负载过大	请求体超过允许大小
`503`	服务不可用	请求了 PDF 上传，但当前没有可用的上传落盘目标
`500`	服务器错误	Lattice 内部处理失败

能力发现

调用 GET /api/v1/status 后再决定是否依赖可选能力。

尤其是：

只有当 capabilities 中包含 create-paper 时，才应尝试 POST /api/v1/papers
把 create-paper-v2 视为支持重复策略与富创建/替换响应的信号
把 pdf-upload 视为 PUT /api/v1/papers/{uuid}/pdf 是否可用的准确信号
不要假设所有用户都已经开启写入权限

字段-方法矩阵

这一节就是为了快速回答两个问题：

一共有哪些字段
每个字段分别在哪个 HTTP 方法里出现或被接受

状态与能力字段

字段	`GET /status` 响应	说明
`ok`	`ok`	健康状态标记
`apiVersion`	`apiVersion`	Local API 版本字符串
`appVersion`	`appVersion`	Lattice 应用版本字符串
`capabilities[]`	`capabilities[]`	当前实例的能力列表
`readOnly`	`readOnly`	当前公开 `/api/v1` 写接口是否仍处于只读
`baseURL`	`baseURL`	当前 localhost 基地址
`browserExtensionEnabled`	`browserExtensionEnabled`	反映设置页中的 Browser Extension 开关

搜索字段

字段	`GET /search` 查询参数	`GET /search` 响应	说明
`q`	`q`	—	搜索词；空字符串时返回最近加入的文献
`limit`	`limit`	—	会被夹到 `1...50`；无法解析时回退为 `10`
`papers[]`	—	`papers[]`	顶层结果数组
`id`	—	`papers[].id`	搜索命中的文献 UUID
`title`	—	`papers[].title`	搜索命中的展示标题
`authorsDisplay`	—	`papers[].authorsDisplay`	仅搜索结果里提供的作者摘要
`subtitle`	—	`papers[].subtitle`	仅搜索结果里提供的次级摘要
`year`	—	`papers[].year`	搜索命中的年份
`citekey`	—	`papers[].citekey`	搜索命中的引用键
`paperType`	—	`papers[].paperType`	搜索命中的文献类型

metadata 查询字段

字段	`GET /metadata` 查询参数	`GET /metadata` 响应	说明
`doi`	`doi`	`doi`	`doi`、`arxivId`、`isbn`、`title` 至少要提供一个
`arxivId`	`arxivId`	—	仅作为查询输入
`isbn`	`isbn`	`isbn`	既可作为输入，也可能作为输出
`title`	`title`	`title`	既可作为输入，也可能作为输出
`authors`	—	`authors`	以分号分隔的作者字符串
`year`	—	`year`	解析出的年份
`journal`	—	`journal`	解析出的来源 / venue
`abstract`	—	`abstract`	解析出的摘要
`volume`	—	`volume`	解析出的卷号
`issue`	—	`issue`	解析出的期号
`pages`	—	`pages`	解析出的页码
`paperType`	—	`paperType`	可用时返回解析出的文献类型

文献集目录字段

字段	`GET /collections` 响应	说明
`id`	`[].id`	文献集 UUID
`name`	`[].name`	当前层级的文献集名称
`path`	`[].path`	完整的斜杠分隔文献集路径
`depth`	`[].depth`	可用于 UI 缩进的层级深度

标签目录字段

字段	`GET /tags` 响应	说明
`id`	`[].id`	标签 UUID
`name`	`[].name`	标签展示名
`colorHex`	`[].colorHex`	可选颜色值

核心文献字段

字段	`GET /papers/{uuid}` 响应	`GET /metadata` 响应	`POST /papers` 请求	`POST /papers` 响应	说明
`id`	`id`	—	—	`id`	稳定文献 UUID；也可据此拼出 `lattice://paper/{id}`
`citekey`	`citekey`	—	—	—	只读引用键
`title`	`title`	`title`	`title`	`title`	读写流程都会出现
`authors`	`authors[]`	`authors`	`authors`	`authors`	详情接口是 `string[]`；metadata 查询和写入请求/响应是分号分隔字符串
`year`	`year`	`year`	`year`	`year`	共享核心字段
`journal`	`journal`	`journal`	`journal`	—	创建时可传；详情和 metadata 查询会返回；创建响应不回显
`abstract`	—	`abstract`	`abstract`	—	创建时可写入，metadata 查询可返回，但详情接口当前不暴露
`doi`	`doi`	`doi`	`doi`	`doi`	共享核心标识符
`volume`	`volume`	`volume`	`volume`	—	创建时可传；详情和 metadata 查询会返回
`issue`	`issue`	`issue`	`issue`	—	创建时可传；详情和 metadata 查询会返回
`pages`	`pages`	`pages`	`pages`	—	创建时可传；详情和 metadata 查询会返回
`isbn`	`isbn`	`isbn`	`isbn`	—	创建时可传；详情和 metadata 查询会返回
`paperType`	`paperType`	`paperType`	`paperType`	—	创建时可传；详情、metadata 查询与搜索结果会返回
`pdfPath`	—	—	`pdfPath`	—	只写输入字段，用于创建时按路径尝试附加 PDF
`collections`	—	—	`collections[]`	—	只写输入字段，按大小写不敏感方式匹配文献集路径
`tags`	—	—	`tags[]`	—	只写输入字段，标签名数组
`enrich`	—	—	`enrich`	—	只写输入字段，后台补全开关
`strategy`	—	—	`strategy`	—	创建时的重复策略：`"skip"` 或 `"replace"`
`pdfAttached`	—	—	—	`pdfAttached`	操作结束后该文献是否带有 PDF
`enrichmentStatus`	—	—	—	`enrichmentStatus`	只在创建/替换响应里返回，值为 `pending` 或 `none`
`warnings`	—	—	—	`warnings[]`	只在创建/替换响应里返回，表示非致命 warning
`alreadyExists`	—	—	—	`alreadyExists`	新建时为 `false`；`strategy: "replace"` 更新已有文献时为 `true`
`conflict`	—	—	—	`conflict`	替换成功时返回的冲突摘要对象
`cslItem`	`cslItem`	—	—	—	只读 CSL 对象

PDF 上传字段

字段	`PUT /papers/{uuid}/pdf` 请求	`PUT /papers/{uuid}/pdf` 响应	说明
`uuid`	路径段	—	目标文献 UUID
`Content-Type`	`application/pdf`	—	必填
请求体	原始 PDF 字节	—	必须以 `%PDF-` 开头
`force`	`force=true` 查询参数	—	可选；用于跳过“已有 PDF”冲突检查
`reason`	—	`reason`	当前成功响应形如 `{ "reason": "uploaded" }`

CSL 子字段

字段	`GET /papers/{uuid}` 响应	说明
`cslItem.id`	`cslItem.id`	与顶层 `id` 相同的 UUID
`cslItem.type`	`cslItem.type`	CSL item type
`cslItem.title`	`cslItem.title`	CSL 标题
`cslItem.author[]`	`cslItem.author[]`	CSL 作者数组
`cslItem.author[].family`	`cslItem.author[].family`	名字可拆分时的姓
`cslItem.author[].given`	`cslItem.author[].given`	名字可拆分时的名
`cslItem.author[].literal`	`cslItem.author[].literal`	单名、机构名或无法拆分时的字面值
`cslItem.container-title`	`cslItem.container-title`	非书籍类文献的容器标题
`cslItem.publisher`	`cslItem.publisher`	书籍类文献的出版社字段
`cslItem.issued.date-parts`	`cslItem.issued.date-parts`	当前格式为 `[[YYYY]]`
`cslItem.DOI`	`cslItem.DOI`	CSL DOI
`cslItem.volume`	`cslItem.volume`	CSL 卷号
`cslItem.issue`	`cslItem.issue`	CSL 期号
`cslItem.page`	`cslItem.page`	CSL 页码
`cslItem.ISBN`	`cslItem.ISBN`	CSL ISBN

当前读接口不会暴露的字段

下面这些字段目前不会出现在 GET /search 或 GET /papers/{uuid} 中：

abstract
collections
tags
notes
pdfPath
pdfURL
latticeURL

`GET /status`

用于检查服务是否在线，以及当前实例支持哪些功能。

请求

GET /api/v1/status

响应字段

字段	类型	说明
`ok`	`boolean`	服务健康标记，正常情况下为 `true`
`apiVersion`	`string`	当前 Local API 版本
`appVersion`	`string`	Lattice 应用版本
`capabilities`	`string[]`	支持的功能列表
`readOnly`	`boolean`	当前公开 `/api/v1` 写接口是否仍处于只读
`baseURL`	`string`	当前 localhost 基地址
`browserExtensionEnabled`	`boolean`	反映设置页中的 Browser Extension 开关

当前能力值

capability	说明
`search`	支持文献搜索
`paper-detail`	支持按文献 ID 拉取详情
`csl-item`	详情中包含可直接用于引用引擎的 CSL-JSON
`create-paper-v2`	创建接口支持重复策略以及更丰富的创建/替换响应
`create-paper`	当前实例已开启 `POST /api/v1/papers` 写入能力
`pdf-upload`	当前实例已开放 `PUT /api/v1/papers/{uuid}/pdf`
`plugin-hosting`	支持托管本地插件静态资源

示例

{
  "ok": true,
  "apiVersion": "1",
  "appVersion": "1.2.3 (456)",
  "readOnly": false,
  "baseURL": "http://127.0.0.1:29467",
  "browserExtensionEnabled": true,
  "capabilities": [
    "search",
    "paper-detail",
    "csl-item",
    "plugin-hosting",
    "create-paper",
    "create-paper-v2",
    "pdf-upload"
  ]
}

`GET /search`

搜索 Lattice 文献库，返回轻量结果列表，适合做搜索建议、结果卡片、选择器等 UI。

请求

GET /api/v1/search?q=<query>&limit=<n>

查询参数

参数	必填	类型	默认值	说明
`q`	否	`string`	空字符串	搜索词；为空时返回最近加入的文献
`limit`	否	`integer`	`10`	期望返回条数；可解析的整数会被夹到 `1...50`，无法解析时回退为 `10`

匹配范围

搜索面向外部使用时可以理解为匹配以下字段：

标题
作者
期刊 / 出版源
citekey
年份

响应结构

{
  "papers": [
    {
      "id": "550E8400-E29B-41D4-A716-446655440000",
      "title": "Attention Is All You Need",
      "authorsDisplay": "Ashish Vaswani, Noam Shazeer, Niki Parmar, ...",
      "subtitle": "Ashish Vaswani, Noam Shazeer, Niki Parmar, ... • 2017 • NeurIPS",
      "year": 2017,
      "citekey": "vaswani2017attention",
      "paperType": "inproceedings"
    }
  ]
}

`papers[]` 字段说明

字段	类型	说明
`id`	`string`	文献 UUID
`title`	`string`	用于展示的标题；空标题会以 `Untitled` 返回
`authorsDisplay`	`string`	适合直接显示在列表中的作者文本
`subtitle`	`string`	次级摘要文本，通常由作者、年份、来源组合而成
`year`	`integer \| null`	发表年份
`citekey`	`string`	推荐引用键；若未显式保存，会返回可用的自动生成键
`paperType`	`string`	文献类型

`paperType` 可能值

article
book
inproceedings
thesis
report
misc

示例

curl "http://127.0.0.1:29467/api/v1/search?q=transformer&limit=5"

`GET /papers/{uuid}`

读取单篇文献的详细引用元数据。

请求

GET /api/v1/papers/{uuid}

路径参数

参数	类型	说明
`uuid`	`string`	文献 UUID。如果路径段不是合法 UUID，请求会直接落到 `404 Not Found`

响应结构

{
  "id": "550E8400-E29B-41D4-A716-446655440000",
  "citekey": "vaswani2017attention",
  "title": "Attention Is All You Need",
  "authors": [
    "Ashish Vaswani",
    "Noam Shazeer"
  ],
  "year": 2017,
  "journal": "NeurIPS",
  "doi": "10.5555/example-doi",
  "volume": "30",
  "issue": null,
  "pages": "5998-6008",
  "isbn": null,
  "paperType": "inproceedings",
  "cslItem": {
    "id": "550E8400-E29B-41D4-A716-446655440000",
    "type": "paper-conference",
    "title": "Attention Is All You Need",
    "author": [
      {
        "family": "Vaswani",
        "given": "Ashish"
      },
      {
        "family": "Shazeer",
        "given": "Noam"
      }
    ],
    "container-title": "NeurIPS",
    "publisher": null,
    "issued": {
      "date-parts": [[2017]]
    },
    "DOI": "10.5555/example-doi",
    "volume": "30",
    "issue": null,
    "page": "5998-6008",
    "ISBN": null
  }
}

顶层字段说明

字段	类型	说明
`id`	`string`	文献 UUID
`citekey`	`string`	推荐引用键
`title`	`string`	标题
`authors`	`string[]`	作者字符串数组
`year`	`integer \| null`	年份
`journal`	`string \| null`	期刊、会议、出版社等来源文本
`doi`	`string \| null`	DOI
`volume`	`string \| null`	卷号
`issue`	`string \| null`	期号
`pages`	`string \| null`	页码范围
`isbn`	`string \| null`	ISBN
`paperType`	`string`	文献类型
`cslItem`	`object`	可直接交给 CSL 引用处理器的对象

`cslItem` 字段说明

字段	类型	说明
`id`	`string`	与文献 ID 一致
`type`	`string`	CSL 文献类型
`title`	`string`	标题
`author`	`object[]`	作者数组，元素为 `family/given/literal` 结构
`container-title`	`string \| null`	期刊、会议等容器标题
`publisher`	`string \| null`	出版社；书籍类文献常用
`issued`	`object \| null`	日期对象，格式为 `{"date-parts": [[YYYY]]}`
`DOI`	`string \| null`	DOI
`volume`	`string \| null`	卷号
`issue`	`string \| null`	期号
`page`	`string \| null`	页码
`ISBN`	`string \| null`	ISBN

`cslItem.author[]` 字段说明

字段	类型	说明
`family`	`string \| null`	可拆分时的姓
`given`	`string \| null`	可拆分时的名
`literal`	`string \| null`	无法拆分、单名或机构名时使用的字面值

`cslItem.issued` 字段说明

字段	类型	说明
`date-parts`	`integer[][]`	当前格式为 `[[YYYY]]`

`paperType` 到 `cslItem.type` 的对应关系

`paperType`	`cslItem.type`
`article`	`article-journal`
`book`	`book`
`inproceedings`	`paper-conference`
`thesis`	`thesis`
`report`	`report`
`misc`	`article`

当前不会返回的字段

GET /api/v1/papers/{uuid} 面向引用场景，当前不会暴露：

abstract
collections
tags
notes
pdfPath
pdfURL
latticeURL

深度链接说明

如果你的集成只是想在 Lattice 中打开这篇文献，可以直接根据返回的 id 自行拼出：

lattice://paper/{id}

当前 Local API 不会返回专门的 latticeURL 字段，也不会暴露本地 PDF 文件路径。

典型用法

引文插入前拉取完整快照
构建 citeproc/csl 引擎输入
在外部工具里展示引用详情卡片
在本地插件中维护文献缓存

`GET /collections`

返回写入型客户端可分配的文献集列表。

请求

GET /api/v1/collections

响应结构

[
  {
    "id": "550E8400-E29B-41D4-A716-446655440000",
    "name": "Transformers",
    "path": "Deep Learning/Transformers",
    "depth": 1
  }
]

行为说明

响应顶层是 JSON 数组，不是对象包裹
文献集按 path 做本地化、大小写不敏感排序
对 POST /api/v1/papers 来说，真正的写入标识符是 path

`GET /tags`

返回写入型客户端可分配的标签列表。

请求

GET /api/v1/tags

响应结构

[
  {
    "id": "550E8400-E29B-41D4-A716-446655440000",
    "name": "foundational",
    "colorHex": "#FF9500"
  }
]

行为说明

响应顶层是 JSON 数组，不是对象包裹
标签先按存储的 sortOrder 排序，再按名称排序
对 POST /api/v1/papers 来说，真正的写入标识符是 name

`GET /metadata`

根据轻量标识符查询引文元数据。

请求

GET /api/v1/metadata?doi=<doi>
GET /api/v1/metadata?arxivId=<id>
GET /api/v1/metadata?isbn=<isbn>
GET /api/v1/metadata?title=<title>

查询参数

参数	必填	类型	说明
`doi`	条件必填	`string`	DOI 查询输入
`arxivId`	条件必填	`string`	arXiv ID 查询输入
`isbn`	条件必填	`string`	ISBN 查询输入
`title`	条件必填	`string`	标题查询输入

以上参数中至少需要提供一个非空值。

响应结构

{
  "title": "Attention Is All You Need",
  "authors": "Ashish Vaswani; Noam Shazeer; Niki Parmar",
  "year": 2017,
  "journal": "NeurIPS",
  "abstract": "The dominant sequence transduction models are based on...",
  "doi": "10.48550/arXiv.1706.03762",
  "volume": "30",
  "issue": null,
  "pages": "5998-6008",
  "isbn": null,
  "paperType": "inproceedings"
}

错误响应

状态码	典型响应	含义
`400`	`{"error":"Provide at least one of doi, arxivId, isbn, or title."}`	没有提供任何查询键
`404`	`{"error":"Not found"}`	没有解析到元数据
`500`	`{"error":"Internal server error"}`	编码或服务端处理发生未预期错误

典型用法

仅凭 DOI、arXiv ID、ISBN 或标题先预填创建表单
在用户真正写入前，先对宿主应用中的轻量结果做元数据补全
在决定跳过重复还是替换已有文献前，先解析出更完整的标题 / 作者信息

`POST /papers`

创建一篇新文献。

可用条件

端点路径为 POST /api/v1/papers
仅限 localhost 调用
只有当 /status.capabilities 中包含 create-paper 时才可用
如果写入权限未开启，会返回 403

请求体

{
  "title": "Attention Is All You Need",
  "authors": "Vaswani, Ashish; Shazeer, Noam; Parmar, Niki",
  "year": 2017,
  "journal": "NeurIPS",
  "abstract": "The dominant sequence transduction models are based on...",
  "doi": "10.48550/arXiv.1706.03762",
  "volume": "30",
  "issue": null,
  "pages": "5998-6008",
  "isbn": "9780306406157",
  "paperType": "inproceedings",
  "pdfPath": "/Users/me/Papers/attention.pdf",
  "collections": ["Deep Learning/Transformers"],
  "tags": ["foundational", "NLP"],
  "strategy": "skip",
  "enrich": true
}

请求字段说明

字段	必填	类型	默认值	说明
`title`	是	`string`	无	文献标题。会先做首尾空白裁剪；空字符串或纯空白会被拒绝
`authors`	否	`string \| null`	`null`	作者列表，使用单个字符串并以分号分隔，例如 `"Einstein, Albert; Bohr, Niels"`
`year`	否	`integer \| null`	`null`	年份
`journal`	否	`string \| null`	`null`	期刊、会议、出版社或其他来源文本
`abstract`	否	`string \| null`	`null`	摘要。会存入文献，但当前读接口不会返回这个字段
`doi`	否	`string \| null`	`null`	DOI。保存前会把 DOI URL 清理成规范 DOI 形式
`volume`	否	`string \| null`	`null`	卷号
`issue`	否	`string \| null`	`null`	期号
`pages`	否	`string \| null`	`null`	页码范围
`isbn`	否	`string \| null`	`null`	ISBN。保存前会清理并校验，无效值会被丢弃
`paperType`	否	`string \| null`	`"misc"`	文献类型，大小写不敏感；非空但非法的值会返回 `400`
`pdfPath`	否	`string \| null`	`null`	要附加的本地 PDF 路径。文件必须存在、必须是 PDF，并且位于某个 Trusted Folder 或其子目录内。这是只写输入字段，不会被 `GET /papers/{uuid}` 回显
`collections`	否	`string[] \| null`	`[]`	需要分配到的文献集路径数组，例如 `"AI/Transformers"`；匹配时大小写不敏感
`tags`	否	`string[] \| null`	`[]`	需要附加的标签名数组。已有标签会复用，不存在时会自动创建
`strategy`	否	`string \| null`	`"skip"`	重复处理策略。`"skip"` 在重复时返回 `409`；`"replace"` 会更新已有文献并返回成功响应
`enrich`	否	`boolean \| null`	`false`	若为 `true`，且创建出的文献已有 DOI 或成功附加 PDF，则加入后台元数据补全队列

请求限制

title：最多 1024 个 UTF-8 字节
abstract：最多 65536 个 UTF-8 字节
authors：最多 16384 个 UTF-8 字节
collections：最多 100 项
tags：最多 100 项
每个 collections[i] 和 tags[i]：最多 256 个 UTF-8 字节

`paperType` 可选值

article
book
inproceedings
thesis
report
misc

成功响应

状态码：201 Created

{
  "id": "550E8400-E29B-41D4-A716-446655440000",
  "title": "Attention Is All You Need",
  "authors": "Vaswani, Ashish; Shazeer, Noam; Parmar, Niki",
  "year": 2017,
  "doi": "10.48550/arXiv.1706.03762",
  "pdfAttached": true,
  "enrichmentStatus": "pending",
  "warnings": ["Collection not found: Deep Learning/Missing"],
  "alreadyExists": false,
  "conflict": null
}

如果 strategy: "replace" 更新了已有文献，状态码会变成 200 OK，同时 alreadyExists 为 true。

成功响应字段说明

字段	类型	说明
`id`	`string`	新创建文献的 UUID
`title`	`string`	保存后的展示标题
`authors`	`string \| null`	保存后的作者字符串，使用 `"; "` 连接
`year`	`integer \| null`	保存后的年份
`doi`	`string \| null`	清理后的 DOI
`pdfAttached`	`boolean`	操作结束后该文献是否带有 PDF
`enrichmentStatus`	`string`	若已入队后台补全则为 `"pending"`，否则为 `"none"`
`warnings`	`string[]`	非致命警告，例如文献集未找到或 PDF 附件失败
`alreadyExists`	`boolean`	新建时为 `false`；`strategy: "replace"` 更新已有文献时为 `true`
`conflict`	`object \| null`	替换成功时返回的冲突摘要对象

错误响应

状态码	典型响应	含义
`400`	`{"error":"Malformed JSON"}`	JSON 请求体格式错误
`400`	`{"error":"Title is required and must not be empty"}`	标题缺失或为空白
`400`	`{"error":"Invalid paperType"}`	`paperType` 取值不支持
`400`	`{"error":"Invalid strategy"}`	`strategy` 取值不支持
`403`	`{"error":"API is in read-only mode"}`	`Read-Only Mode` 仍然开启
`404`	`{"error":"Not found"}`	请求路径不是 `/api/v1/papers`
`409`	`{"error":"Duplicate paper found","existingPaperID":"uuid","existingTitle":"...","conflictField":"doi","latticeURL":"lattice://paper/..."}`	当 `strategy` 最终为 `"skip"` 时，检测到 DOI 或规范化标题重复
`422`	`{"error":"Library limit reached","currentCount":50,"limit":50}`	免费版文献数量已到上限
`500`	`{"error":"Failed to save"}`	保存时发生未预期错误

行为说明

重复检测先看 DOI，再看规范化后的标题
strategy 默认值是 "skip"
"replace" 只覆盖本次请求里实际提供的字段；省略的可选字段会保留已有值
collections 会按大小写不敏感方式匹配已有文献集路径；未找到只会产生 warning，不会自动创建
tags 按规范化名称匹配；不存在时会自动创建
pdfPath 必须存在、必须是 PDF，并且位于某个 Trusted Folder 或其子目录内；失败时只会写 warning，不会阻止文献创建
如果 pdfPath 不在任何 Trusted Folder 内，warning 文案固定为：PDF path is not inside a Trusted Folder. Add the enclosing folder in Settings > Local API > Trusted Folders, or attach the PDF manually in Lattice.
Lattice 不会复制 PDF 文件本体，而是保存 security-scoped bookmark
enrich: true 只有在创建出的文献已有 DOI 或成功附加 PDF 时才会真正入队后台补全
创建完成后再调用 GET /api/v1/papers/{uuid}，仍然只会拿到 citation-oriented 读负载，而不是所有写入字段的完整回显

最小示例

curl -X POST http://127.0.0.1:29467/api/v1/papers \
  -H "Content-Type: application/json" \
  -d '{"title":"A Brief History of Time"}'

`PUT /papers/{uuid}/pdf`

向已有文献上传原始 PDF 字节。

可用条件

端点路径为 PUT /api/v1/papers/{uuid}/pdf
仅限 localhost 调用
/status.capabilities 中的 pdf-upload 是这个端点是否可用的准确信号
如果写入权限未开启，会返回 403

请求

PUT /api/v1/papers/{uuid}/pdf
Content-Type: application/pdf

请求体：原始 PDF 字节。

可选查询参数：

参数	必填	类型	默认值	说明
`force`	否	`boolean`	`false`	为 `true` 时跳过“已有 PDF”冲突检查

成功响应

状态码：201 Created

{
  "reason": "uploaded"
}

错误响应

状态码	典型响应	含义
`400`	`{"error":"Content-Type must be application/pdf"}`	Content-Type 缺失或不正确
`400`	`{"error":"Invalid PDF payload"}`	请求体看起来不是 PDF
`403`	`{"error":"API is in read-only mode"}`	`Read-Only Mode` 仍然开启
`404`	`{"error":"Not found"}`	目标文献或路径不存在
`409`	`{"error":"PDF already attached"}`	该文献已有 PDF，且没有传 `force=true`
`413`	`{"error":"Payload too large"}`	PDF 请求体超过上传上限
`503`	`{"reason":"not-configured"}`	当前没有可用的 PDF 上传落盘目标
`500`	`{"error":"..."}`	上传时发生未预期错误

行为说明

请求体必须是原始字节，且需要以 %PDF- 开头
这条路由当前的上传上限是 200000000 字节
上传成功后会更新文献的 PDF bookmark，并可能触发后台 refresh

`GET /plugins/{name}/...`

托管本地插件的静态文件。

特点

端点前缀：/plugins/
用途：托管插件和加载项前端静态资源
不属于 /api/v1
静态文件来自 Lattice 沙盒 Application Support 下的插件目录
会拦截路径穿越尝试

常见支持的静态资源类型

.html
.js
.css
.json
.png
.svg
.xml
.csl

`OPTIONS`

为了支持浏览器场景下的预检请求，Local API 也接受 OPTIONS。

特点

返回 204 No Content
对允许的来源返回 CORS 相关头
不返回业务内容

如果你的页面也是通过 Lattice 的 /plugins/{name}/... 托管的，通常不需要额外处理这部分。

CORS 与来源限制

Local API 默认面向本地来源：

http://localhost:*
https://localhost:*
http://127.0.0.1:*
https://127.0.0.1:*

这也是为什么推荐把插件页面直接放在 /plugins/{name}/... 下的原因：最简单、最稳。

进阶说明：

服务器允许的 CORS 方法是 GET, POST, PUT, OPTIONS
如需高级集成，可通过 citationBridgeAllowedOrigins 的 user-defaults 覆盖项扩展允许来源

错误示例

非法文献路径段

curl http://127.0.0.1:29467/api/v1/papers/not-a-uuid

{
  "error": "Not found"
}

metadata 查询键缺失

curl http://127.0.0.1:29467/api/v1/metadata

{
  "error": "Provide at least one of doi, arxivId, isbn, or title."
}

端点不存在

{
  "error": "Not found"
}

请求大小限制

大多数路由的 HTTP 请求总大小上限为 262144 字节（256 KiB），包含 headers 和 body。

PUT /api/v1/papers/{uuid}/pdf 这条路由的 PDF 请求体上限更大，为 200000000 字节。

FilesExpand file tree

接口参考.md

Latest commit

History

接口参考.md

File metadata and controls

Local API 参考

基础信息

通用约定

成功响应

错误响应

常见状态码

能力发现

字段-方法矩阵

状态与能力字段

搜索字段

metadata 查询字段

文献集目录字段

标签目录字段

核心文献字段

PDF 上传字段

CSL 子字段

当前读接口不会暴露的字段

GET /status

请求

响应字段

当前能力值

示例

GET /search

请求

查询参数

匹配范围

响应结构

papers[] 字段说明

paperType 可能值

示例

GET /papers/{uuid}

请求

路径参数

响应结构

顶层字段说明

cslItem 字段说明

cslItem.author[] 字段说明

cslItem.issued 字段说明

paperType 到 cslItem.type 的对应关系

当前不会返回的字段

深度链接说明

典型用法

GET /collections

请求

响应结构

行为说明

GET /tags

请求

响应结构

行为说明

GET /metadata

请求

查询参数

响应结构

错误响应

典型用法

POST /papers

可用条件

请求体

请求字段说明

请求限制

paperType 可选值

成功响应

成功响应字段说明

错误响应

行为说明

最小示例

PUT /papers/{uuid}/pdf

可用条件

请求

成功响应

错误响应

行为说明

GET /plugins/{name}/...

`GET /status`

`GET /search`

`papers[]` 字段说明

`paperType` 可能值

`GET /papers/{uuid}`

`cslItem` 字段说明

`cslItem.author[]` 字段说明

`cslItem.issued` 字段说明

`paperType` 到 `cslItem.type` 的对应关系

`GET /collections`

`GET /tags`

`GET /metadata`

`POST /papers`

`paperType` 可选值

`PUT /papers/{uuid}/pdf`

`GET /plugins/{name}/...`

`OPTIONS`