Client API: Container Apps: Snapshots

The 5 Client API operations for snapshots.

View as Markdown

Operations

Method	Path	Summary
GET	`/api/v1/client/servers/{uuid}/snapshots`	List snapshots
POST	`/api/v1/client/servers/{uuid}/snapshots`	Take a snapshot of this server
GET	`/api/v1/client/servers/{uuid}/snapshots/estimate`	How much of the allowance a snapshot of this server would use
GET	`/api/v1/client/servers/{uuid}/snapshots/seed`	The restore a server ordered from a snapshot is waiting on, or got
POST	`/api/v1/client/servers/{uuid}/snapshots/seed/retry`	Run a failed seed again

List snapshots

Section titled List snapshots

GET /api/v1/client/servers/{uuid}/snapshots

Snapshots taken from this server or, with scope=account, every snapshot the account holds, each judged for restoring onto this server.

The account scope is what lets a customer standing on their new Ashburn server see the snapshot they took in Frankfurt, without leaving the panel.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Section titled Parameters

Name	In	Type	Required	Description
`uuid`	path	string	yes
`scope`	query	string	no	Default: `this`.

Responses

Section titled Responses

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

A 200 response is a list; each item has these fields:

Field	Type
`[].id`	integer
`[].uuid`	string
`[].name`	string
`[].kind`	string
`[].status`	string
`[].size_bytes`	integer
`[].is_locked`	boolean
`[].created_by`	string
`[].reason`	string or null
`[].region`	string or null
`[].checksum`	string or null
`[].checksum_type`	string or null
`[].error`	string or null
`[].hold_reason`	string or null
`[].source_id`	integer or null
`[].source_uuid`	string or null
`[].source_server_name`	string or null
`[].source_name`	string or null
`[].source_location`	string or null
`[].source_used_bytes`	integer or null
`[].source_deleted`	boolean
`[].egg_id`	integer or null
`[].software`	SnapshotSoftware or null
`[].software.slug`	string or null
`[].software.name`	string or null
`[].software.mcjars_type`	string or null
`[].software.loader`	string or null
`[].software.loader_family`	string or null
`[].software.game`	string or null
`[].software.edition`	string or null
`[].software.version`	string or null
`[].software.runtime_template_slug`	string or null
`[].software.docker_image`	string or null
`[].software.modpack`	object or null
`[].software.memory_mb`	integer or null
`[].software.disk_mb`	integer or null
`[].software.inferred`	boolean
`[].software_label`	string
`[].software_slug`	string or null
`[].software_version`	string or null
`[].compatibility`	SnapshotCompatibility or null
`[].compatibility.level`	string
`[].compatibility.reason`	string
`[].is_source`	boolean or null
`[].schedule_uuid`	string or null
`[].schedule_name`	string or null
`[].created_at`	string (date-time)
`[].completed_at`	string (date-time) or null

Take a snapshot of this server

Section titled Take a snapshot of this server

POST /api/v1/client/servers/{uuid}/snapshots

Take a snapshot of this server.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Section titled Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Request body

Section titled Request body

application/json (required)

Field	Type	Required
`name`	string	yes
`ignored_files`	array of string or null	no
`is_locked`	boolean	no

Responses

Section titled Responses

Status	Meaning
`201`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 201 response:

Field	Type
`id`	integer
`uuid`	string
`name`	string
`kind`	string
`status`	string
`size_bytes`	integer
`is_locked`	boolean
`created_by`	string
`reason`	string or null
`region`	string or null
`checksum`	string or null
`checksum_type`	string or null
`error`	string or null
`hold_reason`	string or null
`source_id`	integer or null
`source_uuid`	string or null
`source_server_name`	string or null
`source_name`	string or null
`source_location`	string or null
`source_used_bytes`	integer or null
`source_deleted`	boolean
`egg_id`	integer or null
`software`	SnapshotSoftware or null
`software.slug`	string or null
`software.name`	string or null
`software.mcjars_type`	string or null
`software.loader`	string or null
`software.loader_family`	string or null
`software.game`	string or null
`software.edition`	string or null
`software.version`	string or null
`software.runtime_template_slug`	string or null
`software.docker_image`	string or null
`software.modpack`	object or null
`software.memory_mb`	integer or null
`software.disk_mb`	integer or null
`software.inferred`	boolean
`software_label`	string
`software_slug`	string or null
`software_version`	string or null
`compatibility`	SnapshotCompatibility or null
`compatibility.level`	string
`compatibility.reason`	string
`is_source`	boolean or null
`schedule_uuid`	string or null
`schedule_name`	string or null
`created_at`	string (date-time)
`completed_at`	string (date-time) or null

How much of the allowance a snapshot of this server would use

Section titled How much of the allowance a snapshot of this server would use

GET /api/v1/client/servers/{uuid}/snapshots/estimate

How much of the allowance a snapshot of this server would use.

Its own endpoint rather than a field on the listing: the figure is read live from Wings, so folding it in would make the snapshots tab as slow as the slowest node on the fleet, on every load, to answer a question only the create dialog asks.

An over-estimate on purpose: the server's current uncompressed disk usage. An archive is never larger than what it archives, so a creation that fits on this number cannot push the account over, which is the property the retention policy depends on.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Section titled Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Responses

Section titled Responses

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

The restore a server ordered from a snapshot is waiting on, or got

Section titled The restore a server ordered from a snapshot is waiting on, or got

GET /api/v1/client/servers/{uuid}/snapshots/seed

The restore a server ordered from a snapshot is waiting on, or got.

Null for a server ordered the ordinary way. The panel shows "restoring your snapshot" while it is pending or running, and the reason with a retry when it failed.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Section titled Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Responses

Section titled Responses

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type
`uuid`	string
`snapshot_uuid`	string
`snapshot_name`	string or null
`snapshot_software_label`	string
`snapshot_size_bytes`	integer or null
`status`	string
`error`	string or null
`attempts`	integer
`created_at`	string (date-time) or null
`started_at`	string (date-time) or null
`finished_at`	string (date-time) or null

Run a failed seed again

Section titled Run a failed seed again

POST /api/v1/client/servers/{uuid}/snapshots/seed/retry

Run a failed seed again. The snapshot is unharmed by a failed restore.

Authentication: an access token, sent as Authorization: Bearer <token>.

Parameters

Section titled Parameters

Name	In	Type	Required
`uuid`	path	string	yes

Responses

Section titled Responses

Status	Meaning
`200`	Success.
`422`	The request is not valid. `detail` lists each problem.

Fields of a 200 response:

Field	Type
`uuid`	string
`snapshot_uuid`	string
`snapshot_name`	string or null
`snapshot_software_label`	string
`snapshot_size_bytes`	integer or null
`status`	string
`error`	string or null
`attempts`	integer
`created_at`	string (date-time) or null
`started_at`	string (date-time) or null
`finished_at`	string (date-time) or null