VPS.org API

REST API Documentation

Snapshots API

Take labelled snapshots of a server, list them and delete the ones you no longer need.

Endpoints 4
Base Path /api/v1/snapshots
GET /api/v1/snapshots/

List All Snapshots

Returns the snapshots in your account, newest first, 25 per page.

Required permission: snapshots:list

Example Request

cURL
Python
JavaScript
curl -X GET "https://admin.vps.org/api/v1/snapshots/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
import requests

url = "https://admin.vps.org/api/v1/snapshots/"
headers = {"Authorization": "Bearer YOUR_API_TOKEN"}

response = requests.get(url, headers=headers)
for snapshot in response.json()["results"]:
    print(snapshot["uuid"], snapshot["label"], snapshot["ready"])
const response = await fetch('https://admin.vps.org/api/v1/snapshots/', {
  headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' }
});

const data = await response.json();
console.log(data.results);

Example Response

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "uuid": "3f9a1c0e5b7d4e2f8a6c1b3d5e7f9a0b",
      "label": "before-upgrade",
      "server_hostname": "web-01",
      "ready": true,
      "deleting": false,
      "created_at": "2026-09-14T18:30:00.000000Z",
      "size_gb": 3.4
    }
  ]
}

Response Fields

Field Type Description
uuid string Snapshot identifier (32 hexadecimal characters, no hyphens)
label string Label given when the snapshot was created
server_hostname string Hostname of the server the snapshot was taken from, or null if that server no longer exists
ready boolean True once the snapshot has finished
deleting boolean True while a deletion is in progress
created_at datetime Creation time (ISO 8601, UTC)
size_gb number Compressed size in gigabytes
GET /api/v1/snapshots/{uuid}/

Get a Snapshot

Returns one snapshot object with the fields above. Use it to poll ready after creating a snapshot.

curl -X GET "https://admin.vps.org/api/v1/snapshots/3f9a1c0e5b7d4e2f8a6c1b3d5e7f9a0b/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
POST /api/v1/servers/{uuid}/snapshot/

Create a Snapshot

Queues a snapshot of a deployed server and returns the new snapshot's uuid. The snapshot is listed straight away with ready set to false.

Required permission: servers:snapshot

Request Body Parameters

Parameter Type Required Description
action string Yes Must be snapshot
snapshot_label string Yes A label to recognise the snapshot by
cURL
Python
curl -X POST "https://admin.vps.org/api/v1/servers/8c4f2a1e-5b3d-4e6f-9a7b-1c2d3e4f5a6b/snapshot/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action": "snapshot", "snapshot_label": "before-upgrade"}'
import requests

server_uuid = "8c4f2a1e-5b3d-4e6f-9a7b-1c2d3e4f5a6b"
url = f"https://admin.vps.org/api/v1/servers/{server_uuid}/snapshot/"
headers = {"Authorization": "Bearer YOUR_API_TOKEN"}
data = {"action": "snapshot", "snapshot_label": "before-upgrade"}

response = requests.post(url, headers=headers, json=data)
print(response.json()["snapshot_uuid"])

Example Response

{
  "message": "Snapshot queued successfully",
  "snapshot_uuid": "3f9a1c0e5b7d4e2f8a6c1b3d5e7f9a0b"
}

Response Status Codes

200 The action was queued
400 action or snapshot_label missing, or the server is not deployed yet
402 No payment method on file, or unpaid invoices
404 Not found, or it belongs to another account
DELETE /api/v1/snapshots/{uuid}/

Delete a Snapshot

Queues the snapshot for permanent deletion. deleting is true until it is gone.

Required permission: snapshots:delete

curl -X DELETE "https://admin.vps.org/api/v1/snapshots/3f9a1c0e5b7d4e2f8a6c1b3d5e7f9a0b/" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
{
  "message": "Snapshot deletion queued"
}

Response Status Codes

202 Accepted: the request was queued
404 Not found, or it belongs to another account

Notes