Skip to main content
PATCH
Set or clear a volume's storage cap

Authorizations

Authorization
string
header
required

Organization API key (msb_…) - org-scoped programmatic access.

Path Parameters

id
string<uuid>
required

Volume id

Body

application/json

PATCH /v1/orgs/{slug}/volumes/{id} - update the cap and/or labels (#496).

Every field is independently optional: an omitted field is left unchanged. capacity_gib uses the double-Option distinction - omit to leave as-is, explicit null to clear the cap, a number to set it.

capacity_gib
integer<int32> | null

New per-volume storage cap in GiB. Omitted = unchanged; null = clear the cap (back to no per-volume limit); a value sets it. A set value must be >= 1 and <= the org's storage cap.

Required range: x >= 0
labels
object | null

Replacement label set. Omitted = unchanged; an object replaces the labels wholesale (an empty object clears them). Reserved-prefix keys are rejected.

Response

Volume updated

Volume metadata returned in list/create responses. The GCS storage path is derived (not stored) and never exposed.

created_at
string<date-time>
required
id
string<uuid>
required
kind
enum<string>
required

host - the org's shared host disk (not deletable); managed - a user-created named volume.

Available options:
host,
managed
labels
object
required

User-defined labels (empty object when none set).

status
enum<string>
required

Lifecycle status of a volume.

Available options:
active,
deleting
storage
enum<string>
required

How the volume is physically backed (block today).

Available options:
block
updated_at
string<date-time>
required
capacity_bytes
integer<int64> | null

The volume's configured per-volume storage cap in bytes, or null when no cap is set (#496). Derived from the stored capacity_gib (the user's configured intent) - the effective ceiling is min(this, org cap).

Required range: x >= 0
name
string | null

User-facing name. null for the host volume (it has no name; it's identified by kind).

used_bytes
integer<int64> | null

Bytes currently used under this volume's subtree. null when usage is unavailable - the usage service is disabled or unreachable (list degrades gracefully rather than failing) - or on create/delete, which don't sample it.

Required range: x >= 0