Skip to content

Create a volume

POST /api/v2/volumes

Creates a block storage volume and attaches it to a Cloud VPS on your account. The VPS must be a Cloud VPS: billing.isPayg is true in GET /api/v2/vps. Cloud VPS must be enabled for your account. The size must fit in your disk quota. The volume is created and attached before the call returns. The response is the volume with status attached. While the volume is attached, its size is billed by the hour as disk on that VPS.

Authentication: An API key with the scope write:storage. About keys and scopes

Request

Body

namestring
Name for the volume, 1 to 255 characters. Leave it out to get a generated name.
sizeGbintegerrequired
Size in GB, a whole number from 10 to 1000. 10 to 1000.
targetVpsIdstringrequired
The Cloud VPS to attach the volume to (vps_…).

Example

POST /api/v2/volumes
curl -X POST "https://cloud.hostup.se/api/v2/volumes" \
-H "Authorization: Bearer $HOSTUP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "database-data",
"sizeGb": 100,
"targetVpsId": "vps_01hxa3b4c5d6e7f8g9h0j1k2m3"
}'

Responses

201 The new volume, attached to the VPS.

Response 201
{
"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"
}
Response fields
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
When the volume was created (ISO 8601).

Errors

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

400invalid_request: an unknown field, sizeGb not a whole number from 10 to 1000, an empty or too long name, no targetVpsId or a VPS that is not a Cloud VPS.
401Unauthorized. Authentication is required.
403forbidden: the VPS is not on your account. Also returned when the key belongs to a contact who may not place orders. cloud_access_disabled: Cloud VPS is not enabled for your account. disk_limit_exceeded: the volume would exceed your disk quota.
404vps_not_found: no VPS has that ID.
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_failed: the disk could not be created. Try again later.