Sandboxes

Create a sandbox

Provisions a sandbox and returns once it is ready to accept commands. Pass an Idempotency-Key header to make retries safe: repeating a request with the same key returns the original sandbox instead of creating a second one.

post/sandboxes

Request

  • Base URL: https://sandbox-as-a-service.com/v1
  • URL: https://sandbox-as-a-service.com/v1/sandboxes
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Client-generated key that makes this creation request safe to retry.

Request body

size'small' | 'medium' | 'large'

small: 2 vCPU, 4 GB RAM, 40 GB disk; medium: 4 vCPU, 8 GB RAM, 80 GB disk; large: 8 vCPU, 16 GB RAM, 160 GB disk

namestring

Optional label for your own reference.

timeout_minutesinteger

The sandbox is destroyed automatically after this many minutes.

snapshot_idstring

Restore this snapshot into a new sandbox instead of booting a fresh one. The snapshot must be available, and the new sandbox boots from its captured image with the size the snapshot was taken at — omit size for that, or pass size matching it. The captured filesystem is restored; processes are not. Billing, capacity and concurrency checks apply as for any other create.

Example request

{
  "snapshot_id": "snap_4b1d2e3f4a5b6c7d9e"
}

Response

An existing sandbox was returned because the idempotency key was reused.

object'sandbox'
idstring
namestring nullable
status'provisioning' | 'running' | 'deleting' | 'deleted' | 'failed'

Lifecycle state. Commands can only run while the sandbox is running.

size'small' | 'medium' | 'large'
timeout_minutesinteger
created_atstring date-time
ready_atstring date-time nullable
expires_atstring date-time nullable
deleted_atstring date-time nullable

Example response

{
  "id": "sbx_9f2c4a1b8d3e6f0a12",
  "name": "data-cleaning-job",
  "resources": {
    "vcpu": 2,
    "memory_gb": 4,
    "disk_gb": 40
  },
  "timeout_minutes": 15
}

Changes

No recorded changes to this operation across all 1 revision of this API.