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
idstringrequiredvps_…).Body
templateIdstringrequiredGET /api/v2/vps/{id}/templates.clearSshKeysbooleanfalse.Example
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.
{ "operation": { "status": "queued", "jobId": "job_01hxa3b4c5d6e7f8g9h0j1k2m3", "pollUrl": "/api/jobs/job_01hxa3b4c5d6e7f8g9h0j1k2m3" }}Response fields
operationobjectstatusstring202 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.jobIdstringpollUrlstring or nullnull when status is already completed or failed.Errors
Errors are Problem Details with a stable code. Branch on the code, not on the text.
| 400 | invalid_request: templateId is missing, or it is not one of the templates GET /api/v2/vps/{id}/templates lists for this VPS. |
| 401 | Unauthorized. Authentication is required. |
| 403 | forbidden. 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. |
| 404 | Not found. The resource does not exist or is not owned by the caller; code is vps_not_found. |
| 409 | upstream_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. |
| 429 | A 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. |
| 500 | Internal error. Retry later or contact support if the issue persists. |