API by area

Sandboxes

58 endpoints. Paths are relative to https://api.sandscale.dev; values in braces are ones you fill in.

API reference · Authentication · Errors

MethodPathWhat it does
GET/api/v1/sandbox/artifactsList artifacts
POST/api/v1/sandbox/artifacts/{id}/approveApprove an artifact
POST/api/v1/sandbox/artifacts/{id}/rejectReject an artifact
GET/api/v1/sandbox/instancesList instances
POST/api/v1/sandbox/instancesCreate an instance
GET/api/v1/sandbox/instances/{id}Get one instance
DELETE/api/v1/sandbox/instances/{id}Delete one instance
POST/api/v1/sandbox/instances/{id}/execExec an instance
GET/api/v1/sandbox/instances/{id}/filesReads a file or lists a directory inside a running sandbox instance, in its own container.
PUT/api/v1/sandbox/instances/{id}/filesWrites a file into a running sandbox instance, in its own container.
GET/api/v1/sandbox/instances/{id}/logsAs Server-Sent Events.
GET/api/v1/sandbox/instances/{id}/metricsAnswers GET .../metrics once the caller may use the sandbox.
POST/api/v1/sandbox/instances/{id}/pausePause an instance
GET/api/v1/sandbox/instances/{id}/portsThe sandbox's open exposures.
POST/api/v1/sandbox/instances/{id}/portsCreate a port for an instance
DELETE/api/v1/sandbox/instances/{id}/ports/{port}({port} is the exposure's ID or its port number).
GET/api/v1/sandbox/instances/{id}/ports/{port}/connectOne TCP connection to the exposed port, as a WebSocket of binary messages.
POST/api/v1/sandbox/instances/{id}/projectProject an instance
GET/api/v1/sandbox/instances/{id}/project/changesList changes
GET/api/v1/sandbox/instances/{id}/ptyAnswers GET .../pty once the caller may use the sandbox.
POST/api/v1/sandbox/instances/{id}/resumeResume an instance
GET/api/v1/sandbox/instances/{id}/runsList the runs of an instance
POST/api/v1/sandbox/instances/{id}/snapshotSnapshot an instance
GET/api/v1/sandbox/instances/{id}/snapshots(the caller's, or every one for an organization sandbox manager) and GET /api/v1/sandbox/snapshots.
GET/api/v1/sandbox/instances/{id}/sshThe host, user, pinned host key and routes, when the caller may use SSH on the sandbox.
POST/api/v1/sandbox/instances/{id}/ssh/certificateCreate a certificate
GET/api/v1/sandbox/instances/{id}/ssh/connectOne SSH connection, as a WebSocket of binary messages.
POST/api/v1/sandbox/jobs/{id}/inputHandles stdin injection into a running job. POST /api/v1/sandbox/jobs/{id}/input with body {"data":"..."}
POST/api/v1/sandbox/jobs/{id}/pty/resizeHandles PTY window resize requests. POST /api/v1/sandbox/jobs/{id}/pty/resize with body {"rows":N,"cols":N}
GET/api/v1/sandbox/kill-switchList kill switch
GET/api/v1/sandbox/launch-optionsFor whoever may start sandboxes (mayStart). Templates are the ready ones the caller may start from (the template list's rule); sizes and refusals follow the policy, the per-member quota and the organization's concurrency limit as the create checks them.
GET/api/v1/sandbox/orgs/{id}/billing/usageList usage
GET/api/v1/sandbox/policyList policy
PUT/api/v1/sandbox/policySet policy
GET/api/v1/sandbox/policy/port-exposureList port exposure
PUT/api/v1/sandbox/policy/port-exposureThe whole policy. Exposures it no longer allows are closed with the change. A change that widens the policy is re-verified: a stolen administrator session cannot open every sandbox's ports.
GET/api/v1/sandbox/policy/snapshotsList snapshots
PUT/api/v1/sandbox/policy/snapshotsThe whole policy. Existing snapshots keep their retention; a lower quota refuses new snapshots until usage is under it.
GET/api/v1/sandbox/policy/sshList ssh
PUT/api/v1/sandbox/policy/sshThe whole policy. Live sessions it no longer allows end at their next check.
GET/api/v1/sandbox/policy/warm-poolList warm pool
PUT/api/v1/sandbox/policy/warm-pool]}: the whole set. The maintainer starts and ends members to match within a minute.
GET/api/v1/sandbox/quotaList quota
GET/api/v1/sandbox/runsList runs
GET/api/v1/sandbox/runs/{id}Get one run
DELETE/api/v1/sandbox/runs/{id}Cancels a running job by marking it in the store and signaling the assigned worker via a cancellation record.
GET/api/v1/sandbox/snapshots(the caller's, or every one for an organization sandbox manager) and GET /api/v1/sandbox/snapshots.
GET/api/v1/sandbox/snapshots/{snapshotId}Get one snapshot
DELETE/api/v1/sandbox/snapshots/{snapshotId}Delete one snapshot
GET/api/v1/sandbox/templatesList templates
POST/api/v1/sandbox/templatesRecords a template from JSON: - name (required): lowercase name matching [a-z0-9][a-z0-9-]*[a-z0-9] - version (optional): semver string, defaults to "0.1.0" - image (required): the OCI image its sandboxes run, pinned by digest - disk_size_mb / mem_size_mb / cpu_count (optional integers)
GET/api/v1/sandbox/templates/{id}Get one template
DELETE/api/v1/sandbox/templates/{id}Delete one template
GET/api/v1/sandbox/templates/{id}/build-statusReturns the current build state of a template. With ?watch=true it streams SSE updates every 2 seconds until the build is no longer in "building" state or a 5-minute timeout is reached.
GET/api/v1/sandbox/webhooksList webhooks
POST/api/v1/sandbox/webhooksCreate a webhook
DELETE/api/v1/sandbox/webhooks/{id}Delete one webhook
GET/api/v1/sandbox/workers. The route needs ni:sandbox:workers:read (sandbox:admin: account Owners and Admins, and super admins).

Endpoints

GET /api/v1/sandbox/artifacts

List artifacts

Permission
sandboxes:read
Query parameters
status
Response
200: ListResponse
Errors
503: service_unavailable

POST /api/v1/sandbox/artifacts/{id}/approve

Approve an artifact

Permission
sandboxes:write
Path parameters
id
Request body
object
Errors
400: invalid_body, invalid_json, invalid_request; 404: not_found; 422: patch_failed; 501: artifact_apply_unavailable; 503: audit_unavailable, service_unavailable

POST /api/v1/sandbox/artifacts/{id}/reject

Reject an artifact

Permission
sandboxes:write
Path parameters
id
Errors
404: not_found; 503: audit_unavailable, service_unavailable

GET /api/v1/sandbox/instances

List instances

Permission
sandboxes:use
Query parameters
cursor, limit, project_id, status
Response
200: ListResponse
Errors
400: invalid_cursor, invalid_request; 401: unauthenticated; 403: policy_denied; 404: project_not_found; 409: project_inactive; 503: authorization_unavailable, provisioner_unavailable, service_unavailable

POST /api/v1/sandbox/instances

Create an instance

Permission
sandboxes:create
Request body
CreateInstanceRequest
Response
201: CreateInstanceResponse
Errors
400: invalid_body, invalid_json, invalid_request; 401: unauthenticated; 403: access_denied, policy_denied; 404: project_not_found, snapshot_not_found, template_not_found, workspace_not_found; 409: project_inactive, snapshot_not_ready, snapshot_project_mismatch; 422: environment_setup_failed, snapshot_restore_failed; 429: quota_exceeded; 500: policy_error; 502: snapshot_restore_failed; 503: authorization_unavailable, provisioner_unavailable, service_unavailable, storage_unavailable

GET /api/v1/sandbox/instances/{id}

Get one instance

Permission
sandboxes:use
Path parameters
id
Response
200: InstanceDetail
Errors
404: workspace_not_found; 503: provisioner_unavailable

DELETE /api/v1/sandbox/instances/{id}

Delete one instance

Permission
sandboxes:manage
Path parameters
id
Errors
404: workspace_not_found; 503: provisioner_unavailable

POST /api/v1/sandbox/instances/{id}/exec

Exec an instance

Permission
sandboxes:use
Path parameters
id
Request body
ExecRequest
Response
200: ExecOutcome
Errors
400: invalid_body, invalid_json, invalid_request; 403: host_access_denied, policy_denied; 404: workspace_not_found; 409: instance_lost, instance_paused; 500: policy_error; 503: audit_unavailable, authorization_unavailable, dlp_unavailable, service_unavailable

GET /api/v1/sandbox/instances/{id}/files

Reads a file or lists a directory inside a running sandbox instance, in its own container.

Permission
sandboxes:use
Path parameters
id
Query parameters
path, raw
Response
200: PathContent
Errors
400: invalid_request; 404: not_found, workspace_not_found; 409: instance_lost, instance_paused; 413: file_too_large; 422: exec_failed; 504: agent_timeout

PUT /api/v1/sandbox/instances/{id}/files

Writes a file into a running sandbox instance, in its own container.

Permission
sandboxes:use
Path parameters
id
Query parameters
mode, path
Request body
object
Response
200: object of any
Errors
400: invalid_body, invalid_json, invalid_request; 404: workspace_not_found; 409: instance_lost, instance_paused; 413: file_too_large; 422: exec_failed; 502: transfer_incomplete; 503: provisioner_unavailable, service_unavailable; 504: agent_timeout

GET /api/v1/sandbox/instances/{id}/logs

As Server-Sent Events.

Permission
sandboxes:use
Path parameters
id
Query parameters
from_chunk, run_id
Errors
400: bad_request; 404: not_found, workspace_not_found; 503: audit_unavailable, dlp_unavailable, service_unavailable

GET /api/v1/sandbox/instances/{id}/metrics

Answers GET .../metrics once the caller may use the sandbox.

Permission
sandboxes:use
Path parameters
id
Query parameters
start
Response
200: SandboxMetrics
Errors
400: invalid_request; 404: workspace_not_found; 503: provisioner_unavailable

POST /api/v1/sandbox/instances/{id}/pause

Pause an instance

Permission
sandboxes:manage
Path parameters
id
Errors
503: provisioner_unavailable

GET /api/v1/sandbox/instances/{id}/ports

The sandbox's open exposures.

Permission
sandboxes:use
Path parameters
id
Response
200: object of any
Errors
404: workspace_not_found

POST /api/v1/sandbox/instances/{id}/ports

Create a port for an instance

Permission
sandboxes:use
Path parameters
id
Request body
exposePortRequest
Response
PortExposure
Errors
400: invalid_body, invalid_json, invalid_request; 403: policy_denied, port_exposure_disabled, port_not_allowed; 409: instance_not_running, port_exposed, port_exposure_limit, port_exposure_unsupported; 429: rate_limited; 501: port_exposure_unavailable; 503: audit_unavailable, service_unavailable

DELETE /api/v1/sandbox/instances/{id}/ports/{port}

({port} is the exposure's ID or its port number).

Permission
sandboxes:use
Path parameters
id, port
Errors
403: policy_denied; 404: not_found; 501: port_exposure_unavailable; 503: audit_unavailable, service_unavailable

GET /api/v1/sandbox/instances/{id}/ports/{port}/connect

One TCP connection to the exposed port, as a WebSocket of binary messages.

Permission
sandboxes:use
Path parameters
id, port
Errors
400: websocket_required; 403: policy_denied, port_exposure_disabled, port_not_allowed; 404: not_found, workspace_not_found; 409: instance_not_running, port_exposure_unsupported; 410: port_exposure_closed; 422: transfer_failed; 429: rate_limited, tunnel_limit; 501: port_exposure_unavailable; 502: port_refused; 503: audit_unavailable, service_unavailable; 504: tunnel_timeout

POST /api/v1/sandbox/instances/{id}/project

Project an instance

Permission
sandboxes:use
Path parameters
id
Query parameters
dir
Response
200: ProjectUpload
Errors
400: invalid_project_archive, invalid_request; 403: host_access_denied, policy_denied; 409: instance_paused; 413: project_too_large; 422: project_extract_failed; 429: project_upload_busy; 500: policy_error; 502: transfer_incomplete; 503: audit_unavailable, authorization_unavailable, dlp_unavailable, provisioner_unavailable, service_unavailable

GET /api/v1/sandbox/instances/{id}/project/changes

List changes

Permission
sandboxes:use
Path parameters
id
Query parameters
dir
Response
200: ProjectChanges
Errors
400: invalid_request; 403: policy_denied; 404: not_found; 422: project_extract_failed; 500: policy_error; 503: audit_unavailable, dlp_unavailable

GET /api/v1/sandbox/instances/{id}/pty

Answers GET .../pty once the caller may use the sandbox.

Permission
sandboxes:use
Path parameters
id
Errors
404: workspace_not_found; 501: terminal_unavailable

POST /api/v1/sandbox/instances/{id}/resume

Resume an instance

Permission
sandboxes:manage
Path parameters
id
Errors
503: provisioner_unavailable

GET /api/v1/sandbox/instances/{id}/runs

List the runs of an instance

Permission
sandboxes:use
Path parameters
id
Response
200: ListResponse
Errors
404: workspace_not_found; 503: service_unavailable

POST /api/v1/sandbox/instances/{id}/snapshot

Snapshot an instance

Permission
sandboxes:use
Path parameters
id
Request body
object
Response
201: SnapshotView
Errors
400: invalid_body, invalid_json, invalid_request; 403: host_access_denied, policy_denied, snapshots_disabled; 409: instance_not_running, instance_paused, snapshot_quota_exceeded; 413: snapshot_too_large; 422: snapshot_failed; 501: snapshots_unavailable; 502: transfer_incomplete; 503: audit_unavailable, authorization_unavailable, service_unavailable, storage_unavailable

GET /api/v1/sandbox/instances/{id}/snapshots

(the caller's, or every one for an organization sandbox manager) and GET /api/v1/sandbox/snapshots.

Permission
sandboxes:use
Path parameters
id
Query parameters
limit
Response
200: object of any
Errors
400: invalid_request; 404: workspace_not_found; 501: snapshots_unavailable; 503: authorization_unavailable

GET /api/v1/sandbox/instances/{id}/ssh

The host, user, pinned host key and routes, when the caller may use SSH on the sandbox.

Permission
sandboxes:use
Path parameters
id
Response
200: SSHInfo
Errors
403: host_access_denied, policy_denied, ssh_disabled; 409: instance_not_running, instance_paused, ssh_unsupported; 501: ssh_unavailable; 503: authorization_unavailable

POST /api/v1/sandbox/instances/{id}/ssh/certificate

Create a certificate

Permission
sandboxes:use
Path parameters
id
Request body
object
Response
200: SSHCertificateResponse
Errors
400: invalid_body, invalid_json, invalid_request, ssh_key_refused; 403: policy_denied, ssh_disabled; 409: instance_not_running, ssh_unsupported; 503: ssh_ca_unavailable

GET /api/v1/sandbox/instances/{id}/ssh/connect

One SSH connection, as a WebSocket of binary messages.

Permission
sandboxes:use
Path parameters
id
Errors
400: websocket_required; 403: host_access_denied, policy_denied, ssh_disabled; 404: workspace_not_found; 409: instance_not_running, instance_paused, ssh_unsupported; 422: transfer_failed; 501: ssh_unavailable; 503: authorization_unavailable, ssh_ca_unavailable; 504: tunnel_timeout

POST /api/v1/sandbox/jobs/{id}/input

Handles stdin injection into a running job. POST /api/v1/sandbox/jobs/{id}/input with body {"data":"..."}

Permission
sandboxes:use
Path parameters
id
Request body
object
Errors
400: bad_request; 401: unauthenticated; 403: access_denied; 404: not_found; 410: session_closed; 501: pty_unavailable; 503: authorization_unavailable, service_unavailable

POST /api/v1/sandbox/jobs/{id}/pty/resize

Handles PTY window resize requests. POST /api/v1/sandbox/jobs/{id}/pty/resize with body {"rows":N,"cols":N}

Permission
sandboxes:use
Path parameters
id
Request body
object
Errors
400: bad_request; 401: unauthenticated; 403: access_denied; 404: not_found; 410: session_closed; 501: pty_unavailable; 503: authorization_unavailable, service_unavailable

GET /api/v1/sandbox/kill-switch

List kill switch

Permission
sandboxes:read
Response
200: KillSwitchState

GET /api/v1/sandbox/launch-options

For whoever may start sandboxes (mayStart). Templates are the ready ones the caller may start from (the template list's rule); sizes and refusals follow the policy, the per-member quota and the organization's concurrency limit as the create checks them.

Permission
sandboxes:create
Response
200: LaunchOptions
Errors
401: unauthenticated; 503: authorization_unavailable, service_unavailable

GET /api/v1/sandbox/orgs/{id}/billing/usage

List usage

Permission
billing:read
Path parameters
id
Query parameters
end, start
Response
200: WorkspaceBillingUsageResponse
Errors
400: invalid_request; 401: unauthenticated; 403: iam_denied; 503: service_unavailable

GET /api/v1/sandbox/policy

List policy

Permission
sandboxes:read
Response
200: PolicyResponse
Errors
503: service_unavailable

PUT /api/v1/sandbox/policy

Set policy

Permission
sandboxes:write
Request body
PolicyUpdateRequest
Response
200: PolicyResponse
Errors
400: invalid_body, invalid_json, invalid_request; 503: audit_unavailable, service_unavailable

GET /api/v1/sandbox/policy/port-exposure

List port exposure

Permission
sandboxes:read
Response
200: PortPolicy
Errors
503: service_unavailable

PUT /api/v1/sandbox/policy/port-exposure

The whole policy. Exposures it no longer allows are closed with the change. A change that widens the policy is re-verified: a stolen administrator session cannot open every sandbox's ports.

Permission
sandboxes:write
Request body
PortPolicy
Response
200: PortPolicy
Errors
400: invalid_body, invalid_json, invalid_request; 503: audit_unavailable, service_unavailable, step_up_unavailable

GET /api/v1/sandbox/policy/snapshots

List snapshots

Permission
sandboxes:read
Response
200: SnapshotPolicy
Errors
503: service_unavailable

PUT /api/v1/sandbox/policy/snapshots

The whole policy. Existing snapshots keep their retention; a lower quota refuses new snapshots until usage is under it.

Permission
sandboxes:write
Request body
SnapshotPolicy
Response
200: SnapshotPolicy
Errors
400: invalid_body, invalid_json, invalid_request; 503: audit_unavailable, service_unavailable

GET /api/v1/sandbox/policy/ssh

List ssh

Permission
sandboxes:read
Response
200: SSHPolicy
Errors
503: service_unavailable

PUT /api/v1/sandbox/policy/ssh

The whole policy. Live sessions it no longer allows end at their next check.

Permission
sandboxes:write
Request body
SSHPolicy
Response
200: SSHPolicy
Errors
400: invalid_body, invalid_json, invalid_request; 503: audit_unavailable, service_unavailable

GET /api/v1/sandbox/policy/warm-pool

List warm pool

Permission
sandboxes:read
Response
200: WarmPoolPolicy
Errors
501: warm_pool_unavailable

PUT /api/v1/sandbox/policy/warm-pool

]}: the whole set. The maintainer starts and ends members to match within a minute.

Permission
sandboxes:write
Request body
object
Response
200: WarmPoolPolicy
Errors
400: invalid_body, invalid_json, invalid_request; 501: warm_pool_unavailable; 503: audit_unavailable

GET /api/v1/sandbox/quota

List quota

Permission
sandboxes:create
Response
200: QuotaResponse
Errors
401: unauthenticated; 503: provisioner_unavailable

GET /api/v1/sandbox/runs

List runs

Permission
sandboxes:use
Query parameters
from, limit, offset, project_id, status, to, user_id
Response
200: ListResponse
Errors
400: invalid_request; 401: unauthenticated; 503: authorization_unavailable, service_unavailable

GET /api/v1/sandbox/runs/{id}

Get one run

Permission
sandboxes:use
Path parameters
id
Response
200: RunDetail
Errors
401: unauthenticated; 403: access_denied; 404: not_found; 503: authorization_unavailable, service_unavailable

DELETE /api/v1/sandbox/runs/{id}

Cancels a running job by marking it in the store and signaling the assigned worker via a cancellation record.

Permission
sandboxes:use
Path parameters
id
Errors
401: unauthenticated; 403: access_denied; 404: not_found; 409: already_finished; 503: audit_unavailable, authorization_unavailable, service_unavailable

GET /api/v1/sandbox/snapshots

(the caller's, or every one for an organization sandbox manager) and GET /api/v1/sandbox/snapshots.

Permission
sandboxes:use
Query parameters
limit
Response
200: object of any
Errors
400: invalid_request; 404: workspace_not_found; 501: snapshots_unavailable; 503: authorization_unavailable

GET /api/v1/sandbox/snapshots/{snapshotId}

Get one snapshot

Permission
sandboxes:use
Path parameters
snapshotId
Response
200: SnapshotView
Errors
404: snapshot_not_found; 501: snapshots_unavailable; 503: authorization_unavailable

DELETE /api/v1/sandbox/snapshots/{snapshotId}

Delete one snapshot

Permission
sandboxes:use
Path parameters
snapshotId
Errors
404: snapshot_not_found; 503: audit_unavailable, authorization_unavailable

GET /api/v1/sandbox/templates

List templates

Permission
sandboxes:use
Response
200: ListResponse
Errors
401: unauthenticated; 503: authorization_unavailable, service_unavailable

POST /api/v1/sandbox/templates

Records a template from JSON: - name (required): lowercase name matching [a-z0-9][a-z0-9-]*[a-z0-9] - version (optional): semver string, defaults to "0.1.0" - image (required): the OCI image its sandboxes run, pinned by digest - disk_size_mb / mem_size_mb / cpu_count (optional integers)

Permission
sandboxes:write
Request body
object
Response
201: TemplateDetail
Errors
400: invalid_body, invalid_json, invalid_request; 501: template_build_unavailable; 503: audit_unavailable, service_unavailable

GET /api/v1/sandbox/templates/{id}

Get one template

Permission
sandboxes:read
Path parameters
id
Response
200: TemplateDetail
Errors
404: template_not_found; 503: service_unavailable

DELETE /api/v1/sandbox/templates/{id}

Delete one template

Permission
sandboxes:manage
Path parameters
id
Errors
404: template_not_found; 409: template_in_use; 503: audit_unavailable, service_unavailable

GET /api/v1/sandbox/templates/{id}/build-status

Returns the current build state of a template. With ?watch=true it streams SSE updates every 2 seconds until the build is no longer in "building" state or a 5-minute timeout is reached.

Permission
sandboxes:read
Path parameters
id
Query parameters
watch
Response
200: object of any
Errors
404: template_not_found; 503: service_unavailable

GET /api/v1/sandbox/webhooks

List webhooks

Permission
webhooks:read
Errors
501: not_implemented

POST /api/v1/sandbox/webhooks

Create a webhook

Permission
webhooks:create
Errors
501: not_implemented

DELETE /api/v1/sandbox/webhooks/{id}

Delete one webhook

Permission
webhooks:delete
Path parameters
id
Errors
501: not_implemented

GET /api/v1/sandbox/workers

. The route needs ni:sandbox:workers:read (sandbox:admin: account Owners and Admins, and super admins).

Permission
sandboxes:read
Response
200: WorkersResponse
Errors
401: unauthenticated; 503: service_unavailable

Objects

object

FieldTypeDescription
target_pathstring

object

FieldTypeDescription
labelstring

object

FieldTypeDescription
public_keystring

object

FieldTypeDescription
datastringBase64-encoded bytes

object

FieldTypeDescription
rowsinteger
colsinteger

object

FieldTypeDescription
namestring
versionstring
imagestring
disk_size_mbinteger
mem_size_mbinteger
cpu_countinteger

object

FieldTypeDescription
pathstring
contentstringBase64-encoded
modestring

object

FieldTypeDescription
poolsarray of WarmPoolEntry

Cost

What a resource's running time cost: in total and in the current month (UTC).

FieldTypeDescription
totalMoney
this_monthMoney

Money

An amount in US dollars: USD exactly (six decimals, for clients that compute), and Display as people see it. Display has two decimals ("$1,234.56"), "under $0.01" for an amount above zero that rounds below a cent, or the reason there is no amount.

FieldTypeDescription
usdstring
displaystring

Runtime

The runtime a sandbox or workspace ran on.

FieldTypeDescription
kindstringFirecracker, docker_gvisor, docker, kubernetes, gvisor (a gVisor container whose runtime was not recorded) or not_recorded.
labelstringThe kind in words: "Firecracker microVM", "Docker (gVisor)", "Docker", "Kubernetes", "gVisor container" or "Not recorded".

ArtifactDetail

The artifact representation.

FieldTypeDescription
idstring
nrn optionalstringThe resource's NRN, computed by Sandscale from the owning organization's Account ID and this cell; empty when it cannot be computed.
run_idstring
file_pathstring
additionsinteger
deletionsinteger
size_bytesinteger
statusstring
approved_by optionalstring
approved_at optionaltimestamp
target_path optionalstring

CreateInstanceRequest

FieldTypeDescription
template_id optionalstring
command optionalarray of string
env optionalobject of string
mem_mb optionalinteger
cpu_count optionalinteger
disk_mb optionalintegerThe size of the sandbox's /workspace (0: the template's, else the worker's default); bounded by the policy's max_disk_mb and placed only on a worker that can hold it.
image optionalstringThe OCI image the sandbox runs, pinned by digest (name@sha256:...); empty: the template's image, else the worker's default. The sandbox is placed only on a worker that runs images of its own (custom_images) and starts only if the image's repository is on that worker's allowlist.
ttl_seconds optionalinteger
secret_refs optionalarray of string
metadata optionalobject of string
name optionalstringAn optional display name (1 to 64 characters, no control characters).
labels optionalobject of stringOptional key/value labels.
network optionalstringThe network mode: empty or "none" (no network). A mode the policy lists but the runtime does not enforce is refused (GET /api/v1/sandbox/launch-options says which).
environment_id optionalstringEnvironmentID places the sandbox in a cloud environment GET /api/v1/sandbox/launch-options lists; empty uses the product's default environment, or none. On a cell without cloud environments any value is refused rather than ignored.
product optionalstringThe product the sandbox is a session of: agents, cli or sandboxes (default).
snapshot_id optionalstringSnapshotID starts the sandbox from a snapshot: its workspace is restored, it runs in the snapshot's project and, unless the request names one, with its template or image.

CreateInstanceResponse

FieldTypeDescription
idstring
statusstring
worker_node optionalstring
created_attimestamp

ExecOutcome

A finished command.

FieldTypeDescription
run_idstring
exit_codeinteger
stdoutstring
stderrstring
duration_msinteger
oom_killedboolean
timed_outboolean

ExecRequest

FieldTypeDescription
commandarray of string
env optionalobject of string
workdir optionalstring
timeout_sec optionalinteger
stdin optionalstringOptional base64-encoded bytes piped to the process standard input.

InstanceDetail

The full instance representation.

FieldTypeDescription
idstring
nrn optionalstringThe resource's NRN, computed by Sandscale from the owning organization's Account ID and this cell; empty when it cannot be computed.
org_idstring
user_idstring
template_id optionalstring
worker_id optionalstring
statusstring
providerstringThe worker pool's registered provider. It is not the runtime the sandbox ran on (Firecracker workers register as "docker"): that is Runtime.
runtimeRuntimeThe runtime the sandbox ran on, decided by Sandscale from what it recorded when the sandbox was placed ("Not recorded" for sandboxes started before it did).
started_at optionaltimestamp
terminated_at optionaltimestamp
runtime_stopped_at optionaltimestampWhen the sandbox's container or microVM was confirmed removed (on the detail of one sandbox): an ended sandbox without it may still hold its worker's resources until the stop sweep or the worker's restart removes them.
ttl_secondsinteger
mem_mbinteger
cpu_countinteger
cost_usdstringCost.Total in dollars (six decimals); "" when not metered.
costCostWhat the sandbox's running time cost at list price, from the billing usage ledger, in total and this month, with the display Sandscale formats.
metadata optionalobject of string
name optionalstring
labels optionalobject of string
network optionalstring
environment_id optionalstringThe cloud environment the sandbox started in, which decided its network access; empty for none.
started_by optionalStartedByStartedBy says who started the sandbox, described by Sandscale (nil without the store).
files optionalInstanceFilesFiles says whether the sandbox's workspace can be read and written (GET and PUT .../files): while it runs, in the one container all its commands run in.
status_reason optionalstringStatusReason says why the sandbox failed or ended (its worker stopped responding, its container is gone, its time to live ended).
isolation optionalInstanceIsolationHow the sandbox is isolated: a Firecracker microVM or a gVisor container (absent for sandboxes started before Sandscale recorded it).
suspend optionalInstanceSuspendSuspend says whether the sandbox can be paused or resumed now (absent once it ended).

InstanceFiles

InstanceFiles says whether a sandbox's workspace files can be read, and why not.

FieldTypeDescription
availableboolean
reason optionalstring

InstanceIsolation

How a sandbox is isolated.

FieldTypeDescription
kindstringMicrovm_firecracker, container_gvisor or container.
labelstringThe kind in words: "microVM (Firecracker)", "container (gVisor)" or "container".

InstanceSuspend

InstanceSuspend says what pause and resume can do for a sandbox now.

FieldTypeDescription
can_pauseboolean
can_resumeboolean
reason optionalstring

KillSwitchState

FieldTypeDescription
engagedbooleanThe organization kill switch (agent_kill_switch_state).
generationintegerGeneration counts its changes (the signed agent policy carries the same number).
engaged_at optionaltimestamp
sourcesarray of stringWhat engaged it (ai_soc, endpoint).
platform_engagedbooleanThe cell's switch, which the operator sets.
platform_reason optionalstring

LaunchChoice

One value of a choice with its label.

FieldTypeDescription
valuestring
labelstring
description optionalstring
availableboolean
reason optionalstring

LaunchEnvironments

The environments a sandbox may be placed in. Default is the environment a create without environment_id starts in (the account's default for sandboxes), empty for none; DefaultRefusal says why that default cannot be used by the caller, so a create without environment_id would be refused. An environment decides the sandbox's network access, setup script and variables.

FieldTypeDescription
requiredboolean
default optionalstring
default_refusal optionalstring
optionsarray of LaunchChoice

LaunchFeature

Whether a sandbox feature is offered here, and why not.

FieldTypeDescription
availableboolean
code optionalstring
reason optionalstring

LaunchLabelRules

The label rules.

FieldTypeDescription
max_countinteger
key_patternstring
max_value_lengthinteger

LaunchNameRule

The name rule.

FieldTypeDescription
max_lengthinteger

LaunchNetwork

The network modes, the default first.

FieldTypeDescription
defaultstring
optionsarray of LaunchChoice

LaunchOptions

FieldTypeDescription
can_startboolean
refusal optionalLaunchRefusal
templatesarray of LaunchTemplate
sizeLaunchSize
ttlLaunchTTLOptions
networkLaunchNetwork
nameLaunchNameRule
labelsLaunchLabelRules
environmentsLaunchEnvironmentsThe cloud environments the caller may start the sandbox in; empty when none are offered, and a client shows a picker only when Sandscale lists options.
featuresobject of LaunchFeatureThe sandbox features this deployment offers, decided by the server from what it runs: a client offers a feature only when it is available and shows the reason when it is not.

LaunchRefusal

LaunchRefusal says why no sandbox can be started now.

FieldTypeDescription
codestring
messagestring

LaunchSize

The size of a sandbox started without a template (a template's own size is fixed): the CPU and memory choices within the policy and the caller's quota, and the defaults. Note says where the bounds come from.

FieldTypeDescription
cpu_choicesarray of integer
mem_mb_choicesarray of integer
default_cpuinteger
default_mem_mbinteger
max_cpuinteger
max_mem_mbinteger
notestring

LaunchTTLChoice

One time to live, in seconds.

FieldTypeDescription
secondsinteger
labelstring

LaunchTTLOptions

The times to live a sandbox may be started with.

FieldTypeDescription
choicesarray of LaunchTTLChoice
default_secondsinteger
max_secondsinteger

LaunchTemplate

A ready template the caller may start from. Startable is false with Reason when its size is over what the caller may start now.

FieldTypeDescription
idstring
nrn optionalstring
namestring
versionstring
cpu_countinteger
mem_mbinteger
startableboolean
reason optionalstring
builtin optionalbooleanBuiltin marks a built-in template: always offered, not a row of the organization, started with its image at the size the request gives.
image optionalstringA built-in template's image ("" for the workers' default).
description optionalstringDescription says what a built-in template runs.
warm_idle optionalintegerHow many sandboxes of this template wait started in the organization's warm pool (a start of the default size claims one).

ListResponse

The paginated response wrapper.

FieldTypeDescription
dataarray of ArtifactDetail
next_cursor optionalstring
has_moreboolean

PathContent

A file's content or a directory's entries.

FieldTypeDescription
typestring
pathstring
content optionalstring
size_bytes optionalinteger
entries optionalarray of PathEntryA directory's entries (empty, never absent, for an empty directory).

PathEntry

One entry of a directory.

FieldTypeDescription
namestring
typestring
size_bytesinteger

PolicyResponse

The sandbox policy for an org.

FieldTypeDescription
max_concurrentinteger
max_exec_time_secinteger
max_mem_mbinteger
max_cpuinteger
max_disk_mb optionalinteger
max_workspaces_per_user optionalinteger
max_cpu_cores_per_user optionalinteger
max_memory_gb_per_user optionalinteger
egress_allowlistarray of string
allowed_providersarray of string

PolicyUpdateRequest

FieldTypeDescription
max_concurrent optionalinteger
max_exec_time_sec optionalinteger
max_mem_mb optionalinteger
max_cpu optionalinteger
max_disk_mb optionalintegerMaxDiskMB caps a sandbox's disk_mb; 0 removes the cap (the workers' maximum still applies).
max_workspaces_per_user optionalinteger
max_cpu_cores_per_user optionalinteger
max_memory_gb_per_user optionalinteger
egress_allowlist optionalarray of string
allowed_providers optionalarray of string

PortExposure

An exposure as the API shows it.

FieldTypeDescription
idstring
instance_idstring
portinteger
protocolstring
statusstring
created_bystring
created_attimestamp
expires_attimestamp
closed_at optionaltimestamp
close_reason optionalstring
connect_pathstringThe WebSocket route of a connection, on the API origin, with the caller's own credentials; only the exposure's creator may connect.
subprotocolstringThe WebSocket subprotocol ConnectPath speaks.

PortPolicy

The organization's port exposure policy (GET/PUT /api/v1/sandbox/policy/port-exposure).

FieldTypeDescription
modestringOff, owner (the person who started the sandbox) or users (anyone who may use it).
allowed_portsarray of stringThe ports that may be exposed: single ports ("8080") or ranges ("3000-3999"), at most 32.
default_ttl_secondsintegerAn exposure's time to live when the request names none; MaxTTLSeconds the longest it may ask for (60 to 86400).
max_ttl_secondsinteger
max_open_per_sandboxintegerMaxOpenPerSandbox bounds one sandbox's open exposures (1 to 64).

ProjectChanges

FieldTypeDescription
dirstring
changedarray of string
truncatedboolean
run_idstring

ProjectSkip

A file the upload left out, and why: gitignored, special_file, or denied:<rule>.

FieldTypeDescription
pathstring
reasonstring

ProjectUpload

The outcome of an upload.

FieldTypeDescription
dirstring
filesinteger
bytesinteger
skippedobject of integerSkipped counts the files left out by reason class (gitignored, denied, special_file).
skipped_pathsarray of ProjectSkipSkippedPaths names up to 100 of them.
run_idstringThe run of the unpack command.

QuotaResponse

The current quota state for an org.

FieldTypeDescription
active_instancesinteger
max_instancesinteger
cpu_usedinteger
cpu_maxinteger
mem_used_mbinteger
mem_max_mbinteger
cost_this_month_usdstring

RunDetail

The full run representation.

FieldTypeDescription
idstring
nrn optionalstringThe resource's NRN, computed by Sandscale from the owning organization's Account ID and this cell; empty when it cannot be computed.
org_id optionalstring
instance_idstring
project_id optionalstring
user_id optionalstring
tool_identity optionalstring
policy_version optionalstring
policy_decision optionalstring
worker_id optionalstring
provider optionalstring
image optionalstring
status optionalstring
commandarray of string
created_at optionaltimestamp
dispatched_at optionaltimestamp
exit_code optionalinteger
started_attimestamp
finished_at optionaltimestamp
ended_at optionaltimestamp
duration_ms optionalinteger
ram_mb_used optionalinteger
cpu_seconds optionalstring
memory_gb_seconds optionalstring
cost_usdstring
costMoneyCostUSD with the display Sandscale formats.
artifact_ids optionalarray of string

SSHCertificateResponse

SSHCertificateResponse answers POST .../ssh/certificate.

FieldTypeDescription
hoststring
userstring
known_hostsstringThe sandbox's pinned host key as a known_hosts line for Host.
host_key_sha256string
certificate_pathstring
connect_pathstring
subprotocolstring
cert_ttl_secondsinteger
certificatestring
serialstring
key_idstring
valid_beforetimestamp

SSHInfo

FieldTypeDescription
hoststring
userstring
known_hostsstringThe sandbox's pinned host key as a known_hosts line for Host.
host_key_sha256string
certificate_pathstring
connect_pathstring
subprotocolstring
cert_ttl_secondsinteger

SSHPolicy

The organization's SSH policy (GET/PUT /api/v1/sandbox/policy/ssh).

FieldTypeDescription
enabledboolean
modestringOwner (the person who started the sandbox) or users (anyone who may use it).
cert_ttl_secondsintegerA certificate's life (60 to 3600; the authority caps it at 10 minutes).
max_session_secondsintegerMaxSessionSeconds bounds one session (300 to 86400).

SandboxAllocation

A sandbox's allocated resources.

FieldTypeDescription
cpu_countinteger
mem_total_mbinteger

SandboxMetrics

FieldTypeDescription
instance_idstring
statusstring
allocationSandboxAllocationWhat the sandbox was given (the limits of every sample).
metricsarray of object of anyThe samples since start, oldest first: {timestamp, cpu_used_pct, cpu_count, mem_used_mb, mem_total_mb, disk_used_mb, disk_total_mb}. Empty while Available is false.
availablebooleanFalse when this deployment does not sample usage, with Code and Reason.
code optionalstring
reason optionalstring

SharedWorkersView

The shared fleet of the cell as an aggregate: counts, sandbox slots, the runtimes offered and the region. It never names a node, an address or another organization.

FieldTypeDescription
healthyinteger
unresponsiveinteger
capacityinteger
in_useinteger
providersarray of string
runtimesarray of RuntimeThe runtimes the healthy shared workers offer, from their capabilities.
regionstring

SnapshotPolicy

The organization's snapshot policy (GET/PUT /api/v1/sandbox/policy/snapshots).

FieldTypeDescription
enabledboolean
max_snapshotsintegerMaxSnapshots bounds the organization's live snapshots (1 to 10000).
max_total_bytesintegerMaxTotalBytes bounds their stored bytes; MaxSnapshotBytes one snapshot's (it is also bounded by the deployment's file transfer limit).
max_snapshot_bytesinteger
retention_daysintegerHow long a snapshot is kept (1 to 3650).

SnapshotView

A snapshot as the API shows it.

FieldTypeDescription
idstring
instance_idstring
project_id optionalstring
classificationstring
template_id optionalstring
image optionalstring
labelstring
statusstring
size_bytesinteger
sha256 optionalstring
created_bystring
created_attimestamp
ready_at optionaltimestamp
expires_attimestamp
failure optionalstring

StartedBy

Who started a sandbox as Sandscale describes it to the caller: Kind is "person" (a signed-in person, from the console or the API), "api_key" (an API key, the SDK), "agent" (an agent through the sandbox MCP server) or "unknown" (started before Sandscale recorded it). Label names the starter ("You" for the caller) and Detail says how the sandbox was started, so a client renders both as they are.

FieldTypeDescription
kindstring
labelstring
detailstring
user_id optionalstring
api_key_id optionalstring
is_callerboolean

StripeMeterEvent

A neutral event shape that can be mapped to Stripe meters.

FieldTypeDescription
event_namestring
timestampinteger
identifierstring
payloadStripeMeterPayload

StripeMeterPayload

StripeMeterPayload contains the billable quantity and workspace dimensions.

FieldTypeDescription
valueinteger
workspace_idstring
template_id optionalstring
org_idstring
cpu_coresinteger
memory_gbnumber
storage_gb optionalnumber

TemplateDetail

The template representation.

FieldTypeDescription
idstring
nrn optionalstringThe resource's NRN, computed by Sandscale from the owning organization's Account ID and this cell; empty when it cannot be computed.
org_idstring
namestring
versionstring
statusstring
disk_size_mbinteger
mem_size_mbinteger
cpu_countinteger
image optionalstringThe image the template's sandboxes run, pinned by digest ("": the worker's default image).
created_bystring
created_attimestamp

WarmPoolEntry

One pool: its template ("builtin:<name>" or a template ID), its size, and the members waiting now.

FieldTypeDescription
templatestring
sizeinteger
idleinteger

WarmPoolPolicy

FieldTypeDescription
poolsarray of WarmPoolEntry
max_per_templateintegerThe deployment's bounds (read-only).
max_per_orginteger
idle_ttl_secondsinteger

WorkerView

One sandbox worker in GET /api/v1/sandbox/workers. Pool is "shared" (a worker of the cell that serves every organization without workers of its own) or "byoc" (a worker in an organization's own cloud account). OrgID is set only in the platform scope.

FieldTypeDescription
idstring
node_namestring
providerstring
statusstring
healthstring
active_countinteger
capacityinteger
last_heartbeattimestamp
versionstring
runtimeRuntimeThe runtime the worker runs sandboxes on, from its reported capabilities (Provider is the pool's registered provider, "docker" for Firecracker workers too).
poolstring
org_id optionalstring
byoc_worker_id optionalstring

WorkersResponse

FieldTypeDescription
scopestring
placement optionalstring
placeableinteger
dataarray of WorkerView
sharedSharedWorkersView
has_moreboolean
checked_attimestamp

WorkspaceBillingUsageAggregate

WorkspaceBillingUsageAggregate reports query-time aggregate metering totals.

FieldTypeDescription
periodstring
workspace_minutesinteger
cpu_core_minutesinteger
memory_gb_minutesnumber
storage_gb_minutes optionalnumber

WorkspaceBillingUsageResponse

WorkspaceBillingUsageResponse reports workspace-minute metering data for an org.

FieldTypeDescription
org_idstring
starttimestamp
endtimestamp
dailyarray of WorkspaceBillingUsageAggregate
monthlyarray of WorkspaceBillingUsageAggregate
stripe_meter_eventsarray of StripeMeterEvent

exposePortRequest

FieldTypeDescription
portinteger
protocol optionalstring
ttl_seconds optionalinteger

This page is generated from the server's route table and the Go handlers that serve each route. Do not edit it by hand.