> ## Documentation Index > Fetch the complete documentation index at: https://docs.microsandbox.dev/llms.txt > Use this file to discover all available pages before exploring further. # Set or clear a volume's storage cap ## OpenAPI ````yaml /api-reference/openapi.json patch /v1/volumes/{id} openapi: 3.1.0 info: title: microsandbox cloud API description: >- REST API for microsandbox cloud: sandbox and volume lifecycle, organization context, quotas, usage, and audit events, authenticated with an organization API key. version: 0.1.0 servers: - url: https://api.microsandbox.dev security: - api_key: [] paths: /v1/volumes/{id}: patch: tags: - Volumes summary: Set or clear a volume's storage cap operationId: update_volume parameters: - name: id in: path description: Volume id required: true schema: type: string format: uuid requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateVolumeRequest' required: true responses: '200': description: Volume updated content: application/json: schema: $ref: '#/components/schemas/VolumeResponse' '400': description: Invalid request (e.g. cap exceeds the org cap) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: invalid_request message: invalid request details: null '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: invalid_api_key message: unauthorized details: null '404': description: Volume not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: sandbox_not_found message: resource not found details: null '409': description: The host volume cannot be capped content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: invalid_request message: the host volume cannot be capped details: null security: - api_key: [] components: schemas: UpdateVolumeRequest: type: object description: >- 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. properties: capacity_gib: type: - integer - 'null' format: int32 description: >- 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`. minimum: 0 labels: type: - object - 'null' description: >- Replacement label set. Omitted = unchanged; an object replaces the labels wholesale (an empty object clears them). Reserved-prefix keys are rejected. additionalProperties: type: string propertyNames: type: string VolumeResponse: type: object description: >- Volume metadata returned in list/create responses. The GCS storage path is derived (not stored) and never exposed. required: - id - kind - storage - status - labels - created_at - updated_at properties: capacity_bytes: type: - integer - 'null' format: int64 description: >- 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)`. minimum: 0 created_at: type: string format: date-time id: type: string format: uuid kind: $ref: '#/components/schemas/VolumeKind' description: |- `host` - the org's shared host disk (not deletable); `managed` - a user-created named volume. labels: type: object description: User-defined labels (empty object when none set). additionalProperties: type: string propertyNames: type: string name: type: - string - 'null' description: |- User-facing name. `null` for the host volume (it has no name; it's identified by `kind`). status: $ref: '#/components/schemas/VolumeStatus' storage: $ref: '#/components/schemas/VolumeType' description: How the volume is physically backed (`block` today). updated_at: type: string format: date-time used_bytes: type: - integer - 'null' format: int64 description: >- 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. minimum: 0 ErrorResponse: type: object description: Error envelope returned by every non-2xx response. required: - error properties: error: type: object required: - code - message properties: code: type: string description: Stable machine-readable error code, e.g. `invalid_api_key`. message: type: string description: Human-readable description of the error. details: type: - object - 'null' description: Optional structured context for the error. VolumeKind: type: string description: >- 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.) enum: - host - managed VolumeStatus: type: string description: Lifecycle status of a volume. enum: - active - deleting VolumeType: type: string description: >- 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. enum: - block securitySchemes: api_key: type: http scheme: bearer description: Organization API key (msb_…) - org-scoped programmatic access. ````