Skip to main content
PATCH
Update a sandbox

Authorizations

Authorization
string
header
required

workspace API token (sk_akua_...) or OAuth2 JWT. Create tokens at https://akua.dev/developers/api-tokens

Headers

akua-context
string

Optional workspace/scope context for the request. Carries a single workspace wire id (ws_…) today. Only needed for broad tokens - a workspace-owned token implies its workspace.

Required string length: 1 - 53
Example:

"ws_j572abc123def456"

if-match
string
required

The etag of the resource version the client last read. Required on writes when the resource exposes an etag field. Mismatch returns 409 ABORTED with the current etag in the error metadata.

Required string length: 1 - 256
Example:

"42"

Path Parameters

id
string
required

Sandbox id (sbx_...).

Pattern: ^sbx_[A-Za-z0-9]{1,64}$
Example:

"sbx_j572abc123def456"

Body

application/json
name
string

Display name.

Required string length: 1 - 100
Example:

"checkout-service"

size
enum<string>

Compute size. standard is the only size today; larger sizes are added as new values.

Available options:
standard
network_policy
object

Outbound network access. allow_all: HTTP and HTTPS to public internet addresses; private, link-local and cluster-internal addresses are always blocked, and other protocols except DNS are not forwarded. Restrictive modes are added as new values.

idle_timeout_seconds
integer
default:600

Seconds without API activity after which the sandbox suspends itself. Commands that are still running keep it awake. 300 to 86400; default 600.

Required range: 300 <= x <= 86400
Example:

600

labels
object

Response

Sandbox

id
string
required

Sandbox id (sbx_...).

Pattern: ^sbx_[A-Za-z0-9]{1,64}$
Example:

"sbx_j572abc123def456"

workspace_id
string
required
Required string length: 1 - 53
name
string
required

Display name.

Required string length: 1 - 100
Example:

"checkout-service"

state
enum<string>
required

ACTIVE sandboxes run commands and file operations. SUSPENDED sandboxes keep their files and cost only storage. -ING states are in flight; FAILED sandboxes can only be deleted.

Available options:
PROVISIONING,
ACTIVE,
SUSPENDING,
SUSPENDED,
RESUMING,
DELETING,
FAILED
size
enum<string>
required

Compute size. standard is the only size today; larger sizes are added as new values.

Available options:
standard
source
object | null
required

null for a sandbox created empty.

network_policy
object
required

Outbound network access. allow_all: HTTP and HTTPS to public internet addresses; private, link-local and cluster-internal addresses are always blocked, and other protocols except DNS are not forwarded. Restrictive modes are added as new values.

idle_timeout_seconds
integer
default:600
required

Seconds without API activity after which the sandbox suspends itself. Commands that are still running keep it awake. 300 to 86400; default 600.

Required range: 300 <= x <= 86400
Example:

600

env
object
required
labels
object
required
created_by
object
required
usage
object
required
failure
object | null
required

Why the sandbox is FAILED; null otherwise.

last_active_at
integer | null
required

Last API activity (Unix seconds).

Required range: x >= 0
created_at
integer
required

Creation time (Unix seconds).

Required range: x >= 0
updated_at
integer
required

Last change (Unix seconds).

Required range: x >= 0
etag
string
required

Opaque version token. Send it as If-Match on writes.