Skip to content

List volumes

GET /api/v2/volumes

Lists the block storage volumes on your active Cloud VPS, sorted by name. A volume is an extra disk that you can detach and attach to another Cloud VPS. Detached volumes are listed too, with status available and attachedVpsId null. The boot disk of a VPS is not a volume. actions says whether each volume can be attached, detached or deleted now. The list can be up to 30 seconds old.

Authentication: An API key with the scope read:vm. About keys and scopes

Request

Query parameters

limitinteger
Page size, 1 to 100. Default 20. 1 to 100.
cursorstring
The nextCursor from the previous page.

Example

GET /api/v2/volumes
curl "https://cloud.hostup.se/api/v2/volumes" \
-H "Authorization: Bearer $HOSTUP_API_KEY"

Responses

200 One page of volumes.

Response 200
{
"data": [
{
"id": "vol_01hxa3b4c5d6e7f8g9h0j1k2m3",
"displayId": "database-data",
"name": "database-data",
"sizeGb": 100,
"status": "attached",
"attachedVpsId": "vps_01hxa3b4c5d6e7f8g9h0j1k2m3",
"actions": {
"canAttach": {
"allowed": true,
"reason": null
},
"canDetach": {
"allowed": true,
"reason": null
},
"canDelete": {
"allowed": false,
"reason": "Detach this volume before deleting it."
}
},
"createdAt": "2026-04-27T12:00:00.000Z"
}
],
"hasMore": false,
"nextCursor": null
}
Response fields
dataarray of object
The volumes on this page.
idstring
The volume ID (vol_…).
displayIdstring
Display label. The same as name.
namestring
The volume name. A generated disk name when no name was given at creation.
sizeGbinteger
Size in GB.
statusstring
attached: on the VPS in attachedVpsId. available: detached, with its data kept. creating and deleting: an operation is running. error: the volume is in an unexpected state. One of available, attached, creating, deleting, error.
attachedVpsIdstring or null
The VPS the volume is attached to (vps_…). null when it is detached.
actionsobject
What you can do with the volume right now. A closed gate has a reason.
canAttachobject
Attach the volume to a VPS. Also allowed while it is attached: attaching it to another VPS moves it.
allowedboolean
true when the action is allowed now.
reasonstring or null
Why the action is not allowed. null when it is.
canDetachobject
Detach the volume from its VPS.
allowedboolean
true when the action is allowed now.
reasonstring or null
Why the action is not allowed. null when it is.
canDeleteobject
Delete the volume. Closed while it is attached.
allowedboolean
true when the action is allowed now.
reasonstring or null
Why the action is not allowed. null when it is.
createdAtstring or null
When the volume was created (ISO 8601). null when the creation time is not recorded.
hasMoreboolean
true when there is another page.
nextCursorstring or null
Pass it as cursor to get the next page. null on the last page.

Errors

Errors are Problem Details with a stable code. Branch on the code, not on the text.

400invalid_pagination_limit: limit is not a whole number from 1 to 100. invalid_cursor: cursor is malformed.
401Unauthorized. Authentication is required.
403Forbidden. The caller lacks a required scope or does not own the resource.
404Not found. The resource does not exist or is not owned by the caller; code is vps_not_found.
429Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers.
500Internal error. Retry later or contact support if the issue persists.
502Upstream failure. A dependent provider request failed; the Problem Details code is upstream_failed. Retry later or contact support if the issue persists.