Skip to main content
POST
Create a named volume

Authorizations

Authorization
string
header
required

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

Body

application/json

POST /v1/orgs/{slug}/volumes

name
string
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.

capacity_gib
integer<int32> | null

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.

Required range: x >= 0
labels
object

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

storage
null | enum<string>

Physical backing for the volume. Omitted = block (the default and only value today).

Available options:
block

Response

Volume created

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