30 秒跑通

1 · 搜索公开研究

公开读取无需密钥：

curl "https://citeark.com/api/v1/search?q=language+model&limit=5"

从响应中选择一个 repository.id。即使仓库 URL 的 slug 发生变化，ID 仍保持稳定。

2 · 只读取所需结论

curl "https://citeark.com/api/v1/claims?repository_id=<repository-id>&limit=20"

当 hasMore 为真时跟随 pagination.nextCursor。每条计量会分别给出 measurementId、指标名、实验维度、论文报告值、实测值、验证状态与证据 ID。

3 · 为写操作创建 API Key

登录后在账户设置的 Agent API Key 页面创建一个 Key。Key 只在创建时显示一次，默认 90 天过期；调用写接口时放入 x-api-key 请求头。只读取公开数据可以跳过这一步。

export CITEARK_API_KEY="citeark_…"

4 · 发起第一次复现（写接口）

写接口必须携带 x-api-key 请求头。下面针对某个 Claim 发起一次受控复现（repositoryId 与 claimId 取自第 2 步的快照）：

curl -X POST "https://citeark.com/api/v1/runs" \
  -H "x-api-key: $CITEARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"repositoryId": "…", "claimId": "…"}'

成功返回 202 与 run 记录。只有成功进入队列的运行才会扣减月度复现额度，创建失败会自动返还。

5 · 限流与额度（看懂 429）

限制分两层，超出都会收到 429，调用方应按响应头退避：

• 速率限制（防冲击）：每把 API Key 默认 120 次/分钟；发起复现另有 10 次/小时/账号。响应头带 Retry-After（秒）与 X-RateLimit-Limit，等待 Retry-After 后重试即可。
• 月度额度（管资源）：每个账号每月 10 次复现，浏览器会话与所有 Key 共用。耗尽时响应头带 X-Quota-Limit、X-Quota-Used 和 X-Quota-Reset（额度重置时间，UTC），Retry-After 指向重置时间。

每把 Key 的最近使用时间与当月剩余额度可在 Agent API Key 页面查看。

下一步可阅读完整 Agent API、连接 MCP，或直接加载 OpenAPI 契约。