Ciresk Docs
API reference

Cache

Write-once action-cache entries keyed by content, read in the namespaces the caller's trust tier allows.

POST/v1/ci/cache/evict

Evict cache entries

Permission: ci:cache.admin

Request body

beforestring (date-time) or null
repostring or null
uuidv7 rendered as repo_<32 hex>
taskstring or null

Response200 OK

bytesintegerRequired
evictedintegerRequired
curl -X POST "$CIRESK_API/v1/ci/cache/evict" \
  -H "Authorization: Bearer $CIRESK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "before": "2026-10-20T14:04:12Z",
    "repo": "repo_0129354d7b6b4146ad16c315d960365b",
    "task": "test"
  }'
POST/v1/ci/cache/lookups

Read cache entries

The verdict rows of a leased task's per-target unit keys, in one request.

Permission: ci:workers.cache

Request body

keysarray of stringsRequired
outputsarray of strings
: build keys whose recorded outputs row with a target answers (a crate's stored test binaries); empty from older workers
partialsarray of strings
: test keys whose recorded passed tests answer; empty from older workers
repostringRequired
uuidv7 rendered as repo_<32 hex>
taskstringRequired

Response200 OK

hitsarray of objectsRequired
hits[].fromobject or null
the run a cache hit stands on: the job and task whose success was recorded under the key, so a hit names where its verdict, log, junit and artifacts come from
hits[].from.job_idstringRequired
uuidv7 rendered as job_<32 hex>
hits[].from.task_idstringRequired
uuidv7 rendered as tsk_<32 hex>
hits[].keystringRequired
sha-256 digest as sha256:<64 hex>
hits[].riskobject or null
on a hit, what decides its audit; absent from older cells
hits[].risk.age_daysinteger
whole days since the row was recorded or last refreshed
hits[].risk.auditsinteger
audits of the key in the last 7 days, and how many of them passed
hits[].risk.clean_auditsinteger
hits[].risk.failuresinteger
failures observed under the key in the last 7 days
hits[].risk.flakyboolean
the run the row stands on passed only on a retry (CIR-722): its green is a flip within one run
hits[].risk.foreignboolean
another tier recorded it
hits[].risk.holesinteger
key holes recorded under the key in the last 7 days: a run read a file the key does not cover
outputsarray of objects
the outputs keys that hit, each with its blob; absent from older cells
outputs[].fromobject or null
the run a cache hit stands on: the job and task whose success was recorded under the key, so a hit names where its verdict, log, junit and artifacts come from
outputs[].from.job_idstringRequired
uuidv7 rendered as job_<32 hex>
outputs[].from.task_idstringRequired
uuidv7 rendered as tsk_<32 hex>
outputs[].keystringRequired
sha-256 digest as sha256:<64 hex>
outputs[].outputsobjectRequired
a content-addressed blob the receiver fetches by presigned url
outputs[].outputs.digeststringRequired
sha-256 digest as sha256:<64 hex>
outputs[].outputs.downloadobjectRequired
a presigned get
outputs[].outputs.download.expires_atstring (date-time)Required
outputs[].outputs.download.urlstringRequired
outputs[].outputs.sizeintegerRequired
partialsarray of objects
the passed tests recorded under the partials keys; absent from older cells
partials[].binary_idstringRequired
partials[].keystringRequired
sha-256 digest as sha256:<64 hex>
partials[].testsarray of stringsRequired
curl -X POST "$CIRESK_API/v1/ci/cache/lookups" \
  -H "Authorization: Bearer $CIRESK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keys": [
      "sha256:11e0184e1acaf0c0f4c3a5e7be84998835bca8fed12b2d226b82a64811f0bd21"
    ],
    "outputs": [
      "sha256:318d9e972c8f5b5649b8ab8ffb7a7a7cea11e6953bcbb85d4b6d3a382bb2f5dc"
    ],
    "partials": [
      "sha256:2d903f40790faaa47111b63aa8ce91a580edae501379ac8cdc3f7e2b61280798"
    ],
    "repo": "repo_0129354d7b6b4146ad16c315d960365b",
    "task": "test"
  }'
POST/v1/ci/cache/revocations

Revoke cache rows by build

Refuse every cache row a worker build wrote, by release or parser hash.

Permission: ci:cache.adminCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringRequired

Request body

parserstring or null
reasonstringRequired
releasestring or null

Response200 OK

recordedbooleanRequired
false when the producer was already revoked
refusedintegerRequired
rows that name the producer, whatever their age
curl -X POST "$CIRESK_API/v1/ci/cache/revocations" \
  -H "Authorization: Bearer $CIRESK_KEY" \
  -H "Idempotency-Key: e426522a-4622-438e-a5c7-0f5fb46043cc" \
  -H "Content-Type: application/json" \
  -d '{
    "parser": "acme/platform",
    "reason": "a file in globals.inputs changed",
    "release": "acme/platform"
  }'
GET/v1/ci/cache/{key}

Read a cache entry

An action-cache entry in the readable namespaces.

Permission: ci:workers.cache

Parameters

NameTypeRequiredDescription
keypathstringRequiredThe cache key.
repoquerystringOptional
taskquerystringOptional

Response200 OK

content_digeststring or null
on a hit with outputs, sha-256 of their tar before compression, which the restore checks and the report carries for dependants' keys; absent from older cells and rows recorded before it
fromobject or null
the run a cache hit stands on: the job and task whose success was recorded under the key, so a hit names where its verdict, log, junit and artifacts come from
from.job_idstringRequired
uuidv7 rendered as job_<32 hex>
from.task_idstringRequired
uuidv7 rendered as tsk_<32 hex>
hitbooleanRequired
namespacestring or null
outputsobject or null
a content-addressed blob the receiver fetches by presigned url
outputs.digeststringRequired
sha-256 digest as sha256:<64 hex>
outputs.downloadobjectRequired
a presigned get
outputs.download.expires_atstring (date-time)Required
outputs.download.urlstringRequired
outputs.sizeintegerRequired
riskobject or null
on a hit, what decides its audit; absent from older cells
risk.age_daysinteger
whole days since the row was recorded or last refreshed
risk.auditsinteger
audits of the key in the last 7 days, and how many of them passed
risk.clean_auditsinteger
risk.failuresinteger
failures observed under the key in the last 7 days
risk.flakyboolean
the run the row stands on passed only on a retry (CIR-722): its green is a flip within one run
risk.foreignboolean
another tier recorded it
risk.holesinteger
key holes recorded under the key in the last 7 days: a run read a file the key does not cover
curl "$CIRESK_API/v1/ci/cache/f4bf843a1782c52f8a066d3e674da4bfe5081e41023f1ad885412017fec1bdb2" \
  -H "Authorization: Bearer $CIRESK_KEY"
POST/v1/ci/cache/{key}

Write a cache entry

A write-once action-cache entry.

Permission: ci:workers.cacheCommand: send Idempotency-Key

Parameters

NameTypeRequiredDescription
keypathstringRequiredThe cache key.
Idempotency-KeyheaderstringRequired

Request body

bytesintegerRequired
content_digeststring or null
sha-256 of the tar before compression, which the claim names beside the stored file's digest; absent from older workers
outputs_digeststringRequired
sha-256 digest as sha256:<64 hex>
producerobject or null
the worker build that wrote the row; absent from older workers
producer.parserstringRequired
producer.releasestringRequired
repo_idstringRequired
uuidv7 rendered as repo_<32 hex>
signaturestring or null
standard base64 of the worker's signature over the row's cache claim; a write without one records nothing
taskstringRequired
write_tokenstringRequired

Response201 Created

existedboolean
true when the key already held this digest
namespacestringRequired
outputs_digeststringRequired
sha-256 digest as sha256:<64 hex>
curl -X POST "$CIRESK_API/v1/ci/cache/f4bf843a1782c52f8a066d3e674da4bfe5081e41023f1ad885412017fec1bdb2" \
  -H "Authorization: Bearer $CIRESK_KEY" \
  -H "Idempotency-Key: 0a53cf10-bd36-468a-9bd3-04bc3e0864f4" \
  -H "Content-Type: application/json" \
  -d '{
    "bytes": 18432000,
    "content_digest": "sha256:925e14c4b20abd11d0de04c75c568fef25ffb1e15a1b82a73c5a993ca929c1fb",
    "outputs_digest": "sha256:7cf9d095df466528c49ea6cab229fb433ce465de3fd7407f998773542f070110",
    "producer": {
      "parser": "acme/platform",
      "release": "acme/platform"
    },
    "repo_id": "repo_0129354d7b6b4146ad16c315d960365b",
    "signature": "acme/platform",
    "task": "test",
    "write_token": "O3REKlF2j0jrgrhIZSbkTCTSLOAJTTVVRaJppy2c"
  }'