Skip to content

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

idstringrequired
The VPS ID (vps_…).

Body (optional)

notestring
Label stored with the backup. Longer text is cut to 1024 characters. Without a note, the backup is labelled Manual backup.

Example

POST /api/v2/vps/{id}/backups
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"
}'

Responses

202 The backup 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. Its detail still talks about permission.
404Not found. The resource does not exist or is not owned by the caller; code is vps_not_found.
409No 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).
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.