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 or null	A finer-grained step of the same progress, for display, such as `uploading`. More may be added: act on `status`.
`size_gb`	number or null	Its size, or `null` while it isn't known.
`server_id`	string or null	The server it was taken from.
`image`	string or null	The image that server was installed with.
`created_at`	string	When it was taken.
`error`	object or null	On `failed`: a `code`, which is `failed`, and a `message` that says to take a new snapshot, and to contact support with this one's id if that fails too. More codes may be added. 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, oldest first. A snapshot belongs to the project: you can restore it onto any of the project's servers, and it stays when the server it was taken from is gone.

Get a snapshot¶

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

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

One snapshot. Poll it while it is pending.

Rename a snapshot¶

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

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

Change the snapshot's name, 1 to 250 characters. Nothing else about it can change.

{"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, and it no longer counts against the project owner's snapshot limit.

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. The snapshot is pending in the list while it is taken, and the action succeeds once it is completed. 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.

The project owner's account can hold a limited number of snapshots, across all the owner's projects: one more answers 409 snapshot_limit_reached. Delete one of this project's snapshots, or ask the owner to delete one elsewhere. Failed snapshots don't count. 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 on the server's disk now is lost: the snapshot replaces all of it, even when it was taken of another server.

{"snapshot_id": 2958}

The snapshot must be one of the project's, and completed. It can be of this server or of another one. Any other answers 400 validation_error.

A restore that ends in error may have changed the disk already. Check the server before you use it.

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	`billing_account_required`	The project's owner has no billing account.
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	`idempotency_key_reused`	The key was used for another request.
409	`snapshot_limit_reached`	The project owner's 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.
503	`upstream_unavailable`	A system behind the API is unavailable for now. Try again after `Retry-After`.
503	`node_maintenance`	The server's host is in maintenance.