Sign in

v49

latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-01151216390.1 KB
Devbox
Devbox-Lifecycle

Suspend a running Devbox

Suspend a running Devbox and create a disk snapshot to enable resuming the Devbox later with the same disk. Note this will not snapshot memory state such as running processes.

post/v1/devboxes/{id}/suspend

Path parameters

idstring required

The Devbox ID.

Response

OK

idstring required

The ID of the Devbox.

namestring nullable

The name of the Devbox.

status'scheduled' | 'queued' | 'provisioning' | 'initializing' | 'running' | 'suspending' | 'suspended' | 'resuming' | 'failure' | 'shutdown' required

The status of the Devbox.

scheduled: Deprecated. The Devbox is waiting for infrastructure allocation to start. Use queued. queued: The Devbox is waiting for infrastructure allocation to start. provisioning: Runloop is allocating and booting the necessary infrastructure resources. initializing: Runloop defined boot scripts are running to enable the environment for interaction. running: The Devbox is ready for interaction. suspending: The Devbox disk is being snapshotted as part of suspension. suspended: The Devbox disk is saved and no more active compute is being used for the Devbox. resuming: The Devbox disk is being loaded as part of booting a suspended Devbox. failure: The Devbox failed as part of booting or running user requested actions. shutdown: The Devbox was successfully shutdown and no more active compute is being used.

create_time_msinteger required

Creation time of the Devbox (Unix timestamp milliseconds).

end_time_msinteger nullable required

The time the Devbox finished execution (Unix timestamp milliseconds). Present if the Devbox is in a terminal state.

initiator_type'unknown' | 'api' | 'scenario' | 'scoring_validation' | 'reflex'
initiator_idstring nullable

The ID of the initiator that created the Devbox.

blueprint_idstring nullable

The Blueprint ID used in creation of the Devbox, if the devbox was created from a Blueprint.

snapshot_idstring nullable

The Snapshot ID used in creation of the Devbox, if the devbox was created from a Snapshot.

metadataobject required

The user defined Devbox metadata.

failure_reason'out_of_memory' | 'out_of_disk' | 'execution_failed' | 'health_check_failed'

The category of failure experienced by the Devbox.

out_of_memory: The Devbox ran out of memory at runtime. Use launch parameters to request a larger resource size. out_of_disk: The Devbox ran out of disk at runtime. Please reach out to support for us to better support your use case. execution_failed: The Devbox failed at runtime. Please use the dashboard to look at the logs of the failure. health_check_failed: The Devbox failed its health checks. This may indicate resource utilization is close to the maximum. Consider requesting a larger resource size.

shutdown_reason'api_shutdown' | 'keep_alive_timeout' | 'entrypoint_exit' | 'idle' | 'ttl_expired'

The reason that caused the transition of the Devbox to the shutown state.

api_shutdown: The Devbox shutdown due to API request. entrypoint_exit: The Devbox entrypoint program completed. idle: The Devbox shutdown due to configured action on idle configuration. ttl_expired: The Devbox shutdown due to TTL expiration.

capabilitiesDevboxCapabilities[] required

A list of capability groups this devbox has access to.

gateway_specsobject nullable

Gateway specifications configured for this devbox. Map key is the environment variable prefix (e.g., 'GWS_ANTHROPIC').

mcp_specsobject nullable

[Beta] MCP specifications configured for this devbox. Map key is the environment variable name for the MCP token envelope. Each spec links an MCP config to a secret for MCP server access through the MCP hub.