Snapshots¶

A snapshot is a copy of a server's disk at one moment. Take one before a risky change, restore it if the change goes wrong, or create a new server from it.

Endpoints¶

Endpoint	What it does
POST `/projects/{slug}/servers/{id}/actions/create-snapshot/`	Take a snapshot
POST `/projects/{slug}/servers/{id}/actions/restore-snapshot/`	Restore a snapshot
GET `/projects/{slug}/snapshots/`	List snapshots
GET `/projects/{slug}/snapshots/{id}/`	Get a snapshot
PATCH `/projects/{slug}/snapshots/{id}/`	Rename a snapshot
DELETE `/projects/{slug}/snapshots/{id}/`	Delete a snapshot

The snapshot object¶

{
  "id": 2958,
  "name": "before upgrade",
  "status": "completed",
  "state": "completed",
  "size_gb": 12.5,
  "server_id": "4c63f6",
  "image": "almalinux9",
  "created_at": "2026-10-19T10:00:00Z",
  "error": null
}

Field	Type	Description
`id`	integer	The snapshot's id.
`name`	string	Its name, which you can change.
`status`	string	`pending` while it is being taken, then `completed` or `failed`.
`state`	string	A finer-grained step of the same progress, for display. Act on `status`.
`size_gb`	number	Its size.
`server_id`	string	The server it was taken from.
`image`	string	The image that server was installed with.
`created_at`	string	When it was taken.
`error`	object or null	On `failed`: a `code` and a fixed `message` saying why. Otherwise `null`.

Reading, renaming and deleting¶

List snapshots¶

GET /projects/{slug}/snapshots/

Any member · Read-only keys: yes · Returns 200 Snapshot[]

The project's snapshots, of all its servers.

Get a snapshot¶

GET /projects/{slug}/snapshots/{id}/

Any member · Read-only keys: yes · Returns 200 Snapshot

One snapshot.

Rename a snapshot¶

PATCH /projects/{slug}/snapshots/{id}/

Any member · Read-only keys: no · Returns 200 Snapshot

Change the snapshot's name, 1 to 255 characters.

{"name": "before upgrade"}

Delete a snapshot¶

DELETE /projects/{slug}/snapshots/{id}/

Any member · Read-only keys: no · Returns 204

Delete the snapshot. It can't be recovered.

Taking and restoring¶

Both are actions, and exclusive: a server takes or restores one snapshot at a time, and not during another exclusive action. Send an Idempotency-Key with each.

Take a snapshot¶

POST /projects/{slug}/servers/{id}/actions/create-snapshot/

Any member · Read-only keys: no · Returns 202 Action

Take a snapshot of the server's disk. The request takes no body. Once the action has succeeded, its result has the new snapshot's id when it can be told, as {"snapshot_id": 2960}; the snapshot list shows it either way.

Your account can hold a limited number of snapshots: one more answers 409 snapshot_limit_reached, so delete one first. A legacy server can't take snapshots, and answers 409 not_eligible.

Restore a snapshot¶

POST /projects/{slug}/servers/{id}/actions/restore-snapshot/

Any member · Read-only keys: no · Returns 202 Action

Overwrite the server's disk with a snapshot.

Warning

Everything written to the server's disk since the snapshot was taken is lost.

{"snapshot_id": 2958}

The snapshot must be one of the project's, and completed; any other answers 400 validation_error.

New servers from a snapshot¶

To create a new server from a snapshot, order a server with its snapshot_id instead of an image.

Errors¶

Status	Code	When
400	`validation_error`	A field is invalid, or the snapshot to restore isn't the project's or isn't `completed`.
403	`read_only_key`	A change with a read-only key.
403	`project_not_ready`	The project is still being set up.
404	`not_found`	No such snapshot or server in the project.
409	`action_in_progress`	Another exclusive action is running on the server.
409	`snapshot_limit_reached`	Your account has as many snapshots as it can hold.
409	`not_eligible`	A legacy server can't take snapshots.
502	`upstream_error`	A system behind the API failed.