curl --silent --show-error --fail-with-body --request POST \
--url 'https://api.sandbox.stateset.app/api/v1/sandbox/create' \
--header 'Authorization: ApiKey YOUR_API_KEY' \
--header "Idempotency-Key: ${IDEMPOTENCY_KEY:?Set a unique key for this operation; preserve it on retries}" \
--header 'Content-Type: application/json' \
--data '{
"isolation": "gvisor",
"cpus": "1",
"memory": "1Gi",
"timeout_seconds": 600
}'
{
"sandbox_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"org_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "creating",
"pod_ip": "string",
"sandbox_epoch": 1,
"allocated_vcpu": 1.5,
"allocated_memory_gib": 1.5,
"created_at": "2026-08-31T14:22:05Z",
"expires_at": "2026-08-31T14:22:05Z",
"max_expires_at": "2026-08-31T14:22:05Z",
"max_lifetime_seconds": 250,
"remaining_extend_seconds": 250,
"lifetime_used_seconds": 250,
"lifetime_used_percent": 7.5,
"resource_class": "shared",
"workspace": {
"persistence": "ephemeral",
"pvc_name": "string",
"size": "string"
},
"startup_metrics": {
"total_ms": 250,
"pod_creation_ms": 250,
"pod_ready_ms": 250,
"phases": [
{
"name": "Two-Person Tent",
"durationMs": 7.5
}
]
}
}
Create a new sandbox
Sandbox created successfully
POST
/
api
/
v1
/
sandbox
/
create
curl --silent --show-error --fail-with-body --request POST \
--url 'https://api.sandbox.stateset.app/api/v1/sandbox/create' \
--header 'Authorization: ApiKey YOUR_API_KEY' \
--header "Idempotency-Key: ${IDEMPOTENCY_KEY:?Set a unique key for this operation; preserve it on retries}" \
--header 'Content-Type: application/json' \
--data '{
"isolation": "gvisor",
"cpus": "1",
"memory": "1Gi",
"timeout_seconds": 600
}'
{
"sandbox_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"org_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "creating",
"pod_ip": "string",
"sandbox_epoch": 1,
"allocated_vcpu": 1.5,
"allocated_memory_gib": 1.5,
"created_at": "2026-08-31T14:22:05Z",
"expires_at": "2026-08-31T14:22:05Z",
"max_expires_at": "2026-08-31T14:22:05Z",
"max_lifetime_seconds": 250,
"remaining_extend_seconds": 250,
"lifetime_used_seconds": 250,
"lifetime_used_percent": 7.5,
"resource_class": "shared",
"workspace": {
"persistence": "ephemeral",
"pvc_name": "string",
"size": "string"
},
"startup_metrics": {
"total_ms": 250,
"pod_creation_ms": 250,
"pod_ready_ms": 250,
"phases": [
{
"name": "Two-Person Tent",
"durationMs": 7.5
}
]
}
}
Confirm your deployment before running this request. This page describes an API contract;
a published reference does not establish hosted availability. Check the dated
host report and obtain your deployment URL and credentials.
Replace the example host if your provisioned service uses a different URL.
Headers
string
Persist before first dispatch; exact retries retain principal, route, body and original result. Do not change keys to escape an uncertain mutation.
Request body
CreateSandboxRequest
string (uuid)
string
string
string
string
Requested admitted runtime tier; deployment allowlist, RuntimeClass and compatible nodes are required. Wasm is not available. Allowed values:
'container', 'gvisor', 'microvm', 'kata'.integer
Sandbox lifetime including startup, subject to plan limits. Above 86400 requires enabled durable mode and an eligible plan; this is separate from the client startup wait and command timeout. Minimum:
60. Maximum: 604800.object
Additional keys map to values of type
string.object
boolean
string
string
Minimum length:
1. Maximum length: 500.string
Allowed values:
'linux', 'windows', 'macos'. Default: 'linux'.string
Allowed values:
'shared', 'dedicated'.object
object[]
object
Response
SandboxResponse
string (uuid)
required
Unique sandbox identifier.
string
required
Organization that owns this sandbox.
string
required
Session identifier.
string
required
Current sandbox status. Allowed values:
'creating', 'running', 'pausing', 'paused', 'resuming', 'terminating', 'terminated', 'error'.string
Internal pod IP address.
integer
required
Sandbox recycle epoch counter. Minimum:
-9007199254740991. Maximum: 9007199254740991.number
Allocated vCPU cores.
number
Allocated memory in GiB.
string (date-time)
required
ISO 8601 creation timestamp.
string (date-time)
required
ISO 8601 expiration timestamp.
string (date-time)
required
Maximum possible expiration.
integer
required
Maximum sandbox lifetime in seconds. Minimum:
-9007199254740991. Maximum: 9007199254740991.integer
required
Seconds available for extension. Minimum:
-9007199254740991. Maximum: 9007199254740991.integer
required
Seconds of lifetime consumed. Minimum:
-9007199254740991. Maximum: 9007199254740991.number
required
Percentage of lifetime consumed.
string
required
Resource class: dedicated (guaranteed) or shared (burstable, preemptible Spot capacity). Allowed values:
'shared', 'dedicated'.object
required
object
Status codes
| Code | Meaning |
|---|---|
201 | Sandbox created successfully |
202 | Request queued due to concurrency limits |
400 | Invalid request (including RESOURCE_CLASS_UNAVAILABLE: resource_class shared is not enabled) |
401 | Authentication required |
402 | Payment required (including RESOURCE_CLASS_NOT_BILLABLE: the subscription has no shared compute items) |
429 | Concurrent limit exceeded |
Using this contract
Read the source OpenAPI document for declared schemas and alternatives. This page also includes documented corrections from the spec overlays. Example IDs and values are illustrative; replace them with records from your workspace.curl --silent --show-error --fail-with-body --request POST \
--url 'https://api.sandbox.stateset.app/api/v1/sandbox/create' \
--header 'Authorization: ApiKey YOUR_API_KEY' \
--header "Idempotency-Key: ${IDEMPOTENCY_KEY:?Set a unique key for this operation; preserve it on retries}" \
--header 'Content-Type: application/json' \
--data '{
"isolation": "gvisor",
"cpus": "1",
"memory": "1Gi",
"timeout_seconds": 600
}'
{
"sandbox_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"org_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "creating",
"pod_ip": "string",
"sandbox_epoch": 1,
"allocated_vcpu": 1.5,
"allocated_memory_gib": 1.5,
"created_at": "2026-08-31T14:22:05Z",
"expires_at": "2026-08-31T14:22:05Z",
"max_expires_at": "2026-08-31T14:22:05Z",
"max_lifetime_seconds": 250,
"remaining_extend_seconds": 250,
"lifetime_used_seconds": 250,
"lifetime_used_percent": 7.5,
"resource_class": "shared",
"workspace": {
"persistence": "ephemeral",
"pvc_name": "string",
"size": "string"
},
"startup_metrics": {
"total_ms": 250,
"pod_creation_ms": 250,
"pod_ready_ms": 250,
"phases": [
{
"name": "Two-Person Tent",
"durationMs": 7.5
}
]
}
}
Last modified on October 20, 2026