Skip to content

Restore a backup to a new Cloud VPS

POST /api/v2/vps/{id}/backups/{backupId}/actions/restore-to-payg

Creates a new Cloud VPS and restores the chosen backup onto it. The original VPS is not changed. Check actions.canRestoreToNewCloudVm on GET /api/v2/vps/{id}/backups first. The account must be allowed to use Cloud VPS. If it is not, the call returns 403 and blockerReasons says why. That gate does not show an overdue Cloud VPS invoice. The call then returns 403 payg_payment_overdue. Pay the invoice first. The new server is billed pay-as-you-go like any Cloud VPS. Without a body, the new server gets the CPU and memory of the source VPS and the storage the backup needs. The job creates the server and then restores the backup. Poll operation.pollUrl until it finishes (Jobs). When the job is completed, data.result.targetVpsId is the new VPS. data.result.orderId and data.result.invoiceId point to the order behind it. Calling again for the same backup while that job runs returns the same job. The options in the second call are ignored.

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

Request

Path parameters

idstringrequired
The VPS ID (vps_…).
backupIdstringrequired
The backup ID (bkp_…).

Body (optional)

namestring
Hostname of the new Cloud VPS, 3 to 63 characters. Letters, digits and hyphens. It must start and end with a letter or digit. A name with a dot passes this request. The job then fails before it orders the server. Default: restore- followed by the source name and the end of the backup ID.
regionstring
Not used today. Any value is accepted and ignored. Leave it out.
cpuCoresinteger
CPU cores, 1 to 32. A higher number is lowered to 32. Default: the cores of the source VPS. 1 to 32.
memoryGbinteger
Memory in GB, 1 to 256. A higher number is lowered to 256. Default: the memory of the source VPS. 1 to 256.
storageGbinteger
Disk size in GB, at most 2000. It must be at least what the backup needs and never less than 50. Default: the size the backup needs. 50 to 2000.

Example

POST /api/v2/vps/{id}/backups/{backupId}/actions/restore-to-payg
curl -X POST "https://cloud.hostup.se/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/backups/bkp_01hxa3b4c5d6e7f8g9h0j1k2m3/actions/restore-to-payg" \
-H "Authorization: Bearer $HOSTUP_API_KEY" \
-H "Content-Type: application/json"

Responses

202 The job that creates the Cloud VPS and restores the backup 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 new server can’t be ordered. Branch on code: no_card_on_file, not_verified, no_cloud_access, insufficient_trusted_history, country_not_supported or payg_access_unavailable (the account can’t use Cloud VPS yet; blockerReasons lists every reason; detail says what to do), payg_payment_overdue (a Cloud VPS invoice is overdue; pay it first), order_permission_required (the key belongs to a contact on the account without permission to place orders) or forbidden (the key lacks a scope). The key needs both backup:vm and write:billing. The detail of that forbidden says one of them is enough.
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. Branch on code: target_storage_too_small (choose at least requiredStorageGb), target_storage_too_large (the disk would be larger than 2000 GB), payg_limit_exceeded (the new server would pass the account’s Cloud VPS limits; requested, current and max show the numbers), source_vps_not_ready (the source VPS is still being set up) or backup_has_no_disk_images (the backup holds only the server configuration).
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.
503backup_listing_unavailable: the backups could not be read right now. Nothing was ordered. Try again shortly.