API & authentication

The CLI is a thin wrapper over the control-plane REST API. You can call the same API directly for automation.

Base URL & authentication

Base URL: https://cps.run (override with CPS_API_URL).
Auth: the Authorization: Bearer <token> header. Issue a token with cps token create (or, as an admin, cps admin token issue).
Scoping: a token is bound to your organization; you can only see and mutate your org’s resources.
A token is a secret: shown once, keep it out of git, revoke with cps token rm.

Liveness check (no auth):

curl -s https://cps.run/healthz
# {"status":"ok"}

Who am I:

curl -s https://cps.run/v1/whoami -H "Authorization: Bearer $CPS_TOKEN"

Resource model

org ──┬── project ──┬── machine ──┬── snapshot
      │             │             └── backup
      │             └── route (ingress) / secret
      └── (quota: cpu / ram / disk / max-machines)

Almost everything is project-scoped and lives under /v1/projects/{project_id}/…. The default project is prj_default.

Core endpoints

Method + path	Purpose
`GET /v1/whoami`	Current principal.
`GET /v1/projects`	Org projects.
`GET /v1/projects/{p}/machines`	List machines (`?include_deleted=true`).
`POST /v1/projects/{p}/machines`	Create a machine (JSON body: image, resources, ttl…).
`POST /v1/projects/{p}/machines/{m}:start` \| `:stop`	Start / stop (async operation).
`DELETE /v1/projects/{p}/machines/{m}`	Delete.
`GET /v1/projects/{p}/operations/{op}`	Async operation status.
`GET \| POST /v1/projects/{p}/snapshots`	List / create snapshots.
`GET \| POST /v1/projects/{p}/backups`	List / create backups.
`GET \| POST /v1/projects/{p}/routes`	Ingress routes (`expose`).
`GET \| POST \| DELETE /v1/tokens`	Manage tokens.
`GET \| POST /v1/images`	Image registry.

Async operations

Mutating actions (create/start/stop/snapshot/backup/restore) return an operation and run asynchronously. Poll its status to wait for completion:

# create a machine → take operation_id from the response, then poll:
curl -s https://cps.run/v1/projects/prj_default/operations/$OP \
  -H "Authorization: Bearer $CPS_TOKEN"
# status moves pending → running → succeeded | failed

The CLI does this for you with --wait.

Example: list machines

curl -s https://cps.run/v1/projects/prj_default/machines \
  -H "Authorization: Bearer $CPS_TOKEN" | jq .

Error codes

Code	Meaning
`401`	Missing/invalid token.
`403`	Token valid, but no access to the resource (another org / an admin path).
`404`	Resource not found in your scope.
`409`	State conflict (e.g. an action on a machine in the wrong state).
`429`	Rate limit exceeded; see the `Retry-After` header.

The API is under active development (alpha) and may change. For stable workflows, prefer the CLI. The full request/response contract lives in the contracts repository.

Keyboard shortcuts