# VM: Installer images **Page:** api/vm/isos [Download Raw Markdown](./api/vm/isos.md) --- # VM: Installer images Use these endpoints to manage installer images on a computer. Images are content-addressed by their SHA-256 digest, which must contain exactly 64 lowercase hexadecimal characters. You can upload an image in ordered parts, download an image from a URL and poll the resulting job, inspect the operating system catalogue, and delete images or download jobs. Only a published image with `phase: "ready"` can be used to create a VM. These routes use the computer service host. Do not send a Hoody account token to this host. Access is governed by the computer's proxy permission rules. ## Response objects ### Installer image entry Installer image entries are returned by the image list, get, begin upload, upload part, and finalize operations. | Name | Type | Required | Description | | --- | --- | --- | --- | | `media` | object | No | Metadata read from the image and the operating systems matched to it. It is absent while an upload is unverified, when the file is not ISO-9660, or when it declares no identifiers. | | `media.volume_id` | string | No | ISO-9660 volume identifier. | | `media.system_id` | string | No | ISO-9660 system identifier. | | `media.publisher_id` | string | No | ISO-9660 publisher identifier. | | `media.application_id` | string | No | ISO-9660 application identifier. | | `media.os` | array | Yes | Every operating system matched to the image. The array can be empty when the host has no usable operating system database. | | `media.os[].id` | string | Yes | Operating system identifier URI. | | `media.os[].short_id` | string | No | Short operating system identifier. | | `media.os[].name` | string | No | Display name. | | `media.os[].version` | string | No | Operating system version. | | `media.os[].vendor` | string | No | Vendor name. | | `media.os[].family` | string | No | Operating system family. | | `media.os[].distro` | string | No | Distribution name. | | `media.os[].codename` | string | No | Distribution codename. | | `media.os[].arch` | string | No | Matched media architecture. This service can boot only `x86_64`. | | `media.os[].variant` | string | No | Media variant. | | `media.os[].live` | boolean | Yes | Whether the medium boots into a live system without installing. | | `media.os[].installer` | boolean | Yes | Whether the database identifies the medium as an installer. `false` means the database does not say, not that the medium is not an installer. | | `sha256` | string | Yes | Lowercase SHA-256 digest that identifies the image. | | `phase` | string | Yes | `uploading` while parts are being sent, or `ready` after verification. | | `bytes` | integer | Yes | Number of bytes durably stored. | | `part_size` | integer | Yes | Exact size required for every part except the last. Use the returned value. | | `next_part` | integer | No | Zero-based part index to send next. It is absent on a `ready` image. | | `modified_unix` | integer | Yes | Last modification time in seconds since the Unix epoch. | ### Download job | Name | Type | Required | Description | | --- | --- | --- | --- | | `id` | string | Yes | Download job identifier, containing exactly 32 lowercase hexadecimal characters. | | `state` | string | Yes | `running`, `verifying`, `ready`, `failed`, `cancelled`, or `interrupted`. | | `url` | string | Yes | URL being fetched. For a joined download, this can be the URL supplied by the first caller. | | `effective_url` | string | No | Final redirect target that answered, when one was reached. | | `fetched_bytes` | integer | Yes | Bytes fetched so far. | | `expected_bytes` | integer | No | Size declared by the origin through `Content-Length`. It is not used to verify or publish the image. | | `sha256` | string | No | Digest under which the image was published. Present when the job is `ready`. | | `verification` | string | No | `asserted` when an expected digest was supplied and matched, or `tofu` when no expected digest was supplied. | | `error` | string | No | Description of why the download failed. | ### Operating system catalogue | Name | Type | Required | Description | | --- | --- | --- | --- | | `arch` | string or null | Yes | Architecture filter applied to the rows. This is `null` when `arch=all` was requested. | | `available` | boolean | Yes | Whether a usable operating system database was loaded and contains entries. | | `status` | string | Yes | Database status: `healthy`, `damaged`, or `absent`. | | `unreadable` | integer | Yes | Number of database files that could not be read or parsed. | | `entries` | array | Yes | Operating systems and their advertised installer images. | | `entries[].id` | string | Yes | Operating system identifier URI. | | `entries[].short_id` | string | No | Short operating system identifier. | | `entries[].name` | string | No | Display name. | | `entries[].version` | string | No | Operating system version. | | `entries[].vendor` | string | No | Vendor name. | | `entries[].family` | string | No | Operating system family. | | `entries[].distro` | string | No | Distribution name. | | `entries[].codename` | string | No | Distribution codename. | | `entries[].eol` | string | No | End-of-life date in `YYYY-MM-DD` format. | | `entries[].media` | array | Yes | Images advertised for the operating system. | | `entries[].media[].url` | string | Yes | URL from which the image can be fetched. | | `entries[].media[].arch` | string | No | Image architecture. | | `entries[].media[].variant` | string | No | Media variant. | | `entries[].media[].live` | boolean | Yes | Whether the image boots into a live system without installing. | | `entries[].media[].installer` | boolean | Yes | Whether the database identifies the image as an installer. | | `entries[].media[].identifiable` | boolean | Yes | Whether the image can be identified from its own labels after upload. | ### Error | Name | Type | Required | Description | | --- | --- | --- | --- | | `error` | object | Yes | Error details. | | `error.code` | string | Yes | Machine-readable error code. Branch on this value rather than `error.message`. | | `error.message` | string | Yes | Human-readable description of the error. | | `error.retryable` | boolean | Yes | Whether repeating the identical request can succeed without another change. | ## Installer image store ### `GET /api/v1/vm/isos` Lists every installer image in the store, including published images and unfinished uploads. Published entries include the operating systems they match. An upload with `phase: "uploading"` continues to occupy storage and is never removed automatically. This endpoint takes no parameters. #### Responses Returns every image in the store. Media type: application/json ```json [ { "media": { "volume_id": "Debian 13.1.0 amd64 n", "system_id": "Debian 13.1.0", "publisher_id": "Debian", "application_id": "Debian Live Installer", "os": [ { "id": "http://debian.org/debian/13", "short_id": "debian13", "name": "Debian 13", "version": "13.1.0", "vendor": "Debian", "family": "linux", "distro": "debian", "codename": "trixie", "arch": "x86_64", "variant": "netinst", "live": false, "installer": true } ] }, "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "phase": "ready", "bytes": 660700000, "part_size": 8388608, "modified_unix": 1767225600 }, { "sha256": "60303ae22b998861bce3b28f33eec1be758a213c86c93c076dbe9f558c11c752", "phase": "uploading", "bytes": 8388608, "part_size": 8388608, "next_part": 1, "modified_unix": 1767225700 } ] ``` The request included query parameters, but this operation accepts none. Media type: application/json ```json { "error": { "code": "SpecInvalid", "message": "This operation does not accept query parameters.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | | --- | --- | --- | --- | | `SpecInvalid` | Invalid request specification | The operation received query parameters. | Remove the query parameters and retry. | The storage operation failed. Media type: application/json ```json { "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 storage operation failed. Check the relevant image or download state before deciding whether to try again. | #### Examples ```bash curl --request GET \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/isos' ``` ```typescript import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' }); await client.vm.isos.list(); ``` ### `GET /api/v1/vm/isos/{sha256}` Returns an installer image and its current state. A published image includes the operating systems it matches. An unfinished upload reports the number of stored bytes and the next part to send. These values are read from stored data and remain accurate after an interruption on either side. #### Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `sha256` | path | string | Yes | SHA-256 digest identifying the image. It must contain exactly 64 lowercase hexadecimal characters. | #### Responses Returns the image's status. Media type: application/json ```json { "media": { "volume_id": "Debian 13.1.0 amd64 n", "system_id": "Debian 13.1.0", "publisher_id": "Debian", "application_id": "Debian Live Installer", "os": [ { "id": "http://debian.org/debian/13", "short_id": "debian13", "name": "Debian 13", "version": "13.1.0", "vendor": "Debian", "family": "linux", "distro": "debian", "codename": "trixie", "arch": "x86_64", "variant": "netinst", "live": false, "installer": true } ] }, "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "phase": "ready", "bytes": 660700000, "part_size": 8388608, "modified_unix": 1767225600 } ``` The digest is invalid, or the request included query parameters. Media type: application/json ```json { "error": { "code": "NameInvalid", "message": "sha256 must be 64 lowercase hexadecimal characters.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | | --- | --- | --- | --- | | `NameInvalid` | Invalid digest format | `sha256` does not contain exactly 64 lowercase hexadecimal characters. | Recalculate the digest and use its 64-character lowercase hexadecimal value. | | `SpecInvalid` | Invalid request specification | The operation received query parameters. | Remove the query parameters and retry. | No published image or unfinished upload has the requested digest. Media type: application/json ```json { "error": { "code": "NotFound", "message": "No installer image or unfinished upload has this digest.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | | --- | --- | --- | --- | | `NotFound` | Installer image not found | No published image or unfinished upload has this digest. | Verify the digest or begin an upload. | The storage operation failed. Media type: application/json ```json { "error": { "code": "StorageFailed", "message": "The storage operation failed.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | | --- | --- | --- | --- | | `StorageFailed` | Storage operation failed | The service could not read the image state. | The storage operation failed. Check the relevant image or download state before deciding whether to try again. | #### Examples ```bash curl --request GET \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/isos/9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08' ``` ```typescript import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' }); const sha256 = '9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08'; await client.vm.isos.get(sha256); ``` ### `GET /api/v1/vm/osinfo` Lists the operating systems and installer images advertised by the host's `osinfo-db` package. - By default, only `x86_64` media is listed because it is the only architecture this service can boot. - Set `arch=all` to list every architecture, including media this host cannot boot. - Set `arch` to an architecture name to filter the catalogue. - `available: false` means the host has no usable database. The `status` field indicates whether the database is `absent` or `damaged`. - The database can lag new releases. An image uploaded from a newer release might not receive a resolved operating system name. - Vendor URLs can expire. A failed fetch is a normal outcome and publishes no image. - The database does not publish checksums. Downloading one of these URLs without an expected digest produces a job with `verification: "tofu"`. #### Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `arch` | query | string | No | Architecture to list. Default: `"x86_64"`. Set to `all` to include every architecture, including media this host cannot boot. | #### Responses Returns the catalogue. Its `entries` array is empty when the host has no usable database. Media type: application/json ```json { "arch": "x86_64", "available": true, "status": "healthy", "unreadable": 0, "entries": [ { "id": "http://debian.org/debian/13", "short_id": "debian13", "name": "Debian 13", "version": "13.1.0", "vendor": "Debian", "family": "linux", "distro": "debian", "codename": "trixie", "eol": "2032-06-30", "media": [ { "url": "https://cdimage.debian.org/cdimage/release/13.1.0/amd64/iso-cd/debian-13.1.0-amd64-netinst.iso", "arch": "x86_64", "variant": "netinst", "live": false, "installer": true, "identifiable": true } ] } ] } ``` The request specification is invalid. Media type: application/json ```json { "error": { "code": "SpecInvalid", "message": "The request specification is invalid.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | | --- | --- | --- | --- | | `SpecInvalid` | Invalid request specification | The request specification is invalid. | Check the request parameters and retry. | #### Examples ```bash curl --request GET \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/osinfo?arch=x86_64' ``` ```typescript import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' }); await client.vm.osinfo.list({ arch: 'x86_64' }); ``` ## Upload installer images An upload consists of three operations: 1. Begin or resume the upload with the digest and total byte count. 2. Upload each part in order. 3. Finalize the upload after the stored byte count reaches the declared total. Every part except the last must contain exactly `part_size` bytes. The examples use `8388608` bytes, but clients must use the `part_size` value returned by the service. ### `POST /api/v1/vm/isos/{sha256}` Begins or resumes an upload under a digest and declared total size. - If the image is already published, the response has `phase: "ready"` and no upload is needed. - If an earlier upload was interrupted, the response includes `next_part` so you can resume. - Repeating this operation never truncates an upload in progress. - On resume, a different total replaces the declared total when it is at least the number of bytes already stored. The resume point is recalculated from the corrected total. #### Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `sha256` | path | string | Yes | SHA-256 digest identifying the image. It must contain exactly 64 lowercase hexadecimal characters. | #### Request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `bytes` | integer | Yes | Total image size in bytes. It must be at least `1`. On resume, it must not be less than the number of bytes already stored. | #### Responses The upload was declared, resumed, or found already complete. Read `phase` to determine the next action. Media type: application/json ```json { "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "phase": "uploading", "bytes": 0, "part_size": 8388608, "next_part": 0, "modified_unix": 1767225600 } ``` The digest or declared size is invalid, or the request included query parameters. Media type: application/json ```json { "error": { "code": "SpecInvalid", "message": "bytes must be positive and cannot be less than the stored byte count.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | | --- | --- | --- | --- | | `NameInvalid` | Invalid digest format | `sha256` does not contain exactly 64 lowercase hexadecimal characters. | Recalculate the digest and use its 64-character lowercase hexadecimal value. | | `SpecInvalid` | Invalid request specification | `bytes` is zero, a resumed total is below the stored byte count, or the operation received query parameters. | Send a valid total that is not below the stored byte count and remove query parameters. | The request body stopped arriving. Media type: application/json ```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. | Retry the request with the same body. | Another call is working on the same digest. Media type: application/json ```json { "error": { "code": "OperationInProgress", "message": "Another call is working on this digest.", "retryable": true } } ``` | Error Code | Title | Description | Resolution | | --- | --- | --- | --- | | `OperationInProgress` | Operation already in progress | Another call is working on this digest. | Retry shortly. | The storage operation failed. Media type: application/json ```json { "error": { "code": "StorageFailed", "message": "The storage operation failed.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | | --- | --- | --- | --- | | `StorageFailed` | Storage operation failed | The service could not store or read the upload declaration. | The storage operation failed. Check the relevant image or download state before deciding whether to try again. | The declared image size does not fit. On resume, this can mean the remaining bytes do not fit. Media type: application/json ```json { "error": { "code": "InsufficientSpace", "message": "There is not enough storage for the declared image size.", "retryable": false, "need": 660700000, "have": 536870912 } } ``` | Error Code | Title | Description | Resolution | | --- | --- | --- | --- | | `InsufficientSpace` | Insufficient storage | The declared size, or the remaining size on resume, does not fit in available storage. The error reports the required `need` bytes and the available `have` bytes. | Free storage or correct the declared total before retrying. | #### Examples ```bash curl --request POST \ --header 'Content-Type: application/json' \ --data '{"bytes":660700000}' \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/isos/9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08' ``` ```typescript import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' }); const sha256 = '9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08'; await client.vm.isos.create(sha256, { bytes: 660700000 }); ``` ### `PUT /api/v1/vm/isos/{sha256}/parts/{part}` Uploads one part of an installer image. Parts must be sent in order. Part `n` is accepted only when exactly `n * part_size` bytes are stored. Every part except the last must contain exactly `part_size` bytes. A replayed part is refused rather than stored twice, so you can safely retry a request whose response you did not receive. If an upload stops in the middle of a part, `bytes` reports the last complete part boundary and `next_part` identifies the part to send again. After any failure, retrieve the image to determine the correct resume position. #### Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `sha256` | path | string | Yes | SHA-256 digest identifying the image. It must contain exactly 64 lowercase hexadecimal characters. | | `part` | path | integer | Yes | Zero-based part index. Part `n` covers bytes from `n * part_size` up to, but not including, `(n + 1) * part_size`. | #### Request body Send the raw part bytes with `Content-Type: application/octet-stream`. The body is one binary blob, not a JSON object. #### Responses The part was stored. The response reports the stored `bytes` and `next_part`. Media type: application/json ```json { "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "phase": "uploading", "bytes": 8388608, "part_size": 8388608, "next_part": 1, "modified_unix": 1767225600 } ``` The digest or part is invalid, or the request included query parameters. Media type: application/json ```json { "error": { "code": "SpecInvalid", "message": "The part must contain between 1 and part_size bytes.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | | --- | --- | --- | --- | | `NameInvalid` | Invalid digest format | `sha256` does not contain exactly 64 lowercase hexadecimal characters. | Recalculate the digest and use its 64-character lowercase hexadecimal value. | | `SpecInvalid` | Invalid request specification | The part is empty or larger than `part_size`, the part index is not a non-negative integer, or the operation received query parameters. | Send a valid part and index, and remove query parameters. | No upload is in progress for this digest. Media type: application/json ```json { "error": { "code": "NotFound", "message": "No upload is in progress for this digest.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | | --- | --- | --- | --- | | `NotFound` | Installer image not found | No upload is in progress for this digest. | Begin the upload before sending a part. | The request body stopped arriving. Nothing was stored. Media type: application/json ```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, and nothing was stored. | Send the same part again. | The image or upload is not in a state that accepts this part, too many parts are being received at once, or another call is working on the same digest. Media type: application/json ```json { "error": { "code": "BadState", "message": "The upload is not accepting this part.", "retryable": true } } ``` | Error Code | Title | Description | Resolution | | --- | --- | --- | --- | | `BadState` | Unexpected upload state | The requested part is not the next expected part, or too many parts are being received at once. In the concurrent-upload case, this part was not started. | If the requested part is not next, read `next_part` and send that part. If too many parts are being received, send the same part again. | | `AlreadyExists` | Image already published | The image is already published under this digest. | Do not upload more parts. Use the published image. | | `OperationInProgress` | Operation already in progress | Another call is working on this digest. | Retry shortly. | The storage operation failed. Media type: application/json ```json { "error": { "code": "StorageFailed", "message": "The storage operation failed.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | | --- | --- | --- | --- | | `StorageFailed` | Storage operation failed | The service could not store the part. | The storage operation failed. Check the relevant image or download state before deciding whether to try again. | There is not enough storage for the part. Media type: application/json ```json { "error": { "code": "InsufficientSpace", "message": "There is not enough storage for this part.", "retryable": false, "need": 8388608, "have": 4194304 } } ``` | Error Code | Title | Description | Resolution | | --- | --- | --- | --- | | `InsufficientSpace` | Insufficient storage | There is not enough storage for this part. The error reports the required `need` bytes and the available `have` bytes. | Free storage and retry. | #### Examples ```bash curl --request PUT \ --header 'Content-Type: application/octet-stream' \ --data-binary '@installer.part' \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/isos/9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08/parts/0' ``` ```typescript import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' }); const sha256 = '9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08'; const bytes = new Uint8Array(8388608); await client.vm.isos.uploadPart(sha256, 0, bytes); ``` The `bytes` argument can be a `Uint8Array`, `Blob`, `ArrayBuffer`, or `ReadableStream`. ### `POST /api/v1/vm/isos/{sha256}/finalize` Hashes every uploaded byte and publishes the image when the result matches `sha256`. Verification can take a few seconds per gigabyte. If the digest does not match, the upload is kept. Compare `bytes` with the actual image size, upload any missing parts, and call this operation again. The operation is idempotent after the image is published. This endpoint takes no request body. #### Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `sha256` | path | string | Yes | SHA-256 digest identifying the image. It must contain exactly 64 lowercase hexadecimal characters. | #### Responses The image was verified and published. Media type: application/json ```json { "media": { "volume_id": "Debian 13.1.0 amd64 n", "system_id": "Debian 13.1.0", "publisher_id": "Debian", "application_id": "Debian Live Installer", "os": [ { "id": "http://debian.org/debian/13", "short_id": "debian13", "name": "Debian 13", "version": "13.1.0", "vendor": "Debian", "family": "linux", "distro": "debian", "codename": "trixie", "arch": "x86_64", "variant": "netinst", "live": false, "installer": true } ] }, "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "phase": "ready", "bytes": 660700000, "part_size": 8388608, "modified_unix": 1767225600 } ``` The digest is invalid, the uploaded bytes do not match it, no bytes have been uploaded, or the request included query parameters. Media type: application/json ```json { "error": { "code": "SpecInvalid", "message": "The uploaded bytes do not hash to the requested digest.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | | --- | --- | --- | --- | | `NameInvalid` | Invalid digest format | `sha256` does not contain exactly 64 lowercase hexadecimal characters. | Recalculate the digest and use its 64-character lowercase hexadecimal value. | | `SpecInvalid` | Invalid request specification | The uploaded bytes hash to a different digest, no bytes have been uploaded, or the operation received query parameters. | Compare `bytes` with the actual size, upload missing parts, remove query parameters, and finalize again. | No published image or unfinished upload has this digest. Media type: application/json ```json { "error": { "code": "NotFound", "message": "No installer image or unfinished upload has this digest.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | | --- | --- | --- | --- | | `NotFound` | Installer image not found | No published image or unfinished upload has this digest. | Verify the digest or begin an upload. | Another call is working on the same digest. Media type: application/json ```json { "error": { "code": "OperationInProgress", "message": "Another call is working on this digest.", "retryable": true } } ``` | Error Code | Title | Description | Resolution | | --- | --- | --- | --- | | `OperationInProgress` | Operation already in progress | Another call is working on this digest. | Retry shortly. | The storage operation failed. Media type: application/json ```json { "error": { "code": "StorageFailed", "message": "The storage operation failed.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | | --- | --- | --- | --- | | `StorageFailed` | Storage operation failed | The service could not verify or publish the image. | The storage operation failed. Check the relevant image or download state before deciding whether to try again. | #### Examples ```bash curl --request POST \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/isos/9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08/finalize' ``` ```typescript import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' }); const sha256 = '9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08'; await client.vm.isos.finalize(sha256); ``` ### `DELETE /api/v1/vm/isos/{sha256}` Deletes a published image or discards an unfinished upload. This action cannot be undone. The service refuses to delete an image while a VM has it attached. Detach the image or delete the VM first. #### Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `sha256` | path | string | Yes | SHA-256 digest identifying the image. It must contain exactly 64 lowercase hexadecimal characters. | #### Responses The response has no body. Media type: none The image or unfinished upload was deleted. The digest is invalid, or the request included query parameters. Media type: application/json ```json { "error": { "code": "NameInvalid", "message": "sha256 must be 64 lowercase hexadecimal characters.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | | --- | --- | --- | --- | | `NameInvalid` | Invalid digest format | `sha256` does not contain exactly 64 lowercase hexadecimal characters. | Recalculate the digest and use its 64-character lowercase hexadecimal value. | | `SpecInvalid` | Invalid request specification | The operation received query parameters. | Remove the query parameters and retry. | No published image or unfinished upload has this digest. Media type: application/json ```json { "error": { "code": "NotFound", "message": "No installer image or unfinished upload has this digest.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | | --- | --- | --- | --- | | `NotFound` | Installer image not found | No published image or unfinished upload has this digest. | Verify the digest or begin an upload. | A VM has the image attached, or another call is working on the same digest. Media type: application/json ```json { "error": { "code": "BadState", "message": "A VM has this image attached.", "retryable": true } } ``` | Error Code | Title | Description | Resolution | | --- | --- | --- | --- | | `BadState` | Image is in use | A VM has this image attached. | Detach the image or delete the VM, then retry. | | `OperationInProgress` | Operation already in progress | Another call is working on this digest. | Retry shortly. | The storage operation failed. Media type: application/json ```json { "error": { "code": "StorageFailed", "message": "The storage operation failed.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | | --- | --- | --- | --- | | `StorageFailed` | Storage operation failed | The service could not delete the image. | The storage operation failed. Check the relevant image or download state before deciding whether to try again. | #### Examples ```bash curl --request DELETE \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/isos/9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08' ``` ```typescript import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' }); const sha256 = '9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08'; await client.vm.isos.delete(sha256); ``` ## Download installer images A download starts as an asynchronous job. Poll the job until `state` is `ready`, then use its `sha256` when creating a VM. A job without an expected digest reports `verification: "tofu"`. ### `POST /api/v1/vm/isos/downloads` Starts fetching an installer image from a URL. The service returns a job immediately and transfers the image in the background. - With `sha256`, the downloaded bytes must match the supplied digest. A mismatch publishes nothing. - Without `sha256`, the image is published under the digest computed from its bytes. The job reports `verification: "tofu"` because the vendor's bytes were not checked. - If the requested digest is already in the image store, the operation returns `AlreadyExists` without fetching. List the images first if you want to treat this as success. - If another download is already fetching the same digest, this operation returns that job. Its `url` can be the URL supplied by the first caller, and deleting it from either caller cancels the shared download. - Without `sha256`, requests for the same URL create independent downloads. - Up to five redirects are followed. Each redirect is checked before it is contacted. A non-2xx final response fails the job. - At the retention limit, the oldest removable finished download (`ready`, `failed`, `cancelled`, `interrupted`) is removed automatically to make room. A finished download whose files could not be removed stays listed until you delete it and can prevent a new submission. A host name is resolved only when the job runs. A host that resolves to any non-public address, or only IPv6 addresses, ends the job `failed` after the `202`. The URL limit is 2048 bytes. #### Request body | Field | Type | Required | Description | | --- | --- | --- | --- | | `url` | string | Yes | Public HTTP or HTTPS URL to fetch. The URL can contain at most 2048 bytes. | | `sha256` | string | No | Expected SHA-256 digest, containing exactly 64 lowercase hexadecimal characters. If omitted, the job uses trust-on-first-use verification. | #### Responses The download was accepted. The response body is the job to poll. Media type: application/json ```json { "id": "0123456789abcdef0123456789abcdef", "state": "running", "url": "https://cdimage.debian.org/cdimage/release/13.1.0/amd64/iso-cd/debian-13.1.0-amd64-netinst.iso", "fetched_bytes": 0 } ``` The URL failed validation, exceeded the 2048-byte limit, or the request included query parameters. Media type: application/json ```json { "error": { "code": "SpecInvalid", "message": "The URL must be a valid public HTTP or HTTPS URL no longer than 2048 bytes.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | | --- | --- | --- | --- | | `SpecInvalid` | Invalid request specification | The URL is not a valid public HTTP or HTTPS target, exceeds 2048 bytes, or the operation received query parameters. | Provide a valid public HTTP or HTTPS URL no longer than 2048 bytes and remove query parameters. | The request body stopped arriving. Media type: application/json ```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. | Retry the request with the same body. | The image already exists, or the service cannot start another download because too many are running or the retention limit cannot be cleared. Media type: application/json ```json { "error": { "code": "AlreadyExists", "message": "An image with this sha256 is already in the store.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | | --- | --- | --- | --- | | `AlreadyExists` | Image already exists | An image with the requested digest is already in the store. | List the images and use the existing image. | | `OperationInProgress` | Download capacity exhausted | Too many downloads are running, or the retention limit is reached and no finished download can be removed to make room. A finished download whose files could not be removed stays listed until you delete it. | Wait for a running download to finish, or fix the storage problem and delete the affected finished download, then retry. At the retention limit, the oldest removable finished download (`ready`, `failed`, `cancelled`, `interrupted`) is removed automatically. | The storage operation failed. Media type: application/json ```json { "error": { "code": "StorageFailed", "message": "The storage operation failed.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | | --- | --- | --- | --- | | `StorageFailed` | Storage operation failed | The service could not create or store the download job. | The storage operation failed. Check the relevant image or download state before deciding whether to try again. | The host has no program available to fetch URLs, so the download cannot start. DNS, TLS, HTTP status, and timeout failures happen after the `202` and appear in the job's `error` field. Media type: application/json ```json { "error": { "code": "DownloadFailed", "message": "No program is available to fetch URLs on this host.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | | --- | --- | --- | --- | | `DownloadFailed` | Download program unavailable | The host has no program available to fetch URLs, so a download cannot start. | Have an operator install a program that can fetch URLs. | #### Examples ```bash curl --request POST \ --header 'Content-Type: application/json' \ --data '{"url":"https://cdimage.debian.org/cdimage/release/13.1.0/amd64/iso-cd/debian-13.1.0-amd64-netinst.iso","sha256":"60303ae22b998861bce3b28f33eec1be758a213c86c93c076dbe9f558c11c752"}' \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/isos/downloads' ``` ```typescript import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' }); await client.vm.isos.downloads.start({ url: 'https://cdimage.debian.org/cdimage/release/13.1.0/amd64/iso-cd/debian-13.1.0-amd64-netinst.iso', sha256: '60303ae22b998861bce3b28f33eec1be758a213c86c93c076dbe9f558c11c752' }); ``` ### `GET /api/v1/vm/isos/downloads` Lists download jobs, sorted by ID. A download interrupted by a service restart has `state: "interrupted"`. It is never resumed automatically. The job and its partial bytes remain until you delete the job or the service removes the job to make room at the retention limit. Finished jobs are forgotten after a restart, but the images they published remain in the image store. This endpoint takes no parameters. #### Responses Returns the download jobs. Media type: application/json ```json [ { "id": "0123456789abcdef0123456789abcdef", "state": "running", "url": "https://cdimage.debian.org/cdimage/release/13.1.0/amd64/iso-cd/debian-13.1.0-amd64-netinst.iso", "effective_url": "https://cdimage.debian.org/cdimage/release/13.1.0/amd64/iso-cd/debian-13.1.0-amd64-netinst.iso", "fetched_bytes": 12582912 }, { "id": "fedcba9876543210fedcba9876543210", "state": "ready", "url": "https://example.com/images/debian-installer.iso", "effective_url": "https://example.com/images/debian-installer.iso", "fetched_bytes": 660700000, "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "verification": "asserted" } ] ``` The request included query parameters, but this operation accepts none. Media type: application/json ```json { "error": { "code": "SpecInvalid", "message": "This operation does not accept query parameters.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | | --- | --- | --- | --- | | `SpecInvalid` | Invalid request specification | The operation received query parameters. | Remove the query parameters and retry. | #### Examples ```bash curl --request GET \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/isos/downloads' ``` ```typescript import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' }); await client.vm.isos.downloads.list(); ``` ### `GET /api/v1/vm/isos/downloads/{id}` Returns one download job, including its state and fetched byte count. Once the job is `ready`, its `sha256` identifies the published image. #### Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Download job identifier. It must contain exactly 32 lowercase hexadecimal characters. | #### Responses Returns the download job. Media type: application/json ```json { "id": "0123456789abcdef0123456789abcdef", "state": "ready", "url": "https://example.com/images/debian-installer.iso", "effective_url": "https://example.com/images/debian-installer.iso", "fetched_bytes": 660700000, "sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "verification": "asserted" } ``` The job ID is invalid, or the request included query parameters. Media type: application/json ```json { "error": { "code": "NameInvalid", "message": "id must be 32 lowercase hexadecimal characters.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | | --- | --- | --- | --- | | `NameInvalid` | Invalid download job ID format | `id` does not contain exactly 32 lowercase hexadecimal characters. | Use the 32-character lowercase hexadecimal ID returned by the list or start operation. | | `SpecInvalid` | Invalid request specification | The operation received query parameters. | Remove the query parameters and retry. | No download job has this ID. Finished jobs are forgotten after a service restart. Media type: application/json ```json { "error": { "code": "NotFound", "message": "No download job has this id.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | | --- | --- | --- | --- | | `NotFound` | Download job not found | No download job has this ID. | Verify the ID or list the available jobs. | #### Examples ```bash curl --request GET \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/isos/downloads/0123456789abcdef0123456789abcdef' ``` ```typescript import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' }); const id = '0123456789abcdef0123456789abcdef'; await client.vm.isos.downloads.get(id); ``` ### `DELETE /api/v1/vm/isos/downloads/{id}` Cancels a running download or removes a finished job's record. Cancellation is asynchronous. A `204` response means the request was accepted, not that the transfer has already stopped. The transfer stops at its next check, its partial bytes are removed, and the job then enters the `cancelled` state. A job in `verifying` cannot be cancelled because its bytes have arrived and are being hashed. Poll it until it is `ready` or `failed`, then delete it. A finished job whose files could not be removed also answers `409` `BadState` and stays listed. Fix the storage problem, then delete it again. Deleting a `ready` job does not delete the published image. Use the installer image delete operation for that. #### Parameters | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `id` | path | string | Yes | Download job identifier. It must contain exactly 32 lowercase hexadecimal characters. | #### Responses Media type: none The response has no body. Cancellation was accepted, or the finished job was removed. The job ID is invalid, or the request included query parameters. Media type: application/json ```json { "error": { "code": "NameInvalid", "message": "id must be 32 lowercase hexadecimal characters.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | | --- | --- | --- | --- | | `NameInvalid` | Invalid download job ID format | `id` does not contain exactly 32 lowercase hexadecimal characters. | Use the 32-character lowercase hexadecimal ID returned by the list or start operation. | | `SpecInvalid` | Invalid request specification | The operation received query parameters. | Remove the query parameters and retry. | No download job has this ID. Media type: application/json ```json { "error": { "code": "NotFound", "message": "No download job has this id.", "retryable": false } } ``` | Error Code | Title | Description | Resolution | | --- | --- | --- | --- | | `NotFound` | Download job not found | No download job has this ID. | Verify the ID or list the available jobs. | The download is being verified, or the files of a finished job could not be removed. Media type: application/json ```json { "error": { "code": "BadState", "message": "The download is being verified and can no longer be cancelled.", "retryable": true } } ``` | Error Code | Title | Description | Resolution | | --- | --- | --- | --- | | `BadState` | Download cannot be deleted | The download is being verified, or the files of a finished job could not be removed. | If the download is being verified, poll until it is `ready` or `failed`, then delete it. If file removal failed, fix the storage problem and delete the job again. | #### Examples ```bash curl --request DELETE \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/isos/downloads/0123456789abcdef0123456789abcdef' ``` ```typescript import { HoodyClient } from 'hoody-sdk'; const client = new HoodyClient({ baseURL: 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com' }); const id = '0123456789abcdef0123456789abcdef'; await client.vm.isos.downloads.delete(id); ```