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.co/openapi.json - JSON Schema:
https://citeark.co/api/v1/schema - MCP Streamable HTTP:
https://citeark.co/mcp - Agent index:
https://citeark.co/llms.txt
Compact workflow
Search without downloading every full repository:
curl "https://citeark.co/api/v1/search?q=language+model&limit=10"Then fetch only claims for the chosen stable repository ID:
curl "https://citeark.co/api/v1/claims?repository_id=<repository-id>&include=assessments&limit=20"Read one run and opt into evidence only when needed:
curl "https://citeark.co/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.co origin. updated_since accepts ISO 8601 on repository, Claim, and run collections.
Plans, executions, and Assessments
These states are deliberately independent:
claim.plansays how a Claim is intended to be tested; it is not a result;run.execution.staterecords only what physically happened;run.assessment.conclusionandclaim.evidenceaggregate 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.co/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.
ArkGraph research graph
Use GET /api/v1/graph?repositoryId=... or ?artifact=sha256:... for a subgraph. Complex read operations use POST /api/v1/graph; MCP uses query_research_graph. Supply repositoryId or up to 20 artifactDigests; return at most 500 nodes with depth between 0 and 12.
| operation | Required input |
|---|---|
subgraph | Scope; optional roots, predicates, cursor |
record / provenance | reference: {ref, digest}, optionally fixing recordType and artifactDigest |
route | target; optional activities |
compare | left, right route selections and a fixed targets set; each side may select its own artifactDigests |
Responses contain data, readable publications and scope. Check truncation, missing roots and unresolved dependencies. data: null means the selected object is unavailable. Comparisons preserve conflicting assessments and never infer independence from different hashes or merge targets by text. Reads do not run experiments or publicly cache private results.
POST /api/v1/artifacts accepts signed CAP 2 bytes up to 24 MiB. Query parameters are visibility (default private) and optional repository. MCP publish_research_artifact accepts cap_base64, optional repository_id and visibility with the same decoded limit. Upload requires an account and write scope. Paper-free research graphs are valid. GET /api/v1/artifacts/{artifactDigest} returns the artifact; its /objects/{blobDigest} subpath downloads authorized embedded material only.