API Reference
Common behavior, status codes, and endpoint overview for the CiteArk REST API.
All CiteArk endpoints speak JSON, with base URL https://citeark.com. Public reads require no authentication; write operations such as submitting papers or starting reproductions can use a browser session, or an API Key sent via the x-api-key header. See Authentication.
New machine clients should use the versioned, compact Agent API under /api/v1. Its contract is published at /openapi.json and it uses structured { "error": { "code", "message" } } errors. The unversioned endpoints documented in this section remain compatibility and browser workflow endpoints.
curl https://citeark.com/api/repositories \
-H "x-api-key: $CITEARK_API_KEY"Common behavior
/api/v1errors use{"error":{"code":"…","message":"…"}}; compatibility endpoints use{"error":"message"}.- Exceeding a rate limit or monthly quota returns
429, always with aRetry-Afterheader. Rate-limit headers areX-RateLimit-*; monthly-quota headers areX-Quota-*. The two are independent. See Rate limits and quotas. - Request bodies over 26 MB are rejected with
413(the paper PDF itself is limited to 25 MB; the headroom covers multipart boundaries and fields).
Status codes
| Code | Meaning |
|---|---|
| 200 | Success |
| 201 | Created |
| 202 | Accepted (async execution) |
| 304 | Not modified (ETag) |
| 400 | Invalid request |
| 401 | Not signed in or invalid key |
| 403 | Insufficient permission |
| 404 | Not found |
| 409 | Conflict (e.g. paper already exists) |
| 413 | Request body too large |
| 422 | Unprocessable |
| 429 | Rate limit or quota exceeded |
| 451 | License does not allow redistribution |
| 502 | Upstream or integrity check failure |
| 503 | Service degraded |
Endpoint overview
Repositories
GET /api/repositories list and snapshots, POST /api/repositories submit a paper.
Start a reproduction
POST /api/runs start a controlled verification against a Claim.
Evidence & signatures
GET /api/objects/{digest} download evidence objects, GET /api/attestations/{digest} verify signatures.
Fork
POST /api/forks copy a research repository into your own namespace.
Social
Stars, reproduction requests, and follows.
arXiv lookup
Look up arXiv paper metadata.
Processing status
Poll the processing pipeline status after submitting a paper.
Badges & embeds
GET /api/badge/{owner}/{slug} live-issued SVG badges and level criteria.
Health check
GET /api/health service status.
Notes
- The Agent API is versioned at
/api/v1; legacy browser and compatibility routes remain under/api. - If a self-hosted deployment sets
CITEARK_BACKEND_ORIGIN, the frontend proxies API requests verbatim to that backend.