POST /v1/volumes

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Header Parameters

Idempotency-Key?string

Length8 <= length <= 255

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Name is required for Shared Volumes. Legacy Local Volume clients may omit it and receive a deterministic immutable-id-derived name.

name?string

Length1 <= length <= 128

type?string

Default"local"

Value in

"local"
"shared"

driver?string

Storage implementation. JuiceFS is a separately gated Shared Volume driver; do not infer it for legacy Shared Volumes.

Value in

"local"
"object_fuse"
"juicefs"

size_gb?integer

Capacity in GiB (2^30 bytes) — the gb in this frozen wire name has always meant gibibytes. The effective maximum is server policy, identical for every storage implementation, and is readable at GET /v1/volumes/limits; exceeding it returns 413 volume_capacity_above_max. Per-implementation organization caps still apply on top.

Range1 <= value <= 8192

Default1

inode_quota?integer

Required for driver=juicefs; the logical inode hard quota.

Range1 <= value <= 100000000

mount_path?string

Local Volume default mount path. Shared Volume paths belong to individual attachments.

mount_path_policy?"volume_id"

Opt-in, additive. When set to "volume_id", the server derives the Local Volume mount path as /mnt/<id> from the id it mints for this row, instead of using mount_path. Mutually exclusive with an explicit non-default mount_path.

Value in

"volume_id"

sandbox_id?string

Local Volume only: pick this sandbox host and attach when it is running.

host_id?string

Local Volume only: pin the backing disk to this host.

Response Body

`application/json`

curl -X POST "https://example.com/v1/volumes" \  -H "Content-Type: application/json" \  -d '{}'

{  "id": "string",  "name": "string",  "type": "local",  "driver": "local",  "size_gb": 0,  "state": "string",  "mount_path": "string",  "host_id": "string",  "attachment_id": "string",  "attached_to": "string",  "device_path": "string",  "auto_attach": {}}

{  "id": "string",  "name": "string",  "type": "local",  "driver": "local",  "size_gb": 0,  "state": "string",  "mount_path": "string",  "host_id": "string",  "attachment_id": "string",  "attached_to": "string",  "device_path": "string",  "auto_attach": {}}

Empty

{  "error": "string",  "code": "volume_capacity_above_max",  "requested_gib": 1,  "max_gib": 1,  "unit": "GiB"}

Authorization

Header Parameters

Request Body

Response Body

201application/json

207application/json

401

413application/json

`application/json`

`application/json`

`application/json`