MImicrosandbox
volumes

Create a volume

Changed on

Create a named persistent volume with optional capacity and labels.

post/v1/volumes

Request

  • Base URL
    https://api.microsandbox.dev (the document declares no server; this is the origin it was published from)
  • URL
    https://api.microsandbox.dev/v1/volumes
  • Auth
    HTTP bearer

Request body

capacity_gibinteger nullable

Optional per-volume storage cap in GiB (#496). Omitted/null = no per-volume limit (the org's plan cap still governs). Must be >= 1 and <= the org's storage cap.

labelsobject

User-defined labels (free-form string map). Omitted = none. Keys using a platform-reserved prefix are rejected.

namestring required

Volume name, unique within the org. Lowercase alphanumeric with single internal hyphens (e.g. team-ml). Creates a managed volume; the host disk is system-provisioned and has no name.

storage'block'

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.

Response

Volume created

capacity_bytesinteger 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_atstring date-time required
idstring uuid required
kind'host' | 'managed' required

Volume role: the organization's shared host volume or a named managed volume.

labelsobject required

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

namestring 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_atstring date-time required
used_bytesinteger 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.

Changes

  • 90291f62c817Revision changes
    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status