Restore a VPS from a backup
POST /api/v2/vps/{id}/backups/{backupId}/actions/restore
Restores a VPS from one of its own backups. Everything on the server’s disks is replaced with the backup. Changes made after the backup was taken are lost. Check actions.canRestore and the backup’s own actions.canRestore on GET /api/v2/vps/{id}/backups first. The VPS must be active. A VPS that has used up its bandwidth allowance cannot be restored. The call then returns 403 forbidden. A backup that was deleted, or that belongs to another VPS, also returns 403 forbidden. The server is stopped, its disks are restored, its network settings are put back and it starts again. The restore runs as a job. Poll operation.pollUrl until it finishes (Jobs). To restore a backup of another VPS, use POST /api/v2/vps/{id}/backups/actions/restore-from-vps.
Authentication: An API key with the scope backup:vm. About keys and scopes
Request
Path parameters
idstringrequiredvps_…).backupIdstringrequiredbkp_…) from backups[].id on GET /api/v2/vps/{id}/backups.Example
curl -X POST "https://cloud.hostup.se/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/backups/bkp_01hxa3b4c5d6e7f8g9h0j1k2m3/actions/restore" \ -H "Authorization: Bearer $HOSTUP_API_KEY" \ -H "Content-Type: application/json"Responses
202 The restore job is queued.
{ "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. The response body is an RFC 7807 Problem Details document. |
| 401 | Unauthorized. Authentication is required. |
| 403 | The key lacks backup:vm. requiredScopes then names it. The same 403 forbidden, without requiredScopes, means the VPS has used up its bandwidth allowance, or the backup is not a current backup of this VPS. |
| 404 | Not found. The resource does not exist or is not owned by the caller; code names the missing resource: vps_not_found, backup_not_found. |
| 409 | The restore cannot start. code is service_not_active when the VPS is not active. A backup with no disk data, only the server configuration, returns 409 upstream_failed today. Its entry on GET /api/v2/vps/{id}/backups has actions.canRestore.allowed set to false. Check it before you call. |
| 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. |