ISOs¶

Mount an ISO image on a server to boot an installer or a rescue system from it. HostHatch keeps a library of ISOs, and each project can add one ISO of its own, which we download from a URL you give.

Endpoints¶

Endpoint	What it does
POST `/projects/{slug}/servers/{id}/actions/mount-iso/`	Mount an ISO
POST `/projects/{slug}/servers/{id}/actions/unmount-iso/`	Unmount an ISO
GET `/projects/{slug}/isos/`	List ISOs
POST `/projects/{slug}/isos/`	Upload an ISO
GET `/projects/{slug}/isos/{id}/`	Get an ISO
DELETE `/projects/{slug}/isos/{id}/`	Delete an ISO

The ISO object¶

{
  "id": 8980,
  "name": "AlmaLinux-10.2-x86_64-dvd.iso",
  "type": "custom",
  "status": "ready",
  "progress": 100,
  "created_at": "2026-10-07T14:09:24Z"
}

Field	Type	Description
`id`	integer	The ISO's id, which mounting takes.
`name`	string	Its file name.
`type`	string	`library` for HostHatch's ISOs, `custom` for the project's own.
`status`	string	`downloading`, `ready` or `failed`. Library ISOs are always `ready`.
`progress`	integer	How much is downloaded, from 0 to 100.
`created_at`	string or null	When it was added.

Library and custom ISOs¶

List ISOs¶

GET /projects/{slug}/isos/

Any member · Read-only keys: yes · Returns 200 Iso[]

The ISOs the project's servers can boot from: the project's own custom ISO first, then HostHatch's library.

Upload an ISO¶

POST /projects/{slug}/isos/

Any member · Read-only keys: no · Returns 201 Iso

Add the project's custom ISO from a URL. The answer is 201 with the ISO, downloading: poll it until it is ready. Uploads through the API aren't available yet: until they are, this answers 400 feature_unavailable.

{"url": "https://example.com/images/rescue.iso"}

The URL must:

be at most 255 characters of ASCII, use http or https, and have no user name, password, query string or fragment;
end in the file's name, made of letters, digits, dots, hyphens, underscores and plus signs, and ending in .iso;
point at a public host, not a private or internal address;
answer a HEAD request with 200 directly, without redirecting;
be a file that reports its size, at most 10 GiB, with a name the project's owner hasn't uploaded in any of their projects.

A URL that breaks a rule answers 400 validation_error, and the url error's code says which: invalid for the URL itself or the file, unreachable when its host can't be reached or isn't public, redirect, or not_the_file when it answers HEAD with anything but 200.

A project holds one custom ISO: while it has one, an upload answers 409 iso_limit_reached with that ISO's id in iso_id. Delete it to upload another. If you lose the answer to an upload, send it again: if the upload had started, the answer is 409 iso_limit_reached with its id.

Get an ISO¶

GET /projects/{slug}/isos/{id}/

Any member · Read-only keys: yes · Returns 200 Iso

A library ISO, or the project's own. Poll a custom ISO while it is downloading.

Delete an ISO¶

DELETE /projects/{slug}/isos/{id}/

Any member · Read-only keys: no · Returns 204

Delete the project's custom ISO. An ISO mounted on a server answers 409 iso_mounted: unmount it first. Library ISOs are shared by every project, so deleting one answers 403 permission_denied.

Mounting¶

Mounting and unmounting are actions, and exclusive: one at a time per server, and not during another exclusive action. Each changes the server's boot order and reboots it. Send an Idempotency-Key with each.

Mount an ISO¶

POST /projects/{slug}/servers/{id}/actions/mount-iso/

Any member · Read-only keys: no · Returns 202 Action

Mount an ISO on the server: a library ISO, or the project's own once it is ready. One still downloading, or whose download failed, answers 409 conflict, and any other ISO 404 not_found.

{"iso_id": 8980}

The server's iso field shows the mounted ISO.

Unmount an ISO¶

POST /projects/{slug}/servers/{id}/actions/unmount-iso/

Any member · Read-only keys: no · Returns 202 Action

Unmount the server's ISO, so it boots from its disk again. The request takes no body.

Errors¶

Status	Code	When
400	`validation_error`	A field is invalid, or the URL doesn't meet the rules above.
400	`feature_unavailable`	Uploading an ISO, while uploads through the API aren't available.
403	`read_only_key`	A change with a read-only key.
403	`permission_denied`	Deleting a library ISO.
403	`billing_account_required`	The project's owner has no billing account.
403	`project_not_ready`	The project is still being set up.
404	`not_found`	No such ISO or server in the project.
409	`iso_limit_reached`	The project already has a custom ISO.
409	`iso_mounted`	Deleting an ISO that is mounted.
409	`action_in_progress`	Another exclusive action is running on the server.
409	`conflict`	Mounting a custom ISO that isn't `ready`.
409	`idempotency_key_reused`	The key was used for another request.
502	`upstream_error`	A system behind the API failed.
503	`upstream_unavailable`	A system behind the API is unavailable for now. Try again after `Retry-After`.
503	`node_maintenance`	The server's host is in maintenance.