Take a snapshot of a VPS
POST /api/v2/vps/{id}/snapshots
Takes a snapshot of the VPS disks. Use it as a quick undo point, for example before an upgrade. Check actions.canCreate on GET /api/v2/vps/{id}/snapshots first. The VPS needs a free snapshot slot (limits.totalSnapshots above limits.usedSnapshots). Add slots with resources.snapshotSlots on POST /api/v2/vps/{id}/actions/config. Or delete an old snapshot to free a slot. Use a name the VPS does not have yet. The route does not check it. The snapshot is taken in the background. Follow operation.pollUrl (Jobs). When the job has finished, confirm the snapshot in data[].name on GET /api/v2/vps/{id}/snapshots. A finished job alone does not prove it was taken. It is stored on the VPS’s own storage. It is not an offsite backup. It is deleted 24 hours after it is taken.
Authentication: An API key with the scope backup:vm. About keys and scopes
Request
Path parameters
idstringrequiredvps_…).Body
namestringrequired_ or -. You use it later as {snapshotId}. Start it with a letter, use at least two characters and do not use current. A name that breaks these rules is still accepted. Then no snapshot is taken.descriptionstring or nullExample
curl -X POST "https://cloud.hostup.se/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/snapshots" \ -H "Authorization: Bearer $HOSTUP_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "before-upgrade", "description": "Before package upgrade" }'Responses
202 The snapshot job is queued. Follow operation.pollUrl. The snapshot gets the name you sent.
{ "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 | The body is not valid. For a bad name, errors[] points at it. A VPS with no free snapshot slot also gets 400. Then detail is “The request is invalid.” and there is no errors[]. Check actions.canCreate on GET /api/v2/vps/{id}/snapshots first. |
| 401 | Unauthorized. Authentication is required. |
| 403 | Forbidden. The caller lacks a required scope or does not own the resource. |
| 404 | Not found. The resource does not exist or is not owned by the caller; code is vps_not_found. |
| 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. |