Workspaces

Resize a workspace: memory, its allocation mode, CPU and disk, running or suspended

Changes the caps of any workspace, fixed or elastic, running or suspended, without restarting or forking it. Each given field replaces the stored one (omitted fields keep theirs); every later start uses the new caps. Each value is bounded like caps at open: by the plan’s per-workspace maximum and the template’s limit (limit_reason plan or template). A running workspace changes live where it can (memory plugged or unplugged, CPU within its boot vCPUs, disk grown online); a suspended one gets the change right after its next resume, before the first call; what cannot apply now says applies_at: next_start and applies at the next start. The request is held until the resize finishes, up to Prefer: wait=<seconds> (default 20, at most 55): 200 ResizeResult (per resource: applies_at now | resume | next_start, requested, target, previous and applied values, limit_reason, reason) with the workspace caps; otherwise 202 with the resize operation, whose result carries the same per-resource fields when it succeeds. A resize that fails answers with its error. Errors (nothing changes): 409 conflict reason resize_not_available (not enabled for the organization), workspace_deleted, operation_in_progress (another lifecycle operation is active; details.active_operation_id, retryable); 422 validation_failed reason not_supported_for_mode (file-first workspace), shrink_not_supported (disk_gib below the current disk; details.current_disk_gib), requires_elastic (memory_mib_held without an elastic mode), exceeds_memory_mib (memory_mib_held above the maximum), allocation_mode_not_available (elastic memory is not available to the organization); 402 as for a start (no plan, new starts on hold). Owners, admins and members, and API keys with a tool permission. Supports Idempotency-Key.

patch/v1/workspaces/{workspace_id}/caps

Request

  • Base URL: https://api.shardflux.dev
  • URL: https://api.shardflux.dev/v1/workspaces/{workspace_id}/caps
  • Auth: HTTP bearer

Path parameters

workspace_idstring uuid required

UUIDv7, lowercase canonical form.

Headers

preferstring

RFC 7240 preference, e.g. wait=30 (at most 55; default 20).

Request body

memory_mibinteger

Memory (MiB): the size of a fixed workspace, the maximum of an elastic one. Bounded by the plan and the template (limit_reason).

memory_mib_heldinteger

Elastic only: the memory held while idle (MiB), at most the maximum.

allocation_mode'fixed' | 'elastic'

fixed: memory_mib is plugged and held; elastic: the workspace holds memory_mib_held and grows to memory_mib when a command needs it.

cpu_millisinteger

CPU (millicores). Bounded by the plan and the template.

disk_gibinteger

Disk (GiB). Grow only. With at_least, a smaller or equal disk is unchanged. Bounded by the plan and the template.

at_leastboolean

Only increase each named numeric resource; values at or below its current configured size leave it unchanged. The explicit allocation mode still switches.

Response

Per resource the request named (allocation_mode and memory_mib_held report under memory): what applied now and what applies later. caps: the workspace caps every later start uses.

workspace_idstring uuid required

UUIDv7, lowercase canonical form.

operation_idstring uuid required

UUIDv7, lowercase canonical form.

statestring required

The workspace state the resize found (running, suspended, ...).

Changes

No recorded changes to this operation across all 1 revision of this API.