Skip to content

Reinstall a VPS

POST /api/v2/vps/{id}/actions/rebuild

Reinstall a VPS with a fresh operating system. The data on the VPS is erased. This cannot be undone. Pick the system with templateId from GET /api/v2/vps/{id}/templates. With clearSshKeys: true the new system starts without the SSH keys saved on the VPS.

Check actions.canRebuild on GET /api/v2/vps/{id}/details first. That gate does not cover a used-up bandwidth limit. Check bandwidth.hasOverage there too.

The VPS is offline while it reinstalls. The call returns 202 with a job. Follow it at operation.pollUrl until it finishes. See Jobs. The rebuild is refused with 409 while another operation runs on the VPS, such as a migration. It is refused with 403 when the VPS has reached its bandwidth limit. A second rebuild within 5 minutes of the first returns 429 cooldown_active. Check GET /api/v2/vps/{id}/active-jobs before you send it again. Sending it again after the wait reinstalls the VPS a second time.

The snapshots of the VPS are deleted with the old system. The new system gets the root password Hostup has on file for the VPS, the one in the access object of GET /api/v2/vps/{id}/details. A password you changed inside the old system is not kept.

A VPS with a disk besides the system disk cannot be reinstalled. A disk kept as a volume with keepVolume=true blocks the reinstall too. So does a volume detached from this VPS. The call still returns 202. The job then fails before anything is erased. Delete the extra disk first. GET /api/v2/vps/{id}/disks lists the disks. Delete a kept or detached volume with DELETE /api/v2/volumes/{id}.

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

Request

Path parameters

idstringrequired
The VPS ID (vps_…).

Body

templateIdstringrequired
The operating system template ID from GET /api/v2/vps/{id}/templates.
clearSshKeysboolean
Start the new system without the SSH keys saved on the VPS. Default false.

Example

POST /api/v2/vps/{id}/actions/rebuild
curl -X POST "https://cloud.hostup.se/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/actions/rebuild" \
-H "Authorization: Bearer $HOSTUP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"templateId": "os_01hxa3b4c5d6e7f8g9h0j1k2m3",
"clearSshKeys": false
}'

Responses

202 The rebuild is queued. Follow the job.

Response 202
{
"operation": {
"status": "queued",
"jobId": "job_01hxa3b4c5d6e7f8g9h0j1k2m3",
"pollUrl": "/api/jobs/job_01hxa3b4c5d6e7f8g9h0j1k2m3"
}
}
Response fields
operationobject
statusstring
Where the job is. A 202 Accepted response only has pending, queued or in_progress. completed and failed appear when you poll pollUrl. They also appear in a 200 OK response when the action finished during the request. One of pending, queued, in_progress, completed, failed.
jobIdstring
pollUrlstring or null
Where to poll the job while it runs. null when status is already completed or failed.

Errors

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

400invalid_request: templateId is missing, or it is not one of the templates GET /api/v2/vps/{id}/templates lists for this VPS.
401Unauthorized. Authentication is required.
403forbidden. With requiredScopes in the body, the key lacks a scope. The key needs both write:vm and rebuild:vm, although detail asks for one of them. Without requiredScopes, the VPS is not active (for example suspended) or it has used up its bandwidth. The detail is the same in both cases.
404Not found. The resource does not exist or is not owned by the caller; code is vps_not_found.
409upstream_failed: another operation runs on the VPS, such as a power action, a backup or a migration. Wait for it to finish and try again.
429A rebuild started less than 5 minutes ago. Wait the number of seconds in Retry-After. Check GET /api/v2/vps/{id}/active-jobs before you send it again. Sending it again after the wait reinstalls the VPS a second time.
500Internal error. Retry later or contact support if the issue persists.