Open a workspace by key (create on first use, reconnect or resume afterwards)

like names a live workspace ID or key in the caller’s project; a new key inherits its exact template version, caps, inputs, secrets, volumes, idle policy and agent options on a fresh disk. Explicit caps, inputs, secrets, volumes and policy override the inherited values. volumes supplied replaces the set, omitted retains it. Replacement returns 202 with one normal volume_attach/volume_detach operation at a time; after it succeeds repeat open with the same set and a fresh Idempotency-Key until ready. SDKs do this when waiting. New keys resolve template to its latest published version; reopening never changes or resets the workspace (the response reports the template version actually used). 200 when the workspace is already running and ready (with cell_endpoint and a tool token); otherwise 202 with the operation to poll. A running workspace whose startup failed (startup.state failed) is not ready: the open is 202 with an open operation (input.startup_retry) that runs the failed step again. Concurrent opens of one key share one workspace and one operation. secrets (optional) binds secret names injected into every exec/PTY start: it sets the binding of a new key and replaces it on an existing key (omitted = unchanged); an unknown or unusable name is 422 details.reason secret_not_available with details.names (nothing is created or changed). The template version’s secret inputs join the binding on create and whenever secrets is given; a required one this workspace may not use is 422 input_required (details.kind secret); a bound name equal to a template env key or text input is 422 env_collision (details.name). inputs (optional): the version’s text inputs {NAME: string}; stored on create (else the declared default) and replaced on an existing key (omitted = unchanged); 422 input_unknown, input_invalid or input_required (details.names). lifetime: omitted = the version’s default (else persistent); session workspaces are discarded when the session ends (close(), idle timeout), after which the key opens a NEW workspace; reopening a live key with another lifetime is 409 lifetime_mismatch. A new workspace is layered when its version supports it and layered opens are enabled (disk_layout). Errors: 404 template/key outside scope, 402 entitlement_required, 403 quota_exceeded (details.limit retained_state), 429 quota_exceeded (details.limit concurrent_workspaces; see below), 409 operation in progress, key whose deletion is still in progress (workspace_deleted) or lifetime_mismatch, 422 reserved_key_prefix (keys starting with sf:). Supports Idempotency-Key. Held open: with Prefer: wait=<seconds> (at most 20) an open whose outcome is an operation is held until the operation is terminal or the wait elapses; success answers 200 with the running workspace, the succeeded operation and a tool token (Preference-Applied: wait=<seconds>), anything else 202 with the fresh operation. Without Preference-Applied the server did not wait: poll the operation. mode: omitted = processful for a new key and the stored mode for an existing one; file_first creates a workspace whose state is a versioned file tree with no VM between executions: it is ready at once (200 with a tool token, observed_state running, tree_revision 0, no operation), needs a layered template version (409 layout_unsupported otherwise) and is persistent (lifetime: session or idle_policy with it are 422 not_supported_for_mode); each open of a file-first key re-resolves the size of its execution VMs from caps, the template and the plan. 422 mode_not_available while the deployment does not offer file-first workspaces; reopening a key with another mode is 409 mode_mismatch. tool_token is null when the principal’s tool-token rate limit is used up: the open still succeeds, and the client fetches a token from POST /workspaces/{id}/tool-tokens. Plan concurrency: a start the plan’s concurrent_workspaces limit refuses is queued on the request (up to 10 s) and admitted as soon as one of the organization’s workspaces frees; if none does, 429 quota_exceeded with Retry-After: 2 (retryable; details limit concurrent_workspaces, limit_value, current, retry_after_seconds, plan). Nothing was created: retry after Retry-After, with the same Idempotency-Key or a new one. With Prefer: wait the queued time counts against the wait. Memory allocation: caps.allocation_mode elastic with caps.memory_mib_held; 422 validation_failed details.field caps.allocation_mode reason allocation_mode_not_available (the organization lacks elastic memory; nothing is created or changed), reason not_supported_for_mode (file_first); details.field caps.memory_mib_held reason requires_elastic (held without elastic) or exceeds_memory_mib (held above caps.memory_mib).