The API

The caas.sh API lets you automate sandboxes, MCP servers, workflow runs, credentials and billing with an API key. It's a JSON API over HTTPS at https://api.caas.sh, and the caas CLI (The CLI) is built on it.

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.

The Workspace card on the same page shows the workspace's Tenant ID, which every API path includes.

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_TENANT=<tenant-id>
export CAAS_API_KEY=<api-key>

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

Every route in this guide starts with /v1/tenants/<tenant-id>, written … from here on: GET …/sandboxes is GET https://api.caas.sh/v1/tenants/<tenant-id>/sandboxes. A key works only in the workspace it was created in. With another workspace's ID, it gets 401.

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. Changing credentials, OAuth and GitHub apps, and egress rules needs an owner's key.

A revoked key, or a changed role, takes effect within a minute. Some requests check the key at once instead: creating MCP client tokens and sandbox URL tokens, turning on or changing a sandbox URL, changing credentials, apps, egress rules and egress policies, starting and resuming workflow runs, and adding funds or changing auto-recharge.

Requests and responses

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

• Sandbox, snapshot, run, client token and egress rule IDs are UUIDs.

• Times are milliseconds since the Unix epoch.

• Money is in micro-USD: 1,000,000 is $1.

• A list that comes in pages has a cursor: nextCursor, or cursor in the audit log. Pass it back as ?cursor= for the next page. It's null on the last page.

Errors

An error has a JSON body with a readable error message. Some errors add a code you can branch on, and more fields:

{
  "error": "The workspace balance is empty; add funds in the console before running sandboxes",
  "code": "out_of_funds",
  "billingUrl": "https://console.caas.sh/usage"
}

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. caas.sh logs everything the request did under that ID, and the audit log records it with each change. Quote it when you report a problem. When something fails on caas.sh's side, the 503 body has it too, as requestId.

Rate limits

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

GET …/sandboxes returns the sandboxes with their status in one request, so poll it instead of reading each sandbox.

Idempotency keys

Requests that create something you mustn't create twice need an Idempotency-Key header of 8 to 128 characters. 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.

• A repeated sandbox create answers 200 instead of 201. For an MCP server, it doesn't return the client tokens' secrets again; it has "clientTokenNotReturned": true instead.

• A key whose sandbox you've since deleted gets 409.

• Command IDs belong to their sandbox. A command's key can be used again once the command's record is gone.

curl https://api.caas.sh/v1/tenants/$CAAS_TENANT/sandboxes \
  -H "Authorization: Bearer $CAAS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "kind": "agent", "source": { "type": "stdio", "command": ["node", "--version"] } }'

To retry this safely, save the key in a variable and send the same one each time.

Sandboxes

Create a sandbox

curl https://api.caas.sh/v1/tenants/$CAAS_TENANT/sandboxes \
  -H "Authorization: Bearer $CAAS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: build-agent-0001" \
  -d '{
    "kind": "agent",
    "name": "build-agent",
    "size": "l",
    "source": { "type": "stdio", "command": ["node", "--version"] },
    "egressHosts": ["api.github.com"]
  }'

The answer is 201 Created with the new sandbox. It starts at once, and runs its command once it's running:

{
  "id": "7c9e4a2b-1f3d-4b6e-8a5c-3d2f1e0b9a87",
  "tenantId": "0b6f2c1e-4d5a-4e8b-9c3f-2a7d1e6b8f40",
  "kind": "agent",
  "name": "build-agent",
  "status": "starting",
  "endpointId": null,
  "deployment": {
    "source": { "type": "stdio", "command": ["node", "--version"] },
    "size": "l",
    "egressHosts": ["api.github.com"],
    "idleStopMinutes": 15,
    "wakeOnRequest": false,
    "persistent": true
  },
  "resources": { "vcpu": 1, "memoryMib": 6144, "diskGb": 12 },
  "url": null,
  "lastSnapshot": null,
  "snapshotSchedule": { "time": "02:00", "timeZone": "UTC", "nextAt": 1791856800000 },
  "egress": {
    "policy": [{ "host": "api.github.com", "action": "allow" }, { "host": "*", "action": "deny" }],
    "credentials": []
  },
  "stopReason": null,
  "agentExit": null,
  "createdAt": 1791797400000,
  "updatedAt": 1791797400000
}

The body takes these fields:

source is one of:

Choose what it runs has the details of each source, and Images and the registry shows how to push an image.

Upload a source archive

Upload a gzipped tar of up to 250 MiB, then pass the uploadId it returns in a stdio source. An upload is kept for seven days.

tar -czf source.tar.gz -C my-project .

curl https://api.caas.sh/v1/tenants/$CAAS_TENANT/uploads \
  -H "Authorization: Bearer $CAAS_API_KEY" \
  -H "Content-Type: application/gzip" \
  --data-binary @source.tar.gz

The answer is 201 with { "uploadId": "…", "size": 18342 }. See An uploaded archive.

Sandbox routes

A sandbox's status is starting, running, stopping, stopped, error, deleting or deleted. Start and stop wait up to 25 seconds for the sandbox to finish starting or stopping. Start then answers with the sandbox, and stop with its id and status. If it's still under way when the wait ends, the answer is 202 with the sandbox: read it until its status changes. Start also takes a sandbox in error. A start the workspace's balance doesn't allow gets 402.

Sandbox URLs explains ports, access tokens and sessions.

Commands

Send a command with an idempotency key, which becomes the command's ID:

curl https://api.caas.sh/v1/tenants/$CAAS_TENANT/sandboxes/$SANDBOX_ID/commands \
  -H "Authorization: Bearer $CAAS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: say-hello-0001" \
  -d '{ "command": ["echo", "hello"], "timeoutMs": 60000 }'

The answer is 202 Accepted with the command's record. Then read it, waiting up to 25 seconds for it to end:

curl "https://api.caas.sh/v1/tenants/$CAAS_TENANT/sandboxes/$SANDBOX_ID/commands/say-hello-0001?waitMs=25000" \
  -H "Authorization: Bearer $CAAS_API_KEY"

{
  "id": "say-hello-0001",
  "state": "succeeded",
  "exitCode": 0,
  "signal": null,
  "stdout": { "bytes": 6, "base64": "aGVsbG8K", "truncated": false },
  "stderr": { "bytes": 0, "base64": "", "truncated": false },
  "createdAt": 1791797462000
}

A command's state is submitting, running, succeeded, failed, timed_out, canceled or lost. When a stream is short, its base64 holds all of it; otherwise base64 is null, and you download the stream from /stdout or /stderr. Downloaded output bills as egress.

A command sent to a sandbox that stopped while idle starts it first. An agent sandbox's first command has the ID initial-agent-command. Records are kept for seven days after a command ends, at most 1,000 per sandbox. See Run commands.

Files

The file routes read, write and delete one file at a time under /workspace or /tmp, other than /workspace/.caas, which belongs to caas.sh. They need sandbox:execute, reads included, because they reach any file a command could.

curl -X PUT "https://api.caas.sh/v1/tenants/$CAAS_TENANT/sandboxes/$SANDBOX_ID/files?path=/workspace/config.json" \
  -H "Authorization: Bearer $CAAS_API_KEY" \
  --data-binary @config.json

A transfer starts a sandbox that stopped while idle. While the sandbox is still starting, you get 503; while a transfer is still running, 504. Try again shortly in both cases. The bytes you read bill as egress. See Read and write files.

Snapshots

curl https://api.caas.sh/v1/tenants/$CAAS_TENANT/sandboxes/$SANDBOX_ID/snapshot \
  -H "Authorization: Bearer $CAAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "before-upgrade" }'

Taking a snapshot of a large workspace can outlast the request. You then get 504, and the snapshot is listed once it's done. A snapshot of a sandbox that isn't running gets 409, and so does deleting the current recovery point of a sandbox that keeps state. See Snapshots.

MCP servers

Deploy a server

An MCP server is a sandbox with "kind": "mcp", created with POST …/sandboxes. Its command starts the server, which speaks MCP on stdio; a server on your own image can serve HTTP instead, with "transport": "http" and its "port" in the source. clientTokens declares up to 20 client tokens, each with a label, and optionally allowedTools and expiresAt:

curl https://api.caas.sh/v1/tenants/$CAAS_TENANT/sandboxes \
  -H "Authorization: Bearer $CAAS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: search-mcp-0001" \
  -d '{
    "kind": "mcp",
    "name": "search-mcp",
    "source": { "type": "stdio", "command": ["npx", "-y", "search-mcp"] },
    "egressHosts": ["registry.npmjs.org", "api.search.example.com"],
    "clientTokens": [
      { "label": "laptop-claude" },
      { "label": "ci-pipeline", "allowedTools": ["search.query"] }
    ]
  }'

The answer has the server's endpointUrl, https://mcp.caa.sh/<endpoint-id>, and clientTokens: each token's secret and its token record. Without clientTokens, the server gets one token, Initial client, whose secret is in clientToken. Every secret is returned only once, so save it.

Client tokens

curl https://api.caas.sh/v1/tenants/$CAAS_TENANT/sandboxes/$SANDBOX_ID/client-tokens \
  -H "Authorization: Bearer $CAAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "label": "ci-pipeline", "allowedTools": ["search.query"] }'

• label is 1 to 80 characters.

• allowedTools lists up to 32 tool names the token may call. Leave it out to allow every tool; an empty list allows none.

• expiresAt is a time more than a minute and at most a year ahead. Leave it out for a token that never expires.

• A server can have 20 tokens in force at once. A new token beyond that gets 429.

Call the endpoint

MCP clients call the server at its endpointUrl with a client token, not an API key:

curl https://mcp.caa.sh/<endpoint-id> \
  -H "Authorization: Bearer $CAAS_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

Connect a client covers client configuration and the gateway's limits, and Tool grants what a limited token can do.

Workflow runs

Start a run

Send the workflow file's text as file, with its inputs. This example uses jq to build the body from build-and-test.yaml, the file in Workflows:

jq -n --rawfile file build-and-test.yaml '{
  file: $file,
  inputs: { branch: "release" },
  images: { "registry.caas.sh/ci:node24": "registry.caas.sh/<tenant-id>/ci@sha256:<digest>" }
}' | curl https://api.caas.sh/v1/tenants/$CAAS_TENANT/workflow-runs \
  -H "Authorization: Bearer $CAAS_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  --data-binary @-

The answer is 201 with the run:

{
  "id": "5d2b7e1a-9c4f-4a3e-b8d6-1f0e2c3a4b5d",
  "name": "build-and-test",
  "number": 12,
  "status": "queued",
  "resumes": 0,
  "progress": { "total": 3, "done": 0, "states": ["pending", "pending", "pending"], "current": null, "failed": null },
  "createdAt": 1791797400000,
  "startedAt": null,
  "endedAt": null,
  "costMicroUsd": 0,
  "resumeFrom": null,
  "error": null
}

A file with an error gets 400, naming the line or field. So does a run whose steps name a secret that isn't connected and added by a workspace egress rule. The workspace may have 10 runs queued, running or paused at once; another gets 429.

Run routes

Pause, cancel and resume answer with the run. A run's status is queued, running, paused, failed, succeeded or cancelled. A succeeded run can only be replayed from a checkpoint, and a run that ended more than seven days ago can't be resumed (409). See Pause, resume and cancel.

Credentials and outbound access

A credential holds a key or token that caas.sh adds to sandboxes' outbound requests, so the key never enters a sandbox. Egress rules say which requests get which credential, and each sandbox's egress policy says which hosts it may reach. Credentials and outbound access explains how they work together.

Reading them needs sandbox:read. Changing credentials, apps and egress rules needs an owner's key with sandbox:write; changing a sandbox's egress policy needs sandbox:write.

Credential routes

A credential's name is capitals, digits and _, up to 64 characters, not starting with CAAS_. Its method is one of:

• api_key: a key you send as secret. It's ready at once.

• oauth: a sign-in through an OAuth app you added, named in provider, optionally asking for scopes.

• github_app: an installation of a GitHub App you added, named in provider.

• github_user: a GitHub sign-in.

• codex: a ChatGPT account, through a device code.

For every method but api_key, the answer's credential.action has the next step: a page to sign in at ("kind": "redirect"), or a device code to enter at a page ("kind": "device"). A sign-in finishes in the console, signed in as the key's creator.

For example, to connect an Anthropic key and add it to requests to api.anthropic.com:

jq -n --rawfile key anthropic-key.txt \
  '{ credential: { name: "ANTHROPIC_API_KEY", method: "api_key" }, secret: ($key | rtrimstr("\n")) }' |
  curl https://api.caas.sh/v1/tenants/$CAAS_TENANT/credentials \
    -H "Authorization: Bearer $CAAS_API_KEY" \
    -H "Content-Type: application/json" \
    --data-binary @-

curl https://api.caas.sh/v1/tenants/$CAAS_TENANT/egress-rules \
  -H "Authorization: Bearer $CAAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "rule": { "preset": "anthropic", "credential": "ANTHROPIC_API_KEY" } }'

Egress rules

A rule names a credential, the host it goes to, and how it's sent:

{ "rule": { "credential": "SEARCH_API_KEY", "host": "api.search.example.com", "header": "authorization", "scheme": "bearer" } }

• host is an exact host, or *.example.com for example.com and every name under it.

• header is the request header the credential goes in, such as authorization.

• scheme is bearer (Bearer <value>), basic (with a username) or raw (the value alone).

• sandboxId limits the rule to one sandbox. Without it, the rule applies to every sandbox in the workspace.

Or send { "rule": { "preset": "github", "credential": "GITHUB_TOKEN" } }, optionally with sandboxId, for a preset's rules:

Up to 16 rules apply to one sandbox, the workspace's and its own together. A running sandbox takes changed rules when it next starts.

Egress policy

curl -X PUT https://api.caas.sh/v1/tenants/$CAAS_TENANT/sandboxes/$SANDBOX_ID/egress-policy \
  -H "Authorization: Bearer $CAAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "rules": [
    { "host": "github.com", "action": "allow" },
    { "host": "*.example.com", "action": "deny" },
    { "host": "pypi.org", "action": "allow" }
  ] }'

The first rule that matches a host decides. Up to 64 rules come before the closing * deny, which the policy always ends with: you may leave it out, and * allow is refused. In a policy, *.example.com matches every name under example.com, but not example.com itself.

Billing

Billing routes need a key with Billing access, which only an owner can create.

curl "https://api.caas.sh/v1/tenants/$CAAS_TENANT/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 …/audit takes these filters, each at most once:

Each record has its time (at), actor, action, target, outcome, HTTP status, requestId and a short detail. 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.