API reference

Repositories

Registered repositories, their mirrors, what a change would run, and which mirrors hold a commit.

GET/v1/ci/repos

List repositories

Repositories, filtered by remote fingerprint.

Permission: ci:repos.read

Parameters

Name	Type	Required
`cursor`query	string	Optional
`limit`query	string	Optional
`remote`query	string	Optional

Response200 OK

dataarray of anyRequired
has_morebooleanRequired
next_cursorstring or null

curl "$CIRESK_API/v1/ci/repos" \
  -H "Authorization: Bearer $CIRESK_KEY"

POST/v1/ci/repos

Register a repository

Permission: ci:repos.writeCommand: send Idempotency-Key

Parameters

Name	Type	Required	Description
`Idempotency-Key`header	string	Required

Request body

default_branchstringRequired
manifest_pathstring or null: default .ciresk/ci.yaml
remote_urlstring or null: absent for a folder with no git remote: the fingerprint then derives from slug
slugstringRequired

Response201 Created

created_atstring (date-time)Required
default_branchstringRequired
idstringRequired: uuidv7 rendered as repo_<32 hex>
manifest_pathstringRequired
remote_fingerprintstringRequired: sha-256 of the normalised origin url
slugstringRequired
urlstring or null

curl -X POST "$CIRESK_API/v1/ci/repos" \
  -H "Authorization: Bearer $CIRESK_KEY" \
  -H "Idempotency-Key: fd71e4b7-310d-46ae-8559-9d760214a8c9" \
  -H "Content-Type: application/json" \
  -d '{
    "default_branch": "main",
    "manifest_path": ".ciresk/ci.yaml",
    "remote_url": "[email protected]:acme/platform.git",
    "slug": "acme/platform"
  }'

GET/v1/ci/repos/{id}

Get a repository

Permission: ci:repos.read

Parameters

Name	Type	Required	Description
`id`path	string	Required	The repo's ID.

Response200 OK

created_atstring (date-time)Required
default_branchstringRequired
idstringRequired: uuidv7 rendered as repo_<32 hex>
manifest_pathstringRequired
remote_fingerprintstringRequired: sha-256 of the normalised origin url
slugstringRequired
urlstring or null
mirrorsarray of objects
mirrors[].seen_atstring (date-time)Required
mirrors[].worker_idstringRequired: uuidv7 rendered as wrk_<32 hex>

curl "$CIRESK_API/v1/ci/repos/repo_0129354d7b6b4146ad16c315d960365b" \
  -H "Authorization: Bearer $CIRESK_KEY"

DELETE/v1/ci/repos/{id}

Delete a repository

Delete a repository and everything only it references.

Permission: ci:repos.admin

Parameters

Name	Type	Required	Description
`id`path	string	Required	The repo's ID.

Response200 OK

already_deletedbooleanRequired: the repository was already deleted before this call; the purge ran again and found what the counts say
countsobjectRequired: what ci.repos.delete removed; every number is zero on a repeat
counts.artifactsintegerRequired
counts.blob_bytesintegerRequired
counts.blobsintegerRequired: cas blobs nothing else in the tenant references, with their bytes
counts.cache_entriesintegerRequired
counts.jobsintegerRequired: jobs purged: content gone, the row kept as the journal's anchor
counts.jobs_cancelledintegerRequired: jobs that were queued, leased or running and ended cancelled
counts.log_chunksintegerRequired
counts.tasksintegerRequired
counts.test_resultsintegerRequired
counts.tree_nodesintegerRequired: directory manifests only those roots reached
counts.treesintegerRequired: verified roots no other repository's job names
counts.workspaces_evictedintegerRequired: warm workspaces the workers were asked to evict on their next report
deleted_atstring (date-time)Required
idstringRequired: uuidv7 rendered as repo_<32 hex>
slugstringRequired

curl -X DELETE "$CIRESK_API/v1/ci/repos/repo_0129354d7b6b4146ad16c315d960365b" \
  -H "Authorization: Bearer $CIRESK_KEY"

GET/v1/ci/repos/{id}/affected

Preview the affected set

What would run, without running.

Permission: ci:repos.read

Parameters

Name	Type	Required	Description
`id`path	string	Required	The repo's ID.
`base`query	string	Optional
`diff`query	string	Optional
`kind`query	string	Optional
`reference`query	string	Optional
`root`query	string	Optional
`strategy`query	string	Optional

Response200 OK

base_refstringRequired
changed_filesintegerRequired
diff_digeststring or null: sha-256 digest as sha256:<64 hex>
escalatedbooleanRequired
escalation_reasonstring or null
estimated_cost_unitsinteger or null
kindstringRequired: check, test, build, lint or a manifest task id
reference_rootstring or null: the root digest of a working tree: sha-256 of the root directory manifest
rootstring or null: the submitted and the reference tree roots the diff was taken between
strategystringRequired: One of cargo, pnpm, go, turbo, nx, files, none
targetsarray of stringsRequired

curl "$CIRESK_API/v1/ci/repos/repo_0129354d7b6b4146ad16c315d960365b/affected" \
  -H "Authorization: Bearer $CIRESK_KEY"

GET/v1/ci/repos/{id}/commits/{sha}

Check which mirrors hold a commit

Permission: ci:repos.read

Parameters

Name	Type	Required	Description
`id`path	string	Required	The repo's ID.
`sha`path	string	Required	A commit SHA.

Response200 OK

mirrorsarray of objectsRequired
mirrors[].seen_atstring (date-time)Required
mirrors[].worker_idstringRequired: uuidv7 rendered as wrk_<32 hex>
shastringRequired

curl "$CIRESK_API/v1/ci/repos/repo_0129354d7b6b4146ad16c315d960365b/commits/feef45d804737fdf7a297e27e443d914551629de" \
  -H "Authorization: Bearer $CIRESK_KEY"

POST/v1/ci/repos/{id}/graph

Store dependency graph

The dependency graph a worker recorded for a tree root.

Permission: ci:workers.report

Parameters

Name	Type	Required	Description
`id`path	string	Required	The repo's ID.

Request body

graphobjectRequired: the graph snapshot a worker recorded for a tree root; dir is where the tool ran, repository-relative with "" for the root, so node directories map onto changed paths. crates/ci/affected reads it; the api stores it as a cas blob of kind graph
graph.dirstringRequired
graph.formatstringRequired: One of sources
graph.jsonstring
graph.filesmap of string
leasestring or null: the lease whose task the graph was captured after: the cell records it only while that lease is the calling worker's, active or released by its own report, on a job of this repository, root and view, since the first graph of a root steers every later job's affected set; a report without one is 409 lease_not_held
rootstringRequired: the root digest of a working tree: sha-256 of the root directory manifest
strategystringRequired: One of cargo, pnpm, go, turbo, nx, files, none
viewstring or null: a view job's JobView::digest: the graph was recorded from that view's tree, so the cell keeps it apart from the full tree's and serves it to that view's jobs only

Response201 Created

digeststringRequired: the cas digest of the stored document
recordedbooleanRequired: false when the cell already held a graph for this root and strategy

curl -X POST "$CIRESK_API/v1/ci/repos/repo_0129354d7b6b4146ad16c315d960365b/graph" \
  -H "Authorization: Bearer $CIRESK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "graph": {
      "dir": "acme/platform",
      "format": "cargo_metadata",
      "json": "acme/platform"
    },
    "lease": "lease_01778d67b48ee630f44b3f03ab6254a8",
    "root": "sha256:4827d3132b09e1cedc07788771ef7bca9c1140b2dff2ac370fc8433a94de43e5",
    "strategy": "cargo",
    "view": "sha256:62d44f48688d2f810f8be60e21ec9d5920297a2c5fd9534172d15af304819f50"
  }'

POST/v1/ci/repos/{id}/sync

Sync a repository's mirrors

Ask the cell's mirrors to fetch the repository; the head and when it was fetched.

Permission: ci:repos.writeCommand: send Idempotency-Key

Parameters

Name	Type	Required	Description
`id`path	string	Required	The repo's ID.
`Idempotency-Key`header	string	Required

Response201 Created

fetched_atstring (date-time)Required
headstringRequired

curl -X POST "$CIRESK_API/v1/ci/repos/repo_0129354d7b6b4146ad16c315d960365b/sync" \
  -H "Authorization: Bearer $CIRESK_KEY" \
  -H "Idempotency-Key: 8ff057ba-353a-4043-a148-c37fb863fbec"