# Sandbox API reference

Create, list, read, start, stop and delete sandboxes through the customer API.

## Authentication

Call https://api.runzivo.dev with a person's access token or a workspace API key as a bearer token. An API key reads sandboxes with the sandboxes:read or sandboxes:write permission, and creates, starts, stops, deletes, runs commands and opens terminals with sandboxes:write. These are key permissions, not scopes: grant them under Settings, API Keys in the portal, or with rzv api-keys create --permissions sandboxes:write. A key with the all:all scope can do all of this too. A key can never do more than its creator's current workspace role allows. While Agent Sandboxes are off, every route answers 503 sandboxes_unavailable.

## Endpoints

- GET /v1/customer/tenants/{tenantId}/sandboxes lists sandboxes, newest first, with sizes (the sizes on offer) and max_running.
- POST /v1/customer/tenants/{tenantId}/sandboxes creates a sandbox and starts it. Answers 201.
- GET /v1/customer/tenants/{tenantId}/sandboxes/{sandboxId} reads one sandbox.
- POST /v1/customer/tenants/{tenantId}/sandboxes/{sandboxId}/start starts a stopped or failed sandbox. It keeps its original expiry.
- POST /v1/customer/tenants/{tenantId}/sandboxes/{sandboxId}/stop stops a running sandbox. Its files stay.
- DELETE /v1/customer/tenants/{tenantId}/sandboxes/{sandboxId} stops the VM and removes the workspace disk. The files cannot be recovered. Deleting again changes nothing.

## Create request

- name: 1 to 80 characters. Required.
- size: 2vcpu-8gb, 4vcpu-16gb, 8vcpu-32gb or 16vcpu-64gb, billed at 1x, 2x, 4x or 8x. Required. Offered sizes depend on current capacity: use one that the list response's sizes field names.
- disk_gib: 5 to 64, default 20.
- client_operation_id: 8 to 200 characters. Repeating it returns the sandbox it first created.

## Sandbox object

- id (sbx\_ and 24 hex characters), name, size, disk_gib, status, created_at.
- error: null, or a code and message. Codes: no_capacity, insufficient_disk, start_timeout, stop_timeout, boot_failed, host_lost, credit_exhausted, workspace_blocked.
- started_at: the first start, null until then. expires_at: the first start plus eight hours.
- remaining_seconds: lifetime left, 28800 before the first start and 0 once expired. runtime_seconds: time the VM has been up.
- credits_used: unit-minutes charged so far, at the size's multiplier.

## Refusals

- 403: the token or its creator's role does not allow the route. 404 sandbox_not_found: no such sandbox in this workspace.
- 409 sandbox_limit_reached, credit_exhausted, sandbox_name_taken, size_unavailable, workspace_blocked, sandbox_expired or sandbox_wrong_state.

[Read about sandbox statuses](https://runzivo.dev/docs/sandboxes/)

[See limits and billing](https://runzivo.dev/docs/sandboxes-limits/)

On this page and page tools