API reference

Two hosts, one key

Both take the same bearer. Read the edge's address from edge.url in GET /api/v1/me rather than assuming one.

Sandboxes have their own routes on both hosts, with the same key: Sandbox API.

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

Authentication

Send Authorization: Bearer dcp_… on every request, with an API key: make one per script or agent with New key under Dashboard → Settings → API keys (prized login --token dcp_… signs a machine in with one), or, for someone new to Prized, let a coding agent make the account and get its own key with an emailed code (Agent sign-in). An agent key whose code has not come back yet gets 403 verification_required everywhere but GET /api/v1/me. A revoked key gets 401 on its next request. A key made with limited access (read only, or per area) gets 403 key_access_denied on anything outside it, with area, level and a message naming what it lacks (Workspaces: What a key can do).

• What a key can do. It acts as you on every box, snapshot, environment and secret in its workspace; a contractor's key reaches only their own boxes, and no secrets. Minting and rotating credentials, membership and roles, policies, the audit export, billing, and closing the workspace are dashboard-only and answer 401 unauthorized to any bearer, so a leaked key cannot widen itself.
• Expiry. A key past its expiry gets 401 token_expired, with expiresAt, on every route and on the edge. GET /api/v1/me says when the calling key expires (When a key expires).
• A key for some boxes. A key limited to boxes answers 404 not_found for any other box, as if it did not exist, and leaves other boxes out of every list. Workspace-wide routes (creating boxes, forks and templates, secrets, environments, sandboxes, team activity, the audit log, workspace settings) answer 403 key_access_denied with scope: "boxes" (Limit a key to some boxes).
• Other credentials. A dashboard terminal ticket works for its one box only, on the box read, wake and connect routes and the edge's exec, files and prompt routes; monitor tickets, phone passwords and shared-port viewer cookies work nowhere.
• The version header. Scripts should not send X-Prized-CLI-Version, the CLI's header: below the minimum it answers 426 cli_update_required with minVersion.

Conventions

An empty balance's wake_rejected adds reason, cause and billingUrl.

Idempotency keys

A create whose answer is lost (a timeout, a dropped connection, a 5xx) may or may not have made the box. Send an Idempotency-Key header with a value of your own, unique per request (a UUID), and a retry of that request within 24 hours gets the first answer back instead of a second box:

KEY=$(uuidgen)
curl -s --retry 3 --retry-all-errors -X POST "$API/boxes" -H "$AUTH" -H "Idempotency-Key: $KEY" -H "Content-Type: application/json" -d '{"tier":"flow"}'

The header works on POST /api/v1/boxes, POST /api/v1/boxes/{id}/fork, POST /api/v1/boxes/{id}/template, POST /api/v1/boxes/{id}/resize, POST /api/v1/boxes/{id}/region, POST /api/v1/snapshots and POST /api/v1/snapshots/{id}/restore.

A changed box scope refuses the replay rather than returning metadata from the earlier scope. Two credentials for the same member and the same box set can replay each other’s answer; the order of the box ids does not matter.

A key belongs to its workspace and route: the same value on another route, or in another workspace, is another key. Without the header, a retried create makes a second box, unless it names one (then 409 name_taken).

Account

{
  "customer": {
    "id": "3f9c…", "email": "you@example.com", "githubLogin": "you",
    "status": "active", "onboardingStep": "done",
    "onboardingCompletedAt": "2026-08-29T12:04:00Z",
    "createdAt": "2026-08-29T11:58:00Z", "name": "Acme"
  },
  "user": {"email": "you@example.com", "name": "Your Name", "role": "owner"},
  "workspace": {
    "id": "3f9c…", "name": "Acme",
    "zeroDataRetention": false, "closingAt": null, "purgeAfter": null
  },
  "billing": {
    "balanceMicros": 41250000, "burnMicrosPerHour": 160000,
    "runwayHours": 257.8125, "warnBelowHours": 48, "planAmountUsd": 50,
    "overage": true, "collecting": false,
    "paymentFailed": false, "paymentGraceUntil": null
  },
  "boxes": [
    {"id": "5d0a…", "hostname": "mango", "observedState": "running"}
  ],
  "edge": {"url": "https://…"}
}

• customer is the workspace: customer.id is the workspace id.
• user is who the key acts as, with their role; null for a key with no user.
• billing says why an empty balance may not stop boxes: overage, collecting (a renewal collecting, or a failed one in its grace), paymentFailed, paymentGraceUntil. runwayHours is null while nothing is burning. Also trial (free credit) and billingUrl.
• boxes is every box, terminated included (a contractor's own), each the box object, shortened above. box (the oldest live box in boxes) is deprecated; read boxes.
• key is the calling API key: {id, kind, expiresAt, boxIds}, where kind is machine (a prized login, whose expiresAt moves with use) or api (New key), expiresAt is null for a key that never expires, and boxIds is null unless the key is limited to boxes, whose ids it lists (then boxes holds only those). Absent for a dashboard session.
• A limited key adds access, its level per area. Without Boxes: Read it gets boxes: []; without Workspace: Read it gets billing: null, a workspace of only id and name, and null for customer.email and customer.githubLogin.

Boxes

A box-scoped ticket or phone password lists only its bound box. Once either desiredState or observedState is terminated, that list is empty, with or without live=1. Session and CLI-token lists keep their normal history.

A create refused with insufficient_balance includes message, balanceMicros, requiredMicros, and admissionMicrosPerHour. The allowance includes unbilled failed-launch cleanup reservations; it is not a charge. burnMicrosPerHour remains a compatibility alias for that allowance in this error response only. Display message when available.

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:

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, not both, null to clear; autoSnapshotHours 1 to 168 or null; autoSnapshotKeep 1 to 10), or {env} alone, replacing the per-box vars (100 names, 64 KiB in all). A deadline needs a running box (409 box_not_running); clearing one always works. autoPauseMin follows the create rule on the free credit, and a member's above the workspace's auto-pause floor is 403 policy_denied; only the owner may set quietHoursExempt, which keeps the box running through quiet hours (403 not_owner).

Command history

What prized exec and the edge's POST /exec ran on a box, read from the control plane, so it answers while the box is paused (Run commands and files: Command history). A box's records are visible to whoever can see the box.

{
  "id": "p_3f9c0a1b2d4e", "boxId": "5d0a…", "mode": "detached", "source": "cli",
  "command": "./train.sh", "commandTruncated": false, "cwd": "/home/you/app",
  "status": "exited", "exitCode": 0, "signal": null, "pid": 41213,
  "startedAt": "2026-10-11T14:02:11Z", "finishedAt": "2026-10-11T14:05:40Z",
  "actor": {"kind": "cli", "userId": "…", "tokenId": "…"},
  "stdoutBytes": 1830, "stderrBytes": 0,
  "stdoutTruncated": false, "stderrTruncated": false, "outputKept": true
}

• status is running, exited, killed, timed_out, failed, or lost; exitCode, signal, pid, and finishedAt are null until known. source is cli (prized exec) or api (POST /exec).
• command is the first 8,192 characters (commandTruncated says when it was cut). Under zero data retention command and cwd are null and outputKept is false.
• Output pages are bytes of one stream from offset. Read again from nextOffset until done (the command ended and every byte has been read). size is the stream's length; skipped is how many bytes from your offset are no longer kept (up to the last 1 MiB of a stream is; a 256-chunk cap may trim heavily fragmented output sooner), and the page then starts later. utf8 never ends a page inside a character; for exact bytes ask for base64.
• A limited key needs Boxes: Write for every history route, reads included: command lines and output can carry secrets. A key limited to some boxes reaches only those boxes' history; any other box is 404 not_found.

Shared ports

A shared port is a link to one port on a box, for one audience: members (signed-in workspace members who can see the box, under p.prized.dev), anyone (whoever holds the link, which carries a secret), or public (anyone at all) (Ports: Share a port).

• The body: port 1 to 65535; access members (the default), anyone or public; expiresIn in seconds for anyone and public only, 300 to 2592000, 604800 (7 days) by default. Anything else is 400 bad_request.
• The share object: id, boxId, hostname, port, slug, access, url, origin, expiresAt (null for members), createdBy (the member who shared it), createdAt, openCount, lastOpenedAt. url is the link to hand out; an anyone link's carries its secret in the 201 that made it and is null everywhere after.
• modes: for each audience, {"allowed": true} or {"allowed": false, "error", "message"} with what a create would answer, so a client can grey out what you cannot pick.
• Off: enabled: false means members links are off here (a create answers 503 port_share_disabled); linksEnabled: false means anyone and public links are (503 share_links_disabled).

Cloud federation

The IAM roles the workspace's boxes assume (AWS access). Owners and members read, only owners write (403 not_owner), and a contractor gets 403 not_allowed. If federation is off on this deployment, the list answers enabled: false, and connect and verify answer 503 aws_federation_disabled.

Operations

Deletes answer with one. status runs pending, processing, then 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 workspace_held, 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 has the name.

Environments

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

Secrets

Brokered credentials: the box sees a placeholder, swapped for the value only in HTTPS requests to the secret's hosts (Credentials, Connectors).

A secret is {id, name, description, hosts, placeholder, mountCount, scope, grants, createdAt, updatedAt, lastRotatedAt}, where scope is workspace (no grants) or granted (Teams: Scoped secrets) 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.

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}. PATCH /api/v1/workspace/policies (dashboard session only) takes the keys to change, null clearing one: 400 invalid_policy with field and message, 403 not_owner, 409 workspace_closing. A create, wake, resize or fork that a policy refuses answers 403 policy_denied with rule and message; bounds and rules 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. Clients may report only exec, file.upload, file.download, prompt and desktop.start (detail: 16 keys of up to 40 characters, strings of up to 512; body: 64 KiB), and a ticket only on its own box (Teams: Audit log). Reports for a box being deleted or already deleted return 404 not_found; its existing audit history remains readable.

box.connect records SSH certificate issuance, not a successful connection. The dashboard labels it SSH certificate issued; the API, CSV and scheduled export keep the box.connect kind. A failed connection can still have this row (Teams: Audit log).

Team

API key access: Workspace: Read (or Write). Boxes-only keys receive 403 key_access_denied with area: "workspace" and level: "read"; the response includes workspace members, spend and recent activity, not just boxes. Full-access keys and browser sessions keep their existing role-based view.

{
  "now": "2026-09-10T17:20:00Z",
  "cycle": {"start": "2026-09-01T00:00:00Z", "end": "2026-10-01T00:00:00Z"},
  "scope": "workspace",
  "boxes": [
    {
      "id": "5d0a…", "hostname": "mango", "tier": "flow",
      "desiredState": "running", "observedState": "running",
      "ownerUserId": "7Hq2…", "ownerName": "Kat",
      "ownerEmail": "kat@example.com",
      "idleForSec": 0, "cpuPct": 12, "memPct": 41,
      "lastHeartbeatAt": "2026-09-10T17:19:42Z", "sessions": 1,
      "lastPromptAt": "2026-09-10T16:58:03Z", "lastExecAt": null,
      "spendTodayMicros": 1920000, "spendCycleMicros": 28800000
    }
  ],
  "members": [
    {
      "userId": "7Hq2…", "name": "Kat", "email": "kat@example.com",
      "role": "member", "boxes": 1, "sessions": 1,
      "spendCycleMicros": 28800000,
      "lastActiveAt": "2026-09-10T16:58:03Z"
    }
  ],
  "totals": {
    "spendTodayMicros": 1920000, "spendCycleMicros": 28800000,
    "running": 1, "sessions": 1
  },
  "recent": [
    {
      "id": 48213, "at": "2026-09-10T09:02:11Z", "kind": "box.wake",
      "origin": "server", "actorKind": "cli", "actorUserId": "7Hq2…",
      "actorTokenId": "9b1e…", "boxId": "5d0a…", "detail": {}
    }
  ]
}

scope is workspace, or own for a contractor (their boxes only, and members empty). A box's idleForSec, cpuPct and memPct are null unless it is running; recent is the newest 50 audit events. What a session, today and the cycle mean is on Teams: Team activity.

The edge

Routes below are relative to $EDGE/v1/box/{box}/. 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.

A successful answer carries ok: true and a type; a failed one carries a code from Errors.

Commands

The answer to the make test run in Examples:

{
  "ok": true, "type": "exec.result",
  "exitCode": 0, "signal": "",
  "stdout": "ok  \tapp/internal/api\t1.42s\n", "stderr": "",
  "stdoutTruncated": false, "stderrTruncated": false, "timedOut": false,
  "startedAt": "2026-09-10T17:20:01Z", "finishedAt": "2026-09-10T17:20:04Z",
  "cwd": "app"
}

Commands run under sh -c as your box user, in your home or cwd; the answer's cwd is the one you sent, or ~. timedOut means the time limit ended the command (exiting 124 by itself is exitCode: 124, timedOut: false). A synchronous run keeps the last 1 MiB per stream and sets its Truncated flag; for all of it, run detached and /download the log (Run commands and files). Both answers carry commandId when the run was recorded in the command history; for a detached run it equals processId.

The stream follows one detached process from the given offsets. Each event's data: is one JSON object and its id: is <stdoutOffset>:<stderrOffset> after it:

A stream holds one of the token's and the box's 8 concurrent requests while open, and a token holds at most 4 streams; a fifth answers 429 rate_limited.

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} (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 are on Prompt an agent remotely.

Conversations: POST /prompts also takes new (a new conversation) or conversationId (continue that one), at most one of them and continue, and answers conversationId in the run and in prompt.queued; a run also carries conversationId. Without new, conversationId or continue a prompt starts a new conversation, unless queue is set and a run of the same provider is in progress, which it then follows. A conversation is {id, provider, model, prompts, queued, running, lastRunId, lastStatus, sessionId, lastPrompt, createdAt, updatedAt} (Conversations). Every provider, OpenCode and pi included, and every backend model work in conversations alike.

Desktop

Its errors use the bare {"error": "code"} form: unauthorized (a dcp_ token only), token_expired, not_found, bad_request, request_timeout (408 if the request body takes too long to arrive), box_not_running, box_unreachable, desktop_stop_failed, resolve_failed, control_plane_unavailable and rate_limited (429 with Retry-After; a stop counts against the edge's per-token and per-box limits). The desktop stream itself is a dashboard WebSocket; from a script, prized desktop --no-open prints a vnc:// address and the password (Desktop).

Errors

Every edge route but POST /desktop/stop fails 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 (each prompt starts a new conversation unless it names one; run.conversationId is the id to pass as conversationId next time, and a prompt for a conversation with a run in progress answers prompt_in_progress unless it passes queue: true):

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