Host and OS endpoints

These endpoints reach below the containers: the host system and its operating system. Most of them need hassio_api: true with the manager or admin role. The /info endpoints, like GET /host/info, work with any role.

Some endpoints only exist on Home Assistant OS, or need a recent version of it. They return a 404 when they are not available.

Reboots the host. Fails while Home Assistant runs a database migration, unless you force it.

Shuts the host down. Takes the same force key as POST /host/reboot.

Reads the host information again.

Returns the disks with partitions that can be used for a disk mount.

Each partition has device, uuid, label, filesystem, size, read_only, and mountable.

Returns how the space on a disk is used, in bytes. Use default as <disk> for the system disk, or the name of a mount. default always means the system disk, so a mount named default cannot be measured here.

For the system disk, the children are system, addons_data, addons_config, media, share, backup, ssl, and homeassistant, and max_depth sets how far the breakdown goes inside them.

A mount has no such fixed parts, so the Supervisor walks its folders. A max_depth of 0 or 1 returns the totals only, 2 adds the first level of folders, and every level below that needs one more. An other child holds what is not in a folder, like files at the top of the mount. When the files change during the walk and the folders add up to more than used_bytes, the breakdown is left out.

The Supervisor measures a mount by accessing it, which mounts it when it was not mounted yet. A mount that does not exist returns a 404. A mount that cannot be read or is no longer mounted returns an error. When the measurement takes longer than 60 seconds, the request returns an error, but the measurement keeps running. While it runs, a new request for the same mount and max_depth waits for it instead of starting another one. A max_depth below 2 counts as the same depth.

GET /host/logs returns the logs of the host, and works like the other log endpoints. By default it shows the most important services, and every line comes with its timestamp and process, as with verbose. These endpoints narrow it down:

Returns the boots in the journal, by offset. 0 is the current boot.

{
  "boots": {
    "0": "b1c386a144fd44db8f855d7e907256f8",
    "-1": "a3b0e6b2f2cf4e1d9d1e1c8b9a7f6e5d"
  }
}

Returns the syslog identifiers in the journal, as identifiers. Useful ones are NetworkManager for network problems, bluetoothd for Bluetooth, and audit when you work on an AppArmor profile.

These only work on Home Assistant OS.

Installs the update into the inactive slot, and returns. It does not reboot: the new version waits in version_pending of GET /os/info until the system reboots, for example with POST /host/reboot. Until then, version is still the running version. For Home Assistant Core versions older than 2026.8, version reports the pending version instead, so the update is not offered again.

Loads configuration from a USB stick, like network settings.

Needs Home Assistant OS 15.0 or newer.

Takes the same keys. swap_size is a number with an optional unit: B, K, M, or G, optionally followed by B or iB. A size below 40 kB turns swap off. A change creates a reboot required issue.

Switches to the other boot slot and reboots into it.

Moves the data partition to another disk, and reboots the system.

Wipes the data disk and reboots. Only apps with the admin role can call this.

The wipe formats the data partition and the overlay partition. That removes Home Assistant, all apps, backups, and media on the data disk, and host settings like the network connections. The OS and its boot slots stay. After the reboot, the system downloads Home Assistant again and starts with onboarding, like a new installation. You may have to set up the network again to reach it.

Returns success with empty data when <board> is the board in use, and an error otherwise. <board> is the board value of GET /os/info.

POST /os/boards/yellow takes the same keys, all optional. A change creates a reboot required issue.

POST /os/boards/green takes the same keys, all optional.

Returns the state of the Raspberry Pi bootloader firmware, and of the VL805 USB controller firmware where the board has one. Returns a 404 when the board has no firmware to manage, or the OS Agent is older than 1.9.0.

Updates the Raspberry Pi firmware to the version that comes with the OS. Returns an error when update_blocked is true. The new firmware runs after a reboot, so a successful update creates a reboot required issue.

/os/ssh/authorized_keys manages the SSH keys of the root user of the host, for the SSH server on port 22222. Only Home Assistant Core can call these endpoints, not apps.

• GET returns the keys as keys, one entry per line of the file, without blank and comment lines. It needs OS Agent 1.11.0 or newer, and returns a 404 otherwise.
• POST adds the key you send as key, like ssh-ed25519 AAAA..., to the keys that are already there. The key may not be longer than 3000 bytes or contain control characters. Since OS Agent 1.10.0, the key must also be one valid line of an OpenSSH authorized_keys file, options included. Adding a key also starts the SSH server of the host.
• DELETE removes all keys. It also stops the SSH server, which ends open sessions.

Returns the audio devices of the host, by name and description.

{
  "audio": {
    "input": {
      "0,0": "Mic"
    },
    "output": {
      "1,0": "Jack",
      "0,1": "HDMI"
    }
  }
}

<interface> is the name of an interface, like eth0, or default for the primary interface.

{
  "interfaces": [
    {
      "interface": "eth0",
      "type": "ethernet",
      "enabled": true,
      "connected": true,
      "primary": true,
      "mac": "52:54:00:12:34:56",
      "ipv4": {
        "method": "auto",
        "address": ["192.168.1.100/24"],
        "nameservers": ["192.168.1.1"],
        "gateway": "192.168.1.1",
        "route_metric": null,
        "ready": true
      },
      "ipv6": null,
      "wifi": null,
      "vlan": null,
      "mdns": "default",
      "llmnr": "default"
    }
  ],
  "docker": {
    "interface": "hassio",
    "address": "172.30.32.0/23",
    "gateway": "172.30.32.1",
    "dns": "172.30.32.3"
  },
  "host_internet": true,
  "supervisor_internet": true
}

Reads the network state again, and checks the internet connection.

Returns one network interface model.

Changes the configuration of an interface. Send at least one key. A block you send replaces the whole configuration of that block, so send all of its keys.

The ipv4 and ipv6 blocks take:

The wifi block takes:

{
  "ipv4": {
    "method": "static",
    "address": ["192.168.1.100/24"],
    "gateway": "192.168.1.1",
    "nameservers": ["192.168.1.1"]
  }
}

Scans for Wi-Fi networks. Only works on a wireless interface.

Creates a VLAN on an Ethernet interface. <id> is the VLAN ID, from 0 to 4094. Takes the ipv4, ipv6, mdns, and llmnr keys of the update endpoint. Here, method defaults to auto instead of static.

These endpoints set the NTP servers the host uses to sync its clock. They need Home Assistant OS 18.3 or newer, and return a 404 otherwise. When they are available, all_features of GET /host/info lists ntp.

Returns the servers the Supervisor configured, as config. The host can also get servers from other places, like DHCP, so the servers in use can differ.

{
  "config": {
    "servers": ["time.cloudflare.com"],
    "fallback_servers": []
  }
}

A key you leave out keeps its value. An empty list clears the configured servers. Each server is a host name or IP address. After a change, the time sync service of the host restarts.

Mounts add network shares and local disks to the system, for backups, media, or the share folder.

Adds a mount. The body is a mount model.

{
  "name": "nas_backups",
  "usage": "backup",
  "type": "cifs",
  "server": "nas.local",
  "share": "backups",
  "username": "homeassistant",
  "password": "secret"
}

The first backup mount you add becomes the default backup location.

Replaces the configuration of a mount. Takes the same body as POST /mounts. You cannot change the name.

Removes a mount.

Checks whether the mount answers. A mount that answers is left alone. Otherwise Supervisor mounts it again with the same configuration, and returns an error when it still cannot reach it. Useful when a share was not reachable.

A change needs a reboot to take effect, and creates a reboot required issue.

{
  "registries": {
    "ghcr.io": {
      "username": "octocat"
    }
  }
}

Adds credentials for a container registry. The Supervisor uses them to pull images. For Docker Hub, use docker.io as the host name.

{
  "ghcr.io": {
    "username": "octocat",
    "password": "ghp_secret"
  }
}

Removes the credentials of a registry.

Switches the Docker storage driver on the next reboot, and creates a reboot required issue. Needs Home Assistant OS 17.0 or newer, and returns a 404 otherwise.

Throws away all images and containers on the next reboot, and creates a reboot required issue. After the reboot, the system downloads the images of the Supervisor, Home Assistant Core, the plugins, and the apps again, so it needs internet access. Needs Home Assistant OS 18.3 or newer, and returns a 404 otherwise.