Skip to content

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

idstringrequired
The VPS ID (vps_…).
backupIdstringrequired
The backup ID (bkp_…) from backups[].id on GET /api/v2/vps/{id}/backups.

Example

POST /api/v2/vps/{id}/backups/{backupId}/actions/restore
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.

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. The response body is an RFC 7807 Problem Details document.
401Unauthorized. Authentication is required.
403The 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.
404Not found. The resource does not exist or is not owned by the caller; code names the missing resource: vps_not_found, backup_not_found.
409The 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.
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.