Documentation
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. Reads accept a key with sandboxes:read, sandboxes:write or all:all. Create, start, stop, delete, exec and the terminal accept a key with sandboxes:write or all:all. 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 or 4vcpu-16gb. Required.
- 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.