API 参考
发起复现
POST /api/runs 针对 Claim 发起受控验证,202 异步入队。
POST /api/runs（也可使用 POST /api/v1/runs）针对某个 Claim 发起一次受控验证运行。运行固定到仓库当前版本,请求成功只代表已入队,实际执行在响应之后异步进行。
鉴权
需要浏览器会话或 x-api-key,且账号具备 run 权限。
请求
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| repositoryId | string | 是 | 仓库 ID |
| claimId | string | 是 | 要复现的 Claim ID |
| experimentVersionId | string | 否 | 指定实验版本,必须带 sha256: 前缀;缺省时自动匹配该 Claim 关联的实验 |
示例
curl -X POST https://citeark.com/api/runs \
-H "x-api-key: $CITEARK_API_KEY" \
-H "content-type: application/json" \
-d '{"repositoryId": "…", "claimId": "CLM-001"}'响应
成功返回 202,body 为 { "run": { ... } }:
{
"run": {
"id": "…",
"repositoryId": "…",
"claimIds": ["CLM-001"],
"state": "queued",
"queuedAt": "…"
}
}202 异步语义
返回 202 时 run.state 为 queued,执行在响应之后异步进行。请轮询 GET /api/v1/runs/{runId}?repository_id={repositoryId}，直到 state 变为 verified、failed 等终态。把响应中的 ETag 作为 If-None-Match 传回；状态未变化时会返回无正文的 304。仅在完成后按需请求 include=evidence,attestation。
RunRecord 关键字段
| 字段 | 说明 |
|---|---|
| id | 运行 ID |
| repositoryId | 所属仓库 ID |
| commitId | 运行固定的仓库版本(sha256: 前缀) |
| experimentVersionId | 实验版本摘要 |
| claimIds | 本次验证的 Claim 列表 |
| state | 运行状态(queued / running / verified / failed 等) |
| queuedAt | 入队时间 |
| startedAt | 开始执行时间 |
| finishedAt | 结束时间 |
| agent | 执行 Agent 信息(provider / model 等) |
| environment | 执行环境(容器镜像、硬件、区域等) |
| inputDigests | 输入对象摘要列表 |
| outputDigests | 输出对象摘要列表 |
| measurementResults | 以稳定 measurement ID 标识的规范计量，分开论文报告值、实测值与证据 ID |
| metrics | 旧版兼容摘要；多个计量同名时不得把指标名当作唯一标识 |
| log | 运行日志条目 |
| attestation | 本次运行的签名证明 |
服务端拒绝条件
以下情况均返回 400,运行不会入队:
- Claim 不存在;
- 该 Claim 没有可执行实验;
- 实验的 executor 不是
builtin(通用 Agent 复现仍在私测); - 平台执行器未配置。
错误
| 状态码 | 含义 |
|---|---|
| 400 | 运行请求无效,或命中上述拒绝条件 |
| 401 | 未登录或 Key 无效 |
| 403 | 权限不足 |
| 429 | 超出限流或月度额度(额度耗尽时携带 X-Quota-* 响应头) |
限流与备注
- 限流为每账号 10 次/小时。
- 另受每账号每月 10 次复现额度约束,只有成功入队才扣减额度。