---
title: "PATCH /v1/orgs/:slug/volumes/:id — set or clear a volume's storage cap (Admin+)."
method: PATCH
path: "/v1/orgs/{slug}/volumes/{id}"
tags: ["volumes"]
---

# PATCH /v1/orgs/:slug/volumes/:id — set or clear a volume's storage cap (Admin+).

`PATCH /v1/orgs/{slug}/volumes/{id}`

## Path parameters

- `slug` string, required
- `id` string, uuid, required

## Request body

- UpdateVolumeRequest — 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, nullable — 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`.
  - `labels` object, nullable — Replacement label set. Omitted = unchanged; an object replaces the labels wholesale (an empty object clears them). Reserved-prefix keys are rejected.

## Response `200`

Volume updated

- VolumeResponse — Volume metadata returned in list/create responses. The GCS storage path is derived (not stored) and never exposed.
  - `capacity_bytes` integer, nullable — 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)`.
  - `created_at` string, date-time, required
  - `id` string, uuid, required
  - `kind` 'host' | 'managed', required — What kind of volume this is — its storage source / role. The host volume is the org's single shared "host disk"; managed volumes are user-created, named, platform-provisioned (JuiceFS over our object store). (A future `External` variant — bring-your-own S3/GCS — is intentionally out of scope for now.)
  - `labels` object, required — User-defined labels (empty object when none set).
  - `name` string, nullable — User-facing name. `null` for the host volume (it has no name; it's identified by `kind`).
  - `status` 'active' | 'deleting', required — Lifecycle status of a volume.
  - `storage` 'block', required — How a volume is physically backed — distinct from [`VolumeKind`] (ownership). Every volume is `Block` today; the enum exists so future backings can be added (and reported to the SDK) without another schema change.
  - `updated_at` string, date-time, required
  - `used_bytes` integer, nullable — 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.

## Other responses

- `400` — Invalid request (e.g. cap exceeds the org cap)
- `401` — Unauthorized
- `403` — Insufficient permissions
- `404` — Volume not found
- `409` — The host volume cannot be capped

---

[API](https://skmtc.dev/microsandbox/apis/microsandbox-api.md) · [All operations](https://skmtc.dev/microsandbox/apis/microsandbox-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/microsandbox/microsandbox-api/revisions/23f2a45cb09b/schema)