30-Second Quickstart

Search compact research records, fetch only the Claims you need, and optionally queue a reproduction.

1 · Search public research

Public reads require no Key:

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

Choose a repository.id from the response. IDs are stable even if a repository URL slug changes.

2 · Fetch only the Claims you need

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

Follow pagination.nextCursor when hasMore is true. Every measurement separates measurementId, metric, experimental dimensions, paper-reported value, observed value, verification state, and evidence IDs.

3 · Create an API Key for write actions

Sign in, then create a Key on the Agent API Key page in your account settings. The Key is shown only once at creation and expires after 90 days by default; pass it in the x-api-key header when calling write endpoints. You can skip this step if you only read public data.

export CITEARK_API_KEY="citeark_…"

4 · Request your first reproduction (write endpoint)

Write endpoints require the x-api-key header. The request below asks for a controlled reproduction of a specific Claim (repositoryId and claimId come from the snapshot in step 2):

curl -X POST "https://citeark.com/api/v1/runs" \
  -H "x-api-key: $CITEARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"repositoryId": "…", "claimId": "…"}'

Success returns 202 with the run record. Only runs that actually enter the queue consume your monthly reproduction quota; failed requests are automatically refunded.

5 · Rate limits and quotas (reading a 429)

Limits come in two layers, and exceeding either returns 429. Callers should back off based on the response headers:

Rate limit (burst protection): 120 requests/minute per API Key by default; reproduction requests are additionally capped at 10/hour/account. The response carries Retry-After (seconds) and X-RateLimit-Limit — wait for Retry-After, then retry.
Monthly quota (resource control): 10 reproductions per account per month, shared across the browser session and all of the account's Keys. When exhausted, the response carries X-Quota-Limit, X-Quota-Used, and X-Quota-Reset (the quota reset time, UTC); Retry-After points at the reset time.

Each Key's last-used time and remaining monthly quota are visible on the Agent API Key page.

Next, see the complete Agent API, connect MCP, or load the OpenAPI contract.