Skip to content

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

Hoody.com

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.

Installer image entries are returned by the image list, get, begin upload, upload part, and finalize operations.

NameTypeRequiredDescription
mediaobjectNoMetadata 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_idstringNoISO-9660 volume identifier.
media.system_idstringNoISO-9660 system identifier.
media.publisher_idstringNoISO-9660 publisher identifier.
media.application_idstringNoISO-9660 application identifier.
media.osarrayYesEvery operating system matched to the image. The array can be empty when the host has no usable operating system database.
media.os[].idstringYesOperating system identifier URI.
media.os[].short_idstringNoShort operating system identifier.
media.os[].namestringNoDisplay name.
media.os[].versionstringNoOperating system version.
media.os[].vendorstringNoVendor name.
media.os[].familystringNoOperating system family.
media.os[].distrostringNoDistribution name.
media.os[].codenamestringNoDistribution codename.
media.os[].archstringNoMatched media architecture. This service can boot only x86_64.
media.os[].variantstringNoMedia variant.
media.os[].livebooleanYesWhether the medium boots into a live system without installing.
media.os[].installerbooleanYesWhether the database identifies the medium as an installer. false means the database does not say, not that the medium is not an installer.
sha256stringYesLowercase SHA-256 digest that identifies the image.
phasestringYesuploading while parts are being sent, or ready after verification.
bytesintegerYesNumber of bytes durably stored.
part_sizeintegerYesExact size required for every part except the last. Use the returned value.
next_partintegerNoZero-based part index to send next. It is absent on a ready image.
modified_unixintegerYesLast modification time in seconds since the Unix epoch.
NameTypeRequiredDescription
idstringYesDownload job identifier, containing exactly 32 lowercase hexadecimal characters.
statestringYesrunning, verifying, ready, failed, cancelled, or interrupted.
urlstringYesURL being fetched. For a joined download, this can be the URL supplied by the first caller.
effective_urlstringNoFinal redirect target that answered, when one was reached.
fetched_bytesintegerYesBytes fetched so far.
expected_bytesintegerNoSize declared by the origin through Content-Length. It is not used to verify or publish the image.
sha256stringNoDigest under which the image was published. Present when the job is ready.
verificationstringNoasserted when an expected digest was supplied and matched, or tofu when no expected digest was supplied.
errorstringNoDescription of why the download failed.
NameTypeRequiredDescription
archstring or nullYesArchitecture filter applied to the rows. This is null when arch=all was requested.
availablebooleanYesWhether a usable operating system database was loaded and contains entries.
statusstringYesDatabase status: healthy, damaged, or absent.
unreadableintegerYesNumber of database files that could not be read or parsed.
entriesarrayYesOperating systems and their advertised installer images.
entries[].idstringYesOperating system identifier URI.
entries[].short_idstringNoShort operating system identifier.
entries[].namestringNoDisplay name.
entries[].versionstringNoOperating system version.
entries[].vendorstringNoVendor name.
entries[].familystringNoOperating system family.
entries[].distrostringNoDistribution name.
entries[].codenamestringNoDistribution codename.
entries[].eolstringNoEnd-of-life date in YYYY-MM-DD format.
entries[].mediaarrayYesImages advertised for the operating system.
entries[].media[].urlstringYesURL from which the image can be fetched.
entries[].media[].archstringNoImage architecture.
entries[].media[].variantstringNoMedia variant.
entries[].media[].livebooleanYesWhether the image boots into a live system without installing.
entries[].media[].installerbooleanYesWhether the database identifies the image as an installer.
entries[].media[].identifiablebooleanYesWhether the image can be identified from its own labels after upload.
NameTypeRequiredDescription
errorobjectYesError details.
error.codestringYesMachine-readable error code. Branch on this value rather than error.message.
error.messagestringYesHuman-readable description of the error.
error.retryablebooleanYesWhether repeating the identical request can succeed without another change.

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.

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
}
]
Terminal window
curl --request GET \
'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/isos'

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.

NameInTypeRequiredDescription
sha256pathstringYesSHA-256 digest identifying the image. It must contain exactly 64 lowercase hexadecimal characters.

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
}
Terminal window
curl --request GET \
'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/isos/9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08'

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".
NameInTypeRequiredDescription
archquerystringNoArchitecture to list. Default: "x86_64". Set to all to include every architecture, including media this host cannot boot.

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
}
]
}
]
}
Terminal window
curl --request GET \
'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/osinfo?arch=x86_64'

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.

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.
NameInTypeRequiredDescription
sha256pathstringYesSHA-256 digest identifying the image. It must contain exactly 64 lowercase hexadecimal characters.
FieldTypeRequiredDescription
bytesintegerYesTotal image size in bytes. It must be at least 1. On resume, it must not be less than the number of bytes already stored.

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
}
Terminal window
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'

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.

NameInTypeRequiredDescription
sha256pathstringYesSHA-256 digest identifying the image. It must contain exactly 64 lowercase hexadecimal characters.
partpathintegerYesZero-based part index. Part n covers bytes from n * part_size up to, but not including, (n + 1) * part_size.

Send the raw part bytes with Content-Type: application/octet-stream. The body is one binary blob, not a JSON object.

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
}
Terminal window
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'

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.

NameInTypeRequiredDescription
sha256pathstringYesSHA-256 digest identifying the image. It must contain exactly 64 lowercase hexadecimal characters.

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
}
Terminal window
curl --request POST \
'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/isos/9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08/finalize'

Deletes a published image or discards an unfinished upload. This action cannot be undone.

NameInTypeRequiredDescription
sha256pathstringYesSHA-256 digest identifying the image. It must contain exactly 64 lowercase hexadecimal characters.

The response has no body.

Media type: none

The image or unfinished upload was deleted.

Terminal window
curl --request DELETE \
'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/isos/9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08'

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".

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.
FieldTypeRequiredDescription
urlstringYesPublic HTTP or HTTPS URL to fetch. The URL can contain at most 2048 bytes.
sha256stringNoExpected SHA-256 digest, containing exactly 64 lowercase hexadecimal characters. If omitted, the job uses trust-on-first-use verification.

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
}
Terminal window
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'

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.

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"
}
]
Terminal window
curl --request GET \
'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/isos/downloads'

Returns one download job, including its state and fetched byte count. Once the job is ready, its sha256 identifies the published image.

NameInTypeRequiredDescription
idpathstringYesDownload job identifier. It must contain exactly 32 lowercase hexadecimal characters.

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"
}
Terminal window
curl --request GET \
'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/isos/downloads/0123456789abcdef0123456789abcdef'

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.

NameInTypeRequiredDescription
idpathstringYesDownload job identifier. It must contain exactly 32 lowercase hexadecimal characters.

Media type: none

The response has no body. Cancellation was accepted, or the finished job was removed.

Terminal window
curl --request DELETE \
'https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/isos/downloads/0123456789abcdef0123456789abcdef'