Create a VPS backup
POST /api/v2/vps/{id}/backups
Starts a manual backup of a VPS. Check actions.canCreateBackup on GET /api/v2/vps/{id}/backups first. The VPS must be active and have a free backup slot. When every slot is used, the call returns 409 backup_slots_full. Delete a backup you no longer need first. A VPS that has used up its bandwidth allowance cannot start a backup. The call then returns 403 forbidden without requiredScopes. Send an optional note to label the backup. The backup runs as a job. Poll operation.pollUrl until it finishes (Jobs). Backups are offsite, longer-term copies and can take longer to create than a snapshot.
Authentication: An API key with the scope backup:vm. About keys and scopes
Request
Path parameters
idstringrequiredvps_…).Body (optional)
notestringManual backup.Example
curl -X POST "https://cloud.hostup.se/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/backups" \ -H "Authorization: Bearer $HOSTUP_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "note": "Before upgrade" }'curl -X POST "https://cloud.hostup.se/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/backups" \ -H "Authorization: Bearer $HOSTUP_API_KEY" \ -H "Content-Type: application/json"Responses
202 The backup 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. Its detail still talks about permission. |
| 404 | Not found. The resource does not exist or is not owned by the caller; code is vps_not_found. |
| 409 | No backup can start. Branch on code: service_not_active (the VPS is not active) or backup_slots_full (every backup slot is used; delete a backup first). |
| 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. |