VM: Installer images
Section titled “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.
Response objects
Section titled “Response objects”Installer image entry
Section titled “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
Section titled “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
Section titled “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. |
| 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
Section titled “Installer image store”GET /api/v1/vm/isos
Section titled “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
Section titled “Responses”Returns every image in the store.
Media type: application/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
{ "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
{ "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
Section titled “Examples”curl --request GET \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/isos'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}
Section titled “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
Section titled “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
Section titled “Responses”Returns the image’s status.
Media type: application/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
{ "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
{ "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
{ "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
Section titled “Examples”curl --request GET \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/isos/9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08'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
Section titled “GET /api/v1/vm/osinfo”Lists the operating systems and installer images advertised by the host’s osinfo-db package.
- By default, only
x86_64media is listed because it is the only architecture this service can boot. - Set
arch=allto list every architecture, including media this host cannot boot. - Set
archto an architecture name to filter the catalogue. available: falsemeans the host has no usable database. Thestatusfield indicates whether the database isabsentordamaged.- 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
Section titled “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
Section titled “Responses”Returns the catalogue. Its entries array is empty when the host has no usable database.
Media type: application/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
{ "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
Section titled “Examples”curl --request GET \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/osinfo?arch=x86_64'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
Section titled “Upload installer images”An upload consists of three operations:
- Begin or resume the upload with the digest and total byte count.
- Upload each part in order.
- Finalize the upload after the stored byte count reaches the declared total.
POST /api/v1/vm/isos/{sha256}
Section titled “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_partso 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
Section titled “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
Section titled “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
Section titled “Responses”The upload was declared, resumed, or found already complete. Read phase to determine the next action.
Media type: application/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
{ "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
{ "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
{ "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
{ "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
{ "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
Section titled “Examples”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'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}
Section titled “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
Section titled “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
Section titled “Request body”Send the raw part bytes with Content-Type: application/octet-stream. The body is one binary blob, not a JSON object.
Responses
Section titled “Responses”The part was stored. The response reports the stored bytes and next_part.
Media type: application/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
{ "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
{ "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
{ "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
{ "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
{ "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
{ "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
Section titled “Examples”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'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
Section titled “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
Section titled “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
Section titled “Responses”The image was verified and published.
Media type: application/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
{ "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
{ "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
{ "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
{ "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
Section titled “Examples”curl --request POST \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/isos/9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08/finalize'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}
Section titled “DELETE /api/v1/vm/isos/{sha256}”Deletes a published image or discards an unfinished upload. This action cannot be undone.
Parameters
Section titled “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
Section titled “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
{ "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
{ "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
{ "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
{ "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
Section titled “Examples”curl --request DELETE \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/isos/9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08'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
Section titled “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
Section titled “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 reportsverification: "tofu"because the vendor’s bytes were not checked. - If the requested digest is already in the image store, the operation returns
AlreadyExistswithout 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
urlcan 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.
Request body
Section titled “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
Section titled “Responses”The download was accepted. The response body is the job to poll.
Media type: application/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
{ "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
{ "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
{ "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
{ "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
{ "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
Section titled “Examples”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'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
Section titled “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
Section titled “Responses”Returns the download jobs.
Media type: application/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
{ "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
Section titled “Examples”curl --request GET \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/isos/downloads'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}
Section titled “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
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Download job identifier. It must contain exactly 32 lowercase hexadecimal characters. |
Responses
Section titled “Responses”Returns the download job.
Media type: application/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
{ "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
{ "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
Section titled “Examples”curl --request GET \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/isos/downloads/0123456789abcdef0123456789abcdef'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}
Section titled “DELETE /api/v1/vm/isos/downloads/{id}”Cancels a running download or removes a finished job’s record.
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
Section titled “Parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | Download job identifier. It must contain exactly 32 lowercase hexadecimal characters. |
Responses
Section titled “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
{ "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
{ "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
{ "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
Section titled “Examples”curl --request DELETE \ 'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/isos/downloads/0123456789abcdef0123456789abcdef'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);