VM: Snapshots and export
Section titled “VM: Snapshots and export”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.
Snapshots
Section titled “Snapshots”GET /api/v1/vm/vms/{name}/snapshots
Section titled “GET /api/v1/vm/vms/{name}/snapshots”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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | Yes | The VM name: lowercase letters, digits and -, starting with a letter or digit, at most 63 characters. |
This endpoint takes no request body.
Responses
Section titled “Responses”Media type: application/json
The VM’s snapshots. Each item has:
| Field | Type | Required | Description |
|---|---|---|---|
label | string | Yes | The snapshot’s label. |
created_unix | integer | Yes | When the snapshot was taken, in seconds since the Unix epoch. |
disk_bytes | integer | Yes | Size of the captured disk, in bytes. |
nvram_bytes | integer | No | Size of the captured UEFI varstore, in bytes. Absent when the VM had no varstore when the snapshot was taken. |
tpm_bytes | integer | No | Size of the captured vTPM state, in bytes. Absent when the VM had no vTPM when the snapshot was taken. |
restorable | boolean | Yes | Whether restoring this snapshot onto the VM as it is now would be accepted, using the same rule the restore enforces. |
blocked_reason | string | No | Why 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" }]Media type: application/json
{ "error": { "code": "NameInvalid", "message": "The VM name does not match the naming rule", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NameInvalid | Invalid VM name | The VM name does not match the naming rule. | Use lowercase letters, digits and -, starting with a letter or digit, at most 63 characters. |
SpecInvalid | Unexpected query parameters | The request carried query parameters, which this operation does not accept. | Remove all query parameters and send the request again. |
Media type: application/json
{ "error": { "code": "NotFound", "message": "vm web-01 does not exist", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NotFound | VM not found | No VM has this name. | Check the VM name and list the VMs on the computer. |
Media type: application/json
{ "error": { "code": "OperationInProgress", "message": "Another operation is in progress for this VM", "retryable": true }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
OperationInProgress | Operation in progress | Another operation is in progress on this VM. | Wait for it to finish, then retry. |
BadState | Wrong VM state | The VM is in a state that does not allow this command. | Bring the VM to a state the service can manage, then retry. |
Orphaned | Service cannot manage the VM | The service cannot verify the VM’s run, or the VM has been blocked; the guest may still be running. | Check the process yourself, then call forceAdopt to resume managing the VM or forceMarkDead to record it as dead, which is accepted only when the VM’s disk is not locked by a running process. For a blocked VM, resolve the condition named in the message, then restart hoody-vm, which settles the VM’s state as it starts. |
Media type: application/json
{ "error": { "code": "StorageFailed", "message": "storage operation failed", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
StorageFailed | Storage operation failed | The storage operation failed on the computer. | Check free space and the storage backing the VM, then retry. |
curl -X GET "https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/web-01/snapshots" \ -H 'Accept: application/json'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' });
const name = 'web-01';const snapshots = await client.vm.snapshots.list(name);POST /api/v1/vm/vms/{name}/snapshots
Section titled “POST /api/v1/vm/vms/{name}/snapshots”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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | Yes | The VM name: lowercase letters, digits and -, starting with a letter or digit, at most 63 characters. |
Request body
Section titled “Request body”| Field | Type | Required | Description |
|---|---|---|---|
label | string | Yes | Snapshot 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"}Responses
Section titled “Responses”Media type: application/json
Snapshot created.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | The VM’s name. |
label | string | Yes | The snapshot’s label. |
disk_bytes | integer | Yes | Size of the captured disk, in bytes. |
nvram_bytes | integer | No | Size of the captured UEFI varstore, in bytes. Absent when this VM has no UEFI varstore. |
tpm_bytes | integer | No | Size of the captured vTPM state, in bytes. Absent when this VM has no vTPM. |
reflinked | boolean | Yes | True 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. |
warnings | array of string | No | Non-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}Media type: application/json
{ "error": { "code": "NameInvalid", "message": "The snapshot label does not match the naming rule", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NameInvalid | Invalid name or label | The VM name or the label does not match the naming rule. | Use 1 to 63 lowercase letters, digits and -, starting with a letter or digit, for both the VM name and the label. |
SpecInvalid | Unexpected query parameters | The request carried query parameters, which this operation does not accept. | Remove all query parameters and send the request again. |
Media type: application/json
{ "error": { "code": "NotFound", "message": "vm web-01 does not exist", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NotFound | VM not found | No VM has this name. | Check the VM name and list the VMs on the computer. |
Media type: application/json
{ "error": { "code": "RequestBodyStalled", "message": "The request body stopped arriving", "retryable": true }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
RequestBodyStalled | Request body stalled | The request body stopped arriving. | Send the request again with the complete body. |
Media type: application/json
{ "error": { "code": "BadState", "message": "vm is Running and cannot accept this command", "retryable": true }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
AlreadyExists | Label already used | This VM already has a snapshot with that label. | Choose a different label, or delete the existing snapshot first. |
BadState | Wrong VM state | The VM is not stopped, or its create failed. | Stop the VM and wait until it reads Stopped, then retry. If the VM’s create failed, fix the create first. |
SourceBusy | Process cannot be confirmed stopped | The VM’s process cannot be confirmed stopped. | Wait for the process to stop, then retry. |
OperationInProgress | Operation in progress | The VM is being deleted or created, or the VM has just been created and is not ready to be managed yet. | Wait and retry shortly. |
Orphaned | Service cannot manage the VM | The service cannot verify the VM’s run, or the VM has been blocked; the guest may still be running. | Check the process yourself, then call forceAdopt to resume managing the VM or forceMarkDead to record it as dead, which is accepted only when the VM’s disk is not locked by a running process. For a blocked VM, resolve the condition named in the message, then restart hoody-vm, which settles the VM’s state as it starts. |
Media type: application/json
{ "error": { "code": "StorageFailed", "message": "storage operation failed", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
StorageFailed | Storage operation failed | The storage operation failed on the computer. | Check free space and the storage backing the VM, then retry. |
Media type: application/json
The need and have values report the required and available byte counts.
{ "error": { "code": "InsufficientSpace", "message": "Not enough storage to capture the snapshot", "need": 5368709120, "have": 4294967296, "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
InsufficientSpace | Not enough storage | There is not enough storage to capture the snapshot. | Free storage space on the computer, or remove other snapshots, then retry. |
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"}'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' });
const name = 'web-01';const snapshot = await client.vm.snapshots.create(name, { 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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | Yes | The VM name: lowercase letters, digits and -, starting with a letter or digit, at most 63 characters. |
label | path | string | Yes | The snapshot’s label: 1 to 63 lowercase letters, digits and -, starting with a letter or digit. |
This endpoint takes no request body.
Responses
Section titled “Responses”Media type: application/json
Restored. The VM’s state is now the returned generation.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | The VM’s name. |
label | string | Yes | The snapshot that was restored. |
generation | integer | Yes | The 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_bytes | integer | Yes | Size of the restored disk, in bytes. |
nvram_bytes | integer | No | Size of the UEFI varstore this restore put back, in bytes. Absent when the snapshot had none. |
tpm_bytes | integer | No | Size 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}Media type: application/json
{ "error": { "code": "NameInvalid", "message": "The VM name does not match the naming rule", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NameInvalid | Invalid VM name | The VM name does not match the naming rule. | Use lowercase letters, digits and -, starting with a letter or digit, at most 63 characters. |
SpecInvalid | Unexpected query parameters | The request carried query parameters, which this operation does not accept. | Remove all query parameters and send the request again. |
Media type: application/json
{ "error": { "code": "NotFound", "message": "snapshot before-upgrade of vm web-01 does not exist", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NotFound | VM or snapshot not found | There is no such VM or no such snapshot. | Check the VM name and the snapshot label in the snapshot list. |
Media type: application/json
{ "error": { "code": "BadState", "message": "vm is Running and cannot accept this command", "retryable": true }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BadState | Wrong VM state or incompatible snapshot | The VM is not stopped, or the snapshot cannot be restored onto it as it is now. | A restore needs no running process and no operation in progress, normally the Stopped state. A Failed VM whose launch left no process also qualifies. Check restorable and blocked_reason in the snapshot list and resolve the mismatch before retrying. |
SourceBusy | Process cannot be confirmed stopped | The VM’s process cannot be confirmed stopped. | Wait for the process to stop, then retry. |
OperationInProgress | Operation in progress | The VM is being deleted or created, or the VM has just been created and is not ready to be managed yet. | Wait and retry shortly. |
Orphaned | Service cannot manage the VM | The service cannot verify the VM’s run, or the VM has been blocked; the guest may still be running. | Check the process yourself, then call forceAdopt to resume managing the VM or forceMarkDead to record it as dead, which is accepted only when the VM’s disk is not locked by a running process. For a blocked VM, resolve the condition named in the message, then restart hoody-vm, which settles the VM’s state as it starts. |
Media type: application/json
{ "error": { "code": "StorageFailed", "message": "storage operation failed", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
StorageFailed | Storage operation failed | The storage operation failed on the computer. | Check free space and the storage backing the VM, then retry. |
Media type: application/json
The need and have values report the required and available byte counts.
{ "error": { "code": "InsufficientSpace", "message": "Not enough storage to restore the snapshot", "need": 5368709120, "have": 4294967296, "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
InsufficientSpace | Not enough storage | There is not enough storage to restore the snapshot. | Free storage space on the computer, then retry. |
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'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' });
const name = 'web-01';const label = 'before-upgrade';const restored = await client.vm.snapshots.restore(name, label);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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | Yes | The VM name: lowercase letters, digits and -, starting with a letter or digit, at most 63 characters. |
label | path | string | Yes | The snapshot’s label: 1 to 63 lowercase letters, digits and -, starting with a letter or digit. |
This endpoint takes no request body.
Responses
Section titled “Responses”Media type: none
The snapshot was deleted. The response has no body.
Media type: application/json
{ "error": { "code": "NameInvalid", "message": "The snapshot label does not match the naming rule", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NameInvalid | Invalid name or label | The VM name or the label does not match the naming rule. | Use 1 to 63 lowercase letters, digits and -, starting with a letter or digit, for both the VM name and the label. |
SpecInvalid | Unexpected query parameters | The request carried query parameters, which this operation does not accept. | Remove all query parameters and send the request again. |
Media type: application/json
{ "error": { "code": "NotFound", "message": "snapshot before-upgrade of vm web-01 does not exist", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NotFound | VM or snapshot not found | There is no such VM or no such snapshot. | Check the VM name and the snapshot label in the snapshot list. |
Media type: application/json
{ "error": { "code": "OperationInProgress", "message": "An export of this snapshot is being prepared", "retryable": true }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
OperationInProgress | Operation in progress | An export of this snapshot is being declared, or the VM is still being created. | Wait for the export or the create to finish, then retry. |
BadState | Wrong VM state | The VM’s create failed, or its state does not allow this. | Bring the VM to a state the service can manage, then retry. |
Orphaned | Service cannot manage the VM | The service cannot verify the VM’s run, or the VM has been blocked; the guest may still be running. | Check the process yourself, then call forceAdopt to resume managing the VM or forceMarkDead to record it as dead, which is accepted only when the VM’s disk is not locked by a running process. For a blocked VM, resolve the condition named in the message, then restart hoody-vm, which settles the VM’s state as it starts. |
Media type: application/json
{ "error": { "code": "StorageFailed", "message": "storage operation failed", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
StorageFailed | Storage operation failed | The storage operation failed on the computer. | Check free space and the storage backing the VM, then retry. |
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'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' });
const name = 'web-01';const label = 'before-upgrade';await client.vm.snapshots.delete(name, label);Snapshot export
Section titled “Snapshot export”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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | Yes | The VM name: lowercase letters, digits and -, starting with a letter or digit, at most 63 characters. |
label | path | string | Yes | The snapshot’s label: 1 to 63 lowercase letters, digits and -, starting with a letter or digit. |
This endpoint takes no request body.
Responses
Section titled “Responses”Media type: application/json
Export ready, download it with the part download operation.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | The VM’s name. |
label | string | Yes | The snapshot’s label. |
bytes | integer | Yes | Total 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_size | integer | Yes | Size of every part except the last, in bytes. Fixed for the lifetime of this export. |
parts | integer | Yes | Number 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. |
sha256 | string | Yes | SHA-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_unix | integer | Yes | When 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}Media type: application/json
{ "error": { "code": "NameInvalid", "message": "The VM name does not match the naming rule", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NameInvalid | Invalid VM name | The VM name does not match the naming rule. | Use lowercase letters, digits and -, starting with a letter or digit, at most 63 characters. |
SpecInvalid | Unexpected query parameters | The request carried query parameters, which this operation does not accept. | Remove all query parameters and send the request again. |
Media type: application/json
{ "error": { "code": "NotFound", "message": "snapshot before-upgrade of vm web-01 does not exist", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NotFound | VM or snapshot not found | There is no such VM or no such snapshot. | Check the VM name and the snapshot label in the snapshot list. |
Media type: application/json
{ "error": { "code": "OperationInProgress", "message": "This snapshot is already being exported", "retryable": true }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
OperationInProgress | Operation in progress | This snapshot is already being exported, the VM is being deleted or created, or the VM has just been created and is not ready to be managed yet. | Wait and retry shortly. |
BadState | Wrong VM state | The VM was deleted and recreated under the same name during the call, or too many exports are being prepared at once. | Retry shortly. If the VM was recreated, declare the export again for the current VM. |
Orphaned | Service cannot manage the VM | The service cannot verify the VM’s run, or the VM has been blocked; the guest may still be running. | Check the process yourself, then call forceAdopt to resume managing the VM or forceMarkDead to record it as dead, which is accepted only when the VM’s disk is not locked by a running process. For a blocked VM, resolve the condition named in the message, then restart hoody-vm, which settles the VM’s state as it starts. |
Media type: application/json
{ "error": { "code": "StorageFailed", "message": "storage operation failed", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
StorageFailed | Storage operation failed | The storage operation failed on the computer. | Check free space and the storage backing the VM, then retry. |
Media type: application/json
The need and have values report the required and available byte counts.
{ "error": { "code": "InsufficientSpace", "message": "Not enough storage to prepare the export", "need": 5368709120, "have": 4294967296, "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
InsufficientSpace | Not enough storage | There is not enough storage to prepare the export. | Free storage space on the computer, then retry. |
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'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' });
const name = 'web-01';const label = 'before-upgrade';const snapshotExport = await client.vm.snapshots.export.create(name, label);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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | Yes | The VM name: lowercase letters, digits and -, starting with a letter or digit, at most 63 characters. |
label | path | string | Yes | The snapshot’s label: 1 to 63 lowercase letters, digits and -, starting with a letter or digit. |
part | path | integer | Yes | Zero-based part index. The part starts at byte offset part * part_size. |
This endpoint takes no request body.
Responses
Section titled “Responses”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.
Media type: application/json
{ "error": { "code": "SpecInvalid", "message": "The part index is past the last part", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NameInvalid | Invalid name or label | The VM name or the label does not match the naming rule. | Use 1 to 63 lowercase letters, digits and -, starting with a letter or digit, for both the VM name and the label. |
SpecInvalid | Invalid part index or unexpected query parameters | The part index is not a non-negative integer or is past the last part, or the request carried query parameters, which this operation does not accept. | Use a part index from 0 through parts - 1 as given by the export, and remove all query parameters. |
Media type: application/json
{ "error": { "code": "NotFound", "message": "snapshot before-upgrade of vm web-01 has no frozen export", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NotFound | VM, snapshot or export not found | There is no such VM, no such snapshot, or no frozen export. | Check the VM name and the snapshot label, and declare the export again if it was released. |
Media type: application/json
{ "error": { "code": "BadState", "message": "Too many part downloads are running at once", "retryable": true }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BadState | Wrong VM state or too many downloads | The VM was deleted and recreated under the same name since the export was prepared, the VM’s create failed, or too many part downloads are running at once. | Retry shortly when too many downloads are running. If the VM was recreated, declare the export again for the current VM. |
OperationInProgress | Operation in progress | The VM is still being created. | Wait and retry shortly. |
Orphaned | Service cannot manage the VM | The service cannot verify the VM’s run, or the VM has been blocked; the guest may still be running. | Check the process yourself, then call forceAdopt to resume managing the VM or forceMarkDead to record it as dead, which is accepted only when the VM’s disk is not locked by a running process. For a blocked VM, resolve the condition named in the message, then restart hoody-vm, which settles the VM’s state as it starts. |
Media type: application/json
{ "error": { "code": "StorageFailed", "message": "storage operation failed", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
StorageFailed | Storage operation failed | The storage operation failed on the computer. | Check free space and the storage backing the VM, then retry. |
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.binimport { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' });
const name = 'web-01';const label = 'before-upgrade';const part = 0;const partBytes = await client.vm.snapshots.export.getPart(name, label, part);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.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | Yes | The VM name: lowercase letters, digits and -, starting with a letter or digit, at most 63 characters. |
label | path | string | Yes | The snapshot’s label: 1 to 63 lowercase letters, digits and -, starting with a letter or digit. |
This endpoint takes no request body.
Responses
Section titled “Responses”Media type: none
The export was released. The response has no body.
Media type: application/json
{ "error": { "code": "NameInvalid", "message": "The snapshot label does not match the naming rule", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NameInvalid | Invalid name or label | The VM name or the label does not match the naming rule. | Use 1 to 63 lowercase letters, digits and -, starting with a letter or digit, for both the VM name and the label. |
SpecInvalid | Unexpected query parameters | The request carried query parameters, which this operation does not accept. | Remove all query parameters and send the request again. |
Media type: application/json
{ "error": { "code": "NotFound", "message": "snapshot before-upgrade of vm web-01 has no frozen export", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NotFound | VM, snapshot or export not found | There is no such VM, no such snapshot, or no frozen export. | Check the VM name and the snapshot label, and declare the export again if it was released. |
Media type: application/json
{ "error": { "code": "OperationInProgress", "message": "Another operation on this VM or snapshot is in progress", "retryable": true }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
OperationInProgress | Operation in progress | Another operation on this VM or snapshot is in progress. | Wait and retry shortly. |
BadState | Wrong VM state | The VM was deleted and recreated under the same name since the export was prepared. | Declare the export again for the current VM, then release it when the download is done. |
Orphaned | Service cannot manage the VM | The service cannot verify the VM’s run, or the VM has been blocked; the guest may still be running. | Check the process yourself, then call forceAdopt to resume managing the VM or forceMarkDead to record it as dead, which is accepted only when the VM’s disk is not locked by a running process. For a blocked VM, resolve the condition named in the message, then restart hoody-vm, which settles the VM’s state as it starts. |
Media type: application/json
{ "error": { "code": "StorageFailed", "message": "storage operation failed", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
StorageFailed | Storage operation failed | The storage operation failed on the computer. | Check free space and the storage backing the VM, then retry. |
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'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' });
const name = 'web-01';const label = 'before-upgrade';await client.vm.snapshots.export.delete(name, label);