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	When it was added.

Library and custom ISOs¶

List ISOs¶

GET /projects/{slug}/isos/

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

The library's ISOs and the project's own.

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.

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

The URL must:

use http or https, and end with .iso;
be a public address, not a private or internal one;
answer directly, without redirecting.

A project holds one custom ISO: adding a second answers 409 iso_limit_reached, so delete the first. If you lose the answer, list the project's ISOs before trying again: the download carries on, and the list shows it.

Get an ISO¶

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

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

The project's custom ISO. Library ISOs are only in the list.

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.

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.

{"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`	The URL is invalid, or doesn't meet the rules above.
403	`read_only_key`	A change with a read-only key.
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.
502	`upstream_error`	A system behind the API failed.