POST/meta-paper-relations

meta-paper-relations 分页查论文引用关系

分页返回某篇论文的引用/被引/相关工作完整列表。

概述

citations / references / related_works 是无界关系数组（高被引文献可达数千条）。meta-search 出于响应体积考虑只内联截断少量条目，要翻完整列表用本接口。先用 meta-search 或 agentic-search 拿到目标论文 unique_id，再按 relation 分页。

适用场景

· 查某篇论文引用了哪些文献（relation=REFERENCES）
· 查哪些文献引用了某篇论文（relation=CITATIONS）
· 查与某篇论文主题相关的工作（relation=RELATED_WORKS）

不适用场景

· 不用于根据 doc_id 读取正文，请使用 content。
· 不用于语义检索相关论文片段，请使用 agentic-search。
· 不用于字段化论文列表筛选，请使用 meta-search。

鉴权

统一使用 API Key Bearer Token 鉴权，详见统一鉴权章节。在 HTTP Header 中加入：

Authorization: Bearer YOUR_API_TOKEN

请求示例

curl -X POST https://api.sciverse.space/meta-paper-relations \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"unique_id":"paper:10.1038/s41586-021-03819-2","relation":"CITATIONS","page":1,"page_size":25}'

请求体（JSON）

relation 三选一；CITATIONS（被引：谁引用了我）与 REFERENCES（参考文献：我引用了谁）方向相反。

字段	类型	必填	说明
unique_id	string	必填	目标论文 unique_id（如 paper:10.1038/xxx），来自 meta-search / agentic-search；勿传 doc_id。
relation	string	必填	关系类型：CITATIONS（被引）/ REFERENCES（参考文献）/ RELATED_WORKS（相关工作）。
page	integer	可选	页码。默认 1范围 ≥ 1
page_size	integer	可选	每页数量。默认 25范围 1–200

响应结构

字段	类型	说明
items	array<object>	关系条目列表，每条 { id, id_type, title }。
total_count	integer	关系总条数。
page	integer	当前页码。
page_size	integer	每页条数。
total_pages	integer	总页数。
code / message / biz_code	object	统一成功信封字段。

响应示例

{
  "items": [{"id": "10.1080/10400419.2011.571190", "id_type": "doi", "title": "Contesting ... Theory of Creativity"}],
  "total_count": 128,
  "page": 1,
  "page_size": 25,
  "total_pages": 6,
  "code": "SUCCESS",
  "message": "成功",
  "biz_code": 0
}

错误码

错误码	信息	说明
400	INVALID_ARGUMENT	参数错误：unique_id 为空或 relation 非法。
403	FORBIDDEN	无该关系字段（citations/references/related_works）的访问权限。
404	NOT_FOUND	unique_id 对应文档不存在。
429	RATE_LIMITED	触发限流，等窗口恢复后重试。
502	UPSTREAM_UNAVAILABLE	上游 metadata-service 不可用。

通用错误码请参考「错误码」章节。

重试建议

· 建议重试：502 / 503 / 504
· 不应重试：400 / 401 / 403 / 404
· 429 请等限流窗口恢复后重试

能力边界

· meta-paper-relations 使用 unique_id 查询引用、被引或相关工作，不接受 doc_id 作为主键。
· relation 仅支持 CITATIONS、REFERENCES、RELATED_WORKS。
· 高被引论文可能需要分页读取，page_size 应控制在公开限制内。
· 关系条目是论文关系数据，不等同于全文证据片段。

FAQ

unique_id 从哪里来？

通常先用 meta-search 定位论文，再读取返回的 unique_id 后调用 meta-paper-relations。

CITATIONS 和 REFERENCES 有什么区别？

CITATIONS 表示谁引用了目标论文；REFERENCES 表示目标论文引用了哪些文献。

可以用 doc_id 查询引用关系吗？

不可以。doc_id 用于 content 读取正文；引用关系接口需要 unique_id。