The API

The isolance API lets you automate sandboxes, MCP servers, connectors, your users' logins and billing with an API key. It's a JSON API over HTTPS at https://api.caas.sh/v1, the caas CLI (The CLI) maps its commands onto it one to one, and the TypeScript SDK (The TypeScript SDK) offers it as typed methods.

This guide covers authentication, the conventions every route follows, and the routes for each resource. The other guides explain what each resource does.

Authenticate

Create an API key

1. In the console, open Settings.

2. In the API keys card, enter a Key name, such as ci, and choose Create key. If you're an owner, you can also check Billing access, which lets the key read the balance and add funds.

3. Copy the key. It starts with ck_, and it isn't shown again.

Owners and operators can create keys; viewers can't. A key from the console doesn't expire: it works until you choose Revoke beside it. Keys, members and invitations are managed only in the console, never with an API key.

Send the key

Send the key as a bearer token:

export CAAS_API_KEY=<api-key>

curl https://api.caas.sh/v1/sandboxes \
  -H "Authorization: Bearer $CAAS_API_KEY"

A key belongs to one workspace, and every request it sends acts in that workspace: no path names a workspace. A sandbox, server or connector of another workspace, by ID or name, answers 404, as one that doesn't exist does. To work in another workspace, use a key created there.

Scopes

A key's scopes say which routes it may call. A key from the console has every scope but the two billing ones, and Billing access adds those.

Roles

A key can do what its scopes allow, within the role its creator has in the workspace now:

So if an operator who created a key becomes a viewer, the key can only read, and if they leave the workspace, the key gets 403. Adding, changing and removing connectors, and connecting or disconnecting their workspace accounts, needs an owner's key.

A revoked key, or a changed role, takes effect within a minute. Requests that grant access check the key at once instead: creating a sandbox without a user, changing a sandbox's labels, minting MCP client tokens, creating an MCP server, every change of a connector or its workspace account, and adding funds or changing auto-recharge.

Requests and responses

• Send request bodies as JSON, with Content-Type: application/json, except for files. A body larger than its route takes gets 413.

• Objects are flat: what you set and what isolance reports sit side by side. An unknown field is refused, naming it.

• A path's <sandbox> is a sandbox's ID or its name, and <server> an MCP server's ID or name.

• Times are milliseconds since the Unix epoch. Money is in micro-USD: 1,000,000 is $1.

• A list answers { "<resource>": [...] }, and a paged one its nextCursor beside it: pass it back as ?cursor= for the next page. It's null on the last page.

• Deleting a sandbox or a snapshot answers { "id": "…", "deleted": true }. An MCP server's answer adds "sandboxDeleted", whether its sandbox went with it; a connector's adds how many users' connections and whether an account went with it; a file answers { "path": "…", "deleted": true }. Revoking a client token answers the token.

Errors

Every error has the same JSON body:

{ "error": { "code": "invalid_request", "message": "ports[0]: port must be from 1024 to 65535", "field": "ports" } }

field names the request field a validation error is about; a nested one is dotted, as in sandbox.size. Other fields some errors carry sit inside error: a billing refusal's billingUrl, a 5xx's requestId.

Every 402 has a billingUrl: the console page where an owner adds funds or a card. See Billing and usage.

Request IDs

Every response has an x-caas-request-id header that names the request. isolance logs everything the request did under that ID, and the audit log records it with each change. Quote it when you report a problem.

Rate limits

A request over a limit gets 429 with "code": "rate_limited" and a Retry-After header. Limits are counted at each edge location separately.

Idempotency keys

Requests that create something you mustn't create twice take an Idempotency-Key header of 8 to 128 letters, digits, _ and -. If you get no answer, or a 5xx, send the request again with the same key and body. If the first one went through, you get its result, and nothing is created twice.

Without the header, each request creates something new.

Sandboxes

See Sandboxes for every field and what it does.

Create a sandbox

curl https://api.caas.sh/v1/sandboxes \
  -H "Authorization: Bearer $CAAS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: build-agent-0001" \
  -d '{
    "name": "build-agent",
    "image": "default",
    "size": "l",
    "env": { "MODE": "ci" },
    "ports": [{ "port": 3000, "public": true }],
    "egress": ["api.github.com", "*.npmjs.org"],
    "labels": { "team": "ci" }
  }'

{ "image": "default" } alone is a whole request. The answer is 201 Created with the sandbox, which starts on its own:

{
  "id": "7c9e4a2b-1f3d-4b6e-8a5c-3d2f1e0b9a87",
  "name": "build-agent",
  "image": "default",
  "command": null,
  "env": { "MODE": "ci" },
  "workdir": "/workspace",
  "size": "l",
  "volumes": [{ "path": "/workspace" }],
  "ports": [{ "port": 3000, "public": true }],
  "egress": ["api.github.com", "*.npmjs.org"],
  "user": null,
  "idleStopMinutes": 15,
  "labels": { "team": "ci" },
  "connectors": [{ "id": "github", "name": "GitHub", "hosts": ["api.githubcopilot.com", "api.github.com", "github.com"], "account": "workspace" }],
  "provider": "cloudflare",
  "providerId": null,
  "state": "creating",
  "stateMessage": null,
  "urls": [],
  "pendingRestart": [],
  "createdAt": 1791797400000,
  "startedAt": null,
  "stoppedAt": null,
  "usage": { "startedAt": null, "costPerHourMicroUsd": 0, "today": { "microUsd": 0, "egressBytes": 0 }, "lifetimeMicroUsd": 0 },
  "signIn": null
}

state moves through creating, starting and running; read the sandbox until it runs. urls list the provider's own URL of each port it gives one for, while the sandbox runs (see URLs). A failed start leaves it failed, with the reason in stateMessage. signIn is null unless the sandbox is one of your users' and needs a sign-in they make with a code, such as Codex (ChatGPT)'s, which they haven't made: then it's the code they enter, which …/start and …/restart answer too (see Sign users in with a code).

Sandbox routes

… is /v1/sandboxes/<sandbox>.

Execs

curl https://api.caas.sh/v1/sandboxes/build-agent/exec \
  -H "Authorization: Bearer $CAAS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: run-tests-0001" \
  -d '{ "command": ["npm", "test"], "env": { "CI": "1" }, "workdir": "/workspace/app", "timeoutSeconds": 1800 }'

The answer is 200 once the command ended (within about five minutes), or 202 while it runs:

{ "execId": "run-tests-0001", "state": "succeeded", "detach": false, "createdAt": 1791797400000, "endedAt": 1791797412000,
  "exitCode": 0, "signal": null, "stdout": "…", "stderr": "", "stdoutTruncated": false }

state is submitting, running, succeeded, failed, timed_out, canceled or lost; stdout and stderr are null until it ends, then up to 1 MiB each. A command sent to a sandbox that stopped while idle starts it first.

Logs

GET /v1/sandboxes/<sandbox>/logs answers { "entries": [{ "at", "stream", "message", "kind" }] }: the newest 1,000 entries at or after ?since= (milliseconds or an ISO 8601 time), oldest first. stream is system for what isolance recorded, with its kind, or stdout and stderr for what the sandbox's command wrote. With ?follow=true, the answer is newline-delimited JSON (application/x-ndjson): those entries, then each new one as it comes, for up to 10 minutes; follow on with since.

Files

<path> is the absolute path with each segment percent-encoded, as in /v1/sandboxes/build-agent/files/workspace/my%20file.txt; …/files/ is /, which can only be read. Paths under /proc, /sys, /dev and /workspace/.caas are refused.

curl -X PUT "https://api.caas.sh/v1/sandboxes/build-agent/files/workspace?extract=true" \
  -H "Authorization: Bearer $CAAS_API_KEY" \
  -H "Content-Type: application/gzip" \
  --data-binary @project.tar.gz

Snapshots

GET …/snapshots answers { "snapshots": [{ "id", "name", "kind", "createdAt", "size", "current" }], "storedBytes" }, newest first. POST …/snapshots with an optional { "name": "before-upgrade" } takes one of a running sandbox: { "snapshot" }. POST …/restore with { "snapshot": "<id or manual snapshot name>" } restores one into a stopped or failed sandbox and starts it, answering the sandbox and restoredSnapshotId.

MCP servers

curl https://api.caas.sh/v1/mcp-servers \
  -H "Authorization: Bearer $CAAS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "name": "search-mcp",
    "sandbox": { "image": "registry.caas.sh/<tenant-id>/search-mcp@sha256:…", "egress": ["api.search.example.com"] },
    "transport": { "http": { "port": 8080 } },
    "tokens": [{ "label": "laptop-claude", "allowedTools": ["search.query"] }]
  }'

The answer, 201, is the server: its id, its endpoint url (https://mcp.caa.sh/<id>), the sandboxId and sandboxName it runs in, transport, state, stats, and tokens, each minted token with its secret. See MCP servers for the endpoint, tokens and traces.

Connectors

<user> is your ID for the user, URL-encoded: user_123, or auth0%7Cabc for auth0|abc. The two lists take ?limit= (1 to 100, 50 by default) and ?after=, from the answer's next.

curl https://api.caas.sh/v1/users/user_123/connections \
  -H "Authorization: Bearer $CAAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "connector": "linear", "returnUrl": "https://app.acme.com/settings" }'

The answer's connectUrl is the link to send the user. A sandbox created with "user": "user_123" then uses their accounts for the connectors that reach it, and their logins in its browsers (see Logins). Codex (ChatGPT)'s users sign in with a code instead, which a Codex sandbox's start answers when it's needed; see Sign users in with a code.

curl https://api.caas.sh/v1/connectors \
  -H "Authorization: Bearer $CAAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "catalog": "openai", "selector": { "team": "ci" } }'

curl https://api.caas.sh/v1/connectors/openai/account \
  -H "Authorization: Bearer $CAAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "method": "key", "key": "sk-..." }'

A sandbox reaches a connector when it has every label of the connector's selector ({}, every sandbox). Sandboxes without a user then use the workspace's account; a sandbox's connectors lists what it got. See Connectors.

Billing

Billing routes need a key with Billing access, which only an owner can create. They work while the workspace is suspended.

curl "https://api.caas.sh/v1/billing/usage?month=2026-10" \
  -H "Authorization: Bearer $CAAS_API_KEY"

The usage report has a lines entry for each meter, with its quantity, unit and amountMicroUsd, the month's totalMicroUsd, a total for each UTC day in daily, and, while the month is under way, a projection for the whole month. The CSV has one row per UTC day and meter: day,meter,quantity,unit,rate_usd,amount_usd.

Adding funds charges the card on file and answers { "topUp": { … }, "url": null }; the balance goes up once the payment is confirmed. Without a card, or with "checkout": true, url is a Stripe Checkout page to finish the payment in. A declined card gets 402 with the failed topUp. See Billing and usage, and pricing for the rates.

Settings and the audit log

GET /v1/audit-log takes these filters, each at most once:

Each record has its time (at), actor, action, target, outcome, HTTP status, requestId and a short detail, never a secret, a token or a command's text. Records are kept for 365 days. An API key never sees records about API keys, members or invitations, sees billing records only with billing:read, and sees a user who made a change by ID, without their email.