HTTP API

The web app uses this API, and you can too: start tasks from scripts, follow their events or answer approvals from other tools. The API is served by the control plane, http://127.0.0.1:8787 by default.

#Authentication

Send your owner token on every request:

SHELL
curl -H "Authorization: Bearer $CCR_CLOUD_TOKEN" http://127.0.0.1:8787/api/sessions

The event stream also accepts ?token= because browsers' EventSource can't set headers. GET /api/health and the web app's static files need no token.

Errors return JSON, {"error": "..."}, with a matching status code: 400 for invalid input, 401 without a valid token, 404 for an unknown task or request, and 409 when the request conflicts with the task's state.

#Start a task

SHELL
curl -X POST http://127.0.0.1:8787/api/sessions \
  -H "Authorization: Bearer $CCR_CLOUD_TOKEN" -H "Content-Type: application/json" \
  -d '{"prompt": "Reply OK", "permissionMode": "default", "outputStyle": "concise"}'

POST /api/sessions body (all fields optional):

FieldDescription
promptFirst message. The title defaults to its first line.
titleTask title.
projectIdA saved project to work in.
repoClone URL, when not using a project. Work happens on branch ccr/SESSION_ID.
baseBranchBranch to start from.
modelClaude model name. Omit to use the default (or CCR's routing).
permissionModedefault, acceptEdits, auto, plan, dontAsk or bypassPermissions. Omit for the host default. See Permissions.
modelRouteaccount (the server user's Claude login) or ccr (the CCR gateway). Defaults to account in host mode and ccr in Docker mode. ccr needs a configured gateway; Docker mode has no account. See Switch models with CCR.
outputStyledefault or concise. Omit to use the server's own setting. See Response style.

It returns the task record with status 201.

#Sessions

RouteDescription
GET /api/sessionsAll tasks.
GET /api/sessions/:idOne task, including state, openPermissions, permissionMode, outputStyle and modelRoute.
GET /api/sessions/:id/events?from=NThe task's event log from offset N. Send Accept: text/event-stream for live server-sent events; reconnects resume from Last-Event-ID.
GET /api/sessions/:id/changesThe latest summary of what the task changed since it started: {base, at, files: [{path, added, removed, binary, truncated?}], omittedFiles}. Add ?file=PATH for one file, including its patch. Available after the task stops.
POST /api/sessions/:id/prPush the task's branch and open a pull request: {"title": "…", "body"?: "…", "draft"?: true, "commitAll"?: true, "base"?: "main"}. Repository tasks only, while idle; returns 202, and the result arrives as a pull_request or pull_request_failed event and in the task's pullRequest.
POST /api/sessions/:id/messagesSend a follow-up: {"text": "..."}. Returns 409 if the task is stopped.
POST /api/sessions/:id/permissions/:requestIdAnswer an approval: {"behavior": "allow" \| "deny", "message"?: "..."}.
POST /api/sessions/:id/interruptInterrupt the current turn.
POST /api/sessions/:id/stopStop the task, keeping its workspace.
POST /api/sessions/:id/startResume a stopped task. Optional body {"modelRoute": "account" \| "ccr"} moves it to that route first (host mode; 409 while the task is running).
DELETE /api/sessions/:idDelete the task, its workspace and its log.

A task's state is one of pending, cloning, idle, running, waiting (approval needed), exited or failed.

#Projects

RouteDescription
GET /api/projectsSaved projects.
POST /api/projectsCheck a clone URL and save it: {"name": "...", "repo": "URL"}. Returns 422 with the check if the repository isn't readable.
POST /api/projects/checkCheck a clone URL without saving: {"repo": "URL"}.
GET /api/local-repositoriesRepositories discovered on the server (host mode).
POST /api/projects/localSave a discovered checkout: {"path": "...", "name"?: "..."} (host mode).
PUT /api/projects/:id/setupSet a project's setup: {"script": "npm ci", "env": {"NAME": "value"}}. An empty script and env remove it. Reserved variable names are refused with 400.
GET /api/setupWhich execution mode is in use, how credentials are handled, and whether a CCR gateway is configured (ccrGateway).

#Notifications

RouteDescription
GET /api/push/keyThe server's public push key.
GET /api/push/subscriptionsRegistered devices.
POST /api/push/subscriptionsRegister a device: {"subscription": {...}, "label"?: "..."}.
DELETE /api/push/subscriptionsRemove a device: {"endpoint": "..."}.
POST /api/push/testSend a test notification to every device.
POST /api/push/actionA notification button's decision: {"token": "…"}. The signed token from the push payload is the authorization; no owner token. 403 for an invalid or expired token, or Allow for a tool that isn't read-only; 409 if the request is no longer open.

#Devices

RouteDescription
POST /api/pairingCreate a single-use pairing code, valid for 10 minutes: {code, expiresAt}. Open /#pair=CODE on the device.
POST /api/pairExchange {"code": "…", "label"?: "…"} for a device token, without other authentication: {token, device}. 403 if the code is unknown, used or expired.
GET /api/devicesPaired devices; current marks the caller.
DELETE /api/devices/:idRevoke a device and remove its push subscriptions.

A device token works anywhere the owner token does.

#Health

GET /api/health returns {"service": "ccr-cloud", "status": "ok", "apiVersion": 3} without authentication. If apiVersion is missing or lower, an older control plane is running; see Troubleshooting.

Edit this page on GitHub ↗