Ciresk Docs

Ciresk CI API

The REST API behind the ciresk ci CLI, the GitHub Action and the MCP endpoint, for your scripts, servers and integrations; every endpoint is in the reference below.

Quickstart

Create a key on platform.ciresk.com under API tokens with Create token and the Ciresk CI permissions it needs. The token is shown once and starts with csk_live_eu_ for an organization in the EU region. Then set two variables:

Shell
export CIRESK_API=https://ci.eu.ciresk.com
export CIRESK_KEY=csk_live_eu_...

List your organization's recent jobs:

curl -s "$CIRESK_API/v1/ci/jobs?limit=2" \
  -H "Authorization: Bearer $CIRESK_KEY"

Read one job's summary, the same bounded verdict the CLI prints:

curl
curl -s "$CIRESK_API/v1/ci/jobs/$JOB/summary" \
  -H "Authorization: Bearer $CIRESK_KEY"

Submit a job. The Idempotency-Key makes a retry safe; repo_id, manifest_digest and manifest_path name the registered repository and the governing .ciresk/ci.yaml:

curl
curl -s -X POST "$CIRESK_API/v1/ci/jobs" \
  -H "Authorization: Bearer $CIRESK_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: nightly-check-2026-10-20" \
  -d '{
    "repo_id": "repo_01a158ec98b4791ca6e9d35ff2b1c0d4",
    "manifest_digest": "sha256:9f2c...",
    "manifest_path": ".ciresk/ci.yaml",
    "kind": "check",
    "base_ref": "main",
    "base_digest": "1d6ccb175d0e4a3b2c1f0e9d8c7b6a5f4e3d2c1b",
    "actor": "ci:nightly",
    "client": "api"
  }'

The answer is 201 with the job, its budget and the policy that applied, or 200 with deduplicated: true when an identical job is already queued or running. Then GET /v1/ci/jobs/{id}/wait blocks up to 55 s for a terminal state, and GET /v1/ci/jobs/{id}/summary is the verdict. The CLI does the tree upload for you; submitting a working tree from your own code means walking the Trees and Blobs endpoints first.

Base URL and versions

Every endpoint is under https://ci.eu.ciresk.com/v1/ci, except the probes GET /health and GET /ready. The API version is part of the path. The reference below is generated from the API's OpenAPI 3.1 document, and GET /v1/ci/version answers the cell's version and region.

  • Requests and responses are JSON, with snake_case fields. Changes are additive: clients ignore unknown fields.
  • IDs are short and prefixed: job_, repo_, tsk_, wrk_, ws_, whk_ followed by 32 hex characters.
  • Digests are sha256: followed by 64 hex characters; commit SHAs are bare hex.
  • Times are RFC 3339 in UTC. Durations are milliseconds (duration_ms); sizes are bytes.
  • Cost is in cost units: one vCPU-second of the executing worker.

Long-running jobs

A submitted job is queued, then leased, running and finally succeeded, failed, cancelled, timed_out or infra_error.

WantEndpoint
Block until it finishesGET /v1/ci/jobs/{id}/wait: up to 55 s (timeout, 45 s by default); the summary once the job is terminal, otherwise its state and poll_after_ms; call again while it runs.
Follow it liveGET /v1/ci/jobs/{id}/events: the job's journal as server-sent events.
The verdictGET /v1/ci/jobs/{id}/summary: under 2,000 tokens, with next, the exact follow-up call.
Stop itPOST /v1/ci/jobs/{id}/cancel: cooperative; the job reports cancelled once the task is gone.

Budgets and limits

The response to a submitted job carries budget: {session, day, concurrent, resets_at} for the calling actor. Past the hard cap the answer is 403 budget_exceeded with resets_at; past the concurrency limit 429 concurrency_limited with retry_after. Over the tree sync request rate limit the answer is 429 rate_limited with a Retry-After header in seconds. Wait that long, then retry with the same idempotency key. GET /v1/ci/budget shows the whole picture: budget, policy and principal.

Webhooks

Webhook endpoints can be registered, but no deliveries are sent yet; follow a job with GET /v1/ci/jobs/{id}/events or /wait instead. POST /v1/ci/webhooks registers one (url, events from job.started, task.finished, job.finished and job.cancelled, and optionally repo to limit it to one repository) and shows its signing secret once; GET /v1/ci/webhooks lists them and POST /v1/ci/webhooks/{id}/delete removes one. An organization has at most 20.

Good to know

  • The CLI is the reference client: ciresk ci <command> --json shows exactly what the API answers, in the same envelope, and ciresk ci contract prints the JSON schemas. See CLI commands.
  • Agents use the same API through the MCP endpoint at https://ci.eu.ciresk.com/v1/ci/mcp; see How it works.
  • Workers talk to the same API with their own token: registration, heartbeats, leases, log chunks and reports are the Workers, Logs and Tasks endpoints that take the worker scopes (ci:workers.lease, ci:workers.heartbeat, ci:workers.report); registration itself takes the enrolment secret.
  • The platform-wide rules every endpoint below follows are on this tab: API keys, Scopes, Regions, Idempotency, Pagination, Errors and Request IDs.

Reference

All 93 endpoints, generated from the OpenAPI document. The examples read the base URL and an API key from the two variables of the quickstart above.

Jobs

Jobs9 endpointsSubmit a job, read it, wait for it, stream its events, read its summary and cancel it.Tasks4 endpointsA job's tasks: one per manifest task and shard, with their lease, result and artifacts.Tests1 endpointTest results ingested from a task's JUnit report, failing tests first.Logs4 endpointsBounded slices of a task's log: failed-only, the tail, a grep with context or a byte range.Artifacts3 endpointsFiles a task uploaded after its run, with time-limited download URLs.Schedules3 endpointsRuns a branch's manifest starts on a timer: list them with their last run, pause one, run one now.Approvals2 endpointsTasks that wait for a person's decision: list the gates waiting for you, approve or reject one.

Repositories

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

Trees

Trees4 endpointsA working tree as a Merkle tree of content digests: which blobs the cell lacks, and how to send and fetch them.Blobs4 endpointsContent-addressed blobs: declare one inline or through a presigned upload, check it exists, and download it.Cache5 endpointsWrite-once action-cache entries keyed by content, read in the namespaces the caller's trust tier allows.Parts1 endpointRegistered versions of restricted parts, each fetched by name and ref with a signed download URL.Toolchains1 endpointRetire toolchain packs the cell store signed for your organization, by tool, version or publishing worker.

Workers

Workers25 endpointsEnrol, register, list and deregister workers, and the worker protocol: heartbeats and task leases.Workspaces2 endpointsThe warm workspaces and mirror commits workers hold, and evictions.Queue1 endpointQueued tasks per label set, which worker factories poll to start instances.

Account

Auth3 endpointsExchange an OIDC token from GitHub Actions or an agent sandbox for a one-hour cell token.OIDC2 endpointsEach organisation as an OIDC issuer: its discovery document and the keys a cloud verifies a task's ID token with.Budget1 endpointYour spend and limits for the session and the day, the policy that applies and who you are.Policy2 endpointsThe effective policy for the tenant or a repository, with the source of every field, and overrides.Audit1 endpointThe append-only audit log: every job, lease, policy change and key use.Webhooks3 endpointsSigned webhooks for job state changes.

System

System4 endpointsLiveness, readiness, the cell's version and region, and its public status.