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
idstringrequiredvps_…).backupIdstringrequiredbkp_…).Body (optional)
namestringrestore- followed by the source name and the end of the backup ID.regionstringcpuCoresintegermemoryGbintegerstorageGbintegerExample
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"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" \ -d '{ "name": "restore-web-01", "cpuCores": 2, "memoryGb": 4, "storageGb": 80 }'Responses
202 The job that creates the Cloud VPS and restores the backup 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 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. |
| 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. 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). |
| 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. |
| 503 | backup_listing_unavailable: the backups could not be read right now. Nothing was ordered. Try again shortly. |