Agent API

Compact, paginated, cacheable access to CiteArk research claims, executions, measurements, and evidence.

The Agent API is the preferred interface for machine clients. Public reads need no key. Responses are compact by default, use cursor pagination, expose stable links, and support ETag / If-None-Match so polling does not repeatedly download unchanged research snapshots.

Repository pages also support content negotiation. Send Accept: application/json to any /r/{owner}/{slug} or /zh/r/{owner}/{slug} URL to receive its compact repository record. HTML responses advertise the same machine entry point with Link: …; rel="alternate"; type="application/json".

Discovery

OpenAPI 3.1: https://citeark.com/openapi.json
JSON Schema: https://citeark.com/api/v1/schema
MCP Streamable HTTP: https://citeark.com/mcp
Agent index: https://citeark.com/llms.txt

Compact workflow

Search without downloading every full repository:

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

Then fetch only claims for the chosen stable repository ID:

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

Read one run and opt into evidence only when needed:

curl "https://citeark.com/api/v1/runs?repository_id=<repository-id>&execution_state=succeeded&assessment_conclusion=supports&limit=20"

Endpoints

Endpoint	Purpose
`GET /api/v1/search?q=`	Search repository metadata and Claim statements
`GET /api/v1/repositories`	Filter and page compact repository summaries
`GET /api/v1/repositories/resolve?owner=&slug=`	Resolve a human-readable path to a compact repository record
`GET /api/v1/repositories/{id}`	Read one repository; optional `include=readme,claims,experiments,runs,evidence,assessments`
`GET /api/v1/claims`	Filter and page Claims across repositories
`GET /api/v1/claims/{id}?repository_id=`	Resolve one repository-scoped Claim
`GET /api/v1/runs`	Filter physical execution facts and scientific conclusions separately with `execution_state` and `assessment_conclusion`
`GET /api/v1/runs/{id}`	Resolve one run; optional `include=environment,attestation,logs,evidence,assessments`
`GET /api/v1/evidence/{id}?repository_id=`	Resolve evidence metadata and download URL
`POST /api/v1/runs`	Queue a reproduction; requires an API Key with `run` permission

Collections accept limit (1–100), an opaque cursor, and fields with comma-separated top-level fields. Follow pagination.nextCursor or the RFC 8288 Link: <…>; rel="next" response header; never construct a cursor yourself. Every self, next, and Link URL is anchored to the public https://citeark.com origin. updated_since accepts ISO 8601 on repository, Claim, and run collections.

Plans, executions, and Assessments

These states are deliberately independent:

claim.plan says how a Claim is intended to be tested; it is not a result;
run.execution.state records only what physically happened;
run.assessment.conclusion and claim.evidence aggregate immutable Assessments that support, challenge, contradict, or remain inconclusive.

The old claim.verification, claim.reproduction, and run.state fields remain v1 compatibility aliases and are marked deprecated in the Schema. New Agents must not infer that an execution failure contradicts a paper, or let the latest run overwrite earlier Assessments.

Measurement truth model

Use measurementId, not metric, as identity. A paper may report the same metric name for multiple models, datasets, splits, or experimental conditions. Every canonical measurement therefore carries:

{
  "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": ["…"]
}

For legacy snapshots where multiple same-name measurements were collapsed into one scalar, CiteArk returns observedValue: null and verification: "review_required". It deliberately does not copy that scalar into multiple results.

Public projections remove meaningless IEEE-754 tails. Failures use stable diagnostic.code/category/retryable/summary/recoveryAction fields and do not expose internal paths or logs by default; request signed Evidence or include=logs only for audit and recovery.

Conditional polling

Store the ETag returned by a read, then send it back:

curl -i "https://citeark.com/api/v1/runs/<run-id>" \
  -H 'If-None-Match: "<etag>"'

An unchanged record returns 304 with no body. Public v1 reads also advertise Cache-Control: public, max-age=60, stale-while-revalidate=300.

Errors

v1 errors are predictable and machine-readable:

{
  "error": {
    "code": "repository_not_found",
    "message": "Public repository not found."
  }
}

Legacy /api/repositories remains available for browser integrations and full compatibility snapshots, but new Agents should use /api/v1.