9. Volumes
Creating, updating, and deleting volumes, reading their space usage, and volume-level actions (rename, recover).
Endpoint Summary
| Path | Summary | Method |
|---|---|---|
/api/v1/volumes |
List volumes | GET |
/api/v1/volumes |
Create a new volume | POST |
/api/v1/volumes/{volume_id} |
Get volume info | GET |
/api/v1/volumes/{volume_id} |
Update volume | PATCH |
/api/v1/volumes/{volume_id} |
Delete volume | DELETE |
/api/v1/volumes/{volume_id}/actions |
Perform action on volume | POST |
/api/v1/volumes/{volume_id}/space |
Get volume space | GET |
GET /api/v1/volumes
List volumes
Returns a list of volumes accessible to the authenticated user.
Authentication: required (PasswordLogin or BearerJWT).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
tenant_id |
query | string (uuid), nullable | no | Platform tenant only. Read the volumes of another tenant instead of your own. |
all_tenants |
query | boolean | no | Platform tenant only. Read the volumes of every tenant. |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successful response containing the list of volumes | VolumeListResponse |
| 400 | Bad request. Invalid parameters or validation error. | - |
| 401 | Unauthorized. Authentication required. | - |
| 403 | Forbidden. Insufficient permissions. | - |
| 422 | Validation Error | HTTPValidationError |
| 500 | Internal server error. | - |
Response Body (200, VolumeListResponse)
| Field | Type | Required | Default | Example | Description |
|---|---|---|---|---|---|
total |
integer | yes | n/a | 0, 2, 150 |
Total count of volumes available (may exceed returned array size if paginated). |
volumes |
array of Volume object |
no | n/a | Array of volume objects matching the query. Empty array if no volumes found |
Example
{
"total" : 2,
"volumes" : [
{
"efsa_mode" : "retry",
"hard_quota_bytes" : 549755813888,
"id" : 1,
"object_id" : "I-xD0200000000000005-xG82c418af-xU00004a75726a656e",
"pathname" : "/",
"quotas_policy" : "enable",
"raid_type" : "raid6+",
"recovery_priority" : 1,
"soft_quota_bytes" : 524288000000,
"status" : "online",
"storageset_id" : 1,
"tenant_id" : "00000000-0000-0000-0000-000000000001",
"volume_service_id" : "0x0400000000000005"
},
{
"efsa_mode" : "retry",
"id" : 2,
"object_id" : "I-xD0200000000000006-xGc4f7a724-xU00004a75726a656e",
"pathname" : "/home",
"quotas_policy" : "disable",
"raid_type" : "raid6+",
"recovery_priority" : 50,
"status" : "online",
"storageset_id" : 1,
"tenant_id" : "e97b94d6-9cc1-4325-a267-1064ae538ccd",
"volume_service_id" : "0x0400000000000006"
}
]
}POST /api/v1/volumes
Create a new volume
Creates a new volume and returns its ID.
Authentication: required (PasswordLogin or BearerJWT).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
ignore_limits |
query | boolean | no | Platform tenant only. Act without the limits the tenant’s storageset assignment imposes: no assignment need exist, no quota ceiling applies, and free space is not checked, as before tenancy. For a create, the target storageset must still exist in the realm. |
Request Body (application/json, required)
Schema: VolumeCreateRequest
Request payload for creating a volume.
Mirrors the CLI “volume create” command. Requires a volume name and a StorageSet ID. Optional parameters use system defaults when omitted.
| Field | Type | Required | Default | Example | Description |
|---|---|---|---|---|---|
efsa_mode |
EfsaMode (retry, file-unavailable, default) |
no | default |
retry, file-unavailable, default |
EFSA mode for the volume. Defines behavior during partial storage unavailability. Supported: retry, file-unavailable, default. If not specified, system default (retry) is applied. Only for RAID 5+, 6+, 10+ volumes. |
group |
string, nullable | no | null |
0, 100 |
Owner GID of the volume, as a numeric string (e.g. “0”, “100”). Defaults to root group (gid=0) if not specified. String name resolution and Windows SID are not supported. |
group_permissions |
VolumePermission (none, read-only, write-only, execute-only, read-write, read-execute, write-execute, all), nullable |
no | null |
read-only, read-execute |
Filesystem permissions for the owner group on the root of the volume. Allowed values: none, read-only, write-only, execute-only, read-write, read-execute, write-execute, all. |
hard_quota_bytes |
integer, nullable | no | null |
549755813888, null |
Hard quota in bytes. Prevents additional writes when limit is reached. A volume in a tenant requires a value greater than 0; a request without one returns 400. |
max_width |
integer, nullable | no | null |
12, 20 |
Maximum number of VPODs to stripe data across. Minimum depends on RAID layout: 2 for RAID 5+, 3 for RAID 6+, 2 for RAID 10+. If not specified, the system allows striping across the StorageSet. |
other_permissions |
VolumePermission (none, read-only, write-only, execute-only, read-write, read-execute, write-execute, all), nullable |
no | null |
none, read-only |
Filesystem permissions for others on the root of the volume. Allowed values: none, read-only, write-only, execute-only, read-write, read-execute, write-execute, all. |
pathname |
string | yes | n/a | /vol2, /data |
Required unique mount path of the volume. Must start with / and be unique within the system. |
raid_type |
VolumeLayout (raid6+, raid5+, raid10+, raid5, raid10) |
no | raid6+ |
raid6+, raid5+, raid10+, raid5, raid10 |
RAID layout for the volume. Default: raid6+. Cannot be changed after creation. |
recovery_priority |
integer | no | 50 |
0, 1, 50, 100 |
Recovery priority (1-100) of the volume. Lower values indicate higher recovery priority, where 1 represents the highest priority. If not specified the system default (50) is applied. |
rg_depth |
integer, nullable | no | null |
4, 16 |
RAID group depth (number of stripes per RAID parity group). Only for RAID 5+, 6+. If not specified, a system default value is applied. |
rg_width |
integer, nullable | no | null |
8, 12 |
RAID group width (VPODs to stripe over per single RAID group, 3-20). Only for RAID 5+, 6+. If not specified, a system default value is applied. |
soft_quota_bytes |
integer, nullable | no | null |
549755813888, null |
Soft quota limit in bytes. Triggers quota notifications when the threshold is exceeded. Use 0 or null for unlimited. |
storageset_id |
integer | yes | n/a | 1, 2, 5 |
Identifier of the StorageSet where the volume will be created. Required if multiple StorageSets exist. |
stripe_unit_bytes |
integer, nullable | no | null |
262144, 1048576 |
Specifies the number of bytes written to a VPOD before advancing to the next VPOD in the stripe. Must be a multiple of 16 KB (min: 16 KB, max: 4 MB). If not specified, a system default value is applied. |
user |
string, nullable | no | null |
0, 1001 |
Owner UID of the volume, as a numeric string (e.g. “0”, “1001”). Defaults to root (uid=0) if not specified. String name resolution and Windows SID are not supported. |
user_permissions |
VolumePermission (none, read-only, write-only, execute-only, read-write, read-execute, write-execute, all), nullable |
no | null |
read-write, all |
Filesystem permissions for the owner user on the root of the volume. Allowed values: none, read-only, write-only, execute-only, read-write, read-execute, write-execute, all. |
volume_service_id |
string, nullable | no | null |
0x0400000000000005 |
Identifier of the volume service that will manage this volume, in hexadecimal format (e.g., “0x0400000000000005”). This allows control over how volume management load is distributed across Directors. If not specified, the system automatically assigns the volume to an existing service. |
Example
{
"efsa_mode" : "retry",
"pathname" : "/vol2",
"raid_type" : "raid6+",
"recovery_priority" : 50,
"storageset_id" : 1
}Responses
| Status | Description | Schema |
|---|---|---|
| 201 | Volume created successfully | VolumeCreateResponse |
| 400 | Bad request. Custom validation error or invalid parameters, including a hard_quota_bytes too small to hold the new volume. The smallest quota that fits depends on the realm. | - |
| 401 | Unauthorized. Authentication required. | - |
| 403 | Forbidden. Insufficient permissions. | - |
| 404 | Tenant or storageset not found. | - |
| 409 | Conflict. The volume pathname already exists, or the owning tenant holds no issued subnet address. A named tenant is served over its own network, so the realm manager refuses to create a volume for a tenant no client could reach it through: give the tenant a subnet and let one of its nodes report an address into it first. | - |
| 422 | Validation error. Returned for invalid request body. | - |
| 500 | Internal server error. | - |
| 503 | Service unavailable. A backend dependency the request needs is unreachable. The request was well formed and changed nothing, so the same call is worth retrying once the dependency is back; which one failed is recorded server-side, not in the response. | - |
| 504 | Gateway timeout. The storage backend did not answer in time. It cannot abort a create in progress, so the volume may exist, and may appear only later: list the volumes before retrying the create. | - |
Response Body (201, VolumeCreateResponse)
| Field | Type | Required | Default | Example | Description |
|---|---|---|---|---|---|
id |
integer | yes | n/a | 1, 2, 42 |
Unique volume identifier assigned by RM |
Example
{
"id" : 1
}GET /api/v1/volumes/{volume_id}
Get volume info
Returns details for a specific volume by its volume_id.
Authentication: required (PasswordLogin or BearerJWT).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
volume_id |
path | integer | yes | ID of the volume |
tenant_id |
query | string (uuid), nullable | no | Platform tenant only. Read a volume of another tenant instead of your own. There is no all-tenants form here: a volume id already names exactly one volume, so the only question is whose volume the caller may reach. Reads only - a write always stays in the caller’s own tenant. |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successfully retrieved detailed information about the volume. | VolumeGetResponse |
| 400 | Bad request. Invalid volume_id parameter. | - |
| 401 | Unauthorized. Authentication required. | - |
| 403 | Forbidden. Insufficient permissions. | - |
| 404 | Volume not found. | - |
| 422 | Validation error for the volume_id path parameter. | - |
| 500 | Internal server error. | - |
Response Body (200, VolumeGetResponse)
| Field | Type | Required | Default | Example | Description |
|---|---|---|---|---|---|
volume |
Volume object |
yes | n/a | Volume entity with all available details. |
Example
{
"volume" : {
"efsa_mode" : "retry",
"hard_quota_bytes" : 549755813888,
"id" : 1,
"max_width" : 12,
"object_id" : "I-xD0200000000000005-xG82c418af-xU00004a75726a656e",
"pathname" : "/",
"quotas_policy" : "disable",
"raid_type" : "raid6+",
"recovery_priority" : 1,
"rg_depth" : 4,
"rg_width" : 8,
"soft_quota_bytes" : 524288000000,
"status" : "online",
"storageset_id" : 1,
"stripe_unit_bytes" : 262144,
"tenant_id" : "00000000-0000-0000-0000-000000000001",
"volume_service_id" : "0x0400000000000005"
}
}PATCH /api/v1/volumes/{volume_id}
Update volume
Updates an existing volume using PATCH semantics. Only the fields provided in the request are modified.
Authentication: required (PasswordLogin or BearerJWT).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
volume_id |
path | integer | yes | ID of the volume |
ignore_limits |
query | boolean | no | Platform tenant only. Act without the limits the tenant’s storageset assignment imposes: no assignment need exist, no quota ceiling applies, and free space is not checked, as before tenancy. For a create, the target storageset must still exist in the realm. |
Request Body (application/json, required)
Schema: VolumePatchRequest
Request payload for updating an existing volume via PATCH.
| Field | Type | Required | Default | Example | Description |
|---|---|---|---|---|---|
access_permission |
VolumeAccessMode (read-only, read-write), nullable |
no | null |
read-only, read-write |
Volume access permission mode. Set to read-only for administrative purposes |
compression |
VolumeCompressionMode (enable, disable), nullable |
no | null |
enable, disable |
Enable or disable compression for the volume. Affects new data only |
efsa_mode |
EfsaMode (retry, file-unavailable, default), nullable |
no | null |
retry, file-unavailable, default |
EFSA mode for the volume. Defines behavior during partial storage unavailability. Supported: retry, file-unavailable, default. If not specified, system default (retry) is applied. Only for RAID 5+, 6+, 10+ volumes. |
hard_quota_bytes |
integer, nullable | no | null |
1099511627776, 0 |
Hard quota in bytes. Prevents additional writes when limit is reached. A volume in a tenant requires a value greater than 0; a request without one returns 400. |
recovery_priority |
integer, nullable | no | null |
0, 1, 50, 100 |
Recovery priority (1-100) of the volume. Lower values indicate higher recovery priority, where 1 represents the highest priority. If not specified the system default (50) is applied. |
soft_quota_bytes |
integer, nullable | no | null |
549755813888, 0 |
Soft quota limit in bytes. Triggers quota notifications when the threshold is exceeded. Use 0 for unlimited. |
state |
VolumeStateOption (online, offline, paused), nullable |
no | null |
online, offline, paused |
Target operational state for the volume. Use to bring volume online/offline |
Example
{
"access_permission" : "read-write",
"efsa_mode" : "file-unavailable",
"hard_quota_bytes" : 1099511627776,
"recovery_priority" : 75,
"soft_quota_bytes" : 549755813888,
"state" : "online"
}Responses
| Status | Description | Schema |
|---|---|---|
| 204 | Volume updated successfully. | - |
| 400 | Bad request. Invalid volume_id or custom validation error. | - |
| 401 | Unauthorized. Authentication required. | - |
| 403 | Forbidden. Insufficient permissions. | - |
| 404 | Tenant or storageset not found. | - |
| 409 | Conflict. Pathname already exists or update conflicts with system state. | - |
| 422 | Validation error. Returned for invalid request body (all fields are optional). | - |
| 500 | Internal server error. | - |
DELETE /api/v1/volumes/{volume_id}
Delete volume
Deletes the specified volume by its volume_id. The volume record is removed from the realm first, then its PanFS directory is removed. If the directory removal fails the volume is already unregistered and will not appear in listings; the orphaned directory at the reported path must be removed manually.
Authentication: required (PasswordLogin or BearerJWT).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
volume_id |
path | integer | yes | ID of the volume |
Responses
| Status | Description | Schema |
|---|---|---|
| 204 | Volume deleted successfully. | - |
| 400 | Bad request. Invalid volume_id parameter. | - |
| 401 | Unauthorized. Authentication required. | - |
| 403 | Forbidden. Insufficient permissions. | - |
| 404 | Volume not found. | - |
| 409 | Volume backs an enabled tenant’s S3 prefix and cannot be deleted. | - |
| 422 | Validation Error | HTTPValidationError |
| 500 | Internal server error. | - |
POST /api/v1/volumes/{volume_id}/actions
Perform action on volume
Performs a specified action (rename or recover).
Authentication: required (PasswordLogin or BearerJWT).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
volume_id |
path | integer | yes | ID of the volume |
Request Body (application/json, required)
One of the following, selected by action:
action: recover - VolumeRecoverActionRequest
| Field | Type | Required | Default | Example | Description |
|---|---|---|---|---|---|
action |
literal recover |
yes | n/a | The action to perform on the volume. | |
params |
VolumeRecoverActionParams object |
yes | n/a | Parameters required to perform the recover action. |
action: rename - VolumeRenameActionRequest
| Field | Type | Required | Default | Example | Description |
|---|---|---|---|---|---|
action |
literal rename |
yes | n/a | The action to perform on the volume. | |
params |
VolumeRenameActionParams object |
yes | n/a | Parameters required to perform the rename action. |
Responses
| Status | Description | Schema |
|---|---|---|
| 204 | Action performed successfully on the volume. No content is returned. | - |
| 400 | Bad request. Invalid volume_id or invalid action parameters. | - |
| 401 | Unauthorized. Authentication required. | - |
| 403 | Forbidden. Insufficient permissions. | - |
| 404 | Volume not found. | - |
| 409 | Conflict. Action conflicts with current system state. | - |
| 422 | Validation Error | HTTPValidationError |
| 500 | Internal server error. | - |
GET /api/v1/volumes/{volume_id}/space
Get volume space
Returns space usage for a specific volume: used bytes, hard/soft quotas, and free capacity.
Authentication: required (PasswordLogin or BearerJWT).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
volume_id |
path | integer | yes | ID of the volume |
tenant_id |
query | string (uuid), nullable | no | Platform tenant only. Read a volume of another tenant instead of your own. There is no all-tenants form here: a volume id already names exactly one volume, so the only question is whose volume the caller may reach. Reads only - a write always stays in the caller’s own tenant. |
Responses
| Status | Description | Schema |
|---|---|---|
| 200 | Successful response containing space information for the volume. | VolumeSpaceResponse |
| 400 | Bad request. Validation error (e.g., invalid volume ID). | - |
| 401 | Unauthorized. Authentication required. | - |
| 403 | Forbidden. Insufficient permissions. | - |
| 404 | Volume not found. | - |
| 422 | Validation error. Returned for invalid path parameters. | - |
| 500 | Internal server error. | - |
Response Body (200, VolumeSpaceResponse)
| Field | Type | Required | Default | Example | Description |
|---|---|---|---|---|---|
free_bytes |
integer | yes | n/a | 107374182400, 0 |
Remaining capacity within the hard quota (hard_quota_bytes - used_bytes). |
hard_quota_bytes |
integer, nullable | yes | n/a | 214748364800, 549755813888 |
Hard quota limit in bytes. This is the total capacity allocated to the volume. |
soft_quota_bytes |
integer, nullable | no | null |
193273528320, null |
Soft quota limit in bytes. Advisory threshold that triggers warnings. Null if not configured. |
used_bytes |
integer | yes | n/a | 107374182400, 0 |
Bytes consumed by this volume on disk. |
Example
{
"free_bytes" : 107374182400,
"hard_quota_bytes" : 214748364800,
"soft_quota_bytes" : 193273528320,
"used_bytes" : 107374182400
}