VM: VMs
Section titled “VM: VMs”These endpoints manage virtual machines hosted by a Hoody computer. Use them to list VMs, inspect state and creation progress, create a VM, reconfigure a stopped VM, open a VM’s screen, or permanently delete a VM.
The service hostname identifies the target computer.
List VMs
Section titled “List VMs”GET /api/v1/vm/vms
Returns every known VM, including VMs whose creation is still in progress. Optional filters select lifecycle states and storage phases.
This endpoint accepts no request body.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
state | query | string | No | Comma-separated lifecycle states to keep, case-insensitive. For example, state=running or state=Failed,Orphaned. A VM that has no state yet counts as Creating. An unrecognised value is refused with 400 SpecInvalid. |
phase | query | string | No | Comma-separated storage phases to keep: committed or creating. An unrecognised value is refused with 400 SpecInvalid. |
Responses
Section titled “Responses”Media type: application/json
Returns every known VM, including creates still in progress.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
[] | array | Yes | Array of VM summaries. |
[].name | string | Yes | VM name. |
[].vm_id | string | No | VM identifier. |
[].phase | string | Yes | Storage phase, either committed or creating. |
[].state | string | No | Lifecycle state. A VM without a state counts as Creating. |
[].share | object | No | Disk usage for the VM’s share/ folder. It is absent until a measurement has completed, which does not mean the folder is empty. |
[].share.bytes | integer | Yes, when share is present | Allocated size in bytes. Reflinked data shared with the VM disk can be counted in both places, while a hard-linked file is counted once. |
[].share.partial | boolean | Yes, when share is present | Whether the measurement stopped early. When true, bytes is a lower bound rather than a total. |
[].share.sampled_unix | integer | Yes, when share is present | Time of the measurement in Unix seconds. |
[].share.quota_bytes | integer | No | Current share quota in bytes. It is absent when the share has no limit. |
[].share.over_quota | boolean | Yes, when share is present | Latched state left by the last quota crossing, not a comparison with the latest measurement. It becomes true when a measurement exceeds the quota, including a partial measurement. It becomes false only when a complete measurement is at or below quota - quota / 16, with integer division rounded down, or when the quota is removed. It can remain true below the quota. Changing the quota re-checks the last measurement and can change this state. Each change publishes one share-quota event. It is always false when there is no quota. |
[ { "name": "dev-vm", "vm_id": "0000019a3f5c2e11", "phase": "committed", "state": "Running", "share": { "bytes": 3221225472, "partial": false, "sampled_unix": 1767225600, "quota_bytes": 10737418240, "over_quota": false } }, { "name": "web-01", "vm_id": "0000019a3f5c2e13", "phase": "committed", "state": "Running", "share": { "bytes": 1073741824, "partial": false, "sampled_unix": 1767225600, "quota_bytes": 10737418240, "over_quota": false } }]Media type: application/json
The request contains an unrecognised filter value.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
error | object | Yes | Error envelope. |
error.code | string | Yes | Error code. Branch on this value rather than message. |
error.message | string | Yes | Human-readable explanation. |
error.retryable | boolean | Yes | Whether repeating the identical request could succeed without any other change. |
{ "error": { "code": "SpecInvalid", "message": "The state filter contains an unsupported lifecycle state.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
SpecInvalid | Invalid list filter | The request contains an unrecognised state or phase value. | Use only the lifecycle states and storage phases documented by the state and phase parameters. |
Media type: application/json
The storage operation failed.
Response fields
{ "error": { "code": "StorageFailed", "message": "The storage operation failed.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
StorageFailed | Storage operation failed | The service could not complete the storage operation. The error response has retryable set to false. | Resolve the storage condition before retrying the identical request. |
curl --request GET \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms?state=Running&phase=committed'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' });
const vms = await client.vm.vms.list({ state: 'Running', phase: 'committed' });console.log(vms.data);Get a VM
Section titled “Get a VM”GET /api/v1/vm/vms/{name}
Returns the VM’s current state, committed configuration, share measurement, and create progress when creation is still in progress.
This endpoint accepts no request body.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | Yes | VM name. It must contain lowercase letters, digits, and -, begin with a letter or digit, and be at most 63 characters long. |
Responses
Section titled “Responses”Media type: application/json
Returns the VM’s current state, its configuration, and, while it is being created, create progress.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | VM name. |
vm_id | string | No | VM identifier. |
state | string | Yes | Lifecycle state: Creating, Stopped, Starting, Running, Paused, Stopping, Failed, or Orphaned. |
reason | string | No | Prose reason for the current state. |
run | string | No | Identifier of the current run. |
progress | object | No | Create progress. |
progress.phase | string | Yes, when progress is present | Create phase: reserving, importing, committing, committed, or failed. |
progress.bytes_done | integer | Yes, when progress is present | Bytes processed so far. |
progress.bytes_total | integer | Yes, when progress is present | Total bytes to process. |
progress.fell_back | string | No | Set when reflink cloning was unavailable and the disk was fully copied instead. |
progress.warnings | array of string | No | Warnings about a create that succeeded, such as an identity or TPM difference introduced by cloning. |
progress.error | object | No | Present when progress.phase is failed. It contains the background create failure. |
progress.error.error | object | Yes, when progress.error is present | Nested error envelope. |
progress.error.error.code | string | Yes, when progress.error is present | Error code. |
progress.error.error.message | string | Yes, when progress.error is present | Human-readable explanation. |
progress.error.error.retryable | boolean | Yes, when progress.error is present | Whether repeating the identical request could succeed without any other change. |
sidecars | array | No | Health of the VM’s helper processes. It is omitted when empty. |
sidecars[].kind | string | Yes | Helper kind: passt, virtiofsd, or swtpm. |
sidecars[].state | string | Yes | Helper state: absent, starting, ready, degraded, or stopped. |
spec | object | No | Committed VM configuration. It can be absent during creation, when it cannot be read, or when it changed during four consecutive reads. Read again in that case. |
spec.memory_mib | integer | Yes, when spec is present | Guest RAM in MiB. |
spec.vcpus | integer | Yes, when spec is present | Number of virtual CPUs. |
spec.disk_bytes | integer | No | System disk size in bytes. It is absent when the size cannot be read. |
spec.firmware | string | Yes, when spec is present | Firmware: uefi, uefi-secure-boot, or bios. |
spec.bus | string | Yes, when spec is present | System disk controller: virtio or sata. |
spec.display_adapter | string | Yes, when spec is present | Guest display adapter: vga or virtio-vga. It is fixed when the VM is created, and new VMs use virtio-vga. |
spec.cpu | string | Yes, when spec is present | CPU model: qemu-default, westmere, or host. The portable creation setting produces westmere. |
spec.tpm | boolean | Yes, when spec is present | Whether the VM has a TPM 2.0. |
spec.file_sharing | boolean | Yes, when spec is present | Whether the share/ folder is shared into the guest. |
spec.agent | boolean | Yes, when spec is present | Whether the guest-agent channel is configured. |
spec.console | boolean | Yes, when spec is present | Whether the serial console is configured. |
spec.console_input | boolean | Yes, when spec is present | Whether console input is allowed. |
spec.audio | string | Yes, when spec is present | Audio device: none or output. |
spec.machine_type | string | Yes, when spec is present | QEMU machine type to which the VM is pinned. |
spec.display | integer | No | X display number. It is absent when the VM is headless. |
spec.cdroms | array of string or null | No | Attached read-only media in boot order. A null value is an empty slot. |
spec.autostart | boolean | Yes, when spec is present | Whether the VM starts automatically with the service. |
spec.disk_bps | integer | No | Disk throughput limit in bytes per second. It is absent when unlimited. |
spec.disk_iops | integer | No | Disk operations-per-second limit. It is absent when unlimited. |
spec.share_quota_bytes | integer | No | Share quota in bytes. It is absent when unlimited and is checked only when the VM starts. |
spec.ports | array | No | Inbound port forwards. It is absent when the VM accepts no inbound connections. |
spec.ports[].proto | string | No | Transport protocol: tcp or udp. Default: "tcp". |
spec.ports[].host | integer | Yes | Port opened on the computer’s addresses. It is shared by every VM in the computer. |
spec.ports[].guest | integer | Yes | Port on which the guest listens. |
spec.stop_grace_seconds | integer | No | How long a graceful stop waits before forcing the VM off, in seconds. It is absent when the default of 30 applies. |
display_url | string | No | Browser address of the VM’s display. It is present when the VM has a display and the request arrived through the computer’s VM URL. |
monitor_stalled | boolean | No | Whether the QMP monitor has stopped answering. It is omitted when false. |
seq | integer | No | VM event counter as of this response. It is absent when no events have been published for the VM. |
error | object | No | Typed reason the current run failed. The code is nested at error.error.code. |
error.error | object | Yes, when error is present | Nested error envelope. |
error.error.code | string | Yes, when error is present | Error code. |
error.error.message | string | Yes, when error is present | Human-readable explanation. |
error.error.retryable | boolean | Yes, when error is present | Whether repeating the identical request could succeed without any other change. |
share | object | No | Disk usage for the VM’s share/ folder. It is absent until a measurement has completed. |
share.bytes | integer | Yes, when share is present | Allocated size in bytes. Data shared by reflink between share/ and the VM’s disk is counted in both, so this can exceed what deleting the share would free. |
share.partial | boolean | Yes, when share is present | Whether the measurement stopped early. When true, bytes is a lower bound. |
share.sampled_unix | integer | Yes, when share is present | Time of the measurement in Unix seconds. |
share.quota_bytes | integer | No | Current share quota in bytes. |
share.over_quota | boolean | Yes, when share is present | Latched state left by the last quota crossing, not a comparison with the latest measurement. It becomes true when a measurement exceeds the quota, including a partial measurement. It becomes false only after a complete measurement is at or below quota - quota / 16, with integer division rounded down, or when the quota is removed. It can remain true below the quota. Changing the quota re-checks the last measurement and can change this state. Each change publishes one share-quota event. It is always false when there is no quota. |
Sequence note: seq is the VM’s event counter on state frames. A per-VM resync uses data.detail.seq when the detail has one. Otherwise, for example during creation or when a resync carries data.error, it repeats the stream’s last known seq. That repeated value does not prove the current counter, so read the VM again. It is 0 on the all-VMs stream’s resync, on the uncounted kinds progress, sidecar, qmp-error, snapshot, share-quota, monitor-stalled, and deleted, and on the state frame that ends a create. Process every resync whatever its seq.
{ "name": "dev-vm", "vm_id": "0000019a3f5c2e11", "state": "Stopped", "progress": { "phase": "committed", "bytes_done": 68719476736, "bytes_total": 68719476736, "warnings": [] }, "sidecars": [ { "kind": "passt", "state": "ready" }, { "kind": "virtiofsd", "state": "ready" }, { "kind": "swtpm", "state": "ready" } ], "spec": { "memory_mib": 4096, "vcpus": 4, "disk_bytes": 68719476736, "firmware": "uefi", "bus": "virtio", "display_adapter": "virtio-vga", "cpu": "westmere", "tpm": true, "file_sharing": true, "agent": true, "console": true, "console_input": true, "audio": "none", "machine_type": "q35", "display": 7, "autostart": false, "disk_bps": 104857600, "disk_iops": 1000, "share_quota_bytes": 10737418240, "ports": [ { "proto": "tcp", "host": 2222, "guest": 22 } ], "stop_grace_seconds": 60 }, "display_url": "https://{projectId}-{computerId}-display-7.{server}.computers.hoody.com", "seq": 12, "share": { "bytes": 3221225472, "partial": false, "sampled_unix": 1767225600, "quota_bytes": 10737418240, "over_quota": false }}Media type: application/json
The VM name is invalid, or the request contains query parameters that this operation does not accept.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
error | object | Yes | Error envelope. |
error.code | string | Yes | Error code. |
error.message | string | Yes | Human-readable explanation. |
error.retryable | boolean | Yes | Whether repeating the identical request could succeed without any other change. |
{ "error": { "code": "NameInvalid", "message": "The VM name does not match the required format.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NameInvalid | Invalid VM name | The name in the path does not match the required VM name format. | Use lowercase letters, digits, and -, begin with a letter or digit, and limit the name to 63 characters. |
SpecInvalid | Invalid request specification | The request contains query parameters, but this operation accepts none. | Remove all query parameters from the request. |
Media type: application/json
No VM has the requested name.
Response fields
{ "error": { "code": "NotFound", "message": "No VM has this name.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NotFound | VM not found | No VM has the requested name. | Confirm the VM name with the List VMs operation. |
Media type: application/json
The VM is not ready to be managed, another operation is active, or the service cannot verify the VM’s run.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
error | object | Yes | Error envelope. |
error.code | string | Yes | Error code. |
error.message | string | Yes | Human-readable explanation. |
error.retryable | boolean | Yes | Whether repeating the identical request could succeed without any other change. |
{ "error": { "code": "OperationInProgress", "message": "The VM was recently created and is not ready to be managed yet.", "retryable": true }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
OperationInProgress | Operation in progress | The VM has just been created and is not ready to be managed yet. | Retry shortly. |
BadState | VM state changed during the request | A create for this name failed while the VM was being read. | Read the VM again. |
Orphaned | VM run cannot be managed | The service cannot verify the VM’s run, or it has blocked the VM after finding multiple possible live runs or an indeterminate delete. The guest may still be running. The error message distinguishes the condition. | For an unverifiable run, check the process, then use forceAdopt or forceMarkDead; forceMarkDead is accepted only when the disk is not locked. For a blocked VM, both actions are refused. Resolve the condition named in the message and restart hoody-vm. |
Media type: application/json
The storage operation failed.
Response fields
{ "error": { "code": "StorageFailed", "message": "The storage operation failed.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
StorageFailed | Storage operation failed | The service could not complete the storage operation. The error response has retryable set to false. | Resolve the storage condition before retrying the identical request. |
curl --request GET \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/dev-vm'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' });
const vm = await client.vm.vms.get('dev-vm');console.log(vm.data.state);Open a VM’s display
Section titled “Open a VM’s display”GET /api/v1/vm/vms/{name}/display
Opens the VM’s screen in the browser. The route redirects to the computer’s display-N URL for the number in the VM’s spec.display, on the same server and domain as the request. With format=json it answers 200 with the VM’s name, its display number and that address instead.
The address is built from the URL the request arrived on, each time, and is never stored: call this route through the computer’s vm URL. When the request did not arrive through the computer’s vm URL, and for display 0, which has no browser address, there is no address: the redirect is refused with 400 SpecInvalid, and the JSON answer omits url but still carries display.
The address opens the computer’s display service, which applies its own access rules: being allowed to call this route does not grant access to the display, and the address carries no credentials. This route starts nothing. The page shows the VM while the VM is running; starting the VM starts its display if nothing is running on it.
This endpoint accepts no request body.
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. |
format | query | string | No | json answers 200 with {name, display, url} instead of redirecting. Absent: redirect. Any other value is refused with 400 SpecInvalid. |
Responses
Section titled “Responses”Media type: application/json
With format=json: the VM’s display number and its browser address. The answer carries name and display, and url when the VM has a browser address.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | VM name. |
display | integer | Yes | The VM’s X display number, as in spec.display. |
url | string | No | Browser address of that display. It is omitted when the request did not arrive through the computer’s vm URL, or for display 0, which has no browser address. |
{ "name": "dev-vm", "display": 7, "url": "https://{projectId}-{computerId}-display-7.{server}.computers.hoody.com"}Media type: not recorded
Redirects to the VM’s display. The address is in the Location response header, as a URI.
Media type: application/json
format has a value other than json, or the query has another key. For the redirect, there is no address to redirect to: the request did not arrive through the computer’s vm URL, or the VM’s display is 0.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
error | object | Yes | Error envelope. |
error.code | string | Yes | Error code. Branch on this value rather than message. |
error.message | string | Yes | Human-readable explanation. |
error.retryable | boolean | Yes | Whether repeating the identical request could succeed without any other change. |
{ "error": { "code": "SpecInvalid", "message": "The format query parameter must be json.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
SpecInvalid | Invalid display request | format has a value other than json, the query carries another key, or there is no address to redirect to because the request did not arrive through the computer’s vm URL or the VM’s display is 0. | Send only format=json, or call the route through the computer’s vm URL for a VM whose display is not 0. |
Media type: application/json
No VM has the requested name.
Response fields
{ "error": { "code": "NotFound", "message": "No VM has this name.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NotFound | VM not found | No VM has the requested name. | Confirm the VM name with the List VMs operation. |
Media type: application/json
The VM has no display, is not ready to be managed, its create failed, or the service cannot manage it.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
error | object | Yes | Error envelope. |
error.code | string | Yes | Error code. |
error.message | string | Yes | Human-readable explanation. |
error.retryable | boolean | Yes | Whether repeating the identical request could succeed without any other change. |
{ "error": { "code": "DisplayNotConfigured", "message": "The VM is headless and has no display to open.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
DisplayNotConfigured | VM has no display | The VM is headless, so it has no display address. | Give the VM a display with the Reconfigure a stopped VM operation while it is stopped. |
OperationInProgress | Operation in progress | The VM is still being created, or has just been created and is not ready to be managed yet. | Retry shortly. |
BadState | VM create failed | The VM’s create failed. | Delete the VM and create it again. |
Orphaned | VM run cannot be managed | The service cannot verify the VM’s run, or it has blocked the VM after finding multiple possible live runs or an indeterminate delete. The guest may still be running. The error message distinguishes the condition. | For an unverifiable run, check the process, then use forceAdopt or forceMarkDead; forceMarkDead is accepted only when the disk is not locked. For a blocked VM, both actions are refused. Resolve the condition named in the message and restart hoody-vm. |
Media type: application/json
The storage operation failed.
Response fields
{ "error": { "code": "StorageFailed", "message": "The storage operation failed.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
StorageFailed | Storage operation failed | The service could not complete the storage operation. The error response has retryable set to false. | Resolve the storage condition before retrying the identical request. |
curl --request GET \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/dev-vm/display'Add ?format=json to the query to receive the JSON answer instead of the redirect.
import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' });
const display = await client.vm.vms.getDisplay('dev-vm');console.log(display.data);Create a VM
Section titled “Create a VM”POST /api/v1/vm/vms
Creates a VM from a template, blank disk, ISO, offline disk image, existing VM disk, or snapshot artifact.
Request body
Section titled “Request body”VM fields
Section titled “VM fields”| Name | Type | Required | Description |
|---|---|---|---|
name | string | Yes | VM name. It must match ^[a-z0-9][a-z0-9-]{0,62}$. |
source | object | Yes | Tagged disk source. Its type must be one of the six values in the source union below. |
memory_mib | integer | Yes | Guest RAM in MiB. Minimum: 1. It is required even for a snapshot-artifact source because an artifact does not record sizing. |
vcpus | integer | Yes | Number of virtual CPUs. Minimum: 1, maximum: 4096. It is required even for a snapshot-artifact source. |
firmware | string | No | Firmware: uefi or bios. Default: "uefi". It is fixed at creation. With a snapshot-artifact source, the artifact’s firmware is used. A matching value is accepted, but bios against a UEFI artifact is refused. |
bus | string | No | System disk controller: virtio or sata. Default: "virtio", except with a windows-* os on a host without the virtio-win driver ISO, where it is sata. It is fixed at creation. With a snapshot-artifact source, bus must be explicitly set. It must be the bus on which the guest was installed, because the wrong bus can leave the guest unable to boot and cannot be changed later. Omitting it for this source is refused with 400. |
display | integer or string | No | X display from 0 to 65535. The forms 7, "7", and ":7" select the same display. "auto" selects the lowest free display in the automatic range. Omitting it creates a headless VM. |
display_id | integer or string | No | Another name for display, with the same values and meaning, including "auto". Send either field. If both are sent, they must have the same value. |
cpu | string | No | CPU model: portable or host. Default: "portable". portable uses Westmere and produces a consistent CPU identity across hosts. host exposes the physical CPU. It is fixed at creation and refused with a snapshot-artifact source. |
agent | boolean | No | Whether to configure the guest-agent channel. Default: true. It is fixed at creation. A snapshot-artifact source determines this setting. |
console | boolean | No | Whether to configure a serial console. Default: true. It is fixed at creation. A snapshot-artifact source determines this setting. |
console_input | boolean | No | Whether the console accepts input. It defaults to the value of console, and true is refused unless console is also true. With a snapshot-artifact source, it defaults to the artifact’s console setting and is checked against it. |
audio | string | No | Audio configuration: none or output. Default: "none". output requires a display and host audio support. It is fixed at creation. With a snapshot-artifact source, the artifact’s sound card is used. A matching value is accepted, but output against an artifact without a sound card is refused. |
share | boolean | No | Whether to share the VM’s share/ folder into the guest. Default: false. It is fixed at creation and requires host file-sharing support. A snapshot-artifact source determines this setting. |
os | string | No | Guest operating system: windows-11, windows-server, or linux. It selects operating-system-specific firmware, Secure Boot, TPM and disk bus defaults. A windows-* preset uses virtio, except on a host with no virtio-win driver ISO, where it gives the VM a sata system disk and the create carries a warning saying so; the bus is fixed at creation. Any explicitly supplied field takes precedence. A snapshot-artifact source refuses this field. |
secure_boot | boolean | No | Whether Secure Boot is active. Default when os is omitted: false; the windows-11 preset turns it on. It requires firmware: "uefi" and host Secure Boot support. It is fixed at creation and refused with a snapshot-artifact source. |
disk_bps | integer | No | Disk throughput limit in bytes per second for all attached disks and CD-ROMs combined. Minimum: 65536. Omitting it means unlimited. It does not limit shared-folder traffic. |
disk_iops | integer | No | Disk operations-per-second limit for all attached disks and CD-ROMs combined. Minimum: 8. Omitting it means unlimited. It does not limit shared-folder traffic. |
share_quota_bytes | integer | No | Size limit in bytes for the VM’s share/ folder. Minimum: 1. Omitting it means unlimited. A limit on a VM without share is refused. The limit is checked when the VM starts: a share measured over the limit is refused with 507 InsufficientSpace, and the check is skipped if the folder cannot be measured. It is not a hard limit while the VM runs. over_quota is the latched state left by the last quota crossing, not a comparison with the latest measurement. It becomes true when a measurement exceeds the quota, including a partial measurement. It becomes false only when a complete measurement is at or below quota - quota / 16, with integer division rounded down, or when the quota is removed. Changing the quota re-checks the last measurement and can change this state. Each change publishes one share-quota event. It is always false when there is no quota. |
ports | array | No | Inbound port forwards. The array can contain at most 128 entries. Omitting it or passing an empty array makes the VM outbound-only. |
autostart | boolean | No | Whether the VM starts automatically when the service starts. Default: false. |
tpm | boolean | No | Whether to provide a TPM 2.0. When os is omitted, omitting it enables the TPM when the host supports it; the windows-* presets turn it on and linux turns it off. The TPM is fixed at creation and cannot later be replaced by a different TPM. A snapshot-artifact source refuses this field. |
stop_grace_seconds | integer | No | How long a graceful stop waits for the guest to power itself down before forcing it off, from 5 to 900 seconds. Omitting it uses the default of 30. It is mutable only while the VM is stopped. |
Source union
Section titled “Source union”The source object is a tagged union on type. Each variant requires its own fields and rejects fields belonging to other variants.
type | Required fields | Description |
|---|---|---|
template | type, id | Creates the VM from a template catalog entry. Templates include the guest drivers required by the selected operating system. |
blank | type, gib | Creates a VM with an empty, sparsely allocated disk of the requested size in GiB. |
iso | type, gib, and exactly one of sha256 or path | Installs from an ISO onto a new disk. A url is refused. Download the image into the ISO store first, then create the VM from its sha256. |
offline-file | type, path | Copies an existing host disk image into the VM. The source can be removed after the copy completes. |
vm-disk | type, name | Clones the disk of an existing VM. The source VM must not be running. The clone receives a new identity and a new TPM. |
snapshot-artifact | type, sha256, plus the top-level bus | Rebuilds a VM from a snapshot artifact. The artifact provides the disk, firmware, TPM state, CPU model, machine profile, and other hardware. bus must be explicitly supplied because the artifact does not record it. It must match the bus on which the guest was installed, since the wrong bus can leave the guest unable to boot and cannot be changed later. Omitting bus is refused with 400. For every artifact carrying TPM state, including every Windows 11 guest, duplicate_tpm_identity must be explicitly set to true; omitting it is refused with 400. The acknowledgement means the copy holds the same TPM identity and sealed keys as the original. |
| Source field | Applies to | Type | Required | Description |
|---|---|---|---|---|
source.id | template | string | Yes | Template catalog identifier. |
source.gib | blank, iso | integer | Yes | Disk size in GiB. Minimum: 1, maximum: 16384. For a blank disk, the allocation is sparse, but this is the size seen by the guest. |
source.sha256 | iso | string | Conditionally | SHA-256 identifier of an image in the ISO store. It must contain exactly 64 lowercase hexadecimal characters. This is the preferred ISO form because the store verifies the image contents. An upload that is still in progress is refused. |
source.sha256 | snapshot-artifact | string | Yes | SHA-256 identifier of a finalized artifact in the import store. It must contain exactly 64 lowercase hexadecimal characters. The artifact keeps its recorded disk size, so this source has no gib field. |
source.path | iso | string | Conditionally | Absolute path to an installer ISO already on the host. The ISO is used in place, so the file must exist at every VM start, not only at creation. Its contents are not verified. |
source.path | offline-file | string | Yes | Absolute path to a disk image already on the host. The image is copied into the VM, and its contents are not verified. |
source.url | iso | string | No | A URL is not accepted. Download the image into the ISO store first, then create the VM from its sha256. |
source.name | vm-disk | string | Yes | Name of the existing VM whose disk is cloned. The source must not be running. |
source.duplicate_tpm_identity | snapshot-artifact | boolean | Conditionally | Default: false. Every artifact carrying TPM state, including every Windows 11 guest, requires this field to be explicitly set to true; omission is refused with 400. Setting it acknowledges that the copy holds the same TPM identity and sealed keys as the original. Two live copies can therefore unseal each other’s secrets. Setting it for an artifact without TPM state has no effect. |
With a snapshot-artifact source, os, tpm, secure_boot, share, agent, cpu, and console are refused because the artifact already defines that hardware. firmware and audio are refused only when they contradict the artifact: firmware: "bios" for an artifact installed under UEFI, or audio: "output" for one with no sound device. Their defaults, uefi and none, count as omitted, and the artifact’s values apply. The artifact does not record memory_mib, vcpus, display, autostart, disk_bps, disk_iops, share_quota_bytes, or bus, so those values come from the request. Grow the artifact’s disk afterwards with the Reconfigure a stopped VM operation.
Port forward fields
Section titled “Port forward fields”| Name | Type | Required | Description |
|---|---|---|---|
proto | string | No | Transport protocol: tcp or udp. Default: "tcp". TCP and UDP forwards are separate. |
host | integer | Yes | Port opened on the computer’s addresses, from 1 to 65535. Host ports are shared by every VM in the computer, including stopped VMs. The port must be at or above the current unprivileged port threshold, which is 1024 when no lower threshold is configured. |
guest | integer | Yes | Port on which the guest listens, from 1 to 65535. It is not shared between VMs. |
Example body
Section titled “Example body”{ "name": "dev-vm", "source": { "type": "blank", "gib": 64 }, "memory_mib": 4096, "vcpus": 4, "display_id": 7, "os": "linux", "tpm": true, "share": true, "share_quota_bytes": 10737418240, "ports": [ { "proto": "tcp", "host": 2222, "guest": 22 } ], "stop_grace_seconds": 60}Responses
Section titled “Responses”Media type: application/json
The create was accepted and continues in the background. Use the Location response header with the Get a VM operation, and poll until progress.phase is committed or failed. A failure decided in the background appears in progress.error, not as this operation’s status.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Name of the VM being created. |
vm_id | string | Yes | Identifier assigned to the VM. |
state | string | Yes | Initial VM state. |
display | integer | No | X display number selected for the VM, including one selected by display: "auto". It is absent when the VM is headless. |
The Location response header contains the URL to poll for create progress.
{ "name": "dev-vm", "vm_id": "0000019a3f5c2e11", "state": "Creating", "display": 7}Errors reported in progress.error
progress.error has the same envelope as an HTTP error body. These codes arrive only there:
| Error Code | Title | Description | Resolution |
|---|---|---|---|
NotFound | Source VM not found | The vm-disk source VM does not exist. | Check the source VM name. |
SourceBusy | Source is busy or changed | The source VM is running or its state cannot be confirmed as stopped. For an offline-file source, the path may also have changed what it points to while the create was starting, either to a different VM’s disk or into or out of a VM’s storage. | Read the error message to see which case applies. Stop the source VM if it is running. For an offline-file source, check what the path points to. Then retry the create. |
InsufficientSpace | Insufficient storage space | The disk does not fit. The error carries need and have in bytes. | Free storage space or request a smaller disk. |
SpecInvalid, PortForwardConflict and StorageFailed can arrive either as this call’s status or in progress.error.
Media type: application/json
The body is malformed or contains an invalid field value, or the request contains unsupported query parameters.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
error | object | Yes | Error envelope. |
error.code | string | Yes | Error code. |
error.message | string | Yes | Human-readable explanation, including the invalid field and rule when applicable. |
error.retryable | boolean | Yes | Whether repeating the identical request could succeed without any other change. |
{ "error": { "code": "SpecInvalid", "message": "The vcpus field exceeds the maximum supported value.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
SpecInvalid | Invalid create request | The body is malformed, a field violates its schema, the name does not match ^[a-z0-9][a-z0-9-]{0,62}$, or the request contains query parameters. | Correct the field named by the message and remove unsupported query parameters. This operation does not return NameInvalid because the name is supplied in the body. |
Media type: application/json
The request body stopped arriving.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
error | object | Yes | Error envelope. |
error.code | string | Yes | Error code. |
error.message | string | Yes | Human-readable explanation. |
error.retryable | boolean | Yes | Whether repeating the identical request could succeed without any other change. |
{ "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 before it was complete. | Retry the request with error.retryable set to true. |
Media type: application/json
The name is already in use, another operation owns it, a requested host port conflicts, the display number cannot be used, or the source VM is orphaned.
Response fields
{ "error": { "code": "AlreadyExists", "message": "A VM with this name already exists.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
AlreadyExists | VM already exists | A VM with the requested name already exists. | Choose a different name or inspect the existing VM. |
OperationInProgress | Operation in progress | Another operation holds the requested name. | Retry later. |
PortForwardConflict | Port forward conflict | A host port in ports is already declared by another VM, whether that VM is running or stopped. | Choose an unused host port or remove the conflicting rule. |
DisplayRangeExhausted | Display range exhausted | display is "auto" and no number in the automatic range is free. | Choose an explicit display number, or free one in the automatic range. |
DisplayInUse | Display number already in use | display is a number that something else is already using. | Choose another number, or use "auto". |
Orphaned | Source VM cannot be managed | The vm-disk source VM is orphaned, so its disk cannot be read. The source guest may still be running. | Resolve the orphaned source condition before creating the new VM. |
Media type: application/json
A storage error occurred on the host.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
error | object | Yes | Error envelope. |
error.code | string | Yes | Error code. |
error.message | string | Yes | Human-readable explanation. |
error.retryable | boolean | Yes | Whether repeating the identical request could succeed without any other change. |
{ "error": { "code": "StorageFailed", "message": "A storage error occurred on the host.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
StorageFailed | Storage operation failed | The service could not complete the storage operation. The error response has retryable set to false. | Resolve the storage condition before retrying the identical request. |
Media type: application/json
The service could not check whether the display number is in use. With "auto" no number was picked, and with an explicit number nothing was created.
Response fields
{ "error": { "code": "DisplayUnavailable", "message": "The display service could not be reached to check the display number.", "retryable": true }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
DisplayUnavailable | Display availability check failed | The service could not check whether the display number is in use. With "auto" no number was picked, and with an explicit number nothing was created. | Retry the create, or for "auto" give an explicit display number. |
curl --request POST \ --header 'Content-Type: application/json' \ --data '{ "name": "dev-vm", "source": { "type": "blank", "gib": 64 }, "memory_mib": 4096, "vcpus": 4, "display_id": 7, "os": "linux", "tpm": true, "share": true, "share_quota_bytes": 10737418240, "ports": [ { "proto": "tcp", "host": 2222, "guest": 22 } ], "stop_grace_seconds": 60 }' \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' });
const created = await client.vm.vms.create({ name: 'dev-vm', source: { type: 'blank', gib: 64 }, memory_mib: 4096, vcpus: 4, display_id: 7, os: 'linux', tpm: true, share: true, share_quota_bytes: 10737418240, ports: [{ proto: 'tcp', host: 2222, guest: 22 }], stop_grace_seconds: 60});console.log(created.data);Reconfigure a stopped VM
Section titled “Reconfigure a stopped VM”PATCH /api/v1/vm/vms/{name}
Changes the mutable configuration of a stopped VM. The VM must be stopped and must not have another operation in progress. Changes take effect at the next start.
At least one field is required: an empty object is refused with 400 SpecInvalid. Omitted fields remain unchanged. display: null makes the VM headless, cdroms: [] ejects every disc, and ports: [] removes every port forward. ports: null is an error.
disk_gib grows the system disk to an absolute size. It cannot be combined with any other field and must be sent in a separate request. The guest must still extend its partition and filesystem after the disk grows.
The following fields are fixed for the life of the VM: firmware, secure_boot, machine_type, tpm, cpu, agent, audio, console, console_input, share, bus, display_adapter, and name.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | Yes | VM name. It must contain lowercase letters, digits, and -, begin with a letter or digit, and be at most 63 characters long. |
Request body
Section titled “Request body”| Name | Type | Required | Description |
|---|---|---|---|
memory_mib | integer | No | Guest RAM in MiB from the next start. Minimum: 1. Host capacity is checked at the next start, not when the change is saved. |
vcpus | integer | No | Number of virtual CPUs from the next start. Minimum: 1, maximum: 4096. |
disk_gib | integer | No | Grow the system disk to this absolute size in GiB. Minimum: 1, maximum: 16384. The current size is a no-op, and a smaller size is refused. This field must be sent alone. |
display | integer or string or null | No | Move the VM to an X display from 0 to 65535, or use null to make it headless. null is refused when spec.audio is output. |
display_id | integer or string or null | No | Another name for display with the same values and meaning. Send either field. If both are sent, they must have the same value. |
cdroms | array of string or null | No | Replace the attached media in boot order. [] ejects everything. Each path must be absolute and must exist. The array can contain at most six entries, or five when the system disk uses sata. |
autostart | boolean | No | Whether the VM starts automatically when the service starts. |
disk_bps | integer or null | No | Disk throughput limit in bytes per second. Minimum: 65536. null removes the limit, and omitting it leaves the current value unchanged. It does not limit shared-folder traffic. |
disk_iops | integer or null | No | Disk operations-per-second limit. Minimum: 8. null removes the limit, and omitting it leaves the current value unchanged. It does not limit shared-folder traffic. |
share_quota_bytes | integer or null | No | Size limit in bytes for the VM’s share/ folder. Minimum: 1. null removes the limit, and omitting it leaves the current value unchanged. The limit is checked when the VM starts: a share measured over the limit is refused with 507 InsufficientSpace, and the check is skipped if the folder cannot be measured. It is not a hard limit while the VM runs. over_quota is the latched state left by the last quota crossing, not a comparison with the latest measurement. It becomes true when a measurement exceeds the quota, including a partial measurement. It becomes false only when a complete measurement is at or below quota - quota / 16, with integer division rounded down, or when the quota is removed. Changing the quota re-checks the last measurement and can change this state. Each change publishes one share-quota event. It is always false when there is no quota. Removing the quota from a VM that is over it clears over_quota and publishes one share-quota event. |
ports | array | No | Replace all inbound port forwards with this list. Omitting it leaves the rules unchanged, [] removes every rule and makes the VM outbound-only, and null is refused. The array can contain at most 128 entries. A host port already declared by another VM is refused with 409 PortForwardConflict. |
stop_grace_seconds | integer or null | No | How long a graceful stop waits for the guest to power itself down before forcing it off, from 5 to 900 seconds. null restores the default of 30, and omitting it leaves the current value unchanged. |
Each port forward uses the proto, host, and guest fields documented under Create a VM.
{ "memory_mib": 6144, "vcpus": 4, "display": null, "cdroms": [], "disk_bps": 104857600, "disk_iops": 1000, "share_quota_bytes": 10737418240, "ports": [], "stop_grace_seconds": 60}Responses
Section titled “Responses”Media type: application/json
Returns the VM’s configuration after the change, together with any warnings.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | VM name. |
vm_id | string | Yes | VM identifier. |
spec | object | Yes | Updated VM configuration. |
spec.memory_mib | integer | Yes | Guest RAM in MiB. |
spec.vcpus | integer | Yes | Number of virtual CPUs. |
spec.disk_bytes | integer | No | System disk size in bytes. |
spec.firmware | string | Yes | Firmware: uefi, uefi-secure-boot, or bios. |
spec.bus | string | Yes | System disk controller: virtio or sata. |
spec.display_adapter | string | Yes | Guest display adapter: vga or virtio-vga. It is fixed when the VM is created. |
spec.cpu | string | Yes | CPU model: qemu-default, westmere, or host. |
spec.tpm | boolean | Yes | Whether the VM has a TPM 2.0. |
spec.file_sharing | boolean | Yes | Whether the share/ folder is shared into the guest. |
spec.agent | boolean | Yes | Whether the guest-agent channel is configured. |
spec.console | boolean | Yes | Whether the serial console is configured. |
spec.console_input | boolean | Yes | Whether console input is allowed. |
spec.audio | string | Yes | Audio device: none or output. |
spec.machine_type | string | Yes | QEMU machine type to which the VM is pinned. |
spec.display | integer | No | X display number. It is absent when the VM is headless. |
spec.cdroms | array of string or null | No | Attached read-only media in boot order. A null value is an empty slot. |
spec.autostart | boolean | Yes | Whether the VM starts automatically with the service. |
spec.disk_bps | integer | No | Disk throughput limit in bytes per second. It is absent when unlimited. |
spec.disk_iops | integer | No | Disk operations-per-second limit. It is absent when unlimited. |
spec.share_quota_bytes | integer | No | Share quota in bytes. It is checked only when the VM starts. |
spec.ports | array | No | Inbound port forwards. |
spec.ports[].proto | string | No | Transport protocol: tcp or udp. Default: "tcp". |
spec.ports[].host | integer | Yes | Port opened on the computer’s addresses. |
spec.ports[].guest | integer | Yes | Port on which the guest listens. |
spec.stop_grace_seconds | integer | No | How long a graceful stop waits before forcing the VM off, in seconds. It is absent when the default of 30 applies. |
warnings | array of string | No | Details about changes that succeeded, such as devices added to the guest when a display was enabled. |
{ "name": "dev-vm", "vm_id": "0000019a3f5c2e11", "spec": { "memory_mib": 6144, "vcpus": 4, "disk_bytes": 68719476736, "firmware": "uefi", "bus": "virtio", "display_adapter": "virtio-vga", "cpu": "westmere", "tpm": true, "file_sharing": true, "agent": true, "console": true, "console_input": true, "audio": "none", "machine_type": "q35", "autostart": false, "disk_bps": 104857600, "disk_iops": 1000, "share_quota_bytes": 10737418240, "stop_grace_seconds": 60 }, "warnings": []}Media type: application/json
The name or request body is invalid.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
error | object | Yes | Error envelope. |
error.code | string | Yes | Error code. |
error.message | string | Yes | Human-readable explanation. |
error.retryable | boolean | Yes | Whether repeating the identical request could succeed without any other change. |
{ "error": { "code": "SpecInvalid", "message": "disk_gib cannot be combined with other fields.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NameInvalid | Invalid VM name | The name in the path does not match the required VM name format. | Use lowercase letters, digits, and -, begin with a letter or digit, and limit the name to 63 characters. |
SpecInvalid | Invalid reconfiguration request | The body is empty, a value is invalid, disk_gib is combined with another field, the disk is missing, disk_gib is smaller than the current size, or the request contains query parameters. | Correct the named field, remove unsupported query parameters, and send disk_gib alone when growing the disk. |
Media type: application/json
No VM has the requested name.
Response fields
{ "error": { "code": "NotFound", "message": "No VM has this name.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NotFound | VM not found | No VM has the requested name. | Confirm the VM name with the List VMs operation. |
Media type: application/json
The request body stopped arriving.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
error | object | Yes | Error envelope. |
error.code | string | Yes | Error code. |
error.message | string | Yes | Human-readable explanation. |
error.retryable | boolean | Yes | Whether repeating the identical request could succeed without any other change. |
{ "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 before it was complete. | Retry the request with error.retryable set to true. |
Media type: application/json
The VM is not stopped, another operation is active, the VM is orphaned, a host port conflicts, or the requested display number cannot be used.
Response fields
{ "error": { "code": "BadState", "message": "The VM must be stopped before it can be reconfigured.", "retryable": true }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BadState | VM is not stopped | The VM is running or otherwise not in a state that permits reconfiguration. The error response has retryable set to true. | Stop the VM before reconfiguring it. |
OperationInProgress | Operation in progress | Another operation on the VM is active. | Retry later. |
Orphaned | VM run cannot be managed | The service cannot verify the VM’s run, or it has blocked the VM after finding multiple possible live runs or an indeterminate delete. The guest may still be running. The error message distinguishes the condition. | For an unverifiable run, check the process, then use forceAdopt or forceMarkDead; forceMarkDead is accepted only when the disk is not locked. For a blocked VM, both actions are refused. Resolve the condition named in the message and restart hoody-vm. |
PortForwardConflict | Port forward conflict | A host port in ports is already declared by another VM, whether that VM is running or stopped. | Choose an unused host port or remove the conflicting rule. |
DisplayRangeExhausted | Display range exhausted | display is "auto" and no number in the automatic range is free. | Choose an explicit display number, or free one in the automatic range. |
DisplayInUse | Display number already in use | display is a number that something other than this VM is already using. | Choose another number, or use "auto". |
Media type: application/json
The storage operation failed.
Response fields
{ "error": { "code": "StorageFailed", "message": "The storage operation failed.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
StorageFailed | Storage operation failed | The service could not complete the storage operation. The error response has retryable set to false. | Resolve the storage condition before retrying the identical request. |
Media type: application/json
The service could not check whether the display number is in use, so nothing was changed. With "auto" no number was picked.
Response fields
{ "error": { "code": "DisplayUnavailable", "message": "The display service could not be reached to check the display number.", "retryable": true }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
DisplayUnavailable | Display availability check failed | The service could not check whether the display number is in use, so nothing was changed. With "auto" no number was picked. | Retry the request, or for "auto" give an explicit display number. |
Media type: application/json
There is not enough free space to grow the disk to the requested size.
Response fields
{ "error": { "code": "InsufficientSpace", "message": "There is not enough free space to grow the disk to the requested size.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
InsufficientSpace | Insufficient storage space | The storage system does not have enough free space to grow the disk to the requested size. | Request a smaller disk size or make additional storage available before retrying. |
curl --request PATCH \ --header 'Content-Type: application/json' \ --data '{ "memory_mib": 6144, "vcpus": 4, "display": null, "cdroms": [], "disk_bps": 104857600, "disk_iops": 1000, "share_quota_bytes": 10737418240, "ports": [], "stop_grace_seconds": 60 }' \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/dev-vm'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' });
const updated = await client.vm.vms.update('dev-vm', { memory_mib: 6144, vcpus: 4, display: null, cdroms: [], disk_bps: 104857600, disk_iops: 1000, share_quota_bytes: 10737418240, ports: [], stop_grace_seconds: 60});console.log(updated.data);Change the disc in a running VM’s CD-ROM slot
Section titled “Change the disc in a running VM’s CD-ROM slot”PUT /api/v1/vm/vms/{name}/cdroms/{slot}
Replaces the disc in one CD-ROM slot of a running or paused VM. The operation uses QEMU’s blockdev-change-medium and opens the source as a raw read-only image without probing its format.
The VM’s cdroms records the new disc before QEMU opens it. If QEMU refuses the change, the previous disc is restored. Only a slot that held a disc when the VM started has a drive in the current run. Filling a slot that was empty at start is refused until the next start; configure it with the Reconfigure a stopped VM operation while the VM is stopped.
The call returns after QEMU answers, within the monitor command deadline of 10 seconds.
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. |
slot | path | integer | Yes | The CD-ROM slot, counted from 0 in the order of the VM’s cdroms. Slot 0 is the one the VM boots from. |
Request body
Section titled “Request body”| Name | Type | Required | Description |
|---|---|---|---|
source | string | Yes | Absolute path of the disc image to put in the slot. It must exist, be a regular file, and not be part of another VM’s storage. A file in this VM’s shared folder is allowed. It is opened as a raw image without probing its format. |
Responses
Section titled “Responses”Media type: application/json
QEMU opened the disc in the slot, and spec.cdroms names it.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | VM name. |
vm_id | string | No | VM identifier. |
state | string | Yes | Lifecycle state: Creating, Stopped, Starting, Running, Paused, Stopping, Failed, or Orphaned. |
reason | string | No | Prose reason for the current state. |
run | string | No | Identifier of the current run. |
progress | object | No | Create progress. |
progress.phase | string | Yes, when progress is present | Create phase: reserving, importing, committing, committed, or failed. |
progress.bytes_done | integer | Yes, when progress is present | Bytes processed so far. |
progress.bytes_total | integer | Yes, when progress is present | Total bytes to process. |
progress.fell_back | string | No | Set when reflink cloning was unavailable and the disk was fully copied instead. |
progress.warnings | array of string | No | Warnings about a create that succeeded. |
progress.error | object | No | Present when progress.phase is failed. It contains the background create failure. |
progress.error.error | object | Yes, when progress.error is present | Nested error envelope. |
progress.error.error.code | string | Yes, when progress.error is present | Error code. |
progress.error.error.message | string | Yes, when progress.error is present | Human-readable explanation. |
progress.error.error.retryable | boolean | Yes, when progress.error is present | Whether repeating the identical request could succeed without any other change. |
sidecars | array | No | Health of the VM’s helper processes. It is omitted when empty. |
sidecars[].kind | string | Yes | Helper kind: passt, virtiofsd, or swtpm. |
sidecars[].state | string | Yes | Helper state: absent, starting, ready, degraded, or stopped. |
spec | object | No | Committed VM configuration. It can be absent during creation or when it cannot be read. |
spec.memory_mib | integer | Yes, when spec is present | Guest RAM in MiB. |
spec.vcpus | integer | Yes, when spec is present | Number of virtual CPUs. |
spec.disk_bytes | integer | No | System disk size in bytes. |
spec.firmware | string | Yes, when spec is present | Firmware: uefi, uefi-secure-boot, or bios. |
spec.bus | string | Yes, when spec is present | System disk controller: virtio or sata. |
spec.display_adapter | string | Yes, when spec is present | Guest display adapter: vga or virtio-vga. |
spec.cpu | string | Yes, when spec is present | CPU model: qemu-default, westmere, or host. |
spec.tpm | boolean | Yes, when spec is present | Whether the VM has a TPM 2.0. |
spec.file_sharing | boolean | Yes, when spec is present | Whether the share/ folder is shared into the guest. |
spec.agent | boolean | Yes, when spec is present | Whether the guest-agent channel is configured. |
spec.console | boolean | Yes, when spec is present | Whether the serial console is configured. |
spec.console_input | boolean | Yes, when spec is present | Whether console input is allowed. |
spec.audio | string | Yes, when spec is present | Audio device: none or output. |
spec.machine_type | string | Yes, when spec is present | QEMU machine type to which the VM is pinned. |
spec.display | integer | No | X display number. It is absent when the VM is headless. |
spec.cdroms | array of string or null | No | Attached read-only media in boot order. A null value is an empty slot. |
spec.autostart | boolean | Yes, when spec is present | Whether the VM starts automatically with the service. |
spec.disk_bps | integer | No | Disk throughput limit in bytes per second. It is absent when unlimited. |
spec.disk_iops | integer | No | Disk operations-per-second limit. It is absent when unlimited. |
spec.share_quota_bytes | integer | No | Share quota in bytes. It is absent when unlimited and is checked only when the VM starts. |
spec.ports | array | No | Inbound port forwards. |
spec.ports[].proto | string | No | Transport protocol: tcp or udp. Default: "tcp". |
spec.ports[].host | integer | Yes | Port opened on the computer’s addresses. |
spec.ports[].guest | integer | Yes | Port on which the guest listens. |
spec.stop_grace_seconds | integer | No | How long a graceful stop waits before forcing the VM off, in seconds. It is absent when the default of 30 applies. |
display_url | string | No | Browser address of the VM’s display. |
monitor_stalled | boolean | No | Whether the QMP monitor has stopped answering. It is omitted when false. |
seq | integer | No | VM event counter as of this response. |
error | object | No | Typed reason the current run failed. The code is nested at error.error.code. |
error.error | object | Yes, when error is present | Nested error envelope. |
error.error.code | string | Yes, when error is present | Error code. |
error.error.message | string | Yes, when error is present | Human-readable explanation. |
error.error.retryable | boolean | Yes, when error is present | Whether repeating the identical request could succeed without any other change. |
share | object | No | Disk usage for the VM’s share/ folder. It is absent until a measurement has completed. |
share.bytes | integer | Yes, when share is present | Allocated size in bytes. Data shared by reflink between share/ and the VM’s disk is counted in both. |
share.partial | boolean | Yes, when share is present | Whether the measurement stopped early. When true, bytes is a lower bound. |
share.sampled_unix | integer | Yes, when share is present | Time of the measurement in Unix seconds. |
share.quota_bytes | integer | No | Current share quota in bytes. |
share.over_quota | boolean | Yes, when share is present | Latched state left by the last quota crossing. |
{ "name": "dev-vm", "vm_id": "0000019a3f5c2e11", "state": "Running", "spec": { "memory_mib": 6144, "vcpus": 4, "disk_bytes": 68719476736, "firmware": "uefi", "bus": "virtio", "display_adapter": "virtio-vga", "cpu": "westmere", "tpm": true, "file_sharing": true, "agent": true, "console": true, "console_input": true, "audio": "none", "machine_type": "q35", "cdroms": [ "/opt/images/dev-installer.iso" ], "autostart": false, "disk_bps": 104857600, "disk_iops": 1000, "share_quota_bytes": 10737418240, "stop_grace_seconds": 60 }, "share": { "bytes": 3221225472, "partial": false, "sampled_unix": 1767225600, "quota_bytes": 10737418240, "over_quota": false }}Media type: application/json
The VM name, slot, or request body is invalid.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
error | object | Yes | Error envelope. |
error.code | string | Yes | Error code. |
error.message | string | Yes | Human-readable explanation. |
error.retryable | boolean | Yes | Whether repeating the identical request could succeed without any other change. |
{ "error": { "code": "SpecInvalid", "message": "The source must be an absolute path to an attachable regular file.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NameInvalid | Invalid VM name | The name in the path does not match the required VM name format. | Use lowercase letters, digits, and -, begin with a letter or digit, and limit the name to 63 characters. |
SpecInvalid | Invalid CD-ROM change | The body is not valid JSON, contains an unknown field, the slot is not a number or is past the VM’s last slot, source is not an absolute path to an attachable regular file, or the request contains query parameters. | Correct the request and remove unsupported query parameters. |
Media type: application/json
No VM has the requested name.
Response fields
{ "error": { "code": "NotFound", "message": "No VM has this name.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NotFound | VM not found | No VM has the requested name. | Confirm the VM name with the List VMs operation. |
Media type: application/json
The request body stopped arriving.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
error | object | Yes | Error envelope. |
error.code | string | Yes | Error code. |
error.message | string | Yes | Human-readable explanation. |
error.retryable | boolean | Yes | Whether repeating the identical request could succeed without any other change. |
{ "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 before it was complete. | Retry the request with error.retryable set to true. |
Media type: application/json
The VM or its monitor cannot accept the change, another operation is active, or the service cannot manage the VM.
Response fields
{ "error": { "code": "BadState", "message": "The VM must be running or paused for a CD-ROM change.", "retryable": true }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BadState | VM cannot accept the CD-ROM change | The VM is not running or paused, its monitor is not answering, QEMU refused the command, or the service is shutting down. The slot remains unchanged. The error response has retryable set to true. | Make sure the VM is running or paused, resolve the condition named by QEMU, and retry. If the slot was empty at start, configure it with the Reconfigure a stopped VM operation. |
OperationInProgress | Operation in progress | Another operation on the VM has not finished, including another CD-ROM change, or the slot changed while this call ran. | Read the VM with the Get a VM operation and retry. |
Orphaned | VM run cannot be managed | The service cannot verify the VM’s run, or it has blocked the VM after finding multiple possible live runs or an indeterminate delete. The guest may still be running. The error message distinguishes the condition. | For an unverifiable run, check the process, then use forceAdopt or forceMarkDead; forceMarkDead is accepted only when the disk is not locked. For a blocked VM, both actions are refused. Resolve the condition named in the message and restart hoody-vm. |
Media type: application/json
The monitor command’s result is unknown, or the VM’s record could not be read or written.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
error | object | Yes | Error envelope. |
error.code | string | Yes | Error code. |
error.message | string | Yes | Human-readable explanation. |
error.retryable | boolean | Yes | Whether repeating the identical request could succeed without any other change. |
{ "error": { "code": "MonitorCommandIndeterminate", "message": "QEMU did not answer before the monitor command deadline.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
MonitorCommandIndeterminate | Monitor command result is unknown | The command was sent, but QEMU did not answer in time or the monitor closed first. The change may or may not have been applied. The error response has retryable set to false. | Read the VM with the Get a VM operation to inspect the recorded slot before deciding whether to retry. |
StorageFailed | Storage operation failed | The VM’s record could not be read or written. The error response has retryable set to false. | Resolve the storage condition before retrying the identical request. |
curl --request PUT \ --header 'Content-Type: application/json' \ --data '{ "source": "/opt/images/dev-installer.iso" }' \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/dev-vm/cdroms/0'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' });
const vm = await client.vm.vms.changeCdrom('dev-vm', 0, { source: '/opt/images/dev-installer.iso'});console.log(vm.data.state);Eject the disc from a running VM’s CD-ROM slot
Section titled “Eject the disc from a running VM’s CD-ROM slot”DELETE /api/v1/vm/vms/{name}/cdroms/{slot}
Ejects the disc from one CD-ROM slot of a running or paused VM using QEMU’s eject operation. The ejection is never forced. If the guest has locked the tray, QEMU refuses the operation and asks the guest to release it. Try again after the guest releases it.
The slot remains in place and becomes empty. The VM’s cdroms shows null for it only after QEMU has ejected the disc. Ejecting an empty slot succeeds without changing anything.
The call returns after QEMU answers, within the monitor command deadline of 10 seconds.
This endpoint accepts no request body.
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. |
slot | path | integer | Yes | The CD-ROM slot, counted from 0 in the order of the VM’s cdroms. Slot 0 is the one the VM boots from. |
Responses
Section titled “Responses”Media type: application/json
The slot is empty, and spec.cdroms shows null for it.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | VM name. |
vm_id | string | No | VM identifier. |
state | string | Yes | Lifecycle state: Creating, Stopped, Starting, Running, Paused, Stopping, Failed, or Orphaned. |
reason | string | No | Prose reason for the current state. |
run | string | No | Identifier of the current run. |
progress | object | No | Create progress. |
progress.phase | string | Yes, when progress is present | Create phase: reserving, importing, committing, committed, or failed. |
progress.bytes_done | integer | Yes, when progress is present | Bytes processed so far. |
progress.bytes_total | integer | Yes, when progress is present | Total bytes to process. |
progress.fell_back | string | No | Set when reflink cloning was unavailable and the disk was fully copied instead. |
progress.warnings | array of string | No | Warnings about a create that succeeded. |
progress.error | object | No | Present when progress.phase is failed. It contains the background create failure. |
progress.error.error | object | Yes, when progress.error is present | Nested error envelope. |
progress.error.error.code | string | Yes, when progress.error is present | Error code. |
progress.error.error.message | string | Yes, when progress.error is present | Human-readable explanation. |
progress.error.error.retryable | boolean | Yes, when progress.error is present | Whether repeating the identical request could succeed without any other change. |
sidecars | array | No | Health of the VM’s helper processes. It is omitted when empty. |
sidecars[].kind | string | Yes | Helper kind: passt, virtiofsd, or swtpm. |
sidecars[].state | string | Yes | Helper state: absent, starting, ready, degraded, or stopped. |
spec | object | No | Committed VM configuration. It can be absent during creation or when it cannot be read. |
spec.memory_mib | integer | Yes, when spec is present | Guest RAM in MiB. |
spec.vcpus | integer | Yes, when spec is present | Number of virtual CPUs. |
spec.disk_bytes | integer | No | System disk size in bytes. |
spec.firmware | string | Yes, when spec is present | Firmware: uefi, uefi-secure-boot, or bios. |
spec.bus | string | Yes, when spec is present | System disk controller: virtio or sata. |
spec.display_adapter | string | Yes, when spec is present | Guest display adapter: vga or virtio-vga. |
spec.cpu | string | Yes, when spec is present | CPU model: qemu-default, westmere, or host. |
spec.tpm | boolean | Yes, when spec is present | Whether the VM has a TPM 2.0. |
spec.file_sharing | boolean | Yes, when spec is present | Whether the share/ folder is shared into the guest. |
spec.agent | boolean | Yes, when spec is present | Whether the guest-agent channel is configured. |
spec.console | boolean | Yes, when spec is present | Whether the serial console is configured. |
spec.console_input | boolean | Yes, when spec is present | Whether console input is allowed. |
spec.audio | string | Yes, when spec is present | Audio device: none or output. |
spec.machine_type | string | Yes, when spec is present | QEMU machine type to which the VM is pinned. |
spec.display | integer | No | X display number. It is absent when the VM is headless. |
spec.cdroms | array of string or null | No | Attached read-only media in boot order. A null value is an empty slot. |
spec.autostart | boolean | Yes, when spec is present | Whether the VM starts automatically with the service. |
spec.disk_bps | integer | No | Disk throughput limit in bytes per second. It is absent when unlimited. |
spec.disk_iops | integer | No | Disk operations-per-second limit. It is absent when unlimited. |
spec.share_quota_bytes | integer | No | Share quota in bytes. It is absent when unlimited and is checked only when the VM starts. |
spec.ports | array | No | Inbound port forwards. |
spec.ports[].proto | string | No | Transport protocol: tcp or udp. Default: "tcp". |
spec.ports[].host | integer | Yes | Port opened on the computer’s addresses. |
spec.ports[].guest | integer | Yes | Port on which the guest listens. |
spec.stop_grace_seconds | integer | No | How long a graceful stop waits before forcing the VM off, in seconds. It is absent when the default of 30 applies. |
display_url | string | No | Browser address of the VM’s display. |
monitor_stalled | boolean | No | Whether the QMP monitor has stopped answering. It is omitted when false. |
seq | integer | No | VM event counter as of this response. |
error | object | No | Typed reason the current run failed. The code is nested at error.error.code. |
error.error | object | Yes, when error is present | Nested error envelope. |
error.error.code | string | Yes, when error is present | Error code. |
error.error.message | string | Yes, when error is present | Human-readable explanation. |
error.error.retryable | boolean | Yes, when error is present | Whether repeating the identical request could succeed without any other change. |
share | object | No | Disk usage for the VM’s share/ folder. It is absent until a measurement has completed. |
share.bytes | integer | Yes, when share is present | Allocated size in bytes. Data shared by reflink between share/ and the VM’s disk is counted in both. |
share.partial | boolean | Yes, when share is present | Whether the measurement stopped early. When true, bytes is a lower bound. |
share.sampled_unix | integer | Yes, when share is present | Time of the measurement in Unix seconds. |
share.quota_bytes | integer | No | Current share quota in bytes. |
share.over_quota | boolean | Yes, when share is present | Latched state left by the last quota crossing. |
{ "name": "dev-vm", "vm_id": "0000019a3f5c2e11", "state": "Running", "spec": { "memory_mib": 6144, "vcpus": 4, "disk_bytes": 68719476736, "firmware": "uefi", "bus": "virtio", "display_adapter": "virtio-vga", "cpu": "westmere", "tpm": true, "file_sharing": true, "agent": true, "console": true, "console_input": true, "audio": "none", "machine_type": "q35", "cdroms": [ null ], "autostart": false, "disk_bps": 104857600, "disk_iops": 1000, "share_quota_bytes": 10737418240, "stop_grace_seconds": 60 }, "share": { "bytes": 3221225472, "partial": false, "sampled_unix": 1767225600, "quota_bytes": 10737418240, "over_quota": false }}Media type: application/json
The VM name or slot is invalid.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
error | object | Yes | Error envelope. |
error.code | string | Yes | Error code. |
error.message | string | Yes | Human-readable explanation. |
error.retryable | boolean | Yes | Whether repeating the identical request could succeed without any other change. |
{ "error": { "code": "SpecInvalid", "message": "The slot is not a number or is past the VM's last slot.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NameInvalid | Invalid VM name | The name in the path does not match the required VM name format. | Use lowercase letters, digits, and -, begin with a letter or digit, and limit the name to 63 characters. |
SpecInvalid | Invalid CD-ROM eject | The slot is not a number or is past the VM’s last slot, or the request contains query parameters. | Send a valid slot number and remove unsupported query parameters. |
Media type: application/json
No VM has the requested name.
Response fields
{ "error": { "code": "NotFound", "message": "No VM has this name.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NotFound | VM not found | No VM has the requested name. | Confirm the VM name with the List VMs operation. |
Media type: application/json
The VM or its monitor cannot eject the disc, another operation is active, or the service cannot manage the VM.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
error | object | Yes | Error envelope. |
error.code | string | Yes | Error code. |
error.message | string | Yes | Human-readable explanation. |
error.retryable | boolean | Yes | Whether repeating the identical request could succeed without any other change. |
{ "error": { "code": "BadState", "message": "The VM must be running or paused for a CD-ROM eject.", "retryable": true }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BadState | VM cannot eject the disc | The VM is not running or paused, its monitor is not answering, QEMU refused the command, or the service is shutting down. The slot remains unchanged. The error response has retryable set to true. | Make sure the VM is running or paused, ask the guest to release a locked tray, and retry. |
OperationInProgress | Operation in progress | Another operation on the VM has not finished, including another CD-ROM change, or the slot changed while this call ran. | Read the VM with the Get a VM operation and retry. |
Orphaned | VM run cannot be managed | The service cannot verify the VM’s run, or it has blocked the VM after finding multiple possible live runs or an indeterminate delete. The guest may still be running. The error message distinguishes the condition. | For an unverifiable run, check the process, then use forceAdopt or forceMarkDead; forceMarkDead is accepted only when the disk is not locked. For a blocked VM, both actions are refused. Resolve the condition named in the message and restart hoody-vm. |
Media type: application/json
The monitor command’s result is unknown, or the VM’s record could not be read or written.
Response fields
{ "error": { "code": "MonitorCommandIndeterminate", "message": "QEMU did not answer before the monitor command deadline.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
MonitorCommandIndeterminate | Monitor command result is unknown | The command was sent, but QEMU did not answer in time or the monitor closed first. The ejection may or may not have happened. The error response has retryable set to false. | Read the VM with the Get a VM operation to inspect the recorded slot before deciding whether to retry. |
StorageFailed | Storage operation failed | The VM’s record could not be read or written. The error response has retryable set to false. | Resolve the storage condition before retrying the identical request. |
curl --request DELETE \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/dev-vm/cdroms/0'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' });
const vm = await client.vm.vms.ejectCdrom('dev-vm', 0);console.log(vm.data.state);Delete a VM
Section titled “Delete a VM”DELETE /api/v1/vm/vms/{name}
Deletes a VM and its associated resources.
This endpoint accepts no request body.
Parameters
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
name | path | string | Yes | VM name. It must contain lowercase letters, digits, and -, begin with a letter or digit, and be at most 63 characters long. |
force | query | boolean | No | force, force=true, or force=1 deletes the VM even if it is running, stopping it first without asking the guest to shut down. If force is absent, false, or 0, a running VM is refused with 409 BadState. Any other value is refused with 400 SpecInvalid. |
Responses
Section titled “Responses”Media type: application/json
The VM was deleted.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Name of the deleted VM. |
deleted | boolean | Yes | Whether the VM was deleted. |
{ "name": "dev-vm", "deleted": true}Media type: application/json
The VM name or force value is invalid.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
error | object | Yes | Error envelope. |
error.code | string | Yes | Error code. |
error.message | string | Yes | Human-readable explanation. |
error.retryable | boolean | Yes | Whether repeating the identical request could succeed without any other change. |
{ "error": { "code": "SpecInvalid", "message": "The force parameter must be a boolean value.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NameInvalid | Invalid VM name | The name in the path does not match the required VM name format. | Use lowercase letters, digits, and -, begin with a letter or digit, and limit the name to 63 characters. |
SpecInvalid | Invalid delete request | The request specification is invalid, including an unsupported force value. | Omit force or use force=true, force=1, or 0. |
Media type: application/json
No VM has the requested name.
Response fields
{ "error": { "code": "NotFound", "message": "No VM has this name.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
NotFound | VM not found | No VM has the requested name. | Confirm the VM name with the List VMs operation. |
Media type: application/json
The VM cannot be deleted in its current state, another operation is active, or the service cannot verify the VM’s run.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
error | object | Yes | Error envelope. |
error.code | string | Yes | Error code. |
error.message | string | Yes | Human-readable explanation. |
error.retryable | boolean | Yes | Whether repeating the identical request could succeed without any other change. |
{ "error": { "code": "BadState", "message": "The VM is running and force was not requested.", "retryable": true }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
BadState | VM cannot be deleted in its current state | The VM is running and force was not supplied, or the VM is briefly starting or shutting down. The error response has retryable set to true. | Stop the VM, or use force=true to stop it without asking the guest to shut down. Retry if it is transitioning. |
OperationInProgress | Operation in progress | A create, snapshot export setup, start, snapshot, restore, or update owns the VM. | Retry later. |
Orphaned | VM run cannot be managed | The service cannot verify the VM’s run, or it has blocked the VM after finding multiple possible live runs or an indeterminate delete. The guest may still be running. The error message distinguishes the condition. | For an unverifiable run, check the process, then use forceAdopt or forceMarkDead; forceMarkDead is accepted only when the disk is not locked. For a blocked VM, both actions are refused. Resolve the condition named in the message and restart hoody-vm. |
Media type: application/json
The storage operation failed.
Response fields
{ "error": { "code": "StorageFailed", "message": "The storage operation failed.", "retryable": false }}| Error Code | Title | Description | Resolution |
|---|---|---|---|
StorageFailed | Storage operation failed | The service could not complete the storage operation. The error response has retryable set to false. | Resolve the storage condition before retrying the identical request. |
curl --request DELETE \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/vms/dev-vm?force=true'import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' });
const deleted = await client.vm.vms.delete('dev-vm', { force: true });console.log(deleted.data);