Ciresk Docs

Ciresk dev API

The REST API behind ciresk dev and its MCP tools: sessions, their access and sharing, and the organization's policy, templates, usage and logs. Every endpoint is in the reference below, generated from the API's OpenAPI document.

Quickstart

Create a key on platform.ciresk.com under OrganizationAPI keys (Organization, then API keys) with New API key and the product Ciresk Dev. The key 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://api.eu.ciresk.com
export CIRESK_KEY=csk_live_eu_...

List your live sessions:

curl
curl -s "$CIRESK_API/v1/dev/sessions?limit=5" \
  -H "Authorization: Bearer $CIRESK_KEY"

Read your and your organization's use against the policy's budgets:

curl
curl -s "$CIRESK_API/v1/dev/usage" \
  -H "Authorization: Bearer $CIRESK_KEY"

A key acts for the person who created it: the sessions it lists, starts and stops are that person's, and the organization's dev policy applies to them as to the person.

What the CLI does for you

Starting a session from your own code takes more than one call: POST /v1/dev/sessions creates the session or returns the worktree's live one, then the client pushes the worktree's tree, opens the tunnel with a device key and a ticket of at most 30 seconds, and keeps the files in sync. ciresk dev up does all of it. Use the API for what is one call: reading sessions and their events, stopping them, sharing them, raising and answering needs, the policy, templates, usage, the connection and egress logs, and the kill switch.

Base URL and conventions

Every endpoint is under https://api.eu.ciresk.com/v1/dev. The version is part of the path.

  • Requests and responses are JSON, with snake_case fields. Changes are additive: clients ignore unknown fields.
  • IDs are prefixed: a session is devs_, a device grant devg_ and a member devm_, followed by 32 hex characters.
  • Lists page with cursor and limit (at most 200, 50 by default) and answer data, has_more and next_cursor; see Pagination.
  • Stopping, pausing and starting a session and the kill switch take an Idempotency-Key header; a retry with the same key acts once. See Idempotency.
  • Errors are application/problem+json with a stable code, and many carry next, the exact command that fixes them. See Errors.
  • GET /v1/dev/sessions/{session_id} waits for a state with wait_for (at most 25 seconds) and GET /v1/dev/sessions/{session_id}/events follows the session's journal with follow; call again while the session is still on its way.

Good to know

  • The CLI is the reference client: ciresk dev <command> --json prints what the API answers in one JSON envelope.
  • Agents reach the same capabilities through ciresk dev mcp, the dev_session_* MCP tools, which call this API with the person's credential.
  • The platform-wide rules every endpoint below follows are on this tab: API keys, Scopes, Regions, Idempotency, Pagination, Errors and Request IDs.

Reference

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

Sessions

Sessions8 endpointsStart a session for a worktree or return its live one, read it, follow its events, update and stop it.Dotfiles4 endpointsYour dotfiles repository, cloned and installed in the read-write shell of every new session you own.Schedules3 endpointsAutostart a paused session, or a template's session, at a local time on chosen days.Auth1 endpointWho the API sees you as: subject, kind, organization, region and dev scopes.Tunnel5 endpointsDevice grants, tunnel tickets of at most 30 seconds, one-time browser links and the client side of the tunnel.

Collaboration

Members3 endpointsGive organization members view or use on a session, list them and revoke them.Needs4 endpointsAn agent tells its person it is blocked on them; the person replies or dismisses it.CI records2 endpointsCiresk CI jobs attached to a session as evidence, each checked against the trees the session applied.

Administration

Policy3 endpointsThe organization's dev policy: lifecycle limits, budgets, egress ceilings, templates and extras.Templates3 endpointsPublish a template as an organization version, list versions and promote one for a repository pattern.Usage1 endpointYour and your organization's dev use against the policy's budgets.Egress log1 endpointWhat a session's egress proxy let out and refused, with the change that would let a refusal out.Connections1 endpointThe connection log: who reached which session, from which device, by which stream.Secrets3 endpointsThe organization's session secrets, their bound hosts and who may use them; a value is never read back.Audit3 endpointsThe audit trail of the organization's sessions, and how many months it is kept.Export and erasure6 endpointsExport the organization's dev data as a signed archive, or erase it after a 24-hour grace.Kill switch1 endpointStop one session, one owner's sessions or every session of the organization now.