API reference.

Two hosts, one token

The control plane, https://api.prized.dev/api/v1, manages boxes, snapshots, environments, secrets, operations, the audit log, policies, team status and your account; it takes a box's id (a uuid) and answers errors as {"error": "code"}, sometimes with message. The edge, $EDGE/v1/box/{box}/, runs commands, moves files, prompts the agent and stops the desktop; it takes a box's name or id and answers errors as {"ok": false, "error": {"code", "message"}}. Both take the same bearer; read the edge's address from edge.url in GET /api/v1/me 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)

Authentication

Every request carries Authorization: Bearer dcp_…, a CLI token from Dashboard → Workspace → CLI tokens (prized login --token dcp_… signs a machine in with one). Mint one per script or agent and name it, so it can be retired on its own; revoking takes effect on its next request (401) and closes the tunnels that device opened (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 (a contractor's token reaches only the boxes they own and no secrets). Minting credentials, membership and roles, policies, the audit export, billing, and closing the workspace are dashboard-only; those routes answer 401 unauthorized to any bearer, so a leaked token cannot widen itself.
• Other credentials. The dashboard's short-lived terminal tickets are accepted on the box read, wake and connect routes and on the edge's exec, files and prompt routes, for their one box only; monitor tickets and phone passwords are refused everywhere.
• The version header. The CLI sends X-Prized-CLI-Version; one below the 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 (128 KiB on the secrets routes; 2 MiB on environment create, patch, files and repos); over the cap, or not JSON, is 400 bad_request. A 204 has no body.
• Ids. Control-plane routes take the box's id, never its name; GET /api/v1/boxes maps names to ids. Snapshots are snp_…, environments env_…, secrets sec_…, grants sgr_…, operations dop_…. An unknown, malformed, or foreign id is 404 not_found, with nothing written.
• 202 means in progress. 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 seconds to minutes. Poll GET /api/v1/boxes/{id}, or GET /api/v1/operations/{id} for a delete. Setting writes answer 200 or 201.
• Errors. Codes are stable words; messages are for people. Refusals that need numbers carry them: insufficient_balance has balanceMicros, requiredMicros, burnMicrosPerHour; snapshot_limit has limit; box_not_running has state.
• Idempotency. No route takes an idempotency key. A POST /api/v1/boxes retried after a lost response creates a second box; give it a name and the retry answers 409 name_taken instead. Deletes are idempotent, and wake or suspend on a box already in that state is a 202 no-op.
• Limits. The control plane's limits are counts: 409 box_limit, 429 snapshot_limit, 402 secret_limit, 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, then answers 429 rate_limited with Retry-After (Limits).
• 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, 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. The CLI's own tunnel and housekeeping routes are not a scripting surface and are not listed.

Account

customer.id is the workspace id. box (the oldest live box in boxes) is deprecated; read boxes.

Boxes

The box object is the one on CLI: The box object, plus autoSnapshotHours, autoSnapshotKeep, environmentId, environmentVersionNo, envVars ([{name, value}]), restricted, ownerUserId (the member who created it) and quietHoursExempt. desiredState is running, suspended or terminated; observedState is one of requested, provisioning, bootstrapping, running, suspending, suspended, waking, deep_sleep, resizing, migrating, degraded, provision_failed, terminating, terminated (Boxes: States).

Creating. name is a hostname (lowercase letters, digits and hyphens, starting and ending with a letter or digit, 1 to 32 characters; a fruit without one). tier is a size id (nano, micro, lite, flow, pro, max, ultra); without one the control plane picks what the balance runs comfortably (a Small while the workspace runs on the free credit alone, which also starts only nano through flow: the rest answer 409 tier_unavailable with allowed naming the sizes it does). A create on the free credit that omits autoPauseMin gets 60; null keeps auto-pause off. ttlMinutes (5 to 43200) is a pause deadline, autoPauseMin (30 to 10080, or null) the idle window. environment is an id or name, null for none, absent for your default; env is {NAME: "value"}; restricted makes the box safe for third parties (a contractor's box always is). fromSnapshotId or fromTemplate (one, not both) restores instead of booting fresh; 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 lifecycle change 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 snapshot schedule together (autoPauseMin; ttlMinutes or pauseAt, null to clear, only one of the two; autoSnapshotHours 1 to 168 or null; autoSnapshotKeep 1 to 10), or {env} 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. quietHoursExempt keeps the box running through quiet hours and is the owner's alone (403 not_owner); a member's autoPauseMin above the workspace's auto-pause floor is 403 policy_denied.

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 may disappear. Names are 1 to 64 characters of letters, digits, ., _ and -, starting and ending with a letter or digit. Forking and templating a box are under Boxes; what each kind means is on Snapshots.

Refusals: 409 snapshot_in_progress, 409 no_volume, 409 insufficient_balance, 409 name_taken, 409 box_limit, 409 snapshot_unavailable (a failed, deleting, or transient fork snapshot as a template), 429 snapshot_limit, 403 restore_tier_not_allowed. A POST /api/v1/boxes with fromTemplate is 404 when no template wears the name.

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 (Credentials, Connectors).

A secret is {id, name, description, hosts, placeholder, mountCount, scope, grants, createdAt, updatedAt, lastRotatedAt}, where scope is workspace (no grants: every box whose owner is not a contractor may mount it) or granted (only the boxes named, and the boxes owned by the members named) and grants is [{id, boxId, hostname, userId, email, createdAt}]; 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. The grant rule is on Teams: Scoped secrets.

Policies

policy is {memberSpendCapUsd, memberBoxLimit, memberMaxTier, autoPauseFloorMin, quietHours, auditRetentionDays}, each null while off except auditRetentionDays (90 by default); quietHours is {start, end, days, allDayDays, timezone}. Changing them is PATCH /api/v1/workspace/policies from a dashboard session only: the body is the keys to change, null clears one (400 invalid_policy with field and message, 403 not_owner, 409 workspace_closing). A create, wake, resize or fork a policy refuses answers 403 policy_denied with rule and message. Bounds and what each rule does are on Teams: Policies.

Audit log

An event is {id, at, kind, origin, actorKind, actorUserId, actorTokenId, boxId, detail}; actorKind is user, cli, ticket, mobile or system. Owners and members read; a contractor is 403 not_allowed. Only exec, file.upload, file.download, prompt and desktop.start may be reported; detail takes 16 keys of up to 40 characters with strings of up to 512, the body 64 KiB, and a ticket may report only on its own box. Kinds, details and what a reported row means are on Teams: Audit log.

Team

scope is workspace, or own for a contractor (their boxes only, and members empty). A box is {id, hostname, tier, desiredState, observedState, ownerUserId, ownerName, ownerEmail, idleForSec, cpuPct, memPct, lastHeartbeatAt, sessions, lastPromptAt, lastExecAt, spendTodayMicros, spendCycleMicros} (idleForSec, cpuPct and memPct are null on a paused box); a member is {userId, name, email, role, boxes, sessions, spendCycleMicros, lastActiveAt}; totals is {spendTodayMicros, spendCycleMicros, running, sessions}; recent is the newest 50 audit events. What a session, today and the cycle mean is on Teams: Team activity.

The edge

Every route below is under $EDGE/v1/box/{box}/, where {box} is the box's name or id, with the same bearer; each request is checked against the control plane, so a revoked token dies on its next request. POST /exec and POST /prompts wake a suspended box; every other route answers 409 box_not_running instead. Paths 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"}}, with the codes under Errors below; a known path with the wrong method is 405 with Allow, an unknown path 404 not_found, in the same envelope.

Commands

The command runs under sh -c in your home (or cwd) as your box user. timedOut is set only when the time limit ended the command, so a command that exits 124 by itself is exitCode: 124, timedOut: false. A synchronous run that outgrows 1 MiB per stream keeps the last 1 MiB and sets the Truncated flag; use a detached run and /download on its log for the whole thing. The on-box process directory is on Run commands and files.

Files

Size caps are on Limits: 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} (Prompt an agent remotely: JSON and JSON Lines). A stream holds one of the token's concurrent request slots until the run ends. Approvals, continuity, the queue and the run directory on the box are on Prompt an agent remotely.

Desktop

This one route predates the edge envelope: its errors are the bare {"error": "code"} form, with unauthorized (a dcp_ token only), 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; from a script use prized desktop --no-open, which prints a vnc:// address and the password (Desktop).

Errors

Every edge route answers a failure as {"ok": false, "error": {"code", "message"}} with one of these codes:

The prompt routes add:

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)
until [ "$(curl -s "$API/boxes/$BOX" -H "$AUTH" | jq -r .box.observedState)" = running ]; do sleep 5; done

Run a command on it, upload a file, download a directory:

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}'
curl -s -X PUT "$EDGE/v1/box/ci-42/upload?path=data/train.bin" -H "$AUTH" --data-binary @train.bin
curl -s "$EDGE/v1/box/ci-42/download?path=app/dist" -H "$AUTH" -o dist.tar

Prompt the agent and follow it (a box with a run in progress answers prompt.queued with no run; pass 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"

Delete the box and wait for the operation:

OP=$(curl -s -X DELETE "$API/boxes/$BOX" -H "$AUTH" | jq -r .operation.id)
until [ "$(curl -s "$API/operations/$OP" -H "$AUTH" | jq -r .operation.status)" = completed ]; do sleep 5; done

Not yet

• No SDK and no OpenAPI document. The routes above with curl or your language's HTTP client are the whole interface; the CLI's --json output is the other machine interface (CLI: For agents and scripts).
• No webhooks. Poll GET /api/v1/boxes/{id} or GET /api/v1/operations/{id}; the push channels are the prompt event stream and the audit export, which carries audit rows only.
• 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.