Cubicles
Cubicles docs

REST API reference

Everything an API key can do. Send Authorization: Bearer cub_… on every request; JSON in and out.

Conventions

TopicRule
Base URLhttps://api.cubicles.cloud/api/v1
AuthAuthorization: Bearer cub_… on every request. A key acts as the user who made it; no CSRF header or cookies needed.
FormatJSON in and out, camelCase fields, ISO-8601 UTC timestamps, prices in integer cents
Errorsapplication/problem+json with a stable code to branch on (see Errors). Every response has an X-Request-Id: quote it when reporting a problem.
Rate limitsOver a limit answers 429 too_many_attempts with Retry-After in seconds. Commands and screenshots: 120 a minute per account.
Keyscub_ and 43 characters, shown once when made. Up to 25 per account, optionally expiring. A wrong, expired or deleted key gets 401 invalid_api_key.

All endpoints

MethodPathAuthWhat
GET/meAPI keyThe user the key acts as
GET/catalogPublicPlans, operating systems and regions on sale
GET/desktopsAPI keyYour desktops, newest first
GET/desktops/{id}API keyOne desktop
POST/desktops/{id}/startAPI keyStart a stopped desktop
POST/desktops/{id}/stopAPI keyShut a running desktop down
POST/desktops/{id}/restartAPI keyRestart a running desktop
POST/desktops/{id}/execAPI keyRun a shell command and wait for its output
GET/desktops/{id}/screenshotAPI keyA JPEG of the screen
POST/desktops/{id}/filesAPI keyUpload a file to the Desktop folder
GET/desktops/{id}/filesAPI keyList the files and folders in a folder
GET/desktops/{id}/files/downloadAPI keyDownload a file from anywhere on the computer
POST/desktopsAPI keyCreate a desktop
GET/desktops/{id}/checkoutAPI keyWhether a checkout has been paid
DELETE/desktops/{id}API keyDelete a desktop whose subscription is canceled
GET/desktops/{id}/sharesAPI keyThe desktop's shares that haven't ended
POST/desktops/{id}/sharesAPI keyShare the desktop
DELETE/desktops/{id}/shares/{shareId}API keyEnd a share and disconnect its guests
GET/agents/catalogAPI keyHarnesses, model providers and chat apps
GET/agentsAPI keyYour agents, newest first
GET/agents/{id}API keyOne agent
POST/agentsAPI keySet an agent up on a desktop
POST/agents/{id}/redeployAPI keySet a ready or failed agent up again
POST/agents/{id}/linkAPI keyShow the WhatsApp and Signal QR codes on the desktop again
DELETE/agents/{id}API keyRemove an agent from its desktop
GET/billing/upcomingAPI keyThe next charge of every desktop, before tax
GET/invoicesAPI keyPast invoices, newest first
GET/invoices/{id}/pdfAPI keyRedirect to the invoice PDF
GET/payment-methodsAPI keyThe cards on file (display details only)
GET/api-keysBrowser session onlyYour keys that haven't expired
POST/api-keysBrowser session onlyMake a key (shown once)
DELETE/api-keys/{id}Browser session onlyDelete a key: requests with it fail from now on

Account and catalogue

Who the key belongs to, and what can be bought.

GET/me

The user the key acts as. API key

Response
{
  "id": "a0000000-0000-0000-0000-000000000001",
  "fullName": "Ada Lovelace",
  "email": "ada@example.com",
  "emailVerified": true,
  "createdAt": "2026-08-14T00:00:00Z",
  "termsAccepted": true,
  "role": "user"
}

GET/catalog

Plans, operating systems and regions on sale. Public

Prices are integer cents before tax. available is false while no server has room for a plan; reason is then sold_out or no_server. Cached for 30 seconds.

Response
{
  "plans": [
    { "id": "standard", "name": "Standard", "vcpu": 4, "memoryGb": 8, "diskGb": 120,
      "monthlyPriceCents": 2400, "description": "Agents juggling browser, docs and sheets.",
      "popular": true, "available": true, "reason": null, "details": null }
  ],
  "operatingSystems": [
    { "id": "ubuntu", "name": "Ubuntu Desktop", "versionLabel": "24.04 LTS · GNOME", "monthlySurchargeCents": 0 }
  ],
  "regions": [ { "id": "fra", "name": "Frankfurt", "code": "eu-c" } ],
  "currency": "usd"
}

Desktops

A desktop is a cloud computer: Ubuntu 24.04 with a GNOME desktop, on until it's stopped. Its user is named after the desktop and has passwordless sudo.

Desktop fieldNotes
statusawaiting_payment, provisioning, starting, running, stopping, stopped, restarting, deleting or failed. The in-between ones change by themselves within seconds to minutes, so poll.
statusProgress0–100 while provisioning or starting, else null
statusMessageA sentence about the status ("Starting Ubuntu…", why it failed), or null
monthlyPriceCentsWhat's billed each month, before tax
freeThe account's free desktop: nothing is billed, and it can be deleted any time
subscriptionStatusactive, past_due or canceled; null until the payment is confirmed
nextChargeAtEnd of the current billing period; null when canceled
cancelAtWhen a scheduled cancellation deletes the desktop; null if none
allowedActionsWhat can be done now: stop and restart while running, start while stopped, delete once the subscription is canceled

GET/desktops

Your desktops, newest first. API key

Answers { "items": [Desktop, …] }. A desktop is listed once its payment is confirmed.

GET/desktops/{id}

One desktop. API key

FieldRule
statusawaiting_payment, provisioning, starting, running, stopping, stopped, restarting, deleting or failed. The in-between ones change by themselves within seconds to minutes, so poll.
statusProgress0–100 while provisioning or starting, else null
statusMessageA sentence about the status ("Starting Ubuntu…", why it failed), or null
monthlyPriceCentsWhat's billed each month, before tax
freeThe account's free desktop: nothing is billed, and it can be deleted any time
subscriptionStatusactive, past_due or canceled; null until the payment is confirmed
nextChargeAtEnd of the current billing period; null when canceled
cancelAtWhen a scheduled cancellation deletes the desktop; null if none
allowedActionsWhat can be done now: stop and restart while running, start while stopped, delete once the subscription is canceled
Response
{
  "id": "d0000000-0000-0000-0000-000000000003",
  "name": "atlas",
  "plan": { "id": "pro", "name": "Pro", "vcpu": 8, "memoryGb": 16, "diskGb": 240 },
  "os": { "id": "ubuntu", "name": "Ubuntu Desktop" },
  "region": { "id": "fra", "name": "Frankfurt", "code": "eu-c" },
  "status": "running",
  "statusProgress": null,
  "statusMessage": null,
  "monthlyPriceCents": 4800,
  "currency": "usd",
  "subscriptionStatus": "active",
  "nextChargeAt": "2026-12-05T10:00:00Z",
  "cancelAt": null,
  "createdAt": "2026-11-05T10:00:00Z",
  "allowedActions": ["open_session", "stop", "restart"]
}
StatusCodeWhen
404not_foundNot your desktop, or no such id

POST/desktops/{id}/start

Start a stopped desktop. API key

No body. Answers 200 with the Desktop, now starting; it's running a minute or two later (a first start takes a few minutes), so poll GET /desktops/{id}. /stop and /restart work the same way: stop shuts Ubuntu down and forces it off after two minutes; the disk is kept.

StatusCodeWhen
404not_foundNot your desktop, or no such id
409action_not_allowedNot offered in the current status (see allowedActions)

POST/desktops/{id}/stop

Shut a running desktop down. API key

As /start. Programs running on it stop; its disk is kept.

StatusCodeWhen
404not_foundNot your desktop, or no such id
409action_not_allowedNot offered in the current status

POST/desktops/{id}/restart

Restart a running desktop. API key

As /start. Programs running on it stop.

StatusCodeWhen
404not_foundNot your desktop, or no such id
409action_not_allowedNot offered in the current status

POST/desktops/{id}/exec

Run a shell command and wait for its output. API key

Runs as the desktop's user (passwordless sudo) with bash -lc, in their home folder, with DISPLAY=:1 so graphical programs open on the screen. A command still running at timeoutSeconds is stopped. Background a program that should keep running with nohup … &.

exitCode is 124 when it ran out of time. stdout and stderr keep their first 100,000 characters each; truncated says one was longer. Commands and screenshots together are limited to 120 a minute per account.

Each command has about a second of fixed overhead, so timeoutSeconds bounds the command, not the request. At most 8 commands and screenshots run on one desktop at once; more wait in line for up to 30 seconds, so parallel calls queue rather than fail.

Request
{ "command": "cat > notes.txt && wc -c notes.txt", "stdin": "hello\n", "timeoutSeconds": 60 }
FieldRule
commandRequired, at most 16 KiB. Send a longer script as stdin to bash -s.
stdinOptional, at most 512 KiB of UTF-8
timeoutSeconds1 to 300, default 60
Response
{ "exitCode": 0, "stdout": "6 notes.txt\n", "stderr": "", "timedOut": false, "truncated": false }
StatusCodeWhen
400validation_failedNo command, or a field over its limit
404not_foundNot your desktop, or no such id
409desktop_not_runningThe desktop isn't running
429too_many_attemptsOver 120 commands and screenshots a minute
429desktop_busy8 commands were already running on it for the 30 seconds this one waited; see Retry-After
502desktop_unreachableThe desktop didn't answer: still starting, or its guest agent is down (restart it)
503server_busyIts server had no room for another command in time; see Retry-After

GET/desktops/{id}/screenshot

A JPEG of the screen. API key

image/jpeg, at most 1920 pixels wide. Counts toward the 120 a minute of exec.

StatusCodeWhen
404not_foundNot your desktop, or no such id
409desktop_not_runningThe desktop isn't running
429too_many_attemptsOver the rate limit
429desktop_busyToo many commands at once on the desktop; see Retry-After
502desktop_unreachableThe desktop didn't answer

POST/desktops/{id}/files

Upload a file to the Desktop folder. API key

multipart/form-data with one file in the file part, at most 100 MB. It lands in ~/Desktop under its own name; if that's taken, the new one becomes name (1).ext. Upload files one at a time. To get a file back, use GET /desktops/{id}/files/download.

Response
{ "name": "report (1).pdf", "size": 482113 }
StatusCodeWhen
400validation_failedNo file part, or an unusable name
404not_foundNot your desktop, or no such id
409desktop_not_runningThe desktop isn't running
413file_too_largeOver 100 MB
502upload_failedThe desktop didn't take it (disk full, or not answering)

GET/desktops/{id}/files

List the files and folders in a folder. API key

?dir= the folder's absolute path; without it, ~/Desktop. Read as the desktop's user. Hidden ones are included; folders come first, then files, each newest first, at most 500 (truncated if there were more). dir is the folder's real path, parent the one it's in (null for /), home the user's home folder.

Response
{ "dir": "/home/atlas/Desktop", "parent": "/home/atlas", "home": "/home/atlas", "truncated": false, "items": [ { "name": "report (1).pdf", "size": 482113, "modifiedAt": "2026-11-09T10:15:02.250Z", "folder": false } ] }
StatusCodeWhen
400validation_faileddir isn't an absolute path
403folder_not_readableThe desktop's user can't read that folder
404not_foundNot your desktop, or no such id
404folder_not_foundNo folder there
409desktop_not_runningThe desktop isn't running
502desktop_unreachableThe desktop didn't answer

GET/desktops/{id}/files/download

Download a file from anywhere on the computer. API key

?path= the file's absolute path (or ?name= a file in ~/Desktop); at most 100 MB, read as the desktop's user. Answers with the file as application/octet-stream, an attachment with its name, and Content-Length. It comes out of the desktop a few MB at a time; if the desktop stops answering on the way, the response is cut short of its Content-Length.

StatusCodeWhen
400validation_failedNo path, or one that isn't absolute
403file_not_readableThe desktop's user can't read that file
404not_foundNot your desktop, or no such id
404file_not_foundNo file there
409desktop_not_runningThe desktop isn't running
413file_too_largeOver 100 MB
502desktop_unreachableThe desktop didn't answer

POST/desktops

Create a desktop. API key

A paid desktop: holds the name and creates a payment. Answers 201 with a checkoutUrl for a person to pay at; the desktop appears in GET /desktops once paid. Unpaid checkouts are released after 15 minutes. Poll GET /desktops/{id}/checkout: any status other than awaiting_payment means it's paid.

With "free": true, the account's free desktop (the plan in GET /catalog's freePlan, one per account): created at once and starts provisioning, with transactionId and checkoutUrl null. Poll GET /desktops/{id} until it is running.

Request
{ "name": "atlas", "planId": "standard", "osId": "ubuntu", "regionId": "fra", "free": true }
FieldRule
name3–32 characters of a-z, 0-9 and -, starting with a letter. It becomes the desktop's Ubuntu user.
freeOptional. true for the account's free desktop; left out to pay.
Response
{ "desktopId": "…", "transactionId": "txn_01…", "checkoutUrl": "https://cubicles.cloud/pay?_ptxn=txn_01…" }
StatusCodeWhen
400validation_failedA bad name, or a name Ubuntu already uses (root, ubuntu)
400plan_unavailableUnknown plan (also os_unavailable, region_unavailable)
400free_plan_unavailablefree with a plan other than the free one
409too_many_desktopsfree, but the account already has its free desktop
409plan_sold_outNo server has room for the plan right now
409name_takenAnother desktop in that region has the name

GET/desktops/{id}/checkout

Whether a checkout has been paid. API key

Response
{ "desktopId": "…", "status": "awaiting_payment" }
StatusCodeWhen
404not_foundNot your desktop, or no such id

DELETE/desktops/{id}

Delete a desktop whose subscription is canceled. API key

Only once the subscription was canceled (delete in allowedActions). Ends the subscription now and destroys the desktop and its disk. Nothing is refunded. Answers 202 with the Desktop, deleting.

A free desktop can be deleted at any time. Answers 202 with the Desktop, deleting.

A desktop whose checkout is still open (awaiting_payment) can be deleted too: its checkout is canceled and its name freed. Answers 202 with the Desktop, deleted.

Request
{ "confirmName": "atlas" }
StatusCodeWhen
400confirm_name_mismatchconfirmName isn't the desktop's name
404not_foundNot your desktop, or no such id
409subscription_activeCancel the subscription first (in the web app's billing)
409action_not_allowedAlready being deleted, or the open checkout was just paid

Sharing

Share a desktop's screen: a view-only link, or an invitation for one email address to use it too. Guests open the link in a browser.

GET/desktops/{id}/shares

The desktop's shares that haven't ended. API key

{ "items": [Share, …] }, oldest first.

StatusCodeWhen
404not_foundNot your desktop, or no such id

POST/desktops/{id}/shares

Share the desktop. API key

access is view or control. email is required for control; leave it out of a view link anyone holding it can open. With an email, the invitation is emailed. url is only in this answer: keep it.

Request
{ "access": "view", "expiresInMinutes": 60 }
FieldRule
accessview (watch only) or control (use it too)
emailWho may open it; required for control
expiresInMinutes1 to 43200, or null for never
Response
{
  "id": "6f1c…",
  "access": "view",
  "email": null,
  "expiresAt": "2026-11-05T11:00:00Z",
  "createdAt": "2026-11-05T10:00:00Z",
  "guests": 0,
  "url": "https://cubicles.cloud/share/…"
}
StatusCodeWhen
400validation_failedNo email for control, your own email, or expiresInMinutes out of range
404not_foundNot your desktop, or no such id
409action_not_allowedThe desktop's checkout is still open: there's nothing to share yet
409too_many_sharesThe desktop has 20 shares that haven't ended
429too_many_attemptsMore than 30 invitations in an hour

DELETE/desktops/{id}/shares/{shareId}

End a share and disconnect its guests. API key

204. Ending one that already ended does nothing.

StatusCodeWhen
404not_foundNot your desktop, or not its share

Agents

An agent is an AI agent harness (OpenClaw, Hermes Agent, Claude Code, Codex CLI or OpenCode) that Cubicles sets up on one of your desktops with your model and its API key, optionally answering you on Telegram, Discord, WhatsApp or Signal.

GET/agents/catalog

Harnesses, model providers and chat apps. API key

What each harness supports: its providers (default first) and channels.

GET/agents

Your agents, newest first. API key

{ "items": [Agent, …] }.

GET/agents/{id}

One agent. API key

status is pending (waiting for its desktop to run), installing, ready, failed (statusMessage says why) or deleting. A WhatsApp or Signal chat is needs_link until its QR code, shown on the desktop, is scanned.

Response
{
  "id": "5b1e0000-0000-0000-0000-000000000001",
  "name": "OpenClaw",
  "harness": { "id": "openclaw", "name": "OpenClaw" },
  "provider": "anthropic",
  "model": "claude-sonnet-5-5",
  "baseUrl": null,
  "apiKeyHint": "9876",
  "desktop": { "id": "d0000000-…", "name": "atlas", "status": "running" },
  "status": "ready",
  "statusMessage": null,
  "channels": [
    { "kind": "telegram", "allowedSender": "412587349", "account": null, "status": "ready",
      "greeting": "sent", "chatUrl": "https://t.me/atlas_agent_bot" }
  ],
  "createdAt": "2026-11-05T09:24:37Z",
  "allowedActions": ["redeploy", "delete"]
}
StatusCodeWhen
404not_foundNot your agent

POST/agents

Set an agent up on a desktop. API key

Answers 201 with the Agent, pending; it's set up in a few minutes once the desktop runs. Keys and bot tokens are stored encrypted and never sent back. Each chat answers only allowedSender, since whoever can message the agent controls the desktop. A desktop has at most one agent of each harness.

Request
{
  "desktopId": "d0000000-…",
  "name": "OpenClaw",
  "harness": "openclaw",
  "provider": "anthropic",
  "model": "claude-sonnet-5-5",
  "apiKey": "sk-ant-…",
  "baseUrl": null,
  "channels": [
    { "kind": "telegram", "botToken": "123456789:AAH…", "allowedSender": "412587349" }
  ]
}
FieldRule
harnessopenclaw, hermes, claude_code, codex or opencode
providerOne the harness supports (see /agents/catalog); custom needs baseUrl
name1 to 40 characters
channelsOptional. botToken for telegram and discord, account (E.164) for signal, and allowedSender for each: a numeric Telegram or Discord user id, or an E.164 phone number
StatusCodeWhen
400validation_failedA field is missing or malformed, or the harness doesn't support it (fieldErrors names it)
404not_foundNot your desktop
409desktop_unavailableThe desktop is awaiting payment or being deleted
409agent_existsThe desktop already has an agent of that harness
409too_many_agentsThe account has 20 agents

POST/agents/{id}/redeploy

Set a ready or failed agent up again. API key

StatusCodeWhen
409action_not_allowedNot ready or failed

POST/agents/{id}/link

Show the WhatsApp and Signal QR codes on the desktop again. API key

StatusCodeWhen
409desktop_not_runningThe desktop isn't running
409action_not_allowedNo chat waits for its QR code
409agent_unreachableThe desktop didn't answer

DELETE/agents/{id}

Remove an agent from its desktop. API key

202 with the Agent, deleting. Its services, setup and secrets are removed; the harness and what the agent made stay.

Billing

What's due and what was paid. Cards and cancellations are managed in the web app's billing page.

GET/billing/upcoming

The next charge of every desktop, before tax. API key

Response
{
  "nextChargeAt": "2026-12-05T10:00:00Z", "totalCents": 4800, "currency": "usd",
  "lines": [ { "desktopId": "…", "desktopName": "atlas", "description": "Pro · Ubuntu Desktop",
               "amountCents": 4800, "chargeAt": "2026-12-05T10:00:00Z" } ]
}

GET/invoices

Past invoices, newest first. API key

status is open (payment failed), paid, void or uncollectible. Totals include tax.

Response
{ "items": [ { "id": "…", "number": "325-10566", "status": "paid", "totalCents": 4165, "currency": "usd",
  "issuedAt": "…", "paidAt": "…", "periodStart": "…", "periodEnd": "…", "hasPdf": true } ] }

GET/invoices/{id}/pdf

Redirect to the invoice PDF. API key

302 to a link that expires after an hour.

GET/payment-methods

The cards on file (display details only). API key

API keys

Made and deleted in the web app (Developers), with the browser session. A key can't manage keys.

GET/api-keys

Your keys that haven't expired. Browser session only

POST/api-keys

Make a key (shown once). Browser session only

Request
{ "name": "Claude Code on my laptop", "expiresInDays": 90 }
StatusCodeWhen
409too_many_api_keysThe account has 25 keys

DELETE/api-keys/{id}

Delete a key: requests with it fail from now on. Browser session only