Processing status
GET /api/processing polls the processing pipeline progress after a paper submission.
After a paper is submitted, the repository enters a processing pipeline (code discovery, structuring, import, reproduction, verification, publishing, and other stages). GET /api/processing returns the repository's most recent processing job and its events, for polling progress.
Authentication
Identity is optional (browser session or x-api-key), but you need read permission on the repository. Without permission, the endpoint returns 404 {"error": "processing job not found"} — the same as when no job exists — so it does not reveal whether the repository has a job.
Request
Query parameters:
| Parameter | Required | Description |
|---|---|---|
| repositoryId | Yes | Repository ID, max 128 characters |
Example
curl "https://citeark.co/api/processing?repositoryId=<repository-id>" \
-H "x-api-key: $CITEARK_API_KEY"Response
On success returns 200, with response header cache-control: private, no-store:
{
"job": {
"id": "…",
"repositoryId": "…",
"kind": "research_ingestion",
"state": "running",
"stage": "research_compilation",
"priority": 100,
"requestedBy": { "type": "human", "id": "…" },
"attemptCount": 1,
"maxAttempts": 3,
"availableAt": "…",
"result": {},
"lastError": "…",
"createdAt": "…",
"updatedAt": "…",
"startedAt": "…",
"finishedAt": "…"
},
"events": [
{
"eventType": "processing.queued",
"state": "queued",
"stage": "intake",
"payload": {},
"recordedAt": "…"
}
]
}job fields:
| Field | Description |
|---|---|
| id | Processing job ID |
| repositoryId | Owning repository ID |
| kind | Job type; always research_ingestion |
| state | Job state; see the enum below |
| stage | Pipeline stage; see the enum below |
| priority | Scheduling priority |
| requestedBy | Initiator; type is human, api_key, or service, and id is the corresponding principal ID |
| attemptCount | Number of attempts made |
| maxAttempts | Maximum number of attempts |
| availableAt | Time the job becomes schedulable |
| result | Structured result after completion |
| lastError | Most recent error message; may be absent |
| createdAt / updatedAt | Creation and last update times |
| startedAt / finishedAt | Start and finish times; absent while unfinished |
state enum: queued, dispatched, running, blocked (blocked by budget or execution policy), completed, failed, cancelled.
stage enum (pipeline stages): intake, source_discovery, research_compilation, research_import, reproduction_scheduling, reproduction, verification, publishing, completed.
events contains the job's 30 most recent processing events. Each includes eventType, state, stage, payload, recordedAt, and other fields (plus integrity fields such as event digests), recording every state change of the pipeline in chronological order.
Errors
Errors always take the form {"error": "message"}:
| Code | Description |
|---|---|
| 400 | Invalid processing job query (repositoryId missing or too long) |
| 404 | Processing job does not exist, or you lack read permission on the repository |
Notes
This endpoint has no built-in rate limit, but please poll reasonably — an interval of at least 10 seconds is recommended. Once the pipeline completes, structures such as Claims and experiment plans in the repository snapshot are pipeline outputs, readable via GET /api/repositories.
Confirming scope through the research graph
Jobs awaiting manual selection pause at blocked / reproduction_scheduling. The website lets users select executable steps in ArkGraph. Branches of one step count as one execution, explicit prerequisites are included, and shared work is counted once in the estimate.
GET /api/processing/experiments?jobId=<job UUID> returns { graph }. It requires repository read access and does not start work. The graph includes artifactDigest, research objects in nodes, executable routes in steps, and unboundExperimentIds. Each step contains an experimentId, an exact procedure reference, input/target node keys, and requiredExperimentIds. Unresolved materials remain in unresolvedInputs; they are not marked ready.
Confirm with POST /api/processing/experiments. This requires a signed-in user or API key with run scope, plus permission to use the job's credits:
{
"jobId": "<job UUID>",
"graphSelection": {
"artifactDigest": "sha256:<current plan's 64 hexadecimal digest characters>",
"procedures": [
{ "ref": "<procedure reference>", "digest": "sha256:<procedure's 64 hexadecimal digest characters>" }
]
}
}Copy exact references from the graph response and include all required prerequisite steps. The server recalculates the resource estimate; clients cannot submit prices. Success returns { job } and resumes the existing material preparation, credit, and execution workflow. A stale plan or procedure, missing prerequisites, or a job no longer awaiting selection returns 409. Missing funding permission returns 403; malformed requests or an incompatible combined estimate return 400. Existing clients can still send experimentIds, but cannot combine it with graphSelection. Reading, inspecting, or closing the graph never starts computation.