{"components":{"headers":{"RequestId":{"description":"Stable request id for support and retry diagnostics. Echoes the first non-blank of `x-request-id` and `x-correlation-id` when it is at most 128 bytes of `[A-Za-z0-9._:-]`; otherwise, including when the supplied value is longer or contains other characters, SPACE issues a fresh `req_<uuid>`.","schema":{"type":"string"}}},"schemas":{"ConditionStatus":{"description":"Extensible condition status. Clients must accept values not listed in examples.","examples":["true","false","unknown"],"type":"string"},"CreateCommandRequest":{"properties":{"command":{"description":"Non-empty argv with at most 4096 entries and 262144 aggregate UTF-8 bytes including separators. Arguments cannot contain NUL.","items":{"maxLength":262143,"pattern":"^[^\\u0000]*$","type":"string","x-space-max-utf8-bytes":262143},"maxItems":4096,"minItems":1,"type":"array","x-space-max-aggregate-utf8-bytes":262144},"cwd":{"anyOf":[{"description":"Non-empty Linux guest path. Windows drive-letter and UNC paths are rejected.","maxLength":4096,"minLength":1,"not":{"pattern":"^([A-Za-z]:|//|\\\\\\\\)"},"pattern":"^[^\\p{Cc}]+$","type":"string","x-space-max-utf8-bytes":4096},{"type":"null"}],"default":null},"env":{"additionalProperties":{"maxLength":8192,"pattern":"^[^\\u0000]*$","type":"string","x-space-max-utf8-bytes":8192},"default":{},"description":"Environment map with at most 256 entries and 65536 aggregate UTF-8 bytes across keys and values.","maxProperties":256,"propertyNames":{"maxLength":128,"minLength":1,"pattern":"^[A-Za-z_][A-Za-z0-9_]*$","type":"string"},"type":"object","x-space-max-aggregate-utf8-bytes":65536},"pty":{"anyOf":[{"$ref":"#/components/schemas/TerminalSize"},{"type":"null"}],"description":"Runs the command in a pseudo-terminal of this size. Server-sent events\ncarry no input and a pty cannot be closed, so a command with `pty` is\nrejected with `invalid_request` when created with\n`Accept: text/event-stream`, even one that never reads input, and\n`/sessions/{session_id}/events` refuses to start it. Only a WebSocket\nattach can start it; after the WebSocket detaches, `/events` can\nreconnect and read its output."},"stdin":{"description":"Keeps standard input open for a WebSocket attach to write. Server-sent\nevents carry no input, so when `/sessions/{session_id}/events` starts\nthe command, including through `Accept: text/event-stream`, standard\ninput is at end of file instead and a later WebSocket attach cannot\nwrite to it.","type":["boolean","null"]},"timeout":{"anyOf":[{"description":"Positive SPACE compact duration with at most nine integer digits. Units are seconds, minutes, hours, or days; the value must resolve to nanosecond precision.","examples":["30s","1.5m","1h"],"maxLength":24,"pattern":"^((0*[1-9][0-9]{0,8}(\\.(0+|[0-9]{0,8}[1-9]0*))?|0+\\.[0-9]{0,8}[1-9]0*)s|(0*[1-9][0-9]{0,8}(\\.(0+|[0-9]{0,9}[1-9]0*))?|0+\\.[0-9]{0,9}[1-9]0*)m|(0*[1-9][0-9]{0,8}(\\.(0+|[0-9]{0,10}[1-9]0*))?|0+\\.[0-9]{0,10}[1-9]0*)[hd])$","type":"string"},{"type":"null"}],"default":null,"description":"Positive duration using SPACE compact syntax, such as `30s`, `5m`, or `1h`."},"user":{"anyOf":[{"description":"Guest user to run as. Defaults to the sandbox's configured user.","maxLength":64,"minLength":1,"pattern":"^[^\\p{Cc}]+$","type":"string","x-space-max-utf8-bytes":64},{"type":"null"}],"description":"Guest user to run as. Defaults to the sandbox's configured user."}},"required":["command"],"type":"object"},"CreateSandboxRequest":{"properties":{"auto_lifecycle":{"anyOf":[{"description":"Idle-lifecycle policy. Omit it to receive the server-side six-hour idle-to-suspend default, which access and command activity reset. An explicit policy, including a disabled one, is preserved.","type":"object"},{"type":"null"}],"default":null,"x-space-m1-status":"incubating"},"env":{"additionalProperties":{"maxLength":8192,"pattern":"^[^\\u0000]*$","type":"string","x-space-max-utf8-bytes":8192},"default":{},"description":"Guest environment for the sandbox: at most 256 entries, keys of at most 128 and values of at most 8192 UTF-8 bytes, 65536 bytes in total, without NUL.","maxProperties":256,"propertyNames":{"maxLength":128,"pattern":"^[^\\u0000]*$","type":"string","x-space-max-utf8-bytes":128},"type":"object","x-space-max-aggregate-utf8-bytes":65536},"idle_action":{"anyOf":[{"enum":["delete","suspend"],"type":"string","x-enum-varnames":["CREATESANDBOXREQUEST_PROPERTIES_IDLE_ACTION_ANYOF_0_DELETE","CREATESANDBOXREQUEST_PROPERTIES_IDLE_ACTION_ANYOF_0_SUSPEND"]},{"type":"null"}],"description":"Action after the idle duration: delete or suspend. Defaults to suspend\nwhen idle_timeout is provided. Cannot be combined with auto_lifecycle.\nSuspend allows waking on access; delete does not.","x-space-m1-status":"incubating"},"idle_timeout":{"description":"Positive compact idle duration, such as `600s` or `1.5m`, resolving to\nwhole seconds within the supported deadline range. Omit for the default.","type":["string","null"],"x-space-m1-status":"incubating"},"metadata":{"additionalProperties":{"$ref":"#/components/schemas/PublicSandboxMetadataValue"},"default":{},"description":"Caller-defined sandbox metadata: at most 64 entries, keys of at most 128 and string values of at most 1024 UTF-8 bytes, 16384 bytes in total across keys and string values, without NUL.","maxProperties":64,"propertyNames":{"maxLength":128,"pattern":"^[^\\u0000]*$","type":"string","x-space-max-utf8-bytes":128},"type":"object","x-space-max-aggregate-utf8-bytes":16384},"name":{"default":null,"description":"Sandbox name of at most 256 UTF-8 bytes, without NUL.","maxLength":256,"pattern":"^[^\\u0000]*$","type":["string","null"],"x-space-max-utf8-bytes":256},"network_policy":{"anyOf":[{"description":"Sandbox egress policy override, applied on top of the template default.","type":"object"},{"type":"null"}],"default":null,"x-space-m1-status":"incubating"},"resources":{"default":null,"properties":{"disk_mib":{"format":"int64","maximum":131072,"minimum":1,"type":["integer","null"]},"memory_mib":{"format":"int64","maximum":8192,"minimum":512,"type":["integer","null"]},"vcpu":{"format":"int64","maximum":32,"minimum":1,"type":["integer","null"]}},"type":["object","null"]},"runtime":{"anyOf":[{"description":"Sandbox runtime. Prefer the canonical names; the short aliases are accepted for compatibility. Input enums are closed, so new runtimes are added additively.","enum":["firecracker","cloud-hypervisor","gvisor","fc","ch","gv"],"type":"string","x-enum-varnames":["CREATESANDBOXREQUEST_PROPERTIES_RUNTIME_ANYOF_0_FIRECRACKER","CREATESANDBOXREQUEST_PROPERTIES_RUNTIME_ANYOF_0_CLOUD_HYPERVISOR","CREATESANDBOXREQUEST_PROPERTIES_RUNTIME_ANYOF_0_GVISOR","CREATESANDBOXREQUEST_PROPERTIES_RUNTIME_ANYOF_0_FC","CREATESANDBOXREQUEST_PROPERTIES_RUNTIME_ANYOF_0_CH","CREATESANDBOXREQUEST_PROPERTIES_RUNTIME_ANYOF_0_GV"]},{"type":"null"}],"default":null},"template":{"description":"Template reference as `name`, `name:tag`, or `name@<algorithm>:<hex>` (sha256 or blake3). A bare name resolves to `:latest`. A digest may be truncated to a unique prefix.","examples":["seed","seed:latest","seed@sha256:0000000000000000000000000000000000000000000000000000000000000000"],"maxLength":384,"minLength":1,"not":{"pattern":"^[.]{1,2}([:@]|$)"},"pattern":"^[A-Za-z0-9._-]{1,255}(:[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}|@sha256:[0-9a-f]{12,64})?$|^[A-Za-z0-9._-]{1,255}(:[A-Za-z0-9_][A-Za-z0-9_.-]{0,127}|@blake3:[0-9a-f]{12,64})?$","type":"string","x-space-max-utf8-bytes":384}},"required":["template"],"type":"object"},"DataPlaneAttachInfo":{"properties":{"events_url":{"description":"HTTP SSE endpoint for this session, when supported. Attaching a command\nstarts execution. Reconnecting with `Last-Event-ID` resumes with the\noutput after that event while the sandbox retains it, a bounded amount\nper process; otherwise the stream sends `resync_required` first.","type":["string","null"]},"expires_at":{"description":"Attachment-token expiry, separate from session expiry and command timeout.","format":"date-time","type":"string"},"token":{"description":"Session-scoped credential, not a management API token. Keep it secret\nand send it only to the verified attachment destination.","type":"string"},"token_transport":{"description":"Accepted credential transports. Query-string tokens are not supported.","items":{"$ref":"#/components/schemas/DataPlaneTokenTransport"},"type":"array"},"url":{"description":"For commands, the WebSocket attachment endpoint. Use `events_url` for\nHTTP SSE. Resolve relative URLs against the configured data-plane origin\nand validate the destination before sending credentials.","type":"string"}},"required":["url","events_url","token","expires_at","token_transport"],"type":"object"},"DataPlaneErrorCode":{"description":"Extensible data-plane error code. Clients must accept values not listed in examples.","examples":["too_many_unauthenticated_sockets","attach_deadline_exceeded","attach_required","attach_frame_invalid","invalid_token","too_many_attached_streams","unauthenticated","forbidden","session_not_found","session_not_ready","route_resolution_failed","route_state_invalid","session_already_attached","backend_stream_error","binary_client_frames_not_supported","already_attached","process_not_started","invalid_resize","resize_not_supported","input_not_supported","unsupported_session_kind","internal"],"type":"string"},"DataPlaneHttpError":{"properties":{"code":{"$ref":"#/components/schemas/DataPlaneHttpErrorCode"},"details":{"description":"Bounded typed details, as on [`PublicErrorEnvelope::details`]; omitted\nwhen there are none. A `conflict` refusing to start a command because\nthe sandbox is not running carries the same details as `createCommand`.","items":{"$ref":"#/components/schemas/PublicErrorDetail"},"type":"array"},"message":{"type":"string"},"retryable":{"type":"boolean"}},"required":["code","message","retryable"],"type":"object"},"DataPlaneHttpErrorCode":{"description":"Extensible data-plane HTTP error code. Clients must accept values not listed in examples.","examples":["invalid_request","unauthorized","forbidden","not_found","not_ready","conflict","rate_limited","stream_unavailable","service_unavailable","upstream_error","internal"],"type":"string"},"DataPlaneHttpErrorEnvelope":{"properties":{"error":{"$ref":"#/components/schemas/DataPlaneHttpError"}},"required":["error"],"type":"object"},"DataPlaneProcessExitStatus":{"description":"Extensible data-plane process exit status. Clients must accept values not listed in examples.","examples":["exited","signaled","timed_out","unknown"],"type":"string"},"DataPlaneResyncReason":{"description":"Extensible data-plane resync reason. Clients must accept values not listed in examples.","examples":["process_stream_reconnected","file_watch_restarted","cursor_out_of_window","cursor_replay_unavailable"],"type":"string"},"DataPlaneServerFrame":{"oneOf":[{"properties":{"current_node_id":{"type":"string"},"route_generation":{"format":"int64","maximum":9223372036854775807,"minimum":0,"type":"integer"},"session_id":{"pattern":"^(term_|proc_|watch_|port_|proto_)[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","type":"string"},"type":{"const":"attached","type":"string"}},"required":["type","session_id","route_generation","current_node_id"],"type":"object"},{"properties":{"pid":{"format":"int64","maximum":4294967295,"minimum":0,"type":["integer","null"]},"process_id":{"type":"string"},"type":{"const":"process_started","type":"string"}},"required":["type","process_id","pid"],"type":"object"},{"properties":{"data_base64":{"type":"string"},"seq":{"format":"int64","maximum":9223372036854775807,"minimum":0,"type":"integer"},"type":{"const":"stdout","type":"string"}},"required":["type","seq","data_base64"],"type":"object"},{"properties":{"data_base64":{"type":"string"},"seq":{"format":"int64","maximum":9223372036854775807,"minimum":0,"type":"integer"},"type":{"const":"stderr","type":"string"}},"required":["type","seq","data_base64"],"type":"object"},{"properties":{"seq":{"format":"int64","maximum":9223372036854775807,"minimum":0,"type":"integer"},"type":{"const":"input_accepted","type":"string"}},"required":["type","seq"],"type":"object"},{"properties":{"exit_code":{"format":"int32","type":"integer"},"process_id":{"type":"string"},"status":{"$ref":"#/components/schemas/DataPlaneProcessExitStatus"},"type":{"const":"process_exited","type":"string"}},"required":["type","process_id","exit_code","status"],"type":"object"},{"properties":{"kind":{"$ref":"#/components/schemas/FileEventKind"},"path":{"type":"string"},"seq":{"format":"int64","maximum":9223372036854775807,"minimum":0,"type":"integer"},"type":{"const":"file_event","type":"string"}},"required":["type","seq","path","kind"],"type":"object"},{"properties":{"reason":{"$ref":"#/components/schemas/ReconnectReason"},"route_generation":{"format":"int64","maximum":9223372036854775807,"minimum":0,"type":"integer"},"type":{"const":"backend_reconnecting","type":"string"}},"required":["type","reason","route_generation"],"type":"object"},{"properties":{"current_node_id":{"type":"string"},"route_generation":{"format":"int64","maximum":9223372036854775807,"minimum":0,"type":"integer"},"type":{"const":"backend_reconnected","type":"string"}},"required":["type","route_generation","current_node_id"],"type":"object"},{"properties":{"reason":{"$ref":"#/components/schemas/DataPlaneResyncReason"},"type":{"const":"resync_required","type":"string"}},"required":["type","reason"],"type":"object"},{"properties":{"code":{"$ref":"#/components/schemas/DataPlaneErrorCode"},"details":{"description":"As on [`DataPlaneHttpError::details`]; omitted when there are none.","items":{"$ref":"#/components/schemas/PublicErrorDetail"},"type":"array"},"message":{"type":"string"},"retryable":{"type":"boolean"},"type":{"const":"error","type":"string"}},"required":["type","code","message","retryable"],"type":"object"},{"properties":{"reason":{"$ref":"#/components/schemas/StreamCloseReason"},"type":{"const":"closed","type":"string"}},"required":["type","reason"],"type":"object"},{"properties":{"seq":{"format":"int64","maximum":9223372036854775807,"minimum":0,"type":"integer"},"type":{"const":"control_accepted","type":"string"}},"required":["type","seq"],"type":"object"},{"additionalProperties":true,"description":"A future server frame type not understood by this version of the client.","properties":{"type":{"not":{"enum":["attached","process_started","stdout","stderr","input_accepted","process_exited","file_event","backend_reconnecting","backend_reconnected","resync_required","error","closed","control_accepted"],"x-enum-varnames":["DATAPLANESERVERFRAME_ONEOF_13_PROPERTIES_TYPE_NOT_ATTACHED","DATAPLANESERVERFRAME_ONEOF_13_PROPERTIES_TYPE_NOT_PROCESS_STARTED","DATAPLANESERVERFRAME_ONEOF_13_PROPERTIES_TYPE_NOT_STDOUT","DATAPLANESERVERFRAME_ONEOF_13_PROPERTIES_TYPE_NOT_STDERR","DATAPLANESERVERFRAME_ONEOF_13_PROPERTIES_TYPE_NOT_INPUT_ACCEPTED","DATAPLANESERVERFRAME_ONEOF_13_PROPERTIES_TYPE_NOT_PROCESS_EXITED","DATAPLANESERVERFRAME_ONEOF_13_PROPERTIES_TYPE_NOT_FILE_EVENT","DATAPLANESERVERFRAME_ONEOF_13_PROPERTIES_TYPE_NOT_BACKEND_RECONNECTING","DATAPLANESERVERFRAME_ONEOF_13_PROPERTIES_TYPE_NOT_BACKEND_RECONNECTED","DATAPLANESERVERFRAME_ONEOF_13_PROPERTIES_TYPE_NOT_RESYNC_REQUIRED","DATAPLANESERVERFRAME_ONEOF_13_PROPERTIES_TYPE_NOT_ERROR","DATAPLANESERVERFRAME_ONEOF_13_PROPERTIES_TYPE_NOT_CLOSED","DATAPLANESERVERFRAME_ONEOF_13_PROPERTIES_TYPE_NOT_CONTROL_ACCEPTED"]},"type":"string"}},"required":["type"],"type":"object"}]},"DataPlaneTokenTransport":{"description":"Extensible data-plane token transport. Clients must accept values not listed in examples.","examples":["first_frame","sec_websocket_protocol","authorization_header"],"type":"string"},"FileEventKind":{"description":"Extensible file event kind. Clients must accept values not listed in examples.","examples":["created","modified","removed","renamed","chmod","unknown"],"type":"string"},"OperationKind":{"description":"Extensible operation kind. Clients must accept values not listed in examples.","examples":["create_sandbox","fork_sandbox","update_sandbox","delete_sandbox","start_sandbox","stop_sandbox","pause_sandbox","resume_sandbox","suspend_sandbox","restore_sandbox","wake_sandbox","kill_sandbox","checkpoint_sandbox","enable_sandbox_snapshots","disable_sandbox_snapshots","rollback_sandbox","delete_template","create_session"],"type":"string"},"OperationState":{"description":"Extensible operation state. Clients must accept values not listed in examples.","examples":["queued","running","succeeded","failed","canceled","expired"],"type":"string"},"OperationTargetType":{"description":"Extensible operation target type. Clients must accept values not listed in examples.","examples":["sandbox","session","template","snapshot","volume"],"type":"string"},"PageCursor":{"maxLength":4096,"pattern":"^pc1_[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$","type":"string"},"ProcessMutationResponse":{"properties":{"ok":{"description":"The runtime accepted the action. This is not proof that the process has\nexited; inspect its event stream for the exit result.","type":"boolean"}},"required":["ok"],"type":"object"},"ProcessSignalRequest":{"properties":{"signal":{"description":"Unix signal number from 1 through 64, for example 15 for SIGTERM.","format":"int32","maximum":64,"minimum":1,"type":"integer"}},"required":["signal"],"type":"object"},"ProcessState":{"description":"Extensible process state. Clients must accept values not listed in examples.","examples":["running","exited"],"type":"string"},"PublicCommand":{"properties":{"attach":{"anyOf":[{"$ref":"#/components/schemas/DataPlaneAttachInfo"},{"type":"null"}],"description":"Attachment destination and credentials when available."},"created_at":{"format":"date-time","type":"string"},"expires_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"description":"Optional session expiry, distinct from attach.expires_at and the\ncommand's execution timeout. Null means no session expiry is recorded."},"process_id":{"description":"Opaque identity for process endpoint paths, derived from the session\nidentity. Returned before execution starts; process lookup can return\nnot_found before attachment and after exit. This is not a numeric PID.","maxLength":128,"pattern":"^[^\\u0000]+$","type":"string","x-space-max-utf8-bytes":128},"sandbox_id":{"pattern":"^sbx_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","type":"string"},"session_id":{"description":"Session identity for attachment and event-stream paths.","pattern":"^proc_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","type":"string"},"state":{"$ref":"#/components/schemas/SessionState","description":"Session state, not proof of command success. Read the process_exited\nevent and exit result from the command's stream."},"updated_at":{"format":"date-time","type":"string"}},"required":["session_id","process_id","sandbox_id","state","attach","created_at","updated_at","expires_at"],"type":"object"},"PublicErrorCode":{"description":"Extensible public error code. Clients must accept values not listed in examples.","examples":["invalid_request","unauthorized","forbidden","not_found","conflict","failed_precondition","capacity_unavailable","rate_limited","quota_exceeded","idempotency_conflict","operation_failed","service_unavailable","internal"],"type":"string"},"PublicErrorDetail":{"properties":{"key":{"type":"string"},"value":{"type":"string"}},"required":["key","value"],"type":"object"},"PublicErrorEnvelope":{"properties":{"code":{"$ref":"#/components/schemas/PublicErrorCode","description":"Stable programmatic classifier. Branch on this, never on `message`."},"details":{"description":"Bounded typed details; empty when the error has none. A `not_found`\nfrom a file route carries `{\"key\": \"resource\", \"value\": \"path\"}` when\nthe sandbox is yours and the path inside it does not exist; any other\n`not_found`, including a missing or unowned sandbox, carries none. A\n`conflict` from replaying a session create whose session has ended\ncarries `{\"key\": \"reason\", \"value\": \"session_ended\"}`. A `conflict`\nrefusing a command because the sandbox is not running carries `reason`\n(`sandbox_not_running`), `state` (the sandbox's lifecycle state) and,\nunless the sandbox is deleting or failed, `wake` (the request that\nreturns it to running). An `invalid_request` for a command streamed\nwith a `pty` carries `{\"key\": \"field\", \"value\": \"pty\"}`. An\n`invalid_request` for a sandbox create or update field outside its limit\ncarries `{\"key\": \"field\", \"value\": \"<field>\"}`, such as `metadata` or\n`resources.vcpu`.","items":{"$ref":"#/components/schemas/PublicErrorDetail"},"type":"array"},"message":{"description":"Human-readable explanation. Not stable; must not be parsed.","type":"string"},"request_id":{"description":"Matches the `x-request-id` response header; quote it in bug reports.","type":["string","null"]},"retryable":{"description":"Authoritative retry decision. When this envelope is present, retry the\nrequest only if this is `true` (honouring `Retry-After` when sent, else\nexponential backoff from one second with jitter, at most five attempts),\nand only with the same `Idempotency-Key` for mutations. The HTTP status\ndecides only when no valid envelope was returned.","type":"boolean"}},"required":["code","message","request_id","retryable","details"],"type":"object"},"PublicOperationRecord":{"properties":{"completed_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"created_at":{"format":"date-time","type":"string"},"id":{"pattern":"^op_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","type":"string"},"kind":{"$ref":"#/components/schemas/OperationKind"},"progress_message":{"type":"string"},"result":{"anyOf":[{"$ref":"#/components/schemas/PublicOperationResult"},{"type":"null"}],"description":"Typed operation result when available. Check `state` for success before\nconsuming it; null alone does not identify a pending or failed operation."},"started_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}]},"state":{"$ref":"#/components/schemas/OperationState","description":"Progress of asynchronous work: queued/running or a terminal outcome\nsuch as succeeded/failed/canceled/expired. This is neither sandbox state\nnor a command's process exit status. Tolerate future response values."},"target_id":{"type":["string","null"]},"target_type":{"anyOf":[{"$ref":"#/components/schemas/OperationTargetType"},{"type":"null"}]},"terminal_error":true,"terminal_error_code":{"anyOf":[{"$ref":"#/components/schemas/PublicErrorCode"},{"type":"null"}],"description":"Machine-readable failure code for a terminal operation, when present.\nThe separate terminal_error field supplies additional context; do not\nparse human-readable messages as codes."},"updated_at":{"format":"date-time","type":"string"}},"required":["id","kind","state","target_type","target_id","progress_message","terminal_error_code","terminal_error","result","created_at","started_at","completed_at","updated_at"],"type":"object"},"PublicOperationResult":{"oneOf":[{"properties":{"action":{"anyOf":[{"$ref":"#/components/schemas/SandboxLifecycleAction"},{"type":"null"}]},"controller_response":true,"sandbox_id":{"pattern":"^sbx_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","type":"string"},"state":{"$ref":"#/components/schemas/SandboxLifecycleState"},"type":{"const":"sandbox","type":"string"}},"required":["sandbox_id","state","action","controller_response","type"],"type":"object"},{"properties":{"state":{"type":"string"},"template":{"type":"string"},"type":{"const":"template","type":"string"}},"required":["template","state","type"],"type":"object"},{"properties":{"kind":{"$ref":"#/components/schemas/SessionKind"},"sandbox_id":{"pattern":"^sbx_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","type":"string"},"session_id":{"pattern":"^(term_|proc_|watch_|port_|proto_)[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","type":"string"},"type":{"const":"session","type":"string"}},"required":["session_id","sandbox_id","kind","type"],"type":"object"},{"properties":{"results":{"items":true,"type":"array"},"type":{"const":"fork","type":"string"}},"required":["results","type"],"type":"object"}]},"PublicProcess":{"properties":{"command":{"items":{"type":"string"},"type":"array"},"cwd":{"type":["string","null"]},"ended_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"description":"When the process ended, by the sandbox's clock."},"exit_code":{"description":"Set when `state` is `exited`: the same value as `process_exited`'s\n`exit_code`.","format":"int32","type":["integer","null"]},"exit_status":{"anyOf":[{"$ref":"#/components/schemas/DataPlaneProcessExitStatus"},{"type":"null"}],"description":"Set when `state` is `exited`: the same value as `process_exited`'s\n`status`."},"pid":{"description":"Numeric PID inside the guest. Do not substitute it for `process_id`.","format":"int64","maximum":4294967295,"minimum":0,"type":"integer"},"process_id":{"description":"Opaque identity used in process endpoint paths; not the guest's numeric PID.","maxLength":128,"pattern":"^[^\\u0000]+$","type":"string","x-space-max-utf8-bytes":128},"signal":{"description":"The signal that ended the process, when `exit_status` is `signaled` or\n`timed_out` and the sandbox reported it.","format":"int32","type":["integer","null"]},"state":{"anyOf":[{"$ref":"#/components/schemas/ProcessState"},{"type":"null"}],"description":"`exited` once the process has ended, with the exit fields below. Test\nfor `exited`: a running process omits `state` today, but may report\n`running`. A finished process stays visible for a bounded time after\nit exits; then it is `not_found`."},"tag":{"type":["string","null"]},"user":{"type":["string","null"]}},"required":["process_id","pid","command","cwd","user","tag"],"type":"object"},"PublicProcessPage":{"properties":{"data":{"items":{"$ref":"#/components/schemas/PublicProcess"},"type":"array"},"next_cursor":{"anyOf":[{"$ref":"#/components/schemas/PageCursor"},{"type":"null"}],"description":"Opaque continuation token; pass it unchanged to the same collection's\ncursor parameter until null. Cursors for different resources are not\ninterchangeable."}},"required":["data","next_cursor"],"type":"object"},"PublicSandbox":{"properties":{"conditions":{"description":"Readiness and failure observations with explanatory reasons and messages.","items":{"$ref":"#/components/schemas/SandboxCondition"},"type":"array"},"created_at":{"format":"date-time","type":"string"},"expires_at":{"anyOf":[{"format":"date-time","type":"string"},{"type":"null"}],"default":null,"description":"Stored idle deadline; null when no automatic lifecycle event is scheduled.","x-space-m1-status":"incubating"},"failure_code":{"anyOf":[{"$ref":"#/components/schemas/SandboxFailureCode"},{"type":"null"}],"description":"Current observed failure classification when available; null is not a\nguarantee that the sandbox is ready."},"id":{"pattern":"^sbx_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","type":"string"},"idle_action":{"anyOf":[{"$ref":"#/components/schemas/SandboxIdleAction"},{"type":"null"}],"default":null,"description":"Action paired with idle_timeout; null for policies with other shapes.","x-space-m1-status":"incubating"},"idle_timeout":{"default":null,"description":"Idle duration in seconds, such as `600s`, for a single access-idle stage.\nNull when the policy cannot be represented by idle_timeout and idle_action.","type":["string","null"],"x-space-m1-status":"incubating"},"metadata":{"additionalProperties":{"$ref":"#/components/schemas/PublicSandboxMetadataValue"},"type":"object"},"name":{"type":["string","null"]},"resources":{"description":"Stored resource requests, not a measurement of resolved guest capacity.\nNull fields mean no explicit value was recorded, not zero capacity.","properties":{"disk_mib":{"format":"int64","maximum":4294967295,"minimum":0,"type":["integer","null"]},"memory_mib":{"format":"int64","maximum":4294967295,"minimum":0,"type":["integer","null"]},"vcpu":{"format":"int64","maximum":4294967295,"minimum":0,"type":["integer","null"]}},"required":["vcpu","memory_mib","disk_mib"],"type":"object"},"state":{"$ref":"#/components/schemas/SandboxLifecycleState","description":"Current sandbox lifecycle state, distinct from operation progress and\ncommand exit status. Unknown future response values must be tolerated."},"template":{"description":"Template reference recorded for this sandbox, when available.","type":["string","null"]},"template_digest":{"description":"Resolved template content digest, when available.","type":["string","null"]},"updated_at":{"format":"date-time","type":"string"}},"required":["id","name","state","failure_code","conditions","template","template_digest","resources","metadata","expires_at","idle_timeout","idle_action","created_at","updated_at"],"type":"object"},"PublicSandboxMetadataValue":{"anyOf":[{"type":"string"},{"format":"int64","type":"integer"},{"type":"boolean"}]},"PublicSandboxPage":{"properties":{"data":{"items":{"$ref":"#/components/schemas/PublicSandbox"},"type":"array"},"next_cursor":{"anyOf":[{"$ref":"#/components/schemas/PageCursor"},{"type":"null"}],"description":"Opaque continuation token; pass it unchanged to the same collection's\ncursor parameter until null. Cursors for different resources are not\ninterchangeable."}},"required":["data","next_cursor"],"type":"object"},"ReconnectReason":{"description":"Extensible reconnect reason. Clients must accept values not listed in examples.","examples":["backend_restart","sandbox_migration","route_generation_changed","worker_unavailable","data_plane_restart"],"type":"string"},"SandboxCondition":{"properties":{"condition_type":{"$ref":"#/components/schemas/SandboxConditionType"},"message":{"type":"string"},"reason":{"type":"string"},"status":{"$ref":"#/components/schemas/ConditionStatus"}},"required":["condition_type","status","reason","message"],"type":"object"},"SandboxConditionType":{"description":"Extensible sandbox condition type. Clients must accept values not listed in examples.","examples":["ready","network_ready"],"type":"string"},"SandboxFailureCode":{"description":"Extensible sandbox failure code. Clients must accept values not listed in examples.","examples":["runtime_failure"],"type":"string"},"SandboxIdleAction":{"description":"Extensible sandbox idle action. Clients must accept values not listed in examples.","examples":["delete","suspend"],"type":"string"},"SandboxLifecycleAction":{"description":"Extensible sandbox lifecycle action. Clients must accept values not listed in examples.","examples":["start","stop","pause","resume","suspend","restore","wake","kill","checkpoint","enable_snapshots","disable_snapshots","rollback","delete"],"type":"string"},"SandboxLifecycleState":{"description":"Extensible sandbox lifecycle state. Clients must accept values not listed in examples.","examples":["creating","stopped","starting","running","pausing","paused","resuming","suspending","suspended","restoring","migrating","stopping","failed","deleting","deleted"],"type":"string"},"SandboxOperationResponse":{"properties":{"operation":{"anyOf":[{"$ref":"#/components/schemas/PublicOperationRecord"},{"type":"null"}],"description":"The operation's record, as `GET /v1/operations/{operation_id}` returns\nit, when the server finished the work before answering. Present only\nwith a terminal `state`; when absent, poll `operation_id`.","x-space-m1-status":"incubating"},"operation_id":{"description":"Poll this operation and require success before relying on the action's\noutcome. An HTTP 202 response only accepts the work.","pattern":"^op_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","type":"string"},"sandbox_id":{"pattern":"^sbx_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","type":"string"}},"required":["operation_id","sandbox_id"],"type":"object"},"SessionKind":{"description":"Extensible session kind. Clients must accept values not listed in examples.","examples":["terminal","process","file_watch","port","protocol"],"type":"string"},"SessionState":{"description":"Extensible session state. Clients must accept values not listed in examples.","examples":["pending","attaching","open","reconnecting","closing","closed","revoked","failed"],"type":"string"},"StreamCloseReason":{"description":"Extensible stream close reason. Clients must accept values not listed in examples.","examples":["client_closed","backend_closed","backend_reconnecting","token_expired","revoked","idle_timeout","error"],"type":"string"},"TerminalSize":{"properties":{"cols":{"format":"int32","maximum":65535,"minimum":1,"type":"integer"},"rows":{"format":"int32","maximum":65535,"minimum":1,"type":"integer"}},"required":["cols","rows"],"type":"object"}},"securitySchemes":{"apiKey":{"scheme":"bearer","type":"http"},"dataPlaneToken":{"description":"Scoped data-plane token returned in a session or command handle.","scheme":"bearer","type":"http"},"dataPlaneWebSocketProtocol":{"description":"A scoped data-plane token may be carried as a WebSocket subprotocol.","in":"header","name":"Sec-WebSocket-Protocol","type":"apiKey"}}},"info":{"description":"### Errors and retries\n\n- Keep `x-request-id` for troubleshooting. Management errors use `PublicErrorEnvelope`, with a stable `code` and a `retryable` flag; SSE admission errors use the nested `DataPlaneHttpErrorEnvelope`.\n- Follow the returned `retryable` flag, subject to the duplicate-work precautions below. If no valid envelope is available, HTTP 429 and 5xx may be transient, but do not blindly retry mutations with ambiguous outcomes.\n- Wait for `Retry-After` when present (whole seconds). Otherwise, start with a one-second delay and double it with jitter. Stop after five attempts.\n\n### Avoid duplicate work\n\nOnly endpoints declaring a required `Idempotency-Key` deduplicate mutations. Retry those with the same method, path, body, and key. Within 24 hours, this returns the original result, except that replaying a session or command create whose session was revoked returns `conflict` with `{\"key\": \"reason\", \"value\": \"session_ended\"}` in `details` and no token. A different body returns `idempotency_conflict`; a new or expired key can start another operation. Process kill and signal do not use this mechanism: inspect ambiguous outcomes before repeating them, because a repeat can apply the action again.\n\n### Error codes\n\n- Management errors that are not retryable: `invalid_request` (400), `unauthorized` (401), `forbidden` (403), `not_found` (404), `conflict` and `idempotency_conflict` (409), `failed_precondition` (412), `quota_exceeded` (429, an organization or per-user sandbox limit).\n- Usually retryable management errors: `rate_limited` (429), `capacity_unavailable` and `service_unavailable` (503), `internal` (500). Always check the returned `retryable` flag. Data-plane mappings differ; see each response's envelope.\n- Unsupported methods (405), oversized bodies (413), wrong content types (415), and invalid request schemas (422) use `invalid_request` with `retryable: false`. Other unhandled management 5xx errors use `internal`.\n- A file route's `not_found` lists `{\"key\": \"resource\", \"value\": \"path\"}` in `details` when the sandbox is yours and the path does not exist. Without that detail, treat it as the sandbox not being found: a missing sandbox and one you cannot access answer alike.\n- A sandbox create or update that exceeds a documented input limit returns `invalid_request` listing `{\"key\": \"field\", \"value\": \"<field>\"}` in `details`, such as `metadata` or `resources.vcpu`.","title":"SPACE API","version":"0.8.1"},"jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","openapi":"3.1.0","paths":{"/operations/{operation_id}":{"get":{"description":"Returns the current state and result of an asynchronous operation owned by the authenticated organization.","operationId":"getOperation","responses":{"200":{"content":{"application/json":{"examples":{"illustrative":{"description":"Illustrative response with synthetic IDs and timestamps. The token placeholder is not a credential; use values returned by your deployment.","value":{"completed_at":"2026-09-28T12:00:01Z","created_at":"2026-09-28T12:00:00Z","id":"op_00000000-0000-0000-0000-000000000000","kind":"create_sandbox","progress_message":"Sandbox created","result":{"action":null,"controller_response":null,"sandbox_id":"sbx_00000000-0000-0000-0000-000000000000","state":"running","type":"sandbox"},"started_at":"2026-09-28T12:00:00Z","state":"succeeded","target_id":"sbx_00000000-0000-0000-0000-000000000000","target_type":"sandbox","terminal_error":null,"terminal_error_code":null,"updated_at":"2026-09-28T12:00:01Z"}}},"schema":{"$ref":"#/components/schemas/PublicOperationRecord"}}},"description":"Operation","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"content":{"application/json":{"examples":{"invalid_request":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"invalid_request","details":[],"message":"Invalid operation id","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Invalid operation id","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"401":{"content":{"application/json":{"examples":{"unauthorized":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"unauthorized","details":[],"message":"Authentication required","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Authentication required","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"404":{"content":{"application/json":{"examples":{"not_found":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"not_found","details":[],"message":"Operation not found","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Operation not found","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"500":{"content":{"application/json":{"examples":{"internal":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"internal","details":[],"message":"Internal server error","request_id":null,"retryable":true}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Operation lookup failed internally","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}}},"summary":"Get an operation","x-space-m1-status":"m1-supported"},"parameters":[{"in":"path","name":"operation_id","required":true,"schema":{"pattern":"^op_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","type":"string"}}]},"/sandboxes":{"get":{"description":"Returns sandboxes ordered by creation time and ID, newest first.","operationId":"listSandboxes","parameters":[{"in":"query","name":"cursor","required":false,"schema":{"maxLength":4096,"pattern":"^pc1_[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$","type":"string"}},{"description":"Maximum number of sandboxes. Omitted or zero uses the server default of 100; values above 1000 are capped at 1000. A page also ends early once its sandboxes reach 8 MiB of JSON; follow `next_cursor` until it is null.","in":"query","name":"limit","required":false,"schema":{"maximum":65535,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"examples":{"illustrative":{"description":"Illustrative response with synthetic IDs and timestamps. The token placeholder is not a credential; use values returned by your deployment.","value":{"data":[{"conditions":[],"created_at":"2026-09-28T12:00:00Z","expires_at":"2026-09-28T18:00:00Z","failure_code":null,"id":"sbx_00000000-0000-0000-0000-000000000000","idle_action":"suspend","idle_timeout":"21600s","metadata":{},"name":"example-sandbox","resources":{"disk_mib":null,"memory_mib":null,"vcpu":null},"state":"running","template":"seed:latest","template_digest":null,"updated_at":"2026-09-28T12:00:00Z"}],"next_cursor":null}}},"schema":{"$ref":"#/components/schemas/PublicSandboxPage"}}},"description":"Sandbox page","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"content":{"application/json":{"examples":{"invalid_request":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"invalid_request","details":[],"message":"Invalid sandbox cursor","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Invalid sandbox cursor","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"401":{"content":{"application/json":{"examples":{"unauthorized":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"unauthorized","details":[],"message":"Authentication required","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Authentication required","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"500":{"content":{"application/json":{"examples":{"internal":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"internal","details":[],"message":"Internal server error","request_id":null,"retryable":true}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Sandbox listing failed internally","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}}},"summary":"List sandboxes","x-space-m1-status":"m1-supported"},"post":{"description":"Returns an operation handle while the sandbox is being created.\n\n### Wait for readiness\n\nPoll the operation to detect completion. When the server finishes the create before answering, the response also carries the terminal operation record in `operation`, and no poll is needed. `GET /sandboxes/{sandbox_id}` can return 404 while creation is pending.\n\n### Idle timeout\n\nIf `auto_lifecycle` is omitted or null, the sandbox suspends after six idle hours. Access and command activity reset the idle clock. An explicit policy, including a disabled one, is preserved.\n\n### Example request\n\nRequires the published `seed:latest` template:\n\n```json\n{\"template\":\"seed:latest\",\"runtime\":\"fc\"}\n```","operationId":"createSandbox","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"description":"1 to 1024 printable ASCII characters, spaces or tabs.","maxLength":1024,"minLength":1,"pattern":"^[\\t -~]+$","type":"string","x-space-max-utf8-bytes":1024}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSandboxRequest"}}},"required":true},"responses":{"202":{"content":{"application/json":{"examples":{"illustrative":{"description":"Illustrative response with synthetic IDs and timestamps. The token placeholder is not a credential; use values returned by your deployment.","value":{"operation_id":"op_00000000-0000-0000-0000-000000000000","sandbox_id":"sbx_00000000-0000-0000-0000-000000000000"}}},"schema":{"$ref":"#/components/schemas/SandboxOperationResponse"}}},"description":"Sandbox creation operation accepted","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"content":{"application/json":{"examples":{"invalid_request":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"invalid_request","details":[],"message":"Invalid idempotency key or sandbox request","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Invalid idempotency key or sandbox request","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"401":{"content":{"application/json":{"examples":{"unauthorized":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"unauthorized","details":[],"message":"Authentication required","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Authentication required","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"409":{"content":{"application/json":{"examples":{"conflict":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"conflict","details":[],"message":"Request conflicts with the current state","request_id":null,"retryable":false}},"idempotency_conflict":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"idempotency_conflict","details":[],"message":"Idempotency key was used with a different request","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Idempotency conflict","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"413":{"content":{"application/json":{"examples":{"invalid_request":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"invalid_request","details":[],"message":"Request body is too large","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Request body is too large","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"415":{"content":{"application/json":{"examples":{"invalid_request":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"invalid_request","details":[],"message":"Content-Type must be application/json","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Content-Type must be application/json","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"422":{"content":{"application/json":{"examples":{"invalid_request":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"invalid_request","details":[],"message":"JSON body does not match CreateSandboxRequest","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"JSON body does not match CreateSandboxRequest","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"429":{"content":{"application/json":{"examples":{"quota_exceeded":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"quota_exceeded","details":[],"message":"The organization or per-user sandbox limit is reached (`quota_exceeded`). Not retryable: the limit lifts once a delete completes or an in-flight create ends","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"The organization or per-user sandbox limit is reached (`quota_exceeded`). Not retryable: the limit lifts once a delete completes or an in-flight create ends","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"500":{"content":{"application/json":{"examples":{"internal":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"internal","details":[],"message":"Internal server error","request_id":null,"retryable":true}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Sandbox operation could not be persisted","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"503":{"content":{"application/json":{"examples":{"capacity_unavailable":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"capacity_unavailable","details":[],"message":"Sandbox capacity is temporarily unavailable","request_id":null,"retryable":true}},"service_unavailable":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"service_unavailable","details":[],"message":"The operation is temporarily unavailable","request_id":null,"retryable":true}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Sandbox operation is temporarily unavailable","headers":{"Retry-After":{"description":"Wait this many whole seconds before retrying (minimum 1, rounded up; not an HTTP date). Not every 429 or 503 includes this header. When absent, start with a one-second delay and double it with jitter.","schema":{"minimum":1,"type":"integer"}},"x-request-id":{"$ref":"#/components/headers/RequestId"}}}},"summary":"Create a sandbox","x-space-m1-status":"m1-supported"}},"/sandboxes/{sandbox_id}":{"delete":{"description":"Returns an operation handle while the sandbox is being deleted. Poll the operation for completion. Reusing the same idempotency key for the same sandbox returns the original operation.","operationId":"deleteSandbox","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"description":"1 to 1024 printable ASCII characters, spaces or tabs.","maxLength":1024,"minLength":1,"pattern":"^[\\t -~]+$","type":"string","x-space-max-utf8-bytes":1024}}],"responses":{"202":{"content":{"application/json":{"examples":{"illustrative":{"description":"Illustrative response with synthetic IDs and timestamps. The token placeholder is not a credential; use values returned by your deployment.","value":{"operation_id":"op_00000000-0000-0000-0000-000000000000","sandbox_id":"sbx_00000000-0000-0000-0000-000000000000"}}},"schema":{"$ref":"#/components/schemas/SandboxOperationResponse"}}},"description":"Sandbox deletion operation accepted","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"content":{"application/json":{"examples":{"invalid_request":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"invalid_request","details":[],"message":"Invalid sandbox id or idempotency key","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Invalid sandbox id or idempotency key","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"401":{"content":{"application/json":{"examples":{"unauthorized":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"unauthorized","details":[],"message":"Authentication required","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Authentication required","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"404":{"content":{"application/json":{"examples":{"not_found":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"not_found","details":[],"message":"Sandbox not found","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Sandbox not found","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"409":{"content":{"application/json":{"examples":{"conflict":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"conflict","details":[],"message":"Request conflicts with the current state","request_id":null,"retryable":false}},"idempotency_conflict":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"idempotency_conflict","details":[],"message":"Idempotency key was used with a different request","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Idempotency conflict","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"500":{"content":{"application/json":{"examples":{"internal":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"internal","details":[],"message":"Internal server error","request_id":null,"retryable":true}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Sandbox deletion operation could not be persisted","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"503":{"content":{"application/json":{"examples":{"capacity_unavailable":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"capacity_unavailable","details":[],"message":"Sandbox capacity is temporarily unavailable","request_id":null,"retryable":true}},"service_unavailable":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"service_unavailable","details":[],"message":"The operation is temporarily unavailable","request_id":null,"retryable":true}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Sandbox operation is temporarily unavailable","headers":{"Retry-After":{"description":"Wait this many whole seconds before retrying (minimum 1, rounded up; not an HTTP date). Not every 429 or 503 includes this header. When absent, start with a one-second delay and double it with jitter.","schema":{"minimum":1,"type":"integer"}},"x-request-id":{"$ref":"#/components/headers/RequestId"}}}},"summary":"Delete a sandbox","x-space-m1-status":"m1-supported"},"get":{"description":"Returns the sandbox's current lifecycle state, conditions, template, stored resource requests, and metadata. This is not an operation result or command exit status. Deleted sandboxes and sandboxes outside your organization return not_found. After an asynchronous action, poll its operation and inspect this resource before starting dependent work.","operationId":"getSandbox","responses":{"200":{"content":{"application/json":{"examples":{"illustrative":{"description":"Illustrative response with synthetic IDs and timestamps. The token placeholder is not a credential; use values returned by your deployment.","value":{"conditions":[],"created_at":"2026-09-28T12:00:00Z","expires_at":"2026-09-28T18:00:00Z","failure_code":null,"id":"sbx_00000000-0000-0000-0000-000000000000","idle_action":"suspend","idle_timeout":"21600s","metadata":{},"name":"example-sandbox","resources":{"disk_mib":null,"memory_mib":null,"vcpu":null},"state":"running","template":"seed:latest","template_digest":null,"updated_at":"2026-09-28T12:00:00Z"}}},"schema":{"$ref":"#/components/schemas/PublicSandbox"}}},"description":"Sandbox","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"content":{"application/json":{"examples":{"invalid_request":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"invalid_request","details":[],"message":"Invalid sandbox id","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Invalid sandbox id","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"401":{"content":{"application/json":{"examples":{"unauthorized":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"unauthorized","details":[],"message":"Authentication required","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Authentication required","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"404":{"content":{"application/json":{"examples":{"not_found":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"not_found","details":[],"message":"Sandbox not found","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Sandbox not found","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"500":{"content":{"application/json":{"examples":{"internal":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"internal","details":[],"message":"Internal server error","request_id":null,"retryable":true}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Sandbox lookup failed internally","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}}},"summary":"Get a sandbox","x-space-m1-status":"m1-supported"},"parameters":[{"in":"path","name":"sandbox_id","required":true,"schema":{"pattern":"^sbx_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","type":"string"}}]},"/sandboxes/{sandbox_id}/commands":{"parameters":[{"in":"path","name":"sandbox_id","required":true,"schema":{"pattern":"^sbx_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","type":"string"}}],"post":{"description":"Returns a command handle and a session token. Creating the handle does not start the process.\n\n- Attach to `/sessions/{session_id}/events` with the returned session token, not your management API token. Attaching to the stream starts execution.\n- Read stdout, stderr, and the exit status from that stream.\n- To create and attach in one request, send `Accept: text/event-stream`. The 201 response is then that event stream, preceded by a `command` event whose data is `{\"type\":\"command\",\"command\":<PublicCommand>}`. That event has no `id`, and clients that skip unknown frame types may ignore it. When the stream cannot be opened, the response is the JSON handle instead; attach to `events_url` as usual. Reconnect through `/sessions/{session_id}/events`.\n- Interactive input and terminals use a separate WebSocket API, outside this reference. Server-sent events carry no input: a command the events stream starts has standard input at end of file, even with `stdin: true`. A pty cannot be closed, so a `pty` with `Accept: text/event-stream` is rejected with `invalid_request` whether or not the command reads input, and `details` carries `{\"key\":\"field\",\"value\":\"pty\"}`. Without that header the handle is created, but `/sessions/{session_id}/events` refuses to start it with `invalid_request`; after a WebSocket attach starts it and detaches, the events stream can reconnect and read its output.\n\n### Sandboxes that are not running\n\n- A sandbox that is creating, starting, resuming, or restoring accepts the command; the attach waits for it. So does one taking a checkpoint, which reports `suspending` while it does: two `suspending` sandboxes can answer differently.\n- A command wakes a sandbox that is paused, suspended, pausing, or suspending only when its `auto_lifecycle.wake.on` includes `command` or `access`. A sandbox that reports `creating` but whose creation has not started is woken or refused the same way, as one at rest. The handle is created and the sandbox starts waking; an attach answers a retryable 503 only while the wake runs. Once nothing is about to wake the sandbox, as when a later `:suspend` leaves it at rest, the attach answers the same 409 `conflict` described below. The wake is queued with the sandbox's other lifecycle operations: a `:suspend` requested after it runs after it, so the sandbox can end suspended, and the command does not run until the caller wakes it again.\n- Otherwise, and always for a sandbox that is stopped or stopping, the response is a 409 `conflict`, not retryable, whose `details` carry `reason` (`sandbox_not_running`), `state` (the sandbox's state), and `wake`: the request that returns it to running, `:wake`, or `:start` for a stopped sandbox. A sandbox that is deleting or failed has no `wake`.\n\n### Example request\n\n```json\n{\"command\":[\"sh\",\"-c\",\"printf 'Hello from SPACE\\\\n'\"],\"timeout\":\"30s\"}\n```","operationId":"createCommand","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"description":"1 to 1024 printable ASCII characters, spaces or tabs.","maxLength":1024,"minLength":1,"pattern":"^[\\t -~]+$","type":"string","x-space-max-utf8-bytes":1024}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCommandRequest"}}},"required":true},"responses":{"201":{"content":{"application/json":{"examples":{"illustrative":{"description":"Illustrative response with synthetic IDs and timestamps. The token placeholder is not a credential; use values returned by your deployment.","value":{"attach":{"events_url":"/v1/sessions/proc_00000000-0000-0000-0000-000000000000/events","expires_at":"2026-09-28T12:05:00Z","token":"EXAMPLE_SESSION_TOKEN_NOT_A_CREDENTIAL","token_transport":["authorization_header","sec_websocket_protocol"],"url":"/v1/sessions/proc_00000000-0000-0000-0000-000000000000/attach"},"created_at":"2026-09-28T12:00:00Z","expires_at":null,"process_id":"proc_00000000-0000-0000-0000-000000000000","sandbox_id":"sbx_00000000-0000-0000-0000-000000000000","session_id":"proc_00000000-0000-0000-0000-000000000000","state":"pending","updated_at":"2026-09-28T12:00:00Z"}}},"schema":{"$ref":"#/components/schemas/PublicCommand"}},"text/event-stream":{"schema":{"type":"string"},"x-space-sse-event-data-schema":{"oneOf":[{"properties":{"command":{"$ref":"#/components/schemas/PublicCommand"},"type":{"const":"command","type":"string"}},"required":["type","command"],"type":"object"},{"$ref":"#/components/schemas/DataPlaneServerFrame"}]}}},"description":"Command handle with event stream token, or the command's event stream when requested with `Accept: text/event-stream`","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"content":{"application/json":{"examples":{"invalid_request":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"invalid_request","details":[],"message":"Invalid sandbox id, idempotency key, or command request, or pty with Accept: text/event-stream","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Invalid sandbox id, idempotency key, or command request, or pty with Accept: text/event-stream","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"401":{"content":{"application/json":{"examples":{"unauthorized":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"unauthorized","details":[],"message":"Authentication required","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Authentication required","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"404":{"content":{"application/json":{"examples":{"not_found":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"not_found","details":[],"message":"Sandbox not found","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Sandbox not found","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"409":{"content":{"application/json":{"examples":{"conflict":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"conflict","details":[{"key":"reason","value":"sandbox_not_running"},{"key":"state","value":"suspended"},{"key":"wake","value":"POST /v1/sandboxes/sbx_00000000-0000-0000-0000-000000000000:wake"}],"message":"sandbox is suspended, not running","request_id":null,"retryable":false}},"idempotency_conflict":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"idempotency_conflict","details":[],"message":"Idempotency key was used with a different request","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Idempotency conflict, a replayed create whose session was revoked, or the sandbox is not running and this command cannot wake it","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"413":{"content":{"application/json":{"examples":{"invalid_request":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"invalid_request","details":[],"message":"Request body is too large","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Request body is too large","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"415":{"content":{"application/json":{"examples":{"invalid_request":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"invalid_request","details":[],"message":"Content-Type must be application/json","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Content-Type must be application/json","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"422":{"content":{"application/json":{"examples":{"invalid_request":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"invalid_request","details":[],"message":"JSON body does not match CreateCommandRequest","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"JSON body does not match CreateCommandRequest","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"500":{"content":{"application/json":{"examples":{"internal":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"internal","details":[],"message":"Internal server error","request_id":null,"retryable":true}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Command session could not be persisted","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}}},"summary":"Create command","x-space-m1-status":"m1-supported"}},"/sandboxes/{sandbox_id}/processes":{"get":{"description":"Returns running processes ordered by process ID, not completed-command history. To start a process and collect its output, create a command and attach to its event stream.","operationId":"listProcesses","parameters":[{"in":"query","name":"cursor","required":false,"schema":{"maxLength":4096,"pattern":"^pc1_[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+$","type":"string"}},{"description":"Maximum number of processes. Omitted or zero uses the server default of 100; values above 1000 are capped at 1000.","in":"query","name":"limit","required":false,"schema":{"maximum":65535,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"examples":{"illustrative":{"description":"Illustrative response with synthetic IDs and timestamps. The token placeholder is not a credential; use values returned by your deployment.","value":{"data":[{"command":["sleep","30"],"cwd":null,"pid":42,"process_id":"proc_00000000-0000-0000-0000-000000000000","tag":null,"user":null}],"next_cursor":null}}},"schema":{"$ref":"#/components/schemas/PublicProcessPage"}}},"description":"Process page","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"content":{"application/json":{"examples":{"invalid_request":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"invalid_request","details":[],"message":"Invalid sandbox id or cursor","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Invalid sandbox id or cursor","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"401":{"content":{"application/json":{"examples":{"unauthorized":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"unauthorized","details":[],"message":"Authentication required","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Authentication required","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"403":{"content":{"application/json":{"examples":{"forbidden":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"forbidden","details":[],"message":"Caller is not allowed to list processes","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Caller is not allowed to list processes","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"404":{"content":{"application/json":{"examples":{"not_found":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"not_found","details":[],"message":"Sandbox not found","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Sandbox not found","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"409":{"content":{"application/json":{"examples":{"conflict":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"conflict","details":[],"message":"Request conflicts with the current state","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Sandbox process state conflicts with the request","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"412":{"content":{"application/json":{"examples":{"failed_precondition":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"failed_precondition","details":[],"message":"Sandbox process-list precondition failed","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Sandbox process-list precondition failed","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"429":{"content":{"application/json":{"examples":{"rate_limited":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"rate_limited","details":[],"message":"Runtime request rate limited","request_id":null,"retryable":true}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Runtime request rate limited","headers":{"Retry-After":{"description":"Wait this many whole seconds before retrying (minimum 1, rounded up; not an HTTP date). Not every 429 or 503 includes this header. When absent, start with a one-second delay and double it with jitter.","schema":{"minimum":1,"type":"integer"}},"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"500":{"content":{"application/json":{"examples":{"internal":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"internal","details":[],"message":"Internal server error","request_id":null,"retryable":true}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Process listing failed internally","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"503":{"content":{"application/json":{"examples":{"service_unavailable":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"service_unavailable","details":[],"message":"The operation is temporarily unavailable","request_id":null,"retryable":true}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Sandbox runtime unavailable","headers":{"Retry-After":{"description":"Wait this many whole seconds before retrying (minimum 1, rounded up; not an HTTP date). Not every 429 or 503 includes this header. When absent, start with a one-second delay and double it with jitter.","schema":{"minimum":1,"type":"integer"}},"x-request-id":{"$ref":"#/components/headers/RequestId"}}}},"summary":"List running processes","x-space-m1-status":"m1-supported"},"parameters":[{"in":"path","name":"sandbox_id","required":true,"schema":{"pattern":"^sbx_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","type":"string"}}]},"/sandboxes/{sandbox_id}/processes/{process_id}":{"get":{"description":"Returns metadata for a running process, or for a recently exited one with `state` `exited` and its exit. Test for `state` `exited`: a running process omits `state` today and may report `running` later. A sandbox keeps an exited process for up to 15 minutes, less once many newer processes start; then it is `not_found`. A sandbox from an older template returns `not_found` as soon as the process exits. Environment variables are never returned. Collect output from the command's event stream.","operationId":"getProcess","responses":{"200":{"content":{"application/json":{"examples":{"illustrative":{"description":"Illustrative response with synthetic IDs and timestamps. The token placeholder is not a credential; use values returned by your deployment.","value":{"command":["sleep","30"],"cwd":null,"pid":42,"process_id":"proc_00000000-0000-0000-0000-000000000000","tag":null,"user":null}}},"schema":{"$ref":"#/components/schemas/PublicProcess"}}},"description":"Process metadata","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"content":{"application/json":{"examples":{"invalid_request":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"invalid_request","details":[],"message":"Invalid sandbox or process id","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Invalid sandbox or process id","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"401":{"content":{"application/json":{"examples":{"unauthorized":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"unauthorized","details":[],"message":"Authentication required","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Authentication required","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"403":{"content":{"application/json":{"examples":{"forbidden":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"forbidden","details":[],"message":"Caller is not allowed to inspect processes","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Caller is not allowed to inspect processes","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"404":{"content":{"application/json":{"examples":{"not_found":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"not_found","details":[],"message":"Sandbox or process not found","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Sandbox or process not found","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"409":{"content":{"application/json":{"examples":{"conflict":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"conflict","details":[],"message":"Request conflicts with the current state","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Sandbox process state conflicts with the request","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"412":{"content":{"application/json":{"examples":{"failed_precondition":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"failed_precondition","details":[],"message":"Process lookup precondition failed","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Process lookup precondition failed","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"429":{"content":{"application/json":{"examples":{"rate_limited":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"rate_limited","details":[],"message":"Runtime request rate limited","request_id":null,"retryable":true}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Runtime request rate limited","headers":{"Retry-After":{"description":"Wait this many whole seconds before retrying (minimum 1, rounded up; not an HTTP date). Not every 429 or 503 includes this header. When absent, start with a one-second delay and double it with jitter.","schema":{"minimum":1,"type":"integer"}},"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"500":{"content":{"application/json":{"examples":{"internal":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"internal","details":[],"message":"Internal server error","request_id":null,"retryable":true}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Process lookup failed internally","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"503":{"content":{"application/json":{"examples":{"service_unavailable":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"service_unavailable","details":[],"message":"The operation is temporarily unavailable","request_id":null,"retryable":true}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Sandbox runtime unavailable","headers":{"Retry-After":{"description":"Wait this many whole seconds before retrying (minimum 1, rounded up; not an HTTP date). Not every 429 or 503 includes this header. When absent, start with a one-second delay and double it with jitter.","schema":{"minimum":1,"type":"integer"}},"x-request-id":{"$ref":"#/components/headers/RequestId"}}}},"summary":"Get a process","x-space-m1-status":"m1-supported"},"parameters":[{"in":"path","name":"sandbox_id","required":true,"schema":{"pattern":"^sbx_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","type":"string"}},{"in":"path","name":"process_id","required":true,"schema":{"maxLength":128,"minLength":1,"pattern":"^[^\\u0000]+$","type":"string","x-space-max-utf8-bytes":128}}]},"/sandboxes/{sandbox_id}/processes/{process_id}:kill":{"parameters":[{"in":"path","name":"sandbox_id","required":true,"schema":{"pattern":"^sbx_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","type":"string"}},{"in":"path","name":"process_id","required":true,"schema":{"maxLength":128,"minLength":1,"pattern":"^[^\\u0000]+$","type":"string","x-space-max-utf8-bytes":128}}],"post":{"description":"Kill the identified process; no request body is needed. Use the opaque process_id returned by the command or process list, not the guest's numeric pid. HTTP 200 with {\"ok\":true} means the runtime accepted the action, not that the process exited. No operation handle is returned; observe the command's stream for its exit result. This endpoint does not deduplicate with Idempotency-Key. Inspect the outcome before repeating an ambiguous request.","operationId":"killProcess","responses":{"200":{"content":{"application/json":{"examples":{"illustrative":{"description":"Illustrative response with synthetic IDs and timestamps. The token placeholder is not a credential; use values returned by your deployment.","value":{"ok":true}}},"schema":{"$ref":"#/components/schemas/ProcessMutationResponse"}}},"description":"Process action applied","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"content":{"application/json":{"examples":{"invalid_request":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"invalid_request","details":[],"message":"Invalid sandbox id, process id, or signal","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Invalid sandbox id, process id, or signal","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"401":{"content":{"application/json":{"examples":{"unauthorized":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"unauthorized","details":[],"message":"Authentication required","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Authentication required","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"403":{"content":{"application/json":{"examples":{"forbidden":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"forbidden","details":[],"message":"Caller or runtime refused the action","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Caller or runtime refused the action","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"404":{"content":{"application/json":{"examples":{"not_found":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"not_found","details":[],"message":"Sandbox or process not found","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Sandbox or process not found","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"409":{"content":{"application/json":{"examples":{"conflict":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"conflict","details":[],"message":"Request conflicts with the current state","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Process state conflicts with the action","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"412":{"content":{"application/json":{"examples":{"failed_precondition":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"failed_precondition","details":[],"message":"Process action precondition failed","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Process action precondition failed","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"429":{"content":{"application/json":{"examples":{"rate_limited":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"rate_limited","details":[],"message":"Runtime request rate limited","request_id":null,"retryable":true}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Runtime request rate limited","headers":{"Retry-After":{"description":"Wait this many whole seconds before retrying (minimum 1, rounded up; not an HTTP date). Not every 429 or 503 includes this header. When absent, start with a one-second delay and double it with jitter.","schema":{"minimum":1,"type":"integer"}},"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"500":{"content":{"application/json":{"examples":{"internal":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"internal","details":[],"message":"Internal server error","request_id":null,"retryable":true}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Process action failed internally","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"503":{"content":{"application/json":{"examples":{"service_unavailable":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"service_unavailable","details":[],"message":"The operation is temporarily unavailable","request_id":null,"retryable":true}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Sandbox runtime unavailable","headers":{"Retry-After":{"description":"Wait this many whole seconds before retrying (minimum 1, rounded up; not an HTTP date). Not every 429 or 503 includes this header. When absent, start with a one-second delay and double it with jitter.","schema":{"minimum":1,"type":"integer"}},"x-request-id":{"$ref":"#/components/headers/RequestId"}}}},"summary":"Kill a process","x-space-m1-status":"m1-supported"}},"/sandboxes/{sandbox_id}/processes/{process_id}:signal":{"parameters":[{"in":"path","name":"sandbox_id","required":true,"schema":{"pattern":"^sbx_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","type":"string"}},{"in":"path","name":"process_id","required":true,"schema":{"maxLength":128,"minLength":1,"pattern":"^[^\\u0000]+$","type":"string","x-space-max-utf8-bytes":128}}],"post":{"description":"Send a Unix signal using JSON such as {\"signal\":15}; valid signal numbers are 1 through 64. Use the opaque process_id returned by the command or process list, not the guest's numeric pid. HTTP 200 with {\"ok\":true} means the runtime accepted the action, not that the process exited. No operation handle is returned; observe the command's stream for its exit result. This endpoint does not deduplicate with Idempotency-Key. Do not blindly retry an ambiguous outcome: a repeated request may deliver the signal again.","operationId":"signalProcess","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProcessSignalRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"examples":{"illustrative":{"description":"Illustrative response with synthetic IDs and timestamps. The token placeholder is not a credential; use values returned by your deployment.","value":{"ok":true}}},"schema":{"$ref":"#/components/schemas/ProcessMutationResponse"}}},"description":"Process action applied","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"content":{"application/json":{"examples":{"invalid_request":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"invalid_request","details":[],"message":"Invalid sandbox id, process id, or signal","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Invalid sandbox id, process id, or signal","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"401":{"content":{"application/json":{"examples":{"unauthorized":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"unauthorized","details":[],"message":"Authentication required","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Authentication required","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"403":{"content":{"application/json":{"examples":{"forbidden":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"forbidden","details":[],"message":"Caller or runtime refused the action","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Caller or runtime refused the action","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"404":{"content":{"application/json":{"examples":{"not_found":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"not_found","details":[],"message":"Sandbox or process not found","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Sandbox or process not found","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"409":{"content":{"application/json":{"examples":{"conflict":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"conflict","details":[],"message":"Request conflicts with the current state","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Process state conflicts with the action","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"412":{"content":{"application/json":{"examples":{"failed_precondition":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"failed_precondition","details":[],"message":"Process action precondition failed","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Process action precondition failed","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"413":{"content":{"application/json":{"examples":{"invalid_request":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"invalid_request","details":[],"message":"Request body is too large","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Request body is too large","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"415":{"content":{"application/json":{"examples":{"invalid_request":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"invalid_request","details":[],"message":"Content-Type must be application/json","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Content-Type must be application/json","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"429":{"content":{"application/json":{"examples":{"rate_limited":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"rate_limited","details":[],"message":"Runtime request rate limited","request_id":null,"retryable":true}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Runtime request rate limited","headers":{"Retry-After":{"description":"Wait this many whole seconds before retrying (minimum 1, rounded up; not an HTTP date). Not every 429 or 503 includes this header. When absent, start with a one-second delay and double it with jitter.","schema":{"minimum":1,"type":"integer"}},"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"500":{"content":{"application/json":{"examples":{"internal":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"internal","details":[],"message":"Internal server error","request_id":null,"retryable":true}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Process action failed internally","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"503":{"content":{"application/json":{"examples":{"service_unavailable":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"service_unavailable","details":[],"message":"The operation is temporarily unavailable","request_id":null,"retryable":true}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Sandbox runtime unavailable","headers":{"Retry-After":{"description":"Wait this many whole seconds before retrying (minimum 1, rounded up; not an HTTP date). Not every 429 or 503 includes this header. When absent, start with a one-second delay and double it with jitter.","schema":{"minimum":1,"type":"integer"}},"x-request-id":{"$ref":"#/components/headers/RequestId"}}}},"summary":"Send a Unix signal to a process","x-space-m1-status":"m1-supported"}},"/sandboxes/{sandbox_id}:pause":{"parameters":[{"in":"path","name":"sandbox_id","required":true,"schema":{"pattern":"^sbx_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","type":"string"}}],"post":{"description":"Freezes the sandbox in memory without releasing its resources. Use suspend to release resources, or wake to return to running.","operationId":"pauseSandbox","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"description":"1 to 1024 printable ASCII characters, spaces or tabs.","maxLength":1024,"minLength":1,"pattern":"^[\\t -~]+$","type":"string","x-space-max-utf8-bytes":1024}}],"responses":{"202":{"content":{"application/json":{"examples":{"illustrative":{"description":"Illustrative response with synthetic IDs and timestamps. The token placeholder is not a credential; use values returned by your deployment.","value":{"operation_id":"op_00000000-0000-0000-0000-000000000000","sandbox_id":"sbx_00000000-0000-0000-0000-000000000000"}}},"schema":{"$ref":"#/components/schemas/SandboxOperationResponse"}}},"description":"Sandbox lifecycle operation accepted","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"content":{"application/json":{"examples":{"invalid_request":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"invalid_request","details":[],"message":"Invalid sandbox id, idempotency key, or action body","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Invalid sandbox id, idempotency key, or action body","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"401":{"content":{"application/json":{"examples":{"unauthorized":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"unauthorized","details":[],"message":"Authentication required","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Authentication required","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"404":{"content":{"application/json":{"examples":{"not_found":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"not_found","details":[],"message":"Sandbox not found","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Sandbox not found","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"409":{"content":{"application/json":{"examples":{"conflict":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"conflict","details":[],"message":"Request conflicts with the current state","request_id":null,"retryable":false}},"idempotency_conflict":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"idempotency_conflict","details":[],"message":"Idempotency key was used with a different request","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Idempotency key was reused with a different request","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"500":{"content":{"application/json":{"examples":{"internal":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"internal","details":[],"message":"Internal server error","request_id":null,"retryable":true}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Internal server error","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"503":{"content":{"application/json":{"examples":{"capacity_unavailable":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"capacity_unavailable","details":[],"message":"Sandbox capacity is temporarily unavailable","request_id":null,"retryable":true}},"service_unavailable":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"service_unavailable","details":[],"message":"The operation is temporarily unavailable","request_id":null,"retryable":true}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Sandbox operation is temporarily unavailable","headers":{"Retry-After":{"description":"Wait this many whole seconds before retrying (minimum 1, rounded up; not an HTTP date). Not every 429 or 503 includes this header. When absent, start with a one-second delay and double it with jitter.","schema":{"minimum":1,"type":"integer"}},"x-request-id":{"$ref":"#/components/headers/RequestId"}}}},"summary":"Pause a sandbox","x-space-m1-status":"m1-supported"}},"/sandboxes/{sandbox_id}:suspend":{"parameters":[{"in":"path","name":"sandbox_id","required":true,"schema":{"pattern":"^sbx_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","type":"string"}}],"post":{"description":"Saves the sandbox's memory and state, then releases its resources. Use wake to return to running.","operationId":"suspendSandbox","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"description":"1 to 1024 printable ASCII characters, spaces or tabs.","maxLength":1024,"minLength":1,"pattern":"^[\\t -~]+$","type":"string","x-space-max-utf8-bytes":1024}}],"responses":{"202":{"content":{"application/json":{"examples":{"illustrative":{"description":"Illustrative response with synthetic IDs and timestamps. The token placeholder is not a credential; use values returned by your deployment.","value":{"operation_id":"op_00000000-0000-0000-0000-000000000000","sandbox_id":"sbx_00000000-0000-0000-0000-000000000000"}}},"schema":{"$ref":"#/components/schemas/SandboxOperationResponse"}}},"description":"Sandbox lifecycle operation accepted","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"content":{"application/json":{"examples":{"invalid_request":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"invalid_request","details":[],"message":"Invalid sandbox id, idempotency key, or action body","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Invalid sandbox id, idempotency key, or action body","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"401":{"content":{"application/json":{"examples":{"unauthorized":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"unauthorized","details":[],"message":"Authentication required","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Authentication required","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"404":{"content":{"application/json":{"examples":{"not_found":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"not_found","details":[],"message":"Sandbox not found","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Sandbox not found","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"409":{"content":{"application/json":{"examples":{"conflict":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"conflict","details":[],"message":"Request conflicts with the current state","request_id":null,"retryable":false}},"idempotency_conflict":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"idempotency_conflict","details":[],"message":"Idempotency key was used with a different request","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Idempotency key was reused with a different request","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"500":{"content":{"application/json":{"examples":{"internal":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"internal","details":[],"message":"Internal server error","request_id":null,"retryable":true}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Internal server error","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"503":{"content":{"application/json":{"examples":{"capacity_unavailable":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"capacity_unavailable","details":[],"message":"Sandbox capacity is temporarily unavailable","request_id":null,"retryable":true}},"service_unavailable":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"service_unavailable","details":[],"message":"The operation is temporarily unavailable","request_id":null,"retryable":true}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Sandbox operation is temporarily unavailable","headers":{"Retry-After":{"description":"Wait this many whole seconds before retrying (minimum 1, rounded up; not an HTTP date). Not every 429 or 503 includes this header. When absent, start with a one-second delay and double it with jitter.","schema":{"minimum":1,"type":"integer"}},"x-request-id":{"$ref":"#/components/headers/RequestId"}}}},"summary":"Suspend a sandbox","x-space-m1-status":"m1-supported"}},"/sandboxes/{sandbox_id}:wake":{"parameters":[{"in":"path","name":"sandbox_id","required":true,"schema":{"pattern":"^sbx_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","type":"string"}}],"post":{"description":"Returns a sandbox to running by whichever path is valid for its current state: start, resume, or restore. Use this when the caller does not need to know which. When a wake for the sandbox is already pending, with nothing else for the sandbox queued after it, the response names that operation instead of queuing another if it is the caller's own, queued or running, or one a command or process session queued that has not started and no other caller has joined.","operationId":"wakeSandbox","parameters":[{"in":"header","name":"Idempotency-Key","required":true,"schema":{"description":"1 to 1024 printable ASCII characters, spaces or tabs.","maxLength":1024,"minLength":1,"pattern":"^[\\t -~]+$","type":"string","x-space-max-utf8-bytes":1024}}],"responses":{"202":{"content":{"application/json":{"examples":{"illustrative":{"description":"Illustrative response with synthetic IDs and timestamps. The token placeholder is not a credential; use values returned by your deployment.","value":{"operation_id":"op_00000000-0000-0000-0000-000000000000","sandbox_id":"sbx_00000000-0000-0000-0000-000000000000"}}},"schema":{"$ref":"#/components/schemas/SandboxOperationResponse"}}},"description":"Sandbox lifecycle operation accepted","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"400":{"content":{"application/json":{"examples":{"invalid_request":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"invalid_request","details":[],"message":"Invalid sandbox id, idempotency key, or action body","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Invalid sandbox id, idempotency key, or action body","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"401":{"content":{"application/json":{"examples":{"unauthorized":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"unauthorized","details":[],"message":"Authentication required","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Authentication required","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"404":{"content":{"application/json":{"examples":{"not_found":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"not_found","details":[],"message":"Sandbox not found","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Sandbox not found","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"409":{"content":{"application/json":{"examples":{"conflict":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"conflict","details":[],"message":"Request conflicts with the current state","request_id":null,"retryable":false}},"idempotency_conflict":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"idempotency_conflict","details":[],"message":"Idempotency key was used with a different request","request_id":null,"retryable":false}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Idempotency key was reused with a different request","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"500":{"content":{"application/json":{"examples":{"internal":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"internal","details":[],"message":"Internal server error","request_id":null,"retryable":true}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Internal server error","headers":{"x-request-id":{"$ref":"#/components/headers/RequestId"}}},"503":{"content":{"application/json":{"examples":{"capacity_unavailable":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"capacity_unavailable","details":[],"message":"Sandbox capacity is temporarily unavailable","request_id":null,"retryable":true}},"service_unavailable":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"code":"service_unavailable","details":[],"message":"The operation is temporarily unavailable","request_id":null,"retryable":true}}},"schema":{"$ref":"#/components/schemas/PublicErrorEnvelope"}}},"description":"Sandbox operation is temporarily unavailable","headers":{"Retry-After":{"description":"Wait this many whole seconds before retrying (minimum 1, rounded up; not an HTTP date). Not every 429 or 503 includes this header. When absent, start with a one-second delay and double it with jitter.","schema":{"minimum":1,"type":"integer"}},"x-request-id":{"$ref":"#/components/headers/RequestId"}}}},"summary":"Wake a sandbox","x-space-m1-status":"m1-supported"}},"/sessions/{session_id}/events":{"get":{"description":"Streams output from process or file-watch sessions.\n\n### Connect\n\n- Use the session token, not your management API token. Send it in `Authorization: Bearer ...` or `Sec-WebSocket-Protocol`; query-string tokens are rejected.\n- SSE `id`s increase. Every file-watch frame after `attached` has one. On a process stream only `stdout`, `stderr` and `resync_required` frames do; other frames carry none, so the last `id` received stays the one to resume from.\n- Echo the `id` exactly as received: process stream ids are not consecutive. They stay below 2^53, so a JavaScript `Number` holds them exactly.\n\n### Reconnect\n\n- Send the last received `id` as `Last-Event-ID`. An `id` is only valid for the session whose stream sent it.\n- A process stream resumes with the output after that frame while the sandbox retains it, a bounded amount per process. Without `Last-Event-ID` it starts from the beginning of the output, which can repeat output already received.\n- When the output to resume from is no longer retained, the stream sends `resync_required` with reason `cursor_out_of_window`, then continues with the oldest output still retained (with live output on sandboxes from older templates). When `Last-Event-ID` is past the process's output, it sends the same frame and replays the output from its start. Keep output already received.\n- An `id` that does not resume exactly (one from an earlier SPACE version, one altered in transit, or one sent after the stream replayed the output from its start behind `cursor_out_of_window` or continued with live output) replays the retained output behind `resync_required` with reason `cursor_replay_unavailable`.\n- Every `id` a resumed process stream sends is above `Last-Event-ID`.\n- Process stream ids carry the output position for a process's first 2^33 - 1 output chunks (about 8.6 billion; some 99 days at 1,000 separate writes a second). After that, each resume replays the output still retained behind `resync_required`.\n- If the process exited while disconnected, reconnecting still reports `process_exited`.\n- A file-watch stream resumes live: its first identified frame is `resync_required`, with reason `cursor_replay_unavailable` and id `Last-Event-ID + 1`. Re-list the watched path before using new events.","operationId":"streamSessionEvents","parameters":[{"description":"SSE `id` of the last frame received.\n\n- Echo the `id` exactly as received, on the same session's stream.\n- A process stream resumes with the output after that frame while it is retained; otherwise `resync_required` precedes the output it continues with: `cursor_out_of_window` when the output is evicted or the `id` is past it, `cursor_replay_unavailable` when the `id` does not resume exactly.\n- A file-watch stream resumes live; its first identified frame is `resync_required` (`cursor_replay_unavailable`), with id `Last-Event-ID + 1`.\n- Values above the `int64` maximum, and process stream values too high to number a later frame above, return 400.","in":"header","name":"Last-Event-ID","required":false,"schema":{"format":"int64","maximum":9223372036854775807,"minimum":0,"type":"integer"}}],"responses":{"200":{"content":{"text/event-stream":{"schema":{"type":"string"},"x-space-sse-event-data-schema":{"$ref":"#/components/schemas/DataPlaneServerFrame"}}},"description":"### Read the stream\n\n- Each SSE event carries one `DataPlaneServerFrame` JSON object. Ignore comment heartbeats.\n- Decode stdout and stderr's `data_base64` using standard base64.\n- Success requires `process_exited` with exit code zero and no error or missing output. HTTP 200 or a closed stream alone is not success.\n\n### Example output\n\nExcerpt, not a complete stream:\n\n```text\nid: 4503599627632640\nevent: stdout\ndata: {\"type\":\"stdout\",\"seq\":1,\"data_base64\":\"SGVsbG8gZnJvbSBTUEFDRQo=\"}\n\nevent: process_exited\ndata: {\"type\":\"process_exited\",\"process_id\":\"proc_00000000-0000-0000-0000-000000000000\",\"exit_code\":0,\"status\":\"exited\"}\n\n```","headers":{"Cache-Control":{"description":"Disables intermediary caching for the live event stream.","schema":{"const":"no-cache","type":"string"}}}},"400":{"content":{"application/json":{"examples":{"invalid_request":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"error":{"code":"invalid_request","message":"Invalid session id, session kind, token transport, or Last-Event-ID, or a pty process session that has not started","retryable":false}}}},"schema":{"$ref":"#/components/schemas/DataPlaneHttpErrorEnvelope"}}},"description":"Invalid session id, session kind, token transport, or Last-Event-ID, or a pty process session that has not started"},"401":{"content":{"application/json":{"examples":{"unauthorized":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"error":{"code":"unauthorized","message":"Missing, invalid, or expired data-plane token","retryable":false}}}},"schema":{"$ref":"#/components/schemas/DataPlaneHttpErrorEnvelope"}}},"description":"Missing, invalid, or expired data-plane token"},"403":{"content":{"application/json":{"examples":{"forbidden":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"error":{"code":"forbidden","message":"Token does not authorize this session","retryable":false}}}},"schema":{"$ref":"#/components/schemas/DataPlaneHttpErrorEnvelope"}}},"description":"Token does not authorize this session"},"404":{"content":{"application/json":{"examples":{"not_found":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"error":{"code":"not_found","message":"Session not found","retryable":false}}}},"schema":{"$ref":"#/components/schemas/DataPlaneHttpErrorEnvelope"}}},"description":"Session not found"},"409":{"content":{"application/json":{"examples":{"conflict":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"error":{"code":"conflict","message":"Process session is already attached (retryable), or the sandbox is not running and this command cannot wake it (not retryable; `details` as on createCommand's conflict). The same 409 answers whether the node refused to start the command or the sandbox has no node and nothing is about to wake it. Over WebSocket the same refusal is an `error` frame with code `backend_stream_error` and the same `details`: branch on `details` `reason` (`sandbox_not_running`), not on the code","retryable":true}}}},"schema":{"$ref":"#/components/schemas/DataPlaneHttpErrorEnvelope"}}},"description":"Process session is already attached (retryable), or the sandbox is not running and this command cannot wake it (not retryable; `details` as on createCommand's conflict). The same 409 answers whether the node refused to start the command or the sandbox has no node and nothing is about to wake it. Over WebSocket the same refusal is an `error` frame with code `backend_stream_error` and the same `details`: branch on `details` `reason` (`sandbox_not_running`), not on the code"},"429":{"content":{"application/json":{"examples":{"rate_limited":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"error":{"code":"rate_limited","message":"Attached-stream limit exceeded","retryable":true}}}},"schema":{"$ref":"#/components/schemas/DataPlaneHttpErrorEnvelope"}}},"description":"Attached-stream limit exceeded"},"500":{"content":{"application/json":{"examples":{"internal":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"error":{"code":"internal","message":"Session route state is invalid","retryable":false}}}},"schema":{"$ref":"#/components/schemas/DataPlaneHttpErrorEnvelope"}}},"description":"Session route state is invalid"},"503":{"content":{"application/json":{"examples":{"not_ready":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"error":{"code":"not_ready","message":"Session route or backend stream is unavailable. `not_ready` is retryable, with `Retry-After`: something is about to give the sandbox a node. It is heading to running, or a start, resume, restore or wake is queued for it, such as the wake a command queued. Attaching to a sandbox at rest queues one when its `auto_lifecycle.wake.on` allows the attach: `command` or `access` for the first attach, which starts the command, and `access` for a reattach to a command that already started. A sandbox at rest that nothing is about to wake answers the 409 `sandbox_not_running` conflict instead","retryable":true}}},"service_unavailable":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"error":{"code":"service_unavailable","message":"Session route or backend stream is unavailable. `not_ready` is retryable, with `Retry-After`: something is about to give the sandbox a node. It is heading to running, or a start, resume, restore or wake is queued for it, such as the wake a command queued. Attaching to a sandbox at rest queues one when its `auto_lifecycle.wake.on` allows the attach: `command` or `access` for the first attach, which starts the command, and `access` for a reattach to a command that already started. A sandbox at rest that nothing is about to wake answers the 409 `sandbox_not_running` conflict instead","retryable":true}}},"stream_unavailable":{"description":"Illustrative, not exhaustive. Messages can change. Use the returned retryable flag, not this example, to decide whether to retry.","value":{"error":{"code":"stream_unavailable","message":"Session route or backend stream is unavailable. `not_ready` is retryable, with `Retry-After`: something is about to give the sandbox a node. It is heading to running, or a start, resume, restore or wake is queued for it, such as the wake a command queued. Attaching to a sandbox at rest queues one when its `auto_lifecycle.wake.on` allows the attach: `command` or `access` for the first attach, which starts the command, and `access` for a reattach to a command that already started. A sandbox at rest that nothing is about to wake answers the 409 `sandbox_not_running` conflict instead","retryable":true}}}},"schema":{"$ref":"#/components/schemas/DataPlaneHttpErrorEnvelope"}}},"description":"Session route or backend stream is unavailable. `not_ready` is retryable, with `Retry-After`: something is about to give the sandbox a node. It is heading to running, or a start, resume, restore or wake is queued for it, such as the wake a command queued. Attaching to a sandbox at rest queues one when its `auto_lifecycle.wake.on` allows the attach: `command` or `access` for the first attach, which starts the command, and `access` for a reattach to a command that already started. A sandbox at rest that nothing is about to wake answers the 409 `sandbox_not_running` conflict instead"}},"security":[{"dataPlaneToken":[]},{"dataPlaneWebSocketProtocol":[]}],"summary":"Stream process output or file-watch events over SSE","x-space-m1-status":"m1-supported"},"parameters":[{"in":"path","name":"session_id","required":true,"schema":{"pattern":"^(term|proc|watch|port|proto)_[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$","type":"string"}}]}},"security":[{"apiKey":[]}],"servers":[{"url":"/v1"},{"description":"Shared-host public API root","url":"/api/v1"},{"description":"Data-plane host for WebSocket attach and proxy sessions","url":"/v1"}]}