API reference.

Two hosts, one token

Both take the same bearer. https://prized.dev/api/v1 reaches the same control plane through the website's proxy. The edge is a different machine (it holds the tunnel to your box), so always read its address from edge.url rather than assuming one.

export PRIZED_TOKEN=dcp_…
API=https://api.prized.dev/api/v1
AUTH="Authorization: Bearer $PRIZED_TOKEN"
EDGE=$(curl -s "$API/me" -H "$AUTH" | jq -r .edge.url)

GET https://api.prized.dev/healthz needs no token and answers {"ok": true, "sourceCommit": "…", "controlPlaneApiSha256": "…"}.

Authentication

Every request carries Authorization: Bearer dcp_…. The token is a CLI token: Dashboard → Workspace → CLI tokens mints one (prized login opens that page), and prized login --token dcp_… is how a machine without a browser signs in. Mint one per script or agent and name it, so it can be retired on its own. There is no route that mints a token with a token: minting, listing and revoking are dashboard-only, see Workspaces: CLI tokens.

• What a token can do. It acts as you, in the workspace it was minted in: every box, snapshot, environment and secret there. It cannot change who is in the workspace, mint credentials, or close the workspace. Billing and plan changes are dashboard flows and are not part of this reference.
• Revoking one takes effect on its next request (401), and closes the tunnels that device opened.
• Other credential classes. The dashboard's terminal tickets (dtt_…, ten minutes, bound to one box) are accepted on exactly these routes: GET /api/v1/boxes, GET /api/v1/boxes/{id}, POST /api/v1/boxes/{id}/wake, POST /api/v1/connect, POST /api/v1/disconnect, POST /api/v1/ssh-cert, and the edge's exec, files and prompt routes; they see only their one box. Everything else on this page, POST /desktop/stop included, takes a dcp_ token. Monitor tickets and phone passwords are refused everywhere on this page. The dashboard itself uses its session cookie on the same routes.
• The version header. The CLI sends X-Prized-CLI-Version; a request that sends one below the control plane's minimum answers 426 cli_update_required with minVersion. Scripts should not send it.

Conventions

• JSON in, JSON out. Send Content-Type: application/json. Bodies are capped at 64 KiB; the secrets routes take 128 KiB, and environment create, patch, files and repos take 2 MiB (toggles, vars and upgrade stay at 64 KiB); over the cap, or not JSON, reads as 400 bad_request. A 204 has no body.
• Ids. Control-plane routes take the box's id (a uuid) in the path, never its name; GET /api/v1/boxes maps names to ids. Snapshots are snp_…, environments env_…, secrets sec_…, deletion operations dop_…. An id that is unknown, malformed, or belongs to another workspace is 404 not_found, with nothing written.
• 202 means the reconciler is on it. Creating, waking, pausing, resizing, moving, forking, restoring and deleting a box answer 202 with the row as written: desiredState has moved and observedState follows over the next seconds to minutes. Poll GET /api/v1/boxes/{id} until observedState is what you asked for, or GET /api/v1/operations/{id} for a delete. Setting writes (PATCH, templates, secrets, environments) answer 200 or 201 because nothing is left to converge.
• Errors. The control plane answers {"error": "code"}, plus message on the refusals that have a reason and extra fields where a client needs numbers (insufficient_balance carries balanceMicros, requiredMicros, burnMicrosPerHour; snapshot_limit carries limit; box_not_running carries state). The edge answers {"ok": false, "error": {"code", "message"}}. Codes are stable words; messages are for people.
• Idempotency. No route takes an idempotency key. A POST /api/v1/boxes retried after a lost response creates a second box; give the box a name and the retry answers 409 name_taken instead, then GET /api/v1/boxes finds the one that was made. Deletes are idempotent (the same operation comes back), and wake or suspend on a box already in that state is a 202 no-op.
• Rate limits. The control plane has no request-rate limiter; its limits are counts: 409 box_limit (the plan's box count), 429 snapshot_limit (Limits: Snapshots), 402 secret_limit, and 429 customer_session_limit on the CLI's tunnel sessions. The edge admits 8 concurrent requests and 20 per second per token and per box, and answers 429 rate_limited with Retry-After; see Limits: Commands and files.
• Times and money. Timestamps are RFC 3339 UTC. Balances are in micro-dollars (1000000 is $1).
• Stability. This API is what the CLI and the dashboard use, so every route here is exercised daily, and the box object is the one prized … --json prints. Fields and routes are added under /v1 without notice; ignore fields you do not know. Nothing beyond that is promised yet.

Account

customer.id is the workspace id. box (the oldest live box) is also present but deprecated; read boxes.

Boxes

The box object is the one on CLI: The box object, plus fields the CLI does not print: kind (devbox), networkKind, autoSnapshotHours, autoSnapshotKeep, environmentId, environmentVersionNo, envVars (the per-box vars as [{name, value}]) and restricted. desiredState is running, suspended or terminated. observedState is the raw word, one of requested, provisioning, bootstrapping, running, suspending, suspended, waking, deep_sleep, resizing, migrating, degraded, provision_failed, terminating, terminated; Boxes: States says what each means.

Creating. name is a hostname (lowercase letters, digits and hyphens, starting and ending with a letter or digit, 1 to 32 characters); without one you get a fruit. tier is a size id (nano, micro, lite, flow, pro, max, ultra; see CLI: Sizes); without one the control plane picks what the balance runs comfortably. ttlMinutes (5 to 43200) is a pause deadline, autoPauseMin (30 to 10080, or null) the idle window. environment is an environment id or name, null for none, absent for your default; env is {NAME: "value"}; restricted makes the box safe for third parties. fromSnapshotId or fromTemplate (one, not both) restores instead of booting fresh, and tier may then be any size whose disk holds the snapshot.

The detail answer. events is the last 50 state changes as {id, fromState, toState, reason, actor, at}; job is the reconciler job in flight (op, step, attempt, lastError, nextRetryAt) or null; vitals is the last heartbeat (cpu_pct, mem_pct, disk_pct, idle_for_sec, listeners_count, agent_version); environment is {id, name, versionNo, latestVersionNo} or null.

Patching takes one family per request: the pause settings and the snapshot schedule together (autoPauseMin 30 to 10080 or null; ttlMinutes or pauseAt, null to clear, only one of the two; autoSnapshotHours 1 to 168 or null; autoSnapshotKeep 1 to 10), or {env: {NAME: "value"}} alone, which replaces the per-box vars (100 names, 64 KiB in all). A deadline needs a running box (409 box_not_running); clearing one always works.

Operations

A delete answers with one of these; status runs pending, processing, completed, or failed with error. Finished operations stay readable for 30 days. What a delete keeps and removes is on Data retention.

Snapshots

A snapshot is {id, name, description, status, kind, templateName, expiresAt, boxId, sourceBoxHostname, tier, region, sizeGb, error, createdAt} (status: creating, available, failed, deleting; kind: manual, template, fork, auto, final). Other fields are internal and may disappear. Names are 1 to 64 characters of letters, digits, ., _ and -, starting and ending with a letter or digit. Kinds, limits and every refusal code are on Snapshots: API; forking and templating a box are under Boxes above.

Environments

Bodies, the environment object, limits and error codes are on Environments: API.

Secrets

Brokered credentials: the box sees a placeholder, and the broker substitutes the real value only in HTTPS requests to the allowed hosts. What that means for a box is on Connectors and Credentials; these are the routes behind both pages.

A secret is {id, name, description, hosts, placeholder, mountCount, createdAt, updatedAt, lastRotatedAt}; a mount is {id, envName, secret: {id, name, placeholder, hosts}}. name is UPPER_SNAKE_CASE (up to 128 characters), value up to 16 KiB, hosts up to 32 entries, each a hostname or a *. wildcard; envName is a shell identifier.

Tunnel routes

GET /api/v1/ssh-meta, POST /api/v1/connect, POST /api/v1/disconnect, POST /api/v1/ssh-cert and PUT /api/v1/device-ssh-key are how prized ssh builds its WireGuard tunnel and SSH certificate. They are the CLI's, not a surface for scripts: to run something on a box, use the edge or prized exec. Two more routes are the CLI's own housekeeping, POST /api/v1/telemetry/cli (its usage batches) and POST /api/v1/advisor/messages (the environment advisor proxy).

Dashboard only

These answer 401 unauthorized to any bearer, a valid one included, so that a leaked token cannot mint more credentials or change who is in the workspace. Use the dashboard.

The edge

GET /api/v1/me gives edge.url; every route below is under $EDGE/v1/box/{box}/, where {box} is the box's name or id, with the same bearer. Each request opens its own tunnel and SSH session to the box, so a revoked token dies on its next request and nothing is ever served from a pool. POST /exec and POST /prompts wake a suspended box (they were asked for work); every other route answers 409 box_not_running instead. Paths on the box are read the way prized cp reads them: relative paths and ~/… are under your home, absolute paths are taken as is, and every answer echoes the real path it touched.

Every successful answer carries ok: true and a type. A failed one is {"ok": false, "error": {"code", "message"}}; the codes are listed once, on Run commands and files: Errors, with the prompt routes' additions on Prompt an agent remotely: Errors. A known path with the wrong method is 405 with Allow; an unknown path is 404 not_found, in the same envelope.

Commands

The command runs under sh -c in your home (or cwd) as your box user; the time limit and the timedOut verdict, output truncation, and the on-box process directory are on Run commands and files.

Files

Size caps are on Limits: Commands and files; path rules and error codes on Run commands and files.

Prompts and events

A run is {id, provider, model, reasoningEffort, auto, status (running, done, failed, interrupted), exitCode, pid, cwd, startedAt, finishedAt, sessionId, resumedFrom, parent, eventCount, prompt}. An event is {seq, at, type, text, tool: {name, input}, raw}, described on Prompt an agent remotely: JSON and JSON Lines.

The stream form's event names and keep-alive, and approvals, continuity, the queue and the run directory on the box, are on Prompt an agent remotely: The edge API.

Desktop

This one route predates the box API's envelope: its errors are the bare {"error": "code"} form, with unauthorized (a dcp_ token only; tickets are refused here), not_found, bad_request, box_not_running, box_unreachable, desktop_stop_failed, resolve_failed and control_plane_unavailable.

The desktop stream itself is a dashboard WebSocket authenticated by a terminal ticket; from a script use prized desktop --no-open, which prints a vnc:// address and the password, see Desktop.

Examples

Create a box and wait for it to run:

BOX=$(curl -s -X POST "$API/boxes" -H "$AUTH" -H "Content-Type: application/json" -d '{"name":"ci-42","tier":"flow","ttlMinutes":120}' | jq -r .box.id)
# 202; the row comes back with desiredState running and observedState requested
until [ "$(curl -s "$API/boxes/$BOX" -H "$AUTH" | jq -r .box.observedState)" = running ]; do sleep 5; done

Run a command on it and read the exit code:

curl -s -X POST "$EDGE/v1/box/ci-42/exec" -H "$AUTH" -H "Content-Type: application/json" -d '{"command":"make test","cwd":"app","timeoutSeconds":300}' | jq '{exitCode, timedOut, signal, stderrTruncated}'
# {"exitCode": 0, "timedOut": false, "signal": "", "stderrTruncated": false}

Upload a file and download a directory:

curl -s -X PUT "$EDGE/v1/box/ci-42/upload?path=data/train.bin" -H "$AUTH" --data-binary @train.bin
# {"ok": true, "type": "file.uploaded", "path": "/home/you/data/train.bin", "size": 104857600}
curl -s "$EDGE/v1/box/ci-42/download?path=app/dist" -H "$AUTH" -o dist.tar

Prompt the agent on an idle box and follow it as it works (a box with a run in progress answers prompt.queued with no run; queue behind it with queue: true, or interrupt it first):

RUN=$(curl -s -X POST "$EDGE/v1/box/ci-42/prompts" -H "$AUTH" -H "Content-Type: application/json" -d '{"provider":"claude","prompt":"fix the failing tests in app/ and run them again","cwd":"app","auto":true}' | jq -r .run.id)
curl -sN "$EDGE/v1/box/ci-42/prompts/$RUN/events" -H "$AUTH" -H "Accept: text/event-stream"
# event: prompt
# data: {"seq":1,"type":"system",...}
# ...
# event: done
# data: {"run":{"id":"pr_…","status":"done",...},"next":41}

Snapshot the box, then fork it:

curl -s -X POST "$API/snapshots" -H "$AUTH" -H "Content-Type: application/json" -d "{\"boxId\":\"$BOX\",\"name\":\"pre-upgrade\"}" | jq '{id: .snapshot.id, status: .snapshot.status}'
# {"id": "snp_…", "status": "creating"}   poll GET /snapshots until available
curl -s -X POST "$API/boxes/$BOX/fork" -H "$AUTH" -H "Content-Type: application/json" -d '{"name":"ci-42-b"}' | jq '{box: .box.id, state: .box.observedState, copy: .snapshot.id}'
# {"box": "…", "state": "requested", "copy": "snp_…"}   the copy deletes itself once the fork runs

Delete the box and confirm it is gone:

OP=$(curl -s -X DELETE "$API/boxes/$BOX" -H "$AUTH" | jq -r .operation.id)
# 202 {"box": {...}, "operation": {"id": "dop_…", "kind": "box_delete", "status": "pending", ...}}
until [ "$(curl -s "$API/operations/$OP" -H "$AUTH" | jq -r .operation.status)" = completed ]; do sleep 5; done

Not yet

• No SDK. The routes above with curl or your language's HTTP client are the whole interface; the CLI's --json output is the other supported machine interface, see CLI: For agents and scripts.
• No OpenAPI document. This page is the reference.
• No webhooks. Poll GET /api/v1/boxes/{id} or GET /api/v1/operations/{id}; the one push channel is the prompt event stream.
• No API keys apart from CLI tokens. A token is a signed-in machine with your full standing in the workspace; there is no read-only or per-box token. Mint one per script and revoke it when the script is retired.
• No idempotency keys, see Conventions.