REST API reference
Everything an API key can do. Send Authorization: Bearer cub_… on every request; JSON in and out.
Conventions
| Topic | Rule |
|---|---|
| Base URL | https://api.cubicles.cloud/api/v1 |
| Auth | Authorization: Bearer cub_… on every request. A key acts as the user who made it; no CSRF header or cookies needed. |
| Format | JSON in and out, camelCase fields, ISO-8601 UTC timestamps, prices in integer cents |
| Errors | application/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 limits | Over a limit answers 429 too_many_attempts with Retry-After in seconds. Commands and screenshots: 120 a minute per account. |
| Keys | cub_ 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
| Method | Path | Auth | What |
|---|---|---|---|
| GET | /me | API key | The user the key acts as |
| GET | /catalog | Public | Plans, operating systems and regions on sale |
| GET | /desktops | API key | Your desktops, newest first |
| GET | /desktops/{id} | API key | One desktop |
| POST | /desktops/{id}/start | API key | Start a stopped desktop |
| POST | /desktops/{id}/stop | API key | Shut a running desktop down |
| POST | /desktops/{id}/restart | API key | Restart a running desktop |
| POST | /desktops/{id}/exec | API key | Run a shell command and wait for its output |
| GET | /desktops/{id}/screenshot | API key | A JPEG of the screen |
| POST | /desktops/{id}/files | API key | Upload a file to the Desktop folder |
| GET | /desktops/{id}/files | API key | List the files and folders in a folder |
| GET | /desktops/{id}/files/download | API key | Download a file from anywhere on the computer |
| POST | /desktops | API key | Create a desktop |
| GET | /desktops/{id}/checkout | API key | Whether a checkout has been paid |
| DELETE | /desktops/{id} | API key | Delete a desktop whose subscription is canceled |
| GET | /desktops/{id}/shares | API key | The desktop's shares that haven't ended |
| POST | /desktops/{id}/shares | API key | Share the desktop |
| DELETE | /desktops/{id}/shares/{shareId} | API key | End a share and disconnect its guests |
| GET | /agents/catalog | API key | Harnesses, model providers and chat apps |
| GET | /agents | API key | Your agents, newest first |
| GET | /agents/{id} | API key | One agent |
| POST | /agents | API key | Set an agent up on a desktop |
| POST | /agents/{id}/redeploy | API key | Set a ready or failed agent up again |
| POST | /agents/{id}/link | API key | Show the WhatsApp and Signal QR codes on the desktop again |
| DELETE | /agents/{id} | API key | Remove an agent from its desktop |
| GET | /billing/upcoming | API key | The next charge of every desktop, before tax |
| GET | /invoices | API key | Past invoices, newest first |
| GET | /invoices/{id}/pdf | API key | Redirect to the invoice PDF |
| GET | /payment-methods | API key | The cards on file (display details only) |
| GET | /api-keys | Browser session only | Your keys that haven't expired |
| POST | /api-keys | Browser session only | Make a key (shown once) |
| DELETE | /api-keys/{id} | Browser session only | Delete 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
{
"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.
{
"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 field | Notes |
|---|---|
status | awaiting_payment, provisioning, starting, running, stopping, stopped, restarting, deleting or failed. The in-between ones change by themselves within seconds to minutes, so poll. |
statusProgress | 0–100 while provisioning or starting, else null |
statusMessage | A sentence about the status ("Starting Ubuntu…", why it failed), or null |
monthlyPriceCents | What's billed each month, before tax |
free | The account's free desktop: nothing is billed, and it can be deleted any time |
subscriptionStatus | active, past_due or canceled; null until the payment is confirmed |
nextChargeAt | End of the current billing period; null when canceled |
cancelAt | When a scheduled cancellation deletes the desktop; null if none |
allowedActions | What 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
| Field | Rule |
|---|---|
status | awaiting_payment, provisioning, starting, running, stopping, stopped, restarting, deleting or failed. The in-between ones change by themselves within seconds to minutes, so poll. |
statusProgress | 0–100 while provisioning or starting, else null |
statusMessage | A sentence about the status ("Starting Ubuntu…", why it failed), or null |
monthlyPriceCents | What's billed each month, before tax |
free | The account's free desktop: nothing is billed, and it can be deleted any time |
subscriptionStatus | active, past_due or canceled; null until the payment is confirmed |
nextChargeAt | End of the current billing period; null when canceled |
cancelAt | When a scheduled cancellation deletes the desktop; null if none |
allowedActions | What can be done now: stop and restart while running, start while stopped, delete once the subscription is canceled |
{
"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"]
}| Status | Code | When |
|---|---|---|
| 404 | not_found | Not 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.
| Status | Code | When |
|---|---|---|
| 404 | not_found | Not your desktop, or no such id |
| 409 | action_not_allowed | Not 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.
| Status | Code | When |
|---|---|---|
| 404 | not_found | Not your desktop, or no such id |
| 409 | action_not_allowed | Not offered in the current status |
POST/desktops/{id}/restart
Restart a running desktop. API key
As /start. Programs running on it stop.
| Status | Code | When |
|---|---|---|
| 404 | not_found | Not your desktop, or no such id |
| 409 | action_not_allowed | Not 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.
{ "command": "cat > notes.txt && wc -c notes.txt", "stdin": "hello\n", "timeoutSeconds": 60 }| Field | Rule |
|---|---|
command | Required, at most 16 KiB. Send a longer script as stdin to bash -s. |
stdin | Optional, at most 512 KiB of UTF-8 |
timeoutSeconds | 1 to 300, default 60 |
{ "exitCode": 0, "stdout": "6 notes.txt\n", "stderr": "", "timedOut": false, "truncated": false }| Status | Code | When |
|---|---|---|
| 400 | validation_failed | No command, or a field over its limit |
| 404 | not_found | Not your desktop, or no such id |
| 409 | desktop_not_running | The desktop isn't running |
| 429 | too_many_attempts | Over 120 commands and screenshots a minute |
| 429 | desktop_busy | 8 commands were already running on it for the 30 seconds this one waited; see Retry-After |
| 502 | desktop_unreachable | The desktop didn't answer: still starting, or its guest agent is down (restart it) |
| 503 | server_busy | Its 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.
| Status | Code | When |
|---|---|---|
| 404 | not_found | Not your desktop, or no such id |
| 409 | desktop_not_running | The desktop isn't running |
| 429 | too_many_attempts | Over the rate limit |
| 429 | desktop_busy | Too many commands at once on the desktop; see Retry-After |
| 502 | desktop_unreachable | The 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.
{ "name": "report (1).pdf", "size": 482113 }| Status | Code | When |
|---|---|---|
| 400 | validation_failed | No file part, or an unusable name |
| 404 | not_found | Not your desktop, or no such id |
| 409 | desktop_not_running | The desktop isn't running |
| 413 | file_too_large | Over 100 MB |
| 502 | upload_failed | The 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.
{ "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 } ] }| Status | Code | When |
|---|---|---|
| 400 | validation_failed | dir isn't an absolute path |
| 403 | folder_not_readable | The desktop's user can't read that folder |
| 404 | not_found | Not your desktop, or no such id |
| 404 | folder_not_found | No folder there |
| 409 | desktop_not_running | The desktop isn't running |
| 502 | desktop_unreachable | The 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.
| Status | Code | When |
|---|---|---|
| 400 | validation_failed | No path, or one that isn't absolute |
| 403 | file_not_readable | The desktop's user can't read that file |
| 404 | not_found | Not your desktop, or no such id |
| 404 | file_not_found | No file there |
| 409 | desktop_not_running | The desktop isn't running |
| 413 | file_too_large | Over 100 MB |
| 502 | desktop_unreachable | The 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.
{ "name": "atlas", "planId": "standard", "osId": "ubuntu", "regionId": "fra", "free": true }| Field | Rule |
|---|---|
name | 3–32 characters of a-z, 0-9 and -, starting with a letter. It becomes the desktop's Ubuntu user. |
free | Optional. true for the account's free desktop; left out to pay. |
{ "desktopId": "…", "transactionId": "txn_01…", "checkoutUrl": "https://cubicles.cloud/pay?_ptxn=txn_01…" }| Status | Code | When |
|---|---|---|
| 400 | validation_failed | A bad name, or a name Ubuntu already uses (root, ubuntu) |
| 400 | plan_unavailable | Unknown plan (also os_unavailable, region_unavailable) |
| 400 | free_plan_unavailable | free with a plan other than the free one |
| 409 | too_many_desktops | free, but the account already has its free desktop |
| 409 | plan_sold_out | No server has room for the plan right now |
| 409 | name_taken | Another desktop in that region has the name |
GET/desktops/{id}/checkout
Whether a checkout has been paid. API key
{ "desktopId": "…", "status": "awaiting_payment" }| Status | Code | When |
|---|---|---|
| 404 | not_found | Not 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.
{ "confirmName": "atlas" }| Status | Code | When |
|---|---|---|
| 400 | confirm_name_mismatch | confirmName isn't the desktop's name |
| 404 | not_found | Not your desktop, or no such id |
| 409 | subscription_active | Cancel the subscription first (in the web app's billing) |
| 409 | action_not_allowed | Already being deleted, or the open checkout was just paid |
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.
{
"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"]
}| Status | Code | When |
|---|---|---|
| 404 | not_found | Not 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.
{
"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" }
]
}| Field | Rule |
|---|---|
harness | openclaw, hermes, claude_code, codex or opencode |
provider | One the harness supports (see /agents/catalog); custom needs baseUrl |
name | 1 to 40 characters |
channels | Optional. 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 |
| Status | Code | When |
|---|---|---|
| 400 | validation_failed | A field is missing or malformed, or the harness doesn't support it (fieldErrors names it) |
| 404 | not_found | Not your desktop |
| 409 | desktop_unavailable | The desktop is awaiting payment or being deleted |
| 409 | agent_exists | The desktop already has an agent of that harness |
| 409 | too_many_agents | The account has 20 agents |
POST/agents/{id}/redeploy
Set a ready or failed agent up again. API key
| Status | Code | When |
|---|---|---|
| 409 | action_not_allowed | Not ready or failed |
POST/agents/{id}/link
Show the WhatsApp and Signal QR codes on the desktop again. API key
| Status | Code | When |
|---|---|---|
| 409 | desktop_not_running | The desktop isn't running |
| 409 | action_not_allowed | No chat waits for its QR code |
| 409 | agent_unreachable | The 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
{
"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.
{ "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
{ "name": "Claude Code on my laptop", "expiresInDays": 90 }| Status | Code | When |
|---|---|---|
| 409 | too_many_api_keys | The account has 25 keys |
DELETE/api-keys/{id}
Delete a key: requests with it fail from now on. Browser session only