Skip to content

Beta: these docs are still being updated. The next full update is on 18 November at 8 PM UTC. Docs in beta. Full update 18 Nov, 8 PM UTC.

Hoody.com

A snapshot captures a VM’s disk, UEFI varstore and vTPM state together as one labelled restore point. This page covers creating, listing, restoring and deleting snapshots of a single VM, and exporting a snapshot in parts so it can be imported elsewhere. A snapshot can only be taken of a stopped VM. A restore leaves the VM’s configuration, its share/ directory and its other snapshots untouched.

List a VM’s snapshots. Each entry says whether it can be restored onto the VM right now (restorable) and, if not, why (blocked_reason). The answer applies the same rule the restore enforces.

restorable reports compatibility with this VM only, nothing about the VM’s current state. It is false for a snapshot of another incarnation of this VM or of a different machine profile, for a snapshot missing the varstore or TPM state the VM needs, and for a snapshot whose manifest cannot be read. blocked_reason says which of these applies.

NameInTypeRequiredDescription
namepathstringYesThe VM name: lowercase letters, digits and -, starting with a letter or digit, at most 63 characters.

This endpoint takes no request body.

Media type: application/json

The VM’s snapshots. Each item has:

FieldTypeRequiredDescription
labelstringYesThe snapshot’s label.
created_unixintegerYesWhen the snapshot was taken, in seconds since the Unix epoch.
disk_bytesintegerYesSize of the captured disk, in bytes.
nvram_bytesintegerNoSize of the captured UEFI varstore, in bytes. Absent when the VM had no varstore when the snapshot was taken.
tpm_bytesintegerNoSize of the captured vTPM state, in bytes. Absent when the VM had no vTPM when the snapshot was taken.
restorablebooleanYesWhether restoring this snapshot onto the VM as it is now would be accepted, using the same rule the restore enforces.
blocked_reasonstringNoWhy the snapshot cannot be restored. Present exactly when restorable is false.
[
{
"label": "before-upgrade",
"created_unix": 1739318400,
"disk_bytes": 10737418240,
"nvram_bytes": 524288,
"tpm_bytes": 65536,
"restorable": true
},
{
"label": "old-profile",
"created_unix": 1738972800,
"disk_bytes": 10737418240,
"nvram_bytes": 524288,
"restorable": false,
"blocked_reason": "The VM's machine profile has changed since this snapshot was taken"
}
]
Terminal window
curl -X GET "https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/web-01/snapshots" \
-H 'Accept: application/json'

Capture a stopped VM’s disk, UEFI varstore and vTPM state together as one labelled snapshot, a restore point. The VM must be stopped; a running or unverified VM is refused. On btrfs the disk is shared with the live disk rather than copied, so the snapshot is near-instant and initially takes no extra space. reflinked in the response says which happened. Labels are unique per VM.

NameInTypeRequiredDescription
namepathstringYesThe VM name: lowercase letters, digits and -, starting with a letter or digit, at most 63 characters.
FieldTypeRequiredDescription
labelstringYesSnapshot label: 1 to 63 lowercase letters, digits and -, starting with a letter or digit. The same rule as a VM name. Unique per VM.
{
"label": "before-upgrade"
}

Media type: application/json

Snapshot created.

FieldTypeRequiredDescription
namestringYesThe VM’s name.
labelstringYesThe snapshot’s label.
disk_bytesintegerYesSize of the captured disk, in bytes.
nvram_bytesintegerNoSize of the captured UEFI varstore, in bytes. Absent when this VM has no UEFI varstore.
tpm_bytesintegerNoSize of the captured vTPM state, in bytes. Absent when this VM has no vTPM.
reflinkedbooleanYesTrue when the disk shares storage with the live disk instead of being copied, so the snapshot initially takes no extra space. False means it occupies the full size of the disk now.
warningsarray of stringNoNon-fatal problems noticed while taking the snapshot, as sentences. Absent when there are none.
{
"name": "web-01",
"label": "before-upgrade",
"disk_bytes": 10737418240,
"nvram_bytes": 524288,
"tpm_bytes": 65536,
"reflinked": true
}
Terminal window
curl -X POST "https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/web-01/snapshots" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{"label":"before-upgrade"}'

POST /api/v1/vm/vms/{name}/snapshots/{label}/restore

Section titled “POST /api/v1/vm/vms/{name}/snapshots/{label}/restore”

Roll a stopped VM back to this snapshot. The disk, UEFI varstore and vTPM state are replaced together in one atomic step, so after a crash the VM is either fully restored or untouched. The VM’s configuration, its share/ directory and its other snapshots are not changed.

The restore is refused if the machine profile has changed since the snapshot was taken, if the VM has UEFI firmware and the snapshot has no varstore, or if the VM has a vTPM and the snapshot has no TPM state. Check restorable in the snapshot list first.

A restore needs no running process and no operation in progress, which is normally the Stopped state. A Failed VM whose launch left no process also qualifies.

NameInTypeRequiredDescription
namepathstringYesThe VM name: lowercase letters, digits and -, starting with a letter or digit, at most 63 characters.
labelpathstringYesThe snapshot’s label: 1 to 63 lowercase letters, digits and -, starting with a letter or digit.

This endpoint takes no request body.

Media type: application/json

Restored. The VM’s state is now the returned generation.

FieldTypeRequiredDescription
namestringYesThe VM’s name.
labelstringYesThe snapshot that was restored.
generationintegerYesThe VM’s state generation after this restore. Only increases, 0 is the state the VM was created with. It lets a caller tell its own restore from someone else’s.
disk_bytesintegerYesSize of the restored disk, in bytes.
nvram_bytesintegerNoSize of the UEFI varstore this restore put back, in bytes. Absent when the snapshot had none.
tpm_bytesintegerNoSize of the vTPM state this restore put back, in bytes. Absent when the snapshot had none.
{
"name": "web-01",
"label": "before-upgrade",
"generation": 4,
"disk_bytes": 10737418240,
"nvram_bytes": 524288,
"tpm_bytes": 65536
}
Terminal window
curl -X POST "https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/web-01/snapshots/before-upgrade/restore" \
-H 'Accept: application/json'

DELETE /api/v1/vm/vms/{name}/snapshots/{label}

Section titled “DELETE /api/v1/vm/vms/{name}/snapshots/{label}”

Delete one snapshot. The VM’s current state is not affected. On btrfs, only the space the snapshot does not share with the live disk is freed. The request is refused while an export of this snapshot is being declared.

NameInTypeRequiredDescription
namepathstringYesThe VM name: lowercase letters, digits and -, starting with a letter or digit, at most 63 characters.
labelpathstringYesThe snapshot’s label: 1 to 63 lowercase letters, digits and -, starting with a letter or digit.

This endpoint takes no request body.

Media type: none

The snapshot was deleted. The response has no body.

Terminal window
curl -X DELETE "https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/web-01/snapshots/before-upgrade" \
-H 'Accept: application/json'

An export is a portable artifact that contains a snapshot’s disk, UEFI varstore, vTPM state and manifest, identified by a single sha256. Empty regions of the disk are skipped, so the artifact is usually much smaller than the disk.

POST /api/v1/vm/vms/{name}/snapshots/{label}/export

Section titled “POST /api/v1/vm/vms/{name}/snapshots/{label}/export”

Prepare a snapshot for download as one portable artifact containing its disk, UEFI varstore, vTPM state and manifest, identified by a single sha256. Empty regions of the disk are skipped, so the artifact is usually much smaller than the disk. The response gives the size, part_size, the number of parts and the sha256. Download the parts, then import the artifact elsewhere with the snapshot import operation.

The call is idempotent: calling it again returns the same export. No copy is made on disk. While the call is running, the snapshot and the VM cannot be deleted. Preparing an export hashes the whole disk, which can take a while for large disks. Release the export when the download is complete.

NameInTypeRequiredDescription
namepathstringYesThe VM name: lowercase letters, digits and -, starting with a letter or digit, at most 63 characters.
labelpathstringYesThe snapshot’s label: 1 to 63 lowercase letters, digits and -, starting with a letter or digit.

This endpoint takes no request body.

Media type: application/json

Export ready, download it with the part download operation.

FieldTypeRequiredDescription
namestringYesThe VM’s name.
labelstringYesThe snapshot’s label.
bytesintegerYesTotal size of the artifact in bytes, including its framing and header. Empty disk regions are not included, so this is usually well below the sum of the components’ sizes.
part_sizeintegerYesSize of every part except the last, in bytes. Fixed for the lifetime of this export.
partsintegerYesNumber of parts: ceil(bytes / part_size). Part indexes run from 0 through parts - 1. Part n covers [n*part_size, min((n+1)*part_size, bytes)), and the last part may be shorter.
sha256stringYesSHA-256 of the whole artifact, framing, header and contents. The disk, varstore and vTPM state are not addressable separately, the artifact is imported as one unit.
created_unixintegerYesWhen the export was prepared, in seconds since the Unix epoch. Calling export again returns the same value.
{
"name": "web-01",
"label": "before-upgrade",
"bytes": 5242880,
"part_size": 1048576,
"parts": 5,
"sha256": "9f2c4a7d1e6b83c50fa9d472e8b61c3f5a0d97e2b4c86f135a7d92e0c8b461f3",
"created_unix": 1739318600
}
Terminal window
curl -X POST "https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/web-01/snapshots/before-upgrade/export" \
-H 'Accept: application/json'

GET /api/v1/vm/vms/{name}/snapshots/{label}/export/parts/{part}

Section titled “GET /api/v1/vm/vms/{name}/snapshots/{label}/export/parts/{part}”

Return part n of a prepared export as raw bytes. Part n starts at byte n * part_size, and every part except the last is exactly part_size bytes. Parts can be fetched in any order and fetched again, so an interrupted download resumes from any part. Join the parts in order and check the result against the export’s sha256.

A download whose client stops reading for 30 seconds, or that takes longer than 30 minutes, is cut off before the body is complete. Request the same part again.

NameInTypeRequiredDescription
namepathstringYesThe VM name: lowercase letters, digits and -, starting with a letter or digit, at most 63 characters.
labelpathstringYesThe snapshot’s label: 1 to 63 lowercase letters, digits and -, starting with a letter or digit.
partpathintegerYesZero-based part index. The part starts at byte offset part * part_size.

This endpoint takes no request body.

Media type: application/octet-stream

The body is the raw bytes of part n, returned as application/octet-stream. Every part except the last is exactly part_size bytes, and the last part may be shorter.

Terminal window
curl -X GET "https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/web-01/snapshots/before-upgrade/export/parts/0" \
-H 'Accept: application/octet-stream' \
--output part-000.bin

DELETE /api/v1/vm/vms/{name}/snapshots/{label}/export

Section titled “DELETE /api/v1/vm/vms/{name}/snapshots/{label}/export”

Release a prepared export. The snapshot itself is not affected. Any download in progress can no longer be resumed, and exporting again re-hashes the whole disk.

NameInTypeRequiredDescription
namepathstringYesThe VM name: lowercase letters, digits and -, starting with a letter or digit, at most 63 characters.
labelpathstringYesThe snapshot’s label: 1 to 63 lowercase letters, digits and -, starting with a letter or digit.

This endpoint takes no request body.

Media type: none

The export was released. The response has no body.

Terminal window
curl -X DELETE "https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/web-01/snapshots/before-upgrade/export" \
-H 'Accept: application/json'