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
namestringName for the volume, 1 to 255 characters. Leave it out to get a generated name.
sizeGbintegerrequiredSize in GB, a whole number from 10 to 1000. 10 to 1000.
targetVpsIdstringrequiredThe Cloud VPS to attach the volume to (
vps_…).Example
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.
{ "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
idstringThe volume ID (
vol_…).displayIdstringDisplay label. The same as
name.namestringThe volume name. A generated disk name when no name was given at creation.
sizeGbintegerSize in GB.
statusstringattached: 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 nullThe VPS the volume is attached to (
vps_…). null when it is detached.actionsobjectWhat you can do with the volume right now. A closed gate has a
reason.canAttachobjectAttach the volume to a VPS. Also allowed while it is attached: attaching it to another VPS moves it.
allowedbooleantrue when the action is allowed now.reasonstring or nullWhy the action is not allowed.
null when it is.canDetachobjectDetach the volume from its VPS.
allowedbooleantrue when the action is allowed now.reasonstring or nullWhy the action is not allowed.
null when it is.canDeleteobjectDelete the volume. Closed while it is attached.
allowedbooleantrue when the action is allowed now.reasonstring or nullWhy the action is not allowed.
null when it is.createdAtstringWhen the volume was created (ISO 8601).
Errors
Errors are Problem Details with a stable code. Branch on the code, not on the text.
| 400 | invalid_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. |
| 401 | Unauthorized. Authentication is required. |
| 403 | forbidden: 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. |
| 404 | vps_not_found: no VPS has that ID. |
| 429 | Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers. |
| 500 | Internal error. Retry later or contact support if the issue persists. |
| 502 | upstream_failed: the disk could not be created. Try again later. |