Skip to content

Attach a volume to a VPS

POST /api/v2/volumes/{id}/actions/attach

Attaches a volume to a Cloud VPS on your account. If the volume is attached to another VPS, this moves it: it leaves that VPS and is attached to the one in vpsId. Check attachedVpsId on GET /api/v2/volumes/{id} first if you do not mean to move it. The data on the volume is kept. The call does not check that diskSlot is free. Pick a slot the VPS does not use. GET /api/v2/vps/{id}/disks lists the slots in use. The call answers 202 with a job. Follow it as described in Jobs. While another attach or move of the volume runs, the call returns 409 volume_operation_in_progress.

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

Request

Path parameters

idstringrequired
The volume ID (vol_…).

Body

vpsIdstringrequired
The Cloud VPS to attach the volume to (vps_…).
diskSlotstring
The SCSI slot the volume takes on the VPS. Pick one the VPS does not use. Default scsi1. One of scsi1, scsi2, scsi3, scsi4, scsi5, scsi6.

Example

POST /api/v2/volumes/{id}/actions/attach
curl -X POST "https://cloud.hostup.se/api/v2/volumes/vol_01hxa3b4c5d6e7f8g9h0j1k2m3/actions/attach" \
-H "Authorization: Bearer $HOSTUP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"vpsId": "vps_01hxa3b4c5d6e7f8g9h0j1k2m3",
"diskSlot": "scsi2"
}'

Responses

202 The attach or move is queued as a job.

Response 202
{
"operation": {
"status": "queued",
"jobId": "job_01hxa3b4c5d6e7f8g9h0j1k2m3",
"pollUrl": "/api/jobs/job_01hxa3b4c5d6e7f8g9h0j1k2m3"
}
}
Response fields
operationobject
The queued job.
statusstring
The job state when the call returns. One of queued, pending, in_progress.
jobIdstring or null
The job ID (job_…).
pollUrlstring or null
The path to poll for the job’s state. Put https://cloud.hostup.se in front of it.

Errors

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

400volume_already_attached: the volume is already on that VPS. invalid_request: an unknown field, no vpsId, a diskSlot other than scsi1 to scsi6 or a VPS that is not a Cloud VPS.
401Unauthorized. Authentication is required.
403forbidden: the VPS is not on your account.
404volume_not_found: no volume with that ID on your account. vps_not_found: no VPS has that ID.
409volume_operation_in_progress: another attach or move of this volume is still running. Try again when its job has finished.
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.