Repositories

GET /api/repositories lists repositories and returns snapshots; POST /api/repositories uploads a PDF or indexes a paper from arXiv / a URL.

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

Parameter	Type	Required	Description
owner	string	No	Repository owner. When provided together with slug, returns a single repository snapshot
slug	string	No	Repository name. When provided together with owner, returns a single repository snapshot

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.com/api/repositories

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

Response

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

Field	Type	Description
id	string	Repository ID
owner	string	Owner namespace
slug	string	Repository name
title	string	Paper title
description	string	Short description
topics	string[]	Topic tags
headId	string	Current version commit digest (`sha256:` prefixed)
claimCount	number	Total Claim count
verifiedClaimCount	number	Verified Claim count
runCount	number	Run record count
forkCount	number	Fork count
updatedAt	string	Last update time (ISO 8601)

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

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.

Parameter	Type	Required	Description
input	string	Yes	1–300 characters. An arXiv link/ID (e.g. `2401.12345`, `https://arxiv.org/abs/...`, `https://arxiv.org/pdf/...`), or an HTTPS PDF direct link
title	string	No	3–240 characters; only meaningful in PDF direct-link mode (defaults to the filename)
owner	string	No	Target namespace: a personal slug or an organization slug you have permission for; must match `^[a-z0-9-]+$`, ≤64 characters
slug	string	No	≤96 characters; derived automatically when omitted
githubUrl	string	No	Must be an HTTPS link to a repository on github.com
visibility	string	No	`public` / `private`, defaults to `public`

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.

Field	Type	Required	Description
paper	file	Yes	PDF file, ≤25 MB; the server validates the `%PDF` header
title	string	Yes	3–240 characters
slug	string	Yes	≤96 characters; must match `^[a-z0-9-]+$`
owner	string	No	Target namespace: a personal slug or an organization slug you have permission for, ≤64 characters
description	string	No	≤1000 characters
githubUrl	string	No	Must be an HTTPS link to a repository on github.com
sourceUrl	string	No	Original source HTTPS URL
paperLicense	string	No	One of: `CC0-1.0`, `CC-BY-4.0`, `CC-BY-SA-4.0`, `MIT`, `Apache-2.0`, `arXiv-default`, `publisher-restricted`, `unknown`; defaults to `unknown`
codeLicense	string	No	One of: `MIT`, `Apache-2.0`, `BSD-2-Clause`, `BSD-3-Clause`, `ISC`, `MPL-2.0`, `GPL-3.0-only`, `no-code`, `unknown`; defaults to `unknown`
submitterAttested	string	Yes	Must be the string `"true"`, attesting that you have the right to submit this paper
visibility	string	No	`public` / `private`, defaults to `public`

Examples

# Mode 1: index from arXiv
curl -X POST https://citeark.com/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.com/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

Code	Meaning
400	Input not recognized or field validation failed
404	Paper not found on arXiv
409	This paper already exists on CiteArk (the response includes a `url` field pointing to the existing page)
413	PDF exceeds 25 MB
429	Rate limit or monthly quota exceeded

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.

On this page