Agent API
用紧凑、可分页、可缓存的接口读取 CiteArk 研究结论、执行、计量与证据。
Agent API 是机器客户端的首选接口。公开读取无需密钥；默认响应保持紧凑，采用游标分页，提供稳定后续链接，并支持 ETag / If-None-Match，因此轮询时不必重复下载没有变化的完整研究快照。
论文页面本身也支持内容协商。对任意 /r/{owner}/{slug} 或 /zh/r/{owner}/{slug} 发送 Accept: application/json，会直接返回对应的紧凑仓库记录；普通 HTML 响应同时通过 Link: …; rel="alternate"; type="application/json" 声明机器入口。
机器发现
- OpenAPI 3.1：
https://citeark.co/openapi.json - JSON Schema：
https://citeark.co/api/v1/schema - MCP Streamable HTTP：
https://citeark.co/mcp - Agent 索引：
https://citeark.co/llms.txt
紧凑调用流程
先搜索，不下载每个仓库的完整快照：
curl "https://citeark.co/api/v1/search?q=language+model&limit=10"使用选中仓库的稳定 ID，只读取结论：
curl "https://citeark.co/api/v1/claims?repository_id=<repository-id>&include=assessments&limit=20"读取单次运行，仅在需要时加入证据：
curl "https://citeark.co/api/v1/runs?repository_id=<repository-id>&execution_state=succeeded&assessment_conclusion=supports&limit=20"接口
| 接口 | 用途 |
|---|---|
GET /api/v1/search?q= | 搜索仓库元数据与结论文本 |
GET /api/v1/repositories | 筛选、分页读取紧凑仓库摘要 |
GET /api/v1/repositories/resolve?owner=&slug= | 从人类可读路径解析紧凑仓库记录 |
GET /api/v1/repositories/{id} | 读取单个仓库，可选 include=readme,claims,experiments,runs,evidence,assessments |
GET /api/v1/claims | 跨仓库筛选、分页读取结论 |
GET /api/v1/claims/{id}?repository_id= | 解析仓库内唯一的结论 ID |
GET /api/v1/runs | 用 execution_state 与 assessment_conclusion 分别筛选执行事实和科学判断 |
GET /api/v1/runs/{id} | 解析单次运行，可选 include=environment,attestation,logs,evidence,assessments |
GET /api/v1/evidence/{id}?repository_id= | 解析证据元数据与下载地址 |
POST /api/v1/runs | 发起复现，需要具有 run 权限的 API Key |
集合接口支持 limit（1–100）、不透明 cursor，以及用逗号分隔顶层字段的 fields。请跟随 pagination.nextCursor 或响应头里的 RFC 8288 Link: <…>; rel="next"，不要自行拼接游标。所有 self、next 与 Link 地址都固定使用公开域名 https://citeark.co。仓库、结论、运行集合均支持 ISO 8601 格式的 updated_since。
计划、执行与 Assessment
这三类状态不能互相替代：
claim.plan说明准备怎样验证，不表示已经执行；run.execution.state只记录物理执行发生了什么；run.assessment.conclusion与claim.evidence聚合不可变 Assessment，表达证据是支持、质疑、矛盾还是不足。
旧字段 claim.verification、claim.reproduction 与 run.state 为 v1 兼容别名，已在 Schema 中标记弃用。新 Agent 不应根据“执行失败”推断论文结论错误，也不应让最近一次运行覆盖历史 Assessment。
计量真值模型
请使用 measurementId，不要用 metric 作为唯一标识。同一篇论文可能针对不同模型、数据集、数据划分或实验条件报告同名指标。每条规范计量因此都包含：
{
"measurementId": "ag-news-bigram-test-accuracy",
"metric": "accuracy",
"unit": "percentage_points",
"dimensions": { "features": "bigram", "dataset": "AG News" },
"reportedValue": 92.5,
"observedValue": 92.5,
"tolerance": 0.2,
"verification": "verified",
"evidenceIds": ["…"]
}若旧快照曾把多个同名计量压缩为一个数值，CiteArk 会返回 observedValue: null 与 verification: "review_required"，不会把同一个数复制成多个实验结果。
公开投影会去除 IEEE-754 无意义尾数。失败原因使用稳定的 diagnostic.code/category/retryable/summary/recoveryAction，默认响应不会暴露内部文件路径或运行日志；需要审计时再按需读取签名证据或 include=logs。
条件轮询
保存读取响应中的 ETag，下一次请求时原样传回：
curl -i "https://citeark.co/api/v1/runs/<run-id>" \
-H 'If-None-Match: "<etag>"'记录没有变化时返回无正文的 304。公开 v1 读取还会返回 Cache-Control: public, max-age=60, stale-while-revalidate=300。
错误格式
v1 错误具有稳定的机器可读结构：
{
"error": {
"code": "repository_not_found",
"message": "Public repository not found."
}
}旧版 /api/repositories 仍用于浏览器集成与完整兼容快照；新的 Agent 应使用 /api/v1。
ArkGraph 研究图
GET /api/v1/graph?repositoryId=... 或 ?artifact=sha256:... 读取子图。复杂只读操作使用 POST /api/v1/graph；MCP 使用 query_research_graph。提供 repositoryId 或最多 20 个 artifactDigests，每次返回最多 500 个节点，depth 为 0–12。
| operation | 必需输入 |
|---|---|
subgraph | 范围；可选 roots、predicates、cursor |
record / provenance | reference: {ref, digest}，可选固定 recordType 与 artifactDigest |
route | target；可选 activities |
compare | left、right 路线选择及固定 targets；两侧可各指定 artifactDigests |
返回 data、可读 publications 和 scope。检查截断、未解析依赖与缺失根对象；data: null 表示所选对象不可取得。比较不从不同摘要推断独立性，不按文字合并目标，保留冲突评估。读接口不启动实验，私有结果不缓存为公开内容。
POST /api/v1/artifacts 接收最多 24 MiB 的签名 CAP 2 二进制；查询参数 visibility 默认为 private，repository 可选。MCP publish_research_artifact 接收同样大小限制的 cap_base64、可选 repository_id 和 visibility。上传需要账号及写入权限。无论文研究图合法。GET /api/v1/artifacts/{artifactDigest} 返回产物，材料下载使用其 /objects/{blobDigest} 子路径，只提供已授权的嵌入字节。