API 参考
API 参考
CiteArk REST API 的通用行为、状态码与端点总览。
CiteArk 的所有接口均以 JSON 交互,base URL 为 https://citeark.com。公开读取无需鉴权;提交论文、发起复现等写操作可以使用浏览器会话,或通过 x-api-key 请求头发送 API Key,详见 鉴权。
新的机器客户端应使用 /api/v1 下版本化、紧凑的 Agent API。机器契约发布在 /openapi.json，错误采用结构化的 { "error": { "code", "message" } }。本节记录的无版本接口继续用于兼容与浏览器工作流。
curl https://citeark.com/api/repositories \
-H "x-api-key: $CITEARK_API_KEY"通用行为
/api/v1错误采用{"error":{"code":"…","message":"…"}}；兼容接口仍为{"error":"信息"}。- 超出速率限制或月度额度时返回
429,且一定携带Retry-After响应头。速率限制相关头为X-RateLimit-*,月度额度相关头为X-Quota-*,二者相互独立,详见 限流与额度。 - 请求体超过 26 MB 会被拒绝,返回
413(论文 PDF 本身的限制为 25 MB,余量留给 multipart 边界与字段)。
状态码
| 状态码 | 含义 |
|---|---|
| 200 | 成功 |
| 201 | 已创建 |
| 202 | 已接受(异步执行) |
| 304 | 内容未变(ETag) |
| 400 | 请求无效 |
| 401 | 未登录或 Key 无效 |
| 403 | 权限不足 |
| 404 | 不存在 |
| 409 | 冲突(如论文已存在) |
| 413 | 请求体过大 |
| 422 | 无法处理 |
| 429 | 超出限流或额度 |
| 451 | 许可不允许重新分发 |
| 502 | 上游或完整性校验失败 |
| 503 | 服务降级 |
端点总览
研究仓库
GET /api/repositories 列表与快照、POST /api/repositories 提交论文。
发起复现
POST /api/runs 针对 Claim 发起受控验证。
证据与签名
GET /api/objects/{digest} 下载证据对象,GET /api/attestations/{digest} 验证签名。
Fork
POST /api/forks 复制研究仓库到自己的命名空间。
互动
加星、求复现与关注。
arXiv 查询
查询 arXiv 论文元数据。
处理状态
轮询论文提交后的处理流水线状态。
徽章与嵌入
GET /api/badge/{owner}/{slug} 实时签发的 SVG 徽章与等级口径。
健康检查
GET /api/health 服务运行状态。
备注
- Agent API 固定在
/api/v1；旧版浏览器与兼容接口保留在/api。 - 自托管部署若配置了
CITEARK_BACKEND_ORIGIN,前端会把 API 请求原样代理到该后端。