HTTP API

The HTTP API is JSON over HTTPS. The SDK, the CLI and the Dashboard all use it. Every route is under /v1:

https://api.cubicle.sh/v1

The TypeScript SDK wraps this API: it waits for asynchronous requests, retries safely and paces its requests for you. There is no official SDK for other languages yet. From other languages, shell scripts and tools, call the HTTP API directly, or generate a client from the OpenAPI document.

Make a first requestCopy Anchor Link

You need an API key (cbk_…) that belongs to a service account. Sign in and API keys shows how to create one.

export CB_SDK_API_KEY=cbk_…

curl https://api.cubicle.sh/v1/me \
  -H "Authorization: Bearer $CB_SDK_API_KEY"

The response says who the key belongs to:

{
  "id": "8e0a2c4e-6b8d-4f1a-a3c5-9e1b3d5f7a9c",
  "identity": "acme/ci",
  "operator": false,
  "orgs": [
    {
      "id": "6b1f3d2a-8c4e-4f7a-9b2d-1e5c7a9f3b6d",
      "name": "acme",
      "role": "member",
      "personal": false,
      "boxCreateAllowed": true
    }
  ],
  "apiKey": {
    "id": "4b6d8f0a-2c4e-4a6b-8d0f-1a3c5e7b9d2f",
    "orgId": "6b1f3d2a-8c4e-4f7a-9b2d-1e5c7a9f3b6d",
    "scope": "write"
  }
}

• identity is the key's service account, ORG/NAME.
• orgs holds only the key's organization. boxCreateAllowed says whether you can create Boxes in it.
• apiKey.scope is write or read. A read key may only send GET requests.

Next, create a Box. The request returns 202 Accepted at once, with the Box in state pending:

curl -X POST https://api.cubicle.sh/v1/orgs/acme/boxes \
  -H "Authorization: Bearer $CB_SDK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name": "job-1"}'

Poll the Box until ssh.ready is true, as Following a request describes, then run commands in it with Run a command. Delete it with Delete a Box when you are done.

ConventionsCopy Anchor Link

Box and organization referencesCopy Anchor Link

{box} in /v1/boxes/{box}/… takes a Box ID, ORG/NAME or a bare NAME. Box references explains how each form resolves. In a path:

• Encode the slash in ORG/NAME as %2F, as in /v1/boxes/acme%2Fjob-1. Unencoded, the path names a different route.
• Narrow a bare NAME with ?org=, which takes an organization's name or ID: /v1/boxes/job-1?org=acme. ?org= is ignored when {box} is an ID.

{org} in /v1/orgs/{org}/… is the organization's name or ID. An organization where you are not an active member returns 404 not_found, and so does every organization except an API key's own.

Version and OpenAPI documentCopy Anchor Link

/v1 is the only version of the API.

https://docs.cubicle.sh/openapi.json describes every public endpoint as an OpenAPI 3.1 document: parameters, request and response schemas, examples, errors and code samples (x-codeSamples). The endpoint pages below are generated from it. Give it to a client generator, or to a coding agent that needs the whole API. See Docs for AI tools for the plain-text docs.

EndpointsCopy Anchor Link

Routes that accept API keys have an SDK method. The others, apart from the two device sign-in routes that need no credentials, need a sign-in session; an API key gets 403 api_key_not_allowed there. See Authentication.

BoxesCopy Anchor Link

Create Boxes, read them, and change their desired state.

CommandsCopy Anchor Link

Run commands in a Box and follow the operations that carry them out.

SnapshotsCopy Anchor Link

Save a stopped Box's disk, restore it, and create Boxes from snapshots.

Box accessCopy Anchor Link

Grant people and service accounts access to a Box, and read its SSH details.

OrganizationsCopy Anchor Link

List and change an organization's members.

Service accountsCopy Anchor Link

Manage non-interactive members and their API keys.

AccountCopy Anchor Link

The signed-in caller, their sessions and their SSH keys.

Sign-inCopy Anchor Link

Sign a device in with the device authorization flow, and sign out.