Skip to content

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

idstringrequired
The VPS ID (vps_…).

Body

namestringrequired
Snapshot name, 1 to 40 letters, digits, _ 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 null
A note to remember why you took it. Up to 1024 characters. Longer text is cut.

Example

POST /api/v2/vps/{id}/snapshots
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.

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.

400The 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.
401Unauthorized. Authentication is required.
403Forbidden. The caller lacks a required scope or does not own the resource.
404Not found. The resource does not exist or is not owned by the caller; code is vps_not_found.
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.