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 upload an exported snapshot artifact into a computer’s VM import store, verify its SHA-256 digest, publish it, and create one or more VMs from the published artifact. The import store retains artifacts until you delete them.

  1. Declare the artifact. Begin or resume an upload with the artifact’s total size in bytes. The import store identifies each artifact by its 64-character lowercase hexadecimal SHA-256 digest.
  2. Upload every part in order. Use the part_size returned by the service. Every part except the last must contain exactly part_size bytes. The service uses 8 MiB, so examples show part_size as 8388608, but clients must always use the returned value.
  3. Verify and publish. Finalize the upload after all bytes have been sent. The service hashes the uploaded bytes and publishes the artifact only when the digest matches. Only an artifact with phase: ready can be used to create a VM.
  4. Create the VM with the required settings. Use a snapshot-artifact source that names the artifact’s sha256. The source holds only type, sha256, and duplicate_tpm_identity. The memory_mib, vcpus, and bus fields are top-level create fields beside source, and all three are required, because the artifact records none of them. Omitting bus is refused with 400. bus must be the bus the guest was installed on, because selecting a different bus leaves a guest that cannot boot.
  5. Handle TPM state. An artifact that carries TPM state, including every Windows 11 guest, also requires duplicate_tpm_identity: true in the source. Otherwise, the create is refused with 400. This setting gives the new VM the same TPM identity and sealed keys as the original.
  6. Manage retained artifacts. A published artifact remains after a VM is created from it and can build more VMs. It occupies storage until deleted. Deletion is irreversible and does not affect VMs already created from the artifact.

GET /api/v1/vm/imports

Returns all artifacts in the import store, including published artifacts and uploads still in progress. An unfinished upload remains in the store and is never removed automatically. A published artifact remains after a VM is created from it, so it can build more VMs and continues to occupy storage until deletion.

This endpoint takes no parameters.

Terminal window
curl --globoff --request GET \
"https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/imports"

Each item in the response array describes one artifact.

FieldTypeRequiredDescription
sha256stringYesThe artifact’s lowercase hexadecimal SHA-256 digest and identity.
phasestringYesuploading while parts are still being sent, or ready after the bytes are verified.
bytesintegerYesBytes durably stored. This is the resume point while uploading and the final size when ready.
part_sizeintegerYesThe exact size that every part except the last must contain.
next_partintegerNoThe zero-based part index to send next. It is absent on a ready artifact.
modified_unixintegerYesLast modification time in seconds since the Unix epoch.

Error responses contain these fields:

FieldTypeRequiredDescription
errorobjectYesError details.
error.codestringYesA fixed error code. Branch on this value rather than error.message.
error.messagestringYesHuman-readable error information.
error.retryablebooleanYesWhether repeating the identical request could succeed without any other change.

Media type: application/json

[
{
"sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"phase": "uploading",
"bytes": 8388608,
"part_size": 8388608,
"next_part": 1,
"modified_unix": 1767225600
},
{
"sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
"phase": "ready",
"bytes": 12582912,
"part_size": 8388608,
"modified_unix": 1767225601
}
]

GET /api/v1/vm/imports/{sha256}

Returns an artifact’s publication status. For an unfinished upload, it also reports the number of bytes stored and the part to send next. These values are read from the stored data, so they remain accurate after a crash on either side.

NameInTypeRequiredDescription
sha256pathstringYesThe artifact’s SHA-256 digest, exactly 64 lowercase hexadecimal characters.

This endpoint takes no request body.

Terminal window
curl --globoff --request GET \
"https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/imports/9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
FieldTypeRequiredDescription
sha256stringYesThe artifact’s lowercase hexadecimal SHA-256 digest and identity.
phasestringYesuploading while parts are still being sent, or ready after verification.
bytesintegerYesBytes durably stored. This is the resume point while uploading and the final size when ready.
part_sizeintegerYesThe exact size that every part except the last must contain.
next_partintegerNoThe zero-based part index to send next. It is absent on a ready artifact.
modified_unixintegerYesLast modification time in seconds since the Unix epoch.

Error responses contain these fields:

FieldTypeRequiredDescription
errorobjectYesError details.
error.codestringYesA fixed error code. Branch on this value rather than error.message.
error.messagestringYesHuman-readable error information.
error.retryablebooleanYesWhether repeating the identical request could succeed without any other change.

Media type: application/json

{
"sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"phase": "uploading",
"bytes": 8388608,
"part_size": 8388608,
"next_part": 1,
"modified_unix": 1767225600
}

Begin or resume a snapshot artifact upload

Section titled “Begin or resume a snapshot artifact upload”

POST /api/v1/vm/imports/{sha256}

Declares an artifact upload under its SHA-256 digest and total size. If the artifact is already published, the response has phase: ready and no upload is needed. If an earlier upload was interrupted, the response identifies the next part to resume from.

This operation is safe to repeat and never truncates an upload in progress. On a resume, a different bytes value replaces the declared total when it is at least the number of bytes already stored. The resume point is then recalculated, allowing a mis-declared upload to be corrected.

Plan for twice the artifact’s size because the retained artifact and the VM rebuilt from it exist at the same time.

NameInTypeRequiredDescription
sha256pathstringYesThe artifact’s SHA-256 digest, exactly 64 lowercase hexadecimal characters.
FieldTypeRequiredDescription
bytesintegerYesThe artifact’s total size in bytes. It must be positive and cannot be less than the bytes already stored.

Declaring bytes does not reserve storage. It allows the service to return 507 immediately if the artifact cannot fit. On a resume, a larger valid total replaces the previous declaration and recalculates next_part.

Terminal window
curl --globoff --request POST \
"https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/imports/9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08" \
--header "Content-Type: application/json" \
--data '{"bytes": 12582912}'
FieldTypeRequiredDescription
sha256stringYesThe artifact’s lowercase hexadecimal SHA-256 digest and identity.
phasestringYesuploading while parts are still being sent, or ready after verification.
bytesintegerYesBytes durably stored. This is the resume point while uploading and the final size when ready.
part_sizeintegerYesThe exact size that every part except the last must contain.
next_partintegerNoThe zero-based part index to send next. It is absent on a ready artifact.
modified_unixintegerYesLast modification time in seconds since the Unix epoch.

Error responses contain these fields:

FieldTypeRequiredDescription
errorobjectYesError details.
error.codestringYesA fixed error code. Branch on this value rather than error.message.
error.messagestringYesHuman-readable error information.
error.retryablebooleanYesWhether repeating the identical request could succeed without any other change.

Media type: application/json

{
"sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"phase": "uploading",
"bytes": 8388608,
"part_size": 8388608,
"next_part": 1,
"modified_unix": 1767225600
}

PUT /api/v1/vm/imports/{sha256}/parts/{part}

Appends one part of an artifact. 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 applied twice, so a request whose response was not observed can be retried safely.

When the stored bytes reach the declared total, call Verify and publish a snapshot artifact. If an upload is interrupted during a part, bytes reports the last complete part boundary and next_part identifies the part to send again. After any failure, call Get a snapshot artifact to determine where to resume.

NameInTypeRequiredDescription
sha256pathstringYesThe artifact’s SHA-256 digest, exactly 64 lowercase hexadecimal characters.
partpathintegerYesZero-based part index. Part n covers bytes [n*part_size, (n+1)*part_size).

Send the raw part as application/octet-stream. The request has no JSON body fields.

Use the part_size returned by the service. Every part except the final part must contain exactly that many bytes.

Terminal window
curl --globoff --request PUT \
"https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/imports/9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08/parts/0" \
--header "Content-Type: application/octet-stream" \
--data-binary @snapshot.part
FieldTypeRequiredDescription
sha256stringYesThe artifact’s lowercase hexadecimal SHA-256 digest and identity.
phasestringYesuploading while parts are still being sent, or ready after verification.
bytesintegerYesBytes durably stored. This is the resume point while uploading and the final size when ready.
part_sizeintegerYesThe exact size that every part except the last must contain.
next_partintegerNoThe zero-based part index to send next. It is absent on a ready artifact.
modified_unixintegerYesLast modification time in seconds since the Unix epoch.

Error responses contain these fields:

FieldTypeRequiredDescription
errorobjectYesError details.
error.codestringYesA fixed error code. Branch on this value rather than error.message.
error.messagestringYesHuman-readable error information.
error.retryablebooleanYesWhether repeating the identical request could succeed without any other change.

Media type: application/json

{
"sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"phase": "uploading",
"bytes": 8388608,
"part_size": 8388608,
"next_part": 1,
"modified_unix": 1767225600
}

POST /api/v1/vm/imports/{sha256}/finalize

Hashes every uploaded byte and publishes the artifact when the result matches its SHA-256 digest. Only a published artifact can be used to create a VM. Verification takes a few seconds per gigabyte.

A digest mismatch is refused with 400, and the upload is retained. A mismatch often means that parts are missing. Compare bytes with the real artifact size, send any missing parts, and call this operation again. The operation is idempotent after the artifact is published.

NameInTypeRequiredDescription
sha256pathstringYesThe artifact’s SHA-256 digest, exactly 64 lowercase hexadecimal characters.

This endpoint takes no request body.

Terminal window
curl --globoff --request POST \
"https://{projectId}-{computerId}-vm-1.{server}.computers.hoody.com/api/v1/vm/imports/9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08/finalize"
FieldTypeRequiredDescription
sha256stringYesThe artifact’s lowercase hexadecimal SHA-256 digest and identity.
phasestringYesuploading while parts are still being sent, or ready after verification.
bytesintegerYesBytes durably stored. This is the resume point while uploading and the final size when ready.
part_sizeintegerYesThe exact size that every part except the last must contain.
next_partintegerNoThe zero-based part index to send next. It is absent on a ready artifact.
modified_unixintegerYesLast modification time in seconds since the Unix epoch.

Error responses contain these fields:

FieldTypeRequiredDescription
errorobjectYesError details.
error.codestringYesA fixed error code. Branch on this value rather than error.message.
error.messagestringYesHuman-readable error information.
error.retryablebooleanYesWhether repeating the identical request could succeed without any other change.

Media type: application/json

{
"sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
"phase": "ready",
"bytes": 12582912,
"part_size": 8388608,
"modified_unix": 1767225600
}

DELETE /api/v1/vm/imports/{sha256}

Deletes a published artifact or discards an unfinished upload. The operation cannot be undone.

VMs already created from the artifact are unaffected because creating a VM copies the artifact’s contents. A create that is already rebuilding a VM from the artifact also completes normally. The call is refused with 409 while an upload, finalize, or another delete is working on the same digest, or while a create is still opening the artifact. Retry shortly in those cases.

NameInTypeRequiredDescription
sha256pathstringYesThe artifact’s SHA-256 digest, exactly 64 lowercase hexadecimal characters.

This endpoint takes no request body.

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

Error responses contain these fields:

FieldTypeRequiredDescription
errorobjectYesError details.
error.codestringYesA fixed error code. Branch on this value rather than error.message.
error.messagestringYesHuman-readable error information.
error.retryablebooleanYesWhether repeating the identical request could succeed without any other change.

Media type: none

The response has no body.