Snapshots
Take point-in-time snapshots of a server's disk and roll the server back to one.
A snapshot is a copy of the server's disk at one moment. You can roll the server back to it later. Snapshots are free; the number you can keep depends on the plan (maxSnapshots).
The snapshot object
{
"id": "0e8b5c1d-6f3a-4b2e-9c7d-1a2b3c4d5e6f",
"instanceId": "1f757fd5-98d1-490a-81a0-58b5798a5815",
"name": "before-upgrade",
"state": "NORMAL",
"percent": 100,
"diskSize": 40,
"lastJobStatus": "success",
"lastJobError": null,
"createdAt": "2026-10-16T09:00:00.000Z",
"updatedAt": "2026-10-16T09:03:12.000Z"
}| Field | Description |
|---|---|
id | Snapshot id. |
instanceId | Server the snapshot belongs to. |
name | Name you gave it, or snap-<timestamp>. |
state | CREATING while it is being taken, NORMAL when ready, FAILED if it could not be taken, ROLLBACKING while it is being applied. |
percent | Progress from 0 to 100. |
diskSize | Size of the copied disk in GB, once ready. |
lastJobStatus, lastJobError | Outcome of the last job on this snapshot. |
As with instances, undocumented fields in the response are internal and can change.
List snapshots
/vps/:id/snapshotscurl https://api.helipod.io/api/vps/1f757fd5-98d1-490a-81a0-58b5798a5815/snapshots \
-H "Authorization: Bearer hel_your_key"{
"success": true,
"data": {
"snapshots": [
{
"id": "0e8b5c1d-6f3a-4b2e-9c7d-1a2b3c4d5e6f",
"instanceId": "1f757fd5-98d1-490a-81a0-58b5798a5815",
"name": "before-upgrade",
"state": "NORMAL",
"percent": 100,
"diskSize": 40,
"createdAt": "2026-10-16T09:00:00.000Z",
"updatedAt": "2026-10-16T09:03:12.000Z"
}
],
"maxSnapshots": 2,
"totalSnapshots": 1
}
}maxSnapshots is the plan's limit. totalSnapshots counts every snapshot in the list, including failed ones.
Take a snapshot
/vps/:id/snapshotsProp
Type
curl -X POST https://api.helipod.io/api/vps/1f757fd5-98d1-490a-81a0-58b5798a5815/snapshots \
-H "Authorization: Bearer hel_your_key" \
-H "Content-Type: application/json" \
-d '{ "name": "before-upgrade" }'Response 201
{
"success": true,
"data": {
"id": "0e8b5c1d-6f3a-4b2e-9c7d-1a2b3c4d5e6f",
"instanceId": "1f757fd5-98d1-490a-81a0-58b5798a5815",
"name": "before-upgrade",
"state": "CREATING",
"percent": 0,
"createdAt": "2026-10-16T09:00:00.000Z"
}
}- The server must be
runningorstopped, and not busy. - A
namethat breaks the rule above answers400 INVALID_SNAPSHOT_NAMEand nothing is taken. - The limit counts snapshots in
NORMALstate. At the limit the call answers400 REQUEST_ERROR; delete one first. A plan withmaxSnapshots: 0has no snapshots. - The snapshot is taken in the background. Poll list snapshots until its
stateisNORMALorFAILED. Other changes to the server answer409 VPS_BUSYmeanwhile.
Roll back to a snapshot
/vps/:id/snapshots/:snapshotId/applyEverything written to the disk after the snapshot was taken is lost.
curl -X POST https://api.helipod.io/api/vps/1f757fd5-98d1-490a-81a0-58b5798a5815/snapshots/0e8b5c1d-6f3a-4b2e-9c7d-1a2b3c4d5e6f/apply \
-H "Authorization: Bearer hel_your_key"{
"success": true,
"data": {
"status": "pending",
"message": "Rollback in progress. Instance will restart."
}
}The snapshot must belong to this server and be finished. The server's status becomes provisioning and returns to the status it had before the call when the rollback is done; poll GET /vps/:id. If the rollback fails, the server also goes back to its previous status, and lastJobError explains why.
Errors: 409 VPS_BUSY; 400 REQUEST_ERROR when the snapshot does not belong to this server or is still being taken.
Delete a snapshot
/vps/snapshots/:snapshotIdThe path has no server id: the snapshot id is enough.
curl -X DELETE https://api.helipod.io/api/vps/snapshots/0e8b5c1d-6f3a-4b2e-9c7d-1a2b3c4d5e6f \
-H "Authorization: Bearer hel_your_key"{
"success": true,
"data": { "status": "pending", "message": "Deletion in progress" }
}The snapshot is removed in the background and disappears from the list when done.
An unknown snapshot, or one whose server the key cannot reach, answers 404 SNAPSHOT_NOT_FOUND. While the server is busy, including while a snapshot of it is being taken, the call answers 409 VPS_BUSY.