典型用法

批量拉取已验证结论、发起并跟踪复现、处理 429 退避、索引 arXiv 论文、在 README 挂徽章。

批量拉取已验证结论

先列出公开仓库（按 updatedAt 倒序，最多 50 条；条目含 claimCount、verifiedClaimCount、runCount 摘要，可用于粗筛），再逐个读取快照，用 jq 筛出已验证的 Claims：

# 列出公开仓库的 owner/slug
curl https://citeark.com/api/repositories \
  | jq -r '.repositories[] | "\(.owner)/\(.slug)"'

# 读取单个仓库快照,筛出已验证的 claims
curl "https://citeark.com/api/repositories?owner=<所有者>&slug=<仓库名>" \
  | jq '.repository.claims[] | select(.verification == "verified")'

发起一次复现

用快照中的 repository.id 和要验证的 claim.id 提交运行请求，返回 202 表示已排队；之后重新读取快照即可跟踪 runs 里的状态变化（完整流程见下文）：

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"}'

当前为受控私测：只接受平台受控执行器（builtin）的实验。许可元数据只控制源材料再分发，不阻断隔离执行；每小时最多提交 10 次。执行任意第三方代码的通用 Agent 复现尚未开放。

在 README 挂徽章

徽章由平台按仓库当前数据实时签发（SVG，缓存 5 分钟），嵌入时链接回仓库页，读者可以继续查看 Claims、运行记录与证据：

[![CiteArk](https://citeark.com/api/badge/<所有者>/<仓库名>)](https://citeark.com/r/<所有者>/<仓库名>)

等级口径见徽章与嵌入。

发起并跟踪一次完整复现

把前面的步骤串成完整流程：读快照 → 提交运行 → 轮询状态 → 验证签名。

GET /api/repositories?owner&slug 读取快照，记下 repository.id 与目标 claim.id；
POST /api/runs 提交运行，从 202 响应中拿到 run.id，此时 state 为 queued；
轮询同一快照端点，观察 runs[] 中该 run 的 state（建议间隔 ≥10 秒）；
state 到达终态 verified / failed 后读取 run.attestation，需要独立验签时按摘要调用 GET /api/attestations/{digest}。

OWNER="…"   # 仓库所有者
SLUG="…"    # 仓库 slug

# 1) 读快照,记下 repository.id 与目标 claim.id
SNAPSHOT=$(curl -s "https://citeark.com/api/repositories?owner=$OWNER&slug=$SLUG")
REPO_ID=$(echo "$SNAPSHOT" | jq -r '.repository.id')
CLAIM_ID=$(echo "$SNAPSHOT" | jq -r '.repository.claims[0].id')

# 2) 提交运行,从 202 响应中取 run.id(此时 state=queued)
RUN_ID=$(curl -s -X POST https://citeark.com/api/runs \
  -H "x-api-key: $CITEARK_API_KEY" \
  -H "content-type: application/json" \
  -d "{\"repositoryId\": \"$REPO_ID\", \"claimId\": \"$CLAIM_ID\"}" \
  | jq -r '.run.id')

# 3) 轮询同一快照端点,用 jq 取该 run 的 state
while true; do
  STATE=$(curl -s "https://citeark.com/api/repositories?owner=$OWNER&slug=$SLUG" \
    | jq -r --arg id "$RUN_ID" '.repository.runs[] | select(.id == $id) | .state')
  echo "run $RUN_ID state: $STATE"
  case "$STATE" in verified|failed) break ;; esac
  sleep 10
done

# 4) 终态后按摘要验证签名(attestations 路径参数不带 sha256: 前缀)
DIGEST=$(curl -s "https://citeark.com/api/repositories?owner=$OWNER&slug=$SLUG" \
  | jq -r --arg id "$RUN_ID" '.repository.runs[] | select(.id == $id) | .attestation.statementDigest' \
  | sed 's/^sha256://')
curl -s "https://citeark.com/api/attestations/$DIGEST" | jq '.verified'

处理 429 与退避

超出限制时接口返回 429，响应头分两类，退避策略不同（详见限流与额度）：

类型	响应头	处理方式
速率限制	`Retry-After`、`X-RateLimit-Limit`、`X-RateLimit-Remaining`	窗口过后自动恢复，等待 `Retry-After` 秒后重试即可
月度额度	`Retry-After`、`X-Quota-Limit`、`X-Quota-Used`、`X-Quota-Reset`	要等次月重置（`Retry-After` 指向 `X-Quota-Reset` 的 UTC 重置时间），应停止重试并提示

HEADERS=$(mktemp)
while true; do
  STATUS=$(curl -s -D "$HEADERS" -o /tmp/citeark-body.json -w '%{http_code}' \
    https://citeark.com/api/repositories)
  [ "$STATUS" != "429" ] && break

  if grep -qi '^X-Quota-Limit:' "$HEADERS"; then
    # 月度额度耗尽:重试无意义,等待 X-Quota-Reset 指示的次月重置
    echo "月度额度已耗尽,重置时间:" \
      "$(grep -i '^X-Quota-Reset:' "$HEADERS" | tr -d '\r' | awk '{print $2}')" >&2
    exit 1
  fi

  # 速率限制:按 Retry-After(秒)退避后重试
  RETRY_AFTER=$(grep -i '^Retry-After:' "$HEADERS" | tr -d '\r' | awk '{print $2}')
  sleep "${RETRY_AFTER:-60}"
done
cat /tmp/citeark-body.json

索引一篇 arXiv 论文

arXiv 论文无需上传文件，三步完成索引：

GET /api/arxiv?input=2401.12345 查询元数据与 suggestedSlug（需 read 权限，须携带 API Key）；
POST /api/repositories 提交 {"input": "2401.12345"}，标题、摘要、许可与 PDF 全部由服务端提取；
GET /api/processing?repositoryId=… 轮询处理状态，直到 job.state 变为 completed。

# 1) 查询 arXiv 元数据与 suggestedSlug(需 read 权限)
curl "https://citeark.com/api/arxiv?input=2401.12345" \
  -H "x-api-key: $CITEARK_API_KEY" | jq '.metadata.suggestedSlug'

# 2) 提交索引,返回 201 与 repository.id
curl -X POST https://citeark.com/api/repositories \
  -H "x-api-key: $CITEARK_API_KEY" \
  -H "content-type: application/json" \
  -d '{"input": "2401.12345"}'

# 3) 轮询处理状态,直到 completed
curl "https://citeark.com/api/processing?repositoryId=<仓库id>" \
  -H "x-api-key: $CITEARK_API_KEY" | jq '.job.state'

追踪私有仓库或组织仓库

POST /api/repositories 时传 visibility=private 或 owner=<组织slug>，即可把仓库建在个人私有空间或组织名下；读取私有仓库需要相应权限，未授权的公开查询只能看到投影后的信息（见核心概念的公开投影说明）。