Skip to content

Instantly share code, notes, and snippets.

@IntegralPilot
Last active October 14, 2026 12:17
Show Gist options
  • Select an option

  • Save IntegralPilot/47ca5f9ae4a877bfb2a36d530d4e90de to your computer and use it in GitHub Desktop.

Select an option

Save IntegralPilot/47ca5f9ae4a877bfb2a36d530d4e90de to your computer and use it in GitHub Desktop.
Asahi Linux Installer API v1 Draft 1

Asahi Linux Installer API v1

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.

GET /api/info

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.

DeviceInfo

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.

GET /api/edition/[edition]/size

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.

GET /api/partitions

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.

Partition

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.

POST /api/install

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.

GET /api/progress

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.

GET /api/telemetry

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.

POST /api/shutdown

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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment