One API for every product

Send the key as a bearer token. Keys stay in server-side secret storage; never in a URL, a browser or a command line others can read.

Terminalcurl https://api.withruntime.com/v1/sandboxes \  -H "Authorization: Bearer ${RUNTIME_API_KEY}" \  -H "Content-Type: application/json" \  -H "Prefer: wait=60" \  -d '{}'

In a shell, put a variable before a colon in braces: "${ID}:exec". zsh, the macOS default, reads $ID:e as a modifier and sends /xec. Never use curl -v or --trace with the key: they print the Authorization header.

Terminalcurl -sS "https://api.withruntime.com/v1/sandboxes/${ID}:exec" \  -H "Authorization: Bearer ${RUNTIME_API_KEY}" \  -H "Content-Type: application/json" \  -d '{"command": "python3 -c \"print(6 * 7)\""}'

• Resources live at /v1/<plural>/{id}. A change that is not a plain update is POST /v1/<plural>/{id}:<verb>: :stop, :pause, :wake, :exec.
• Field names are camelCase. Times are ISO 8601 in UTC. Money is integer microdollars: 1,000,000 is one US dollar.
• Unknown fields are refused, and every wrong field is named in one answer.
• Prefer: wait=N (seconds, at most 120) on a change answers once the resource has settled rather than at once. GET /v1/sandboxes/{id}?waitFor=running&timeoutSeconds=60 waits for a state without polling.

Every response carries x-request-id. Every error has one shape:

JSON{  "error": {    "code": "trial_busy",    "status": 409,    "message": "The trial runs 3 sandboxes at once; ... are running or paused.",    "hint": "Stop one (runtime sandbox stop <id>), or pass funding: \"paid\" to use prepaid credit.",    "details": { "sandboxIds": ["..."], "concurrent": 3 },    "requestId": "req_0mud1dtgjogtn2z8t6y"  }}

Follow the hint. Quote the requestId when you report a problem. A 5xx never carries internal detail, only a fixed message and the request id.

The server can refuse capacity; a request is not a guarantee of allocation.

Send Idempotency-Key: <any unique string> on a change. The server remembers the key for 24 hours:

• The same key with the same body answers the first result again, marked "replayed": true and with the header Idempotency-Replayed: true. Nothing happens twice.
• The same key with a different body is refused with 422 idempotency_key_reused.
• A new key is new work.

The SDKs send a key on every change and retry transport failures, 429, 502, 503 and 504 with it. Changing the body while reusing a key is not a retry.

Each key may make about 50 requests a second, in bursts of up to 200, with 128 being served at once; past that, a request waits its turn for up to five seconds before it is refused. An organization may have 192 requests in flight across all its keys, and eight terminals open. Over a limit you get 429 with Retry-After. These are protection, not quotas, and a refusal costs nothing.

The create body:

Sizes are subject to the deployed host's measured capacity. Sizes are limits you ask for; the server checks their combinations, account limits and available host capacity.

The exec body is command (run under bash -c) or argv (no shell), and optionally cwd, env, stdin, timeoutMs (default 60,000; at most 24 hours) and stream. With "stream": true the answer is NDJSON, one event a line: start, stdout, stderr, exit, and continue with a cursor when a stream passes the server's time limit, from which …/output?follow=true&cursor= resumes. A timeout is a result with timedOut: true, not an error. env values are never echoed and are stored only as hashes.

GET /v1/sandboxes/{id}/terminal with Upgrade: websocket and the bearer header opens a terminal: cols, rows, command (default bash -l), cwd, or processId to attach to a process started with a pty. Binary frames are terminal bytes both ways. Text frames are JSON: you send {"type":"resize","cols":120,"rows":40}; the server sends {"type":"ready","processId":...} and {"type":"exit","exitCode":...}.

Paths are absolute. File errors name the path: file_not_found, is_a_directory, not_a_directory, permission_denied.

The OpenAPI document has every field of every route.

GET /v1/me says who a key is: orgId, principalId, credentialId. GET /v1/usage says what the account has and has used. Money is integer microdollars in strings (1,000,000 is one dollar), exact however large:

GET /v1/limits says what this key may do and what its agent may still spend:

JSON{  "access": "full",  "daily": {    "limitMicros": "25000000",    "usedMicros": "3100000",    "remainingMicros": "21900000",    "window": "24h"  }}

access is full (every action in every product), read (a read-only key: every read, no change and no spending) or selected (the actions the key names). daily.limitMicros is the most the key's agent may commit in any 24 hours, or null when the owner set no limit. usedMicros counts settled charges plus money still on hold. Past the limit, a create, wake, extension or renewal fails with 402 spending_limit_reached and charges nothing. Only an account owner sets, changes or removes a limit, at API keys; no key can.

Every list, in every product, answers {"data": [...], "nextCursor": "..."}. Pass nextCursor back as cursor; null ends the list. limit is 1 to 100.

This is 0.2.0. The 0.1.0 routes under /v1/resources were removed on 22 September 2026: each answers 410 upgrade_required, and details.replacement names the route that replaced it. The migration guide maps each old call to its new one. The OpenAPI document's info.version is the version you are talking to.