Repositories

A research repository is CiteArk's fundamental object, corresponding to a paper together with its Claims, experiments, run records, and evidence. GET /api/repositories serves the public list and individual repository snapshots; POST /api/repositories submits a new paper.

For Agents, prefer GET /api/v1/repositories and GET /api/v1/repositories/{id}. They provide cursor pagination, fields, opt-in include sections, stable ID lookup, ETag revalidation, and much smaller default responses. See Agent API. The endpoint below is the legacy full-snapshot interface.

Authentication

• GET is public; no authentication required.
• POST requires a browser session or x-api-key, and the account must have write permission.

GET /api/repositories

Request

Without parameters, returns the list of public repositories, sorted by updatedAt descending, at most 50 entries, with no pagination parameters.

Examples

# Public repository list
curl https://citeark.co/api/repositories

# Single repository snapshot
curl "https://citeark.co/api/repositories?owner=<owner>&slug=<slug>"

Response

The list returns { "repositories": [...] }, where each entry is a RepositorySummary:

A single repository returns { "repository": { ... } }, a full snapshot (top-level structure described in Core concepts). Private repositories are readable only by the owner / organization members; everyone else gets 404 {"error": "repository not found"}. Non-owners reading a public repository receive a redacted projection.

POST /api/repositories

Both JSON and multipart submissions accept reproductionScope: low (default, evaluate existing scientific state and produce fresh measurements), medium (regenerate scientific state for one or a few key experiments), or high (rebuild the agreed major research workflow). Scientific state includes trained weights, collected data, simulation trajectories, generated samples, and attack traces. Dependency setup, software compilation, fixed workloads, temporary tensors, evaluators, and analysis code are operational scaffolding, so they do not automatically make work medium. Scope is independent of budget, runtime, GPU count, and scientific conclusions; missing material creates a blocker rather than an automatic upgrade. Existing repositories and signed plans are not changed by submitting the same paper again. If zero experiments enter execution, the processing page explicitly reports a completed plan with no experiment executed rather than a completed reproduction.

Two modes, distinguished by Content-Type.

Mode 1: JSON indexing (application/json, recommended for Agents)

Submit an arXiv link/ID or an HTTPS PDF direct link; the server fetches and indexes the paper — no file upload needed.

Behavior: in arXiv mode the server fetches the title, abstract, and license, and downloads the PDF. When the License Gate is green, the PDF is stored in object storage; otherwise only metadata is kept, linking back to the original source. After creation the repository automatically enters the processing pipeline; poll progress via Processing status.

Mode 2: Multipart upload (multipart/form-data)

Upload the paper PDF file directly.

Examples

# Mode 1: index from arXiv
curl -X POST https://citeark.co/api/repositories \
  -H "x-api-key: $CITEARK_API_KEY" \
  -H "content-type: application/json" \
  -d '{"input": "https://arxiv.org/abs/2401.00001"}'

# Mode 2: upload a PDF
curl -X POST https://citeark.co/api/repositories \
  -H "x-api-key: $CITEARK_API_KEY" \
  -F "paper=@paper.pdf" \
  -F "title=Paper title" \
  -F "slug=your-paper-slug" \
  -F "submitterAttested=true"

Response

On success returns 201:

{
  "repository": { "id": "…", "owner": "<owner>", "slug": "<slug>", "title": "…" },
  "url": "/r/<owner>/<slug>"
}

Errors

Rate limits and notes

• POST is limited to 5 requests per hour per account.
• Uploads and indexing are additionally subject to a 25-upload monthly quota per account; when exhausted, returns 429 with X-Quota-* headers.