GB in this document refers to decimal GB (10^9 bytes).
All API queries require Authorization: Bearer [random token]. The random token should be provided to the installer web app as a query string parameter.
Retrieve information about the installer and the user’s device.
Response schema: 200 OK, JSON
| Field | Type | Contents |
|---|---|---|
| version | String | Installer version without a leading “v”, e.g. “0.9.2”. |
| device | DeviceInfo | Information about the device running the installer. |
All fields except productName are optional and may be null.
| Field | Type | Contents |
|---|---|---|
| productName | String | Apple’s full product name, e.g. “MacBook Air (13-inch, M3, 2024)”. |
| soc | String | Apple’s name for the SoC, e.g. “Apple M3”. |
| osVersion | String | macOS version and build. |
| bootMode | String | Current boot environment, e.g. “macOS”. |
| deviceClass | String | Internal device class, e.g. “j613ap”. |
| productType | String | Model identifier, e.g. “Mac15,12”. |
| boardId | String | Board identifier, e.g. “0x30”. |
| chipId | String | Chip identifier, e.g. “0x8122”. |
| systemFirmware | String | System firmware version. |
| bootUuid | String | Current boot UUID. |
| bootVgid | String | Current boot VGID. |
| defaultBootVgid | String | Default boot VGID. |
| osRestoreVersion | String | OS restore version. |
| mainFirmwareVersion | String | Main firmware version. |
| fallbackSystemFirmware | String | Fallback system firmware version. |
| sfrVersion | String | SFR version. |
| systemRecoveryVersion | String | SystemRecovery version. |
| loginUser | String | Logged-in account name. |
Retrieve the current minimum space required by an edition.
Path parameters:
| Field | Type | Contents |
|---|---|---|
| edition | String | Edition identifier recognised by the installer, e.g. “kde”. |
Response schema: 200 OK, JSON
| Field | Type | Contents |
|---|---|---|
| minGB | Number | Minimum total space required for this edition, in GB. |
Retrieve the internal disk layout and valid installation locations.
Response schema: 200 OK, JSON
| Field | Type | Contents |
|---|---|---|
| sizeGB | Number | Total disk capacity in GB. |
| partitions | Partition[] | All regions in physical disk order, including free space and unsuitable partitions. May be empty. |
| Field | Type | Contents |
|---|---|---|
| id | String | Region identifier, unique within the disk and stable for the session. |
| label | String | Display name, e.g. “Macintosh HD”. Required unless labelKey is supplied. |
| labelKey | String | Supported translation key, e.g. “storage.free”. Optional, takes precedence over label. |
| kind | String | free, apfs, or other for an unsuitable region. |
| sizeGB | Number | Current region size in GB. |
| maxGB | Number | Maximum available space to allocate safetly. Exclude any headroom or space that should be left. Should only be present if kind is apfs. |
Start an installation.
Request schema: JSON
| Field | Type | Contents |
|---|---|---|
| edition | String | Edition identifier recognised by the installer, e.g. “kde”. |
| target | String | Identifier of a usable region on the internal disk. |
| sizeGB | Number | For free space, the amount of space to allocate to Linux. For APFS, the amount of space to allocate to Linux by first shrinking the container. |
| volumeName | String | Name for the Volume |
Response schema: 202 Accepted, JSON
Register the installation and return without waiting for it to finish.
409 Conflict if an install is already processing.
Retrieve the latest state of an installation.
Response schema: 200 OK, JSON
| Field | Type | Contents |
|---|---|---|
| status | String | running, complete or failed. |
| stage | String | preparing, resizing, writing or finalising. For failures, the stage where installation stopped. |
| percent | Number or null | Overall completion percentage from 0 to 100, or null if unknown. Must be 100 when complete. |
| step | Integer | Current stage number, starting at 1 and no greater than total. |
| total | Integer | Number of stages planned for this installation. |
| log | String | Full plain-text log, including any failure reason. May be empty. |
Return 200 OK if there's been an install this session, even if it failed.
Return 404 Not Found if /api/install hasn't been called yet.
Retrieve the anonymous installation statistics that would be shared for this session.
Response schema: 200 OK, JSON object
There is no specified format, this may change as needed. The raw object is shown to the user.
Record the user’s statistics choice and request shutdown of the Mac.
Request schema: JSON
| Field | Type | Contents |
|---|---|---|
| shareAnonymousStatistics | Boolean | The user's choice. |
Response schema: 202 Accepted, JSON.
| Field | Type | Contents |
|---|---|---|
| status | String | shutting-down. |