---
title: "Resize a workspace: memory, its allocation mode, CPU and disk, running or suspended"
method: PATCH
path: "/v1/workspaces/{workspace_id}/caps"
tags: ["Workspaces"]
---

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

`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

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.

## Path parameters

- `workspace_id` string, uuid, required

## Headers

- `prefer` string

## Request body

- ResizeWorkspaceBody: At least one field. Each given value replaces the stored one; omitted fields keep theirs.
  - `memory_mib` integer: 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_held` integer: 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_millis` integer: CPU (millicores). Bounded by the plan and the template.
  - `disk_gib` integer: Disk (GiB). Grow only. With at_least, a smaller or equal disk is unchanged. Bounded by the plan and the template.
  - `at_least` boolean: Only increase each named numeric resource; values at or below its current configured size leave it unchanged. The explicit allocation mode still switches.

## Response `200`

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.

- ResizeResult: 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_id` string, uuid, required: UUIDv7, lowercase canonical form.
  - `operation_id` string, uuid, required: UUIDv7, lowercase canonical form.
  - `state` string, required: The workspace state the resize found (running, suspended, ...).
  - `memory` object
    - `applies_at` 'now' | 'resume' | 'next_start', required: now: live; resume: right after the next resume, before its first call; next_start: at the next start that boots the workspace.
    - `allocation_mode` 'fixed' | 'elastic', required: The memory layout after the resize.
    - `requested_mib` integer, nullable, required: memory_mib as sent (null when only the mode or the held floor was sent).
    - `target_mib` integer, nullable, required: The size (fixed) or the maximum (elastic) the workspace gets.
    - `previous_mib` integer, nullable, required: The size or maximum before the resize.
    - `applied_mib` integer, nullable, required: What is live after the call (null when no VM runs).
    - `held_mib` integer, nullable, required: Elastic: the held floor; null for fixed.
    - `converged` boolean, nullable, required: A live change reached the guest (null when nothing ran).
    - `limit_reason` 'plan' | 'template' | 'host_capacity' | 'shrink_stalled', nullable, required: Why the target or the applied value is below what was requested: plan or template (bounded like caps at open), host_capacity (the rest did not fit on the host at once), shrink_stalled (the guest kept the memory its processes use).
    - `reason` 'region' | 'below_base' | 'legacy_layout' | 'boot_vcpus' | 'suspended' | 'stopped', nullable, required: Why it does not apply now (null when it does).
  - `cpu` object
    - `applies_at` 'now' | 'resume' | 'next_start', required: now: live; resume: right after the next resume, before its first call; next_start: at the next start that boots the workspace.
    - `requested_millis` integer, nullable, required: cpu_millis as sent.
    - `target_millis` integer, nullable, required: The CPU the workspace gets.
    - `previous_millis` integer, nullable, required: The CPU before the resize.
    - `applied_millis` integer, nullable, required: What is live after the call (null when no VM runs).
    - `limit_reason` 'plan' | 'template' | 'host_capacity' | 'shrink_stalled', nullable, required: Why the target or the applied value is below what was requested: plan or template (bounded like caps at open), host_capacity (the rest did not fit on the host at once), shrink_stalled (the guest kept the memory its processes use).
    - `reason` 'region' | 'below_base' | 'legacy_layout' | 'boot_vcpus' | 'suspended' | 'stopped', nullable, required: Why it does not apply now (null when it does).
  - `disk` object
    - `applies_at` 'now' | 'resume' | 'next_start', required: now: live; resume: right after the next resume, before its first call; next_start: at the next start that boots the workspace.
    - `requested_gib` integer, nullable, required: disk_gib as sent.
    - `target_gib` integer, nullable, required: The disk size the workspace gets.
    - `previous_gib` integer, nullable, required: The disk size before the resize.
    - `applied_gib` integer, nullable, required: What is live after the call (null when no VM runs).
    - `limit_reason` 'plan' | 'template' | 'host_capacity' | 'shrink_stalled', nullable, required: Why the target or the applied value is below what was requested: plan or template (bounded like caps at open), host_capacity (the rest did not fit on the host at once), shrink_stalled (the guest kept the memory its processes use).
    - `reason` 'region' | 'below_base' | 'legacy_layout' | 'boot_vcpus' | 'suspended' | 'stopped', nullable, required: Why it does not apply now (null when it does).
  - `caps` object, required: CPU and memory user caps (null = no user restriction), the effective disk cap, and the memory allocation mode.
    - `cpu_millis` integer, nullable, required
    - `memory_mib` integer, nullable, required
    - `disk_gib` integer, nullable, required: Requested disk cap (GiB), bounded by the admitted plan/template ceiling and acknowledged VM disk. Null means no user disk restriction.
    - `allocation_mode` 'fixed' | 'elastic', required: Memory allocation: fixed (default) boots memory_mib and holds it; elastic holds memory_mib_held while idle and is grown up to memory_mib (the promise) when a command needs it. The mode the next VM start uses: an elastic request whose promise does not exceed the held floor by at least 512 MiB is fixed at the promise.
    - `memory_mib_held` integer: Elastic only: the memory held while idle (MiB).

## Other responses

- `202`: Default Response
- `4XX`: Default Response
- `5XX`: Default Response

---

[API](https://skmtc.dev/shardflux/apis/shardflux-api.md) · [All operations](https://skmtc.dev/shardflux/apis/shardflux-api/llms.txt) · [OpenAPI document](https://skmtc.dev/shardflux/apis/shardflux-api/revisions/ea685f7b39c4?raw)