Sandbox API reference
Project-scoped durable environments and isolated compute sessions.
Published contracts: @socra/sandbox-api@0.0.7.
Base URL
https://sandbox.socra.cloudSandboxes
A durable project-scoped environment with replaceable isolated Sessions.
Find a provisioned environment by its stable key
GET
/v1/sandboxes/provisioningQuery parameters
project_idcustomrequiredprovisioning_keystringrequiredpattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$Response
object | null
object | null
Create sandbox
POST
/v1/sandboxesRequest body
project_idcustomrequiredimagestringrequiredmin length: 1commandstring[]optionalmin items: 1persistentbooleanoptionaldefault: falsemountsobjectoptionaldefault: {}timeout_secondsintegeroptionaldefault: 3600 · min: 60 · max: 86400storage_size_gibintegeroptionaldefault: 20 · min: 1 · max: 16384startbooleanoptionaldefault: trueprovisioning_keystringoptionalStable project-scoped key for retrying stopped-environment provisioning; requires start=false
pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$Response
16 fields
idcustomrequiredproject_idcustomrequiredimagestringrequiredcommandstring[] | nullrequiredpersistentbooleanrequiredmountsobjectrequireddefault: {}mounts_backend"block" | "ebs"optionalmigration_mountsobjectoptionaltimeout_secondsintegerrequiredmin: 60 · max: 86400storage_size_gibinteger | nullrequiredstatus"starting" | "running" | "stopping" | "stopped" | "failed"requiredactive_session_idcustom | nullrequiredlatest_snapshot_idcustom | nullrequirederrorstring | nullrequiredcreated_atcustomrequiredupdated_atcustomrequiredList sandboxes
GET
/v1/sandboxesQuery parameters
limitintegeroptionalmin: 1 · max: 100afterstringoptionalproject_idcustomrequiredstatus"starting" | "running" | "stopping" | "stopped" | "failed"optionalResponse
2 fields
dataobject[]required
dataobject[]requiredidcustomrequiredproject_idcustomrequiredimagestringrequiredcommandstring[] | nullrequiredpersistentbooleanrequiredmountsobjectrequireddefault: {}mounts_backend"block" | "ebs"optionalmigration_mountsobjectoptionaltimeout_secondsintegerrequiredmin: 60 · max: 86400storage_size_gibinteger | nullrequiredstatus"starting" | "running" | "stopping" | "stopped" | "failed"requiredactive_session_idcustom | nullrequiredlatest_snapshot_idcustom | nullrequirederrorstring | nullrequiredcreated_atcustomrequiredupdated_atcustomrequiredhas_morebooleanrequiredGet sandbox
GET
/v1/sandboxes/{id}Path parameters
idcustomrequiredQuery parameters
No query parameters
Response
16 fields
idcustomrequiredproject_idcustomrequiredimagestringrequiredcommandstring[] | nullrequiredpersistentbooleanrequiredmountsobjectrequireddefault: {}mounts_backend"block" | "ebs"optionalmigration_mountsobjectoptionaltimeout_secondsintegerrequiredmin: 60 · max: 86400storage_size_gibinteger | nullrequiredstatus"starting" | "running" | "stopping" | "stopped" | "failed"requiredactive_session_idcustom | nullrequiredlatest_snapshot_idcustom | nullrequirederrorstring | nullrequiredcreated_atcustomrequiredupdated_atcustomrequiredUpdate sandbox
PATCH
/v1/sandboxes/{id}Path parameters
idcustomrequiredRequest body
timeout_secondsintegeroptionalmin: 60 · max: 86400imagestringoptionalmin length: 1mountsobjectoptionalcommandstring[]optionalmin items: 1Response
16 fields
idcustomrequiredproject_idcustomrequiredimagestringrequiredcommandstring[] | nullrequiredpersistentbooleanrequiredmountsobjectrequireddefault: {}mounts_backend"block" | "ebs"optionalmigration_mountsobjectoptionaltimeout_secondsintegerrequiredmin: 60 · max: 86400storage_size_gibinteger | nullrequiredstatus"starting" | "running" | "stopping" | "stopped" | "failed"requiredactive_session_idcustom | nullrequiredlatest_snapshot_idcustom | nullrequirederrorstring | nullrequiredcreated_atcustomrequiredupdated_atcustomrequiredStart sandbox
POST
/v1/sandboxes/{id}/startPath parameters
idcustomrequiredRequest body
No request body
Response
16 fields
idcustomrequiredproject_idcustomrequiredimagestringrequiredcommandstring[] | nullrequiredpersistentbooleanrequiredmountsobjectrequireddefault: {}mounts_backend"block" | "ebs"optionalmigration_mountsobjectoptionaltimeout_secondsintegerrequiredmin: 60 · max: 86400storage_size_gibinteger | nullrequiredstatus"starting" | "running" | "stopping" | "stopped" | "failed"requiredactive_session_idcustom | nullrequiredlatest_snapshot_idcustom | nullrequirederrorstring | nullrequiredcreated_atcustomrequiredupdated_atcustomrequiredStop sandbox
POST
/v1/sandboxes/{id}/stopPath parameters
idcustomrequiredRequest body
No request body
Response
16 fields
idcustomrequiredproject_idcustomrequiredimagestringrequiredcommandstring[] | nullrequiredpersistentbooleanrequiredmountsobjectrequireddefault: {}mounts_backend"block" | "ebs"optionalmigration_mountsobjectoptionaltimeout_secondsintegerrequiredmin: 60 · max: 86400storage_size_gibinteger | nullrequiredstatus"starting" | "running" | "stopping" | "stopped" | "failed"requiredactive_session_idcustom | nullrequiredlatest_snapshot_idcustom | nullrequirederrorstring | nullrequiredcreated_atcustomrequiredupdated_atcustomrequiredRestart sandbox
POST
/v1/sandboxes/{id}/restartPath parameters
idcustomrequiredRequest body
No request body
Response
16 fields
idcustomrequiredproject_idcustomrequiredimagestringrequiredcommandstring[] | nullrequiredpersistentbooleanrequiredmountsobjectrequireddefault: {}mounts_backend"block" | "ebs"optionalmigration_mountsobjectoptionaltimeout_secondsintegerrequiredmin: 60 · max: 86400storage_size_gibinteger | nullrequiredstatus"starting" | "running" | "stopping" | "stopped" | "failed"requiredactive_session_idcustom | nullrequiredlatest_snapshot_idcustom | nullrequirederrorstring | nullrequiredcreated_atcustomrequiredupdated_atcustomrequiredExecute command in sandbox
POST
/v1/sandboxes/{id}/execPath parameters
idcustomrequiredRequest body
commandstring[]requiredmin items: 1Response
5 fields
session_idcustomrequiredresumedbooleanrequiredexit_codeintegerrequiredmin: -9007199254740991 · max: 9007199254740991stdoutstringrequiredstderrstringrequiredDelete sandbox
DELETE
/v1/sandboxes/{id}Path parameters
idcustomrequiredQuery parameters
No query parameters
Response
No response body
Sessions
One observable Kata microVM incarnation of a Sandbox.
Create session
POST
/v1/sessionsRequest body
sandbox_idcustomrequiredResponse
14 fields
idcustomrequiredsandbox_idcustomrequiredproject_idcustomrequirednumberintegerrequiredgreater than: 0 · max: 9007199254740991status"starting" | "running" | "stopping" | "stopped" | "failed"requiredtimeout_secondsintegerrequiredmin: 60 · max: 86400expires_atcustomrequiredstop_reason"requested" | "timeout" | "restart" | "failure" | "replaced" | nullrequiredsnapshot_idcustom | nullrequirederrorstring | nullrequiredcreated_atcustomrequiredupdated_atcustomrequiredstarted_atcustom | nullrequiredstopped_atcustom | nullrequiredList sessions
GET
/v1/sessionsQuery parameters
limitintegeroptionalmin: 1 · max: 100afterstringoptionalproject_idcustomrequiredsandbox_idcustomoptionalstatus"starting" | "running" | "stopping" | "stopped" | "failed"optionalResponse
2 fields
dataobject[]required
dataobject[]requiredidcustomrequiredsandbox_idcustomrequiredproject_idcustomrequirednumberintegerrequiredgreater than: 0 · max: 9007199254740991status"starting" | "running" | "stopping" | "stopped" | "failed"requiredtimeout_secondsintegerrequiredmin: 60 · max: 86400expires_atcustomrequiredstop_reason"requested" | "timeout" | "restart" | "failure" | "replaced" | nullrequiredsnapshot_idcustom | nullrequirederrorstring | nullrequiredcreated_atcustomrequiredupdated_atcustomrequiredstarted_atcustom | nullrequiredstopped_atcustom | nullrequiredhas_morebooleanrequiredGet session
GET
/v1/sessions/{id}Path parameters
idcustomrequiredQuery parameters
No query parameters
Response
14 fields
idcustomrequiredsandbox_idcustomrequiredproject_idcustomrequirednumberintegerrequiredgreater than: 0 · max: 9007199254740991status"starting" | "running" | "stopping" | "stopped" | "failed"requiredtimeout_secondsintegerrequiredmin: 60 · max: 86400expires_atcustomrequiredstop_reason"requested" | "timeout" | "restart" | "failure" | "replaced" | nullrequiredsnapshot_idcustom | nullrequirederrorstring | nullrequiredcreated_atcustomrequiredupdated_atcustomrequiredstarted_atcustom | nullrequiredstopped_atcustom | nullrequiredUpdate session timeout
PATCH
/v1/sessions/{id}Path parameters
idcustomrequiredRequest body
timeout_secondsintegerrequiredmin: 60 · max: 86400Response
14 fields
idcustomrequiredsandbox_idcustomrequiredproject_idcustomrequirednumberintegerrequiredgreater than: 0 · max: 9007199254740991status"starting" | "running" | "stopping" | "stopped" | "failed"requiredtimeout_secondsintegerrequiredmin: 60 · max: 86400expires_atcustomrequiredstop_reason"requested" | "timeout" | "restart" | "failure" | "replaced" | nullrequiredsnapshot_idcustom | nullrequirederrorstring | nullrequiredcreated_atcustomrequiredupdated_atcustomrequiredstarted_atcustom | nullrequiredstopped_atcustom | nullrequiredStop session
POST
/v1/sessions/{id}/stopPath parameters
idcustomrequiredRequest body
No request body
Response
14 fields
idcustomrequiredsandbox_idcustomrequiredproject_idcustomrequirednumberintegerrequiredgreater than: 0 · max: 9007199254740991status"starting" | "running" | "stopping" | "stopped" | "failed"requiredtimeout_secondsintegerrequiredmin: 60 · max: 86400expires_atcustomrequiredstop_reason"requested" | "timeout" | "restart" | "failure" | "replaced" | nullrequiredsnapshot_idcustom | nullrequirederrorstring | nullrequiredcreated_atcustomrequiredupdated_atcustomrequiredstarted_atcustom | nullrequiredstopped_atcustom | nullrequiredExecute command in session
POST
/v1/sessions/{id}/execPath parameters
idcustomrequiredRequest body
commandstring[]requiredmin items: 1Response
5 fields
session_idcustomrequiredresumedbooleanrequiredexit_codeintegerrequiredmin: -9007199254740991 · max: 9007199254740991stdoutstringrequiredstderrstringrequiredSnapshots
An immutable checkpoint of a persistent Sandbox home.
Create snapshot
POST
/v1/snapshotsRequest body
sandbox_idcustomrequiredResponse
9 fields
idcustomrequiredsandbox_idcustomrequiredsession_idcustom | nullrequiredproject_idcustomrequiredstatus"creating" | "ready" | "failed"requiredvolume_snapshot_namestringrequiredready_atcustom | nullrequirederrorstring | nullrequiredcreated_atcustomrequiredList snapshots
GET
/v1/snapshotsQuery parameters
limitintegeroptionalmin: 1 · max: 100afterstringoptionalproject_idcustomrequiredsandbox_idcustomoptionalstatus"creating" | "ready" | "failed"optionalResponse
2 fields
dataobject[]required
dataobject[]requiredidcustomrequiredsandbox_idcustomrequiredsession_idcustom | nullrequiredproject_idcustomrequiredstatus"creating" | "ready" | "failed"requiredvolume_snapshot_namestringrequiredready_atcustom | nullrequirederrorstring | nullrequiredcreated_atcustomrequiredhas_morebooleanrequiredGet snapshot
GET
/v1/snapshots/{id}Path parameters
idcustomrequiredQuery parameters
No query parameters
Response
9 fields
idcustomrequiredsandbox_idcustomrequiredsession_idcustom | nullrequiredproject_idcustomrequiredstatus"creating" | "ready" | "failed"requiredvolume_snapshot_namestringrequiredready_atcustom | nullrequirederrorstring | nullrequiredcreated_atcustomrequiredDelete snapshot
DELETE
/v1/snapshots/{id}Path parameters
idcustomrequiredQuery parameters
No query parameters
Response
No response body