Start a reproduction
POST /api/runs starts a controlled verification against a Claim; queued asynchronously with 202.
POST /api/runs (also available as POST /api/v1/runs) starts a controlled verification run against a Claim. The run is pinned to the repository's current version; a successful response only means the run was queued — actual execution happens asynchronously after the response.
Authentication
Requires a browser session or x-api-key, and the account must have run permission.
Request
| Parameter | Type | Required | Description |
|---|---|---|---|
| repositoryId | string | Yes | Repository ID |
| claimId | string | Yes | ID of the Claim to reproduce |
| experimentVersionId | string | No | Pin an experiment version; must carry a sha256: prefix. When omitted, the experiment associated with the Claim is matched automatically |
Example
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"}'Response
On success returns 202 with body { "run": { ... } }:
{
"run": {
"id": "…",
"repositoryId": "…",
"claimIds": ["CLM-001"],
"state": "queued",
"queuedAt": "…"
}
}202 async semantics
When 202 is returned, run.state is queued; execution proceeds asynchronously after the response. Poll GET /api/v1/runs/{runId}?repository_id={repositoryId} until state reaches a terminal state such as verified or failed. Send the returned ETag as If-None-Match; unchanged state returns 304 without a body. Opt into include=evidence,attestation only after completion.
Key RunRecord fields
| Field | Description |
|---|---|
| id | Run ID |
| repositoryId | Owning repository ID |
| commitId | Repository version the run is pinned to (sha256: prefixed) |
| experimentVersionId | Experiment version digest |
| claimIds | Claims verified in this run |
| state | Run state (queued / running / verified / failed, etc.) |
| queuedAt | Time the run was queued |
| startedAt | Time execution started |
| finishedAt | Time execution finished |
| agent | Executing Agent info (provider / model, etc.) |
| environment | Execution environment (container image, hardware, region, etc.) |
| inputDigests | Input object digest list |
| outputDigests | Output object digest list |
| measurementResults | Canonical measurements keyed by stable measurement IDs, with reported and observed values plus evidence IDs |
| metrics | Legacy compatibility summary; do not use metric name as identity when multiple measurements share it |
| log | Run log entries |
| attestation | Signed attestation for this run |
Server-side rejection conditions
All of the following return 400, and the run is not queued:
- The Claim does not exist;
- The Claim has no executable experiment;
- The experiment's executor is not
builtin(general Agent reproduction is still in private beta); - No platform executor is configured.
Errors
| Code | Meaning |
|---|---|
| 400 | Invalid run request, or one of the rejection conditions above |
| 401 | Not signed in or invalid key |
| 403 | Insufficient permission |
| 429 | Rate limit or monthly quota exceeded (carries X-Quota-* headers when the quota is exhausted) |
Rate limits and notes
- Limited to 10 requests per hour per account.
- Additionally subject to a 10-reproduction monthly quota per account; quota is only deducted when a run is successfully queued.