developers.home-assistant/endpoints.md at pr/gjohansson-ST/1616

90 KiB

Raw Permalink Blame History

title
Endpoints

import ApiEndpoint from '@site/static/js/api_endpoint.jsx'

For API endpoints marked with 🔒 you need use an authorization header with a Bearer token.

The token is available for add-ons and Home Assistant using the SUPERVISOR_TOKEN environment variable.

To see more details about each endpoint, click on it to expand it.

Addons

Return overview information about installed add-ons.

Payload:

key	type	description
addons	list	A list of Addon models

Example response:

{
  "addons": [
    {
      "name": "Awesome add-on",
      "slug": "awesome_addon",
      "description": "My awesome add-on",
      "advanced": false,
      "stage": "stable",
      "repository": "core",
      "version": null,
      "version_latest": "1.0.1",
      "update_available": false,
      "installed": false,
      "detached": true,
      "available": true,
      "build": false,
      "url": null,
      "icon": false,
      "logo": false
    }
  ]
}

Reloads the information stored about add-ons. Get the changelog for an add-on. Get the documentation for an add-on. Returns the raw container logs from docker. Get the add-on icon Get details about an add-on

Returned data:

key	type	description
advanced	boolean	`true` if advanced mode is enabled
apparmor	string	disabled, default or the name of the profile
arch	list	A list of supported architectures for the add-on
audio	boolean	`true` if audio is enabled
audio_input	float or null	The device index
audio_output	float or null	The device index
auth_api	boolean	`true` if auth api access is granted is enabled
auto_uart	boolean	`true` if auto_uart access is granted is enabled
auto_update	boolean	`true` if auto update is enabled
available	boolean	`true` if the add-on is available
boot	string	"boot" or "manual"
build	boolean	`true` if local add-on
changelog	boolean	`true` if changelog is available
description	string	The add-on description
detached	boolean	`true` if the add-on is running detached
devices	list	A list of attached devices
devicetree	boolean	`true` if devicetree access is granted is enabled
discovery	list	A list of discovery services
dns	list	A list of DNS servers used by the add-on
docker_api	boolean	`true` if docker_api access is granted is enabled
documentation	boolean	`true` if documentation is available
full_access	boolean	`true` if full access access is granted is enabled
gpio	boolean	`true` if gpio access is granted is enabled
hassio_api	boolean	`true` if hassio api access is granted is enabled
hassio_role	string	The hassio role (default, homeassistant, manager, admin)
homeassistant	string or null	The minimum Home Assistant Core version
homeassistant_api	boolean	`true` if homeassistant api access is granted is enabled
host_dbus	boolean	`true` if host dbus access is granted is enabled
host_ipc	boolean	`true` if host ipc access is granted is enabled
host_network	boolean	`true` if host network access is granted is enabled
host_pid	boolean	`true` if host pid access is granted is enabled
host_uts	boolean	`true` if host UTS namespace access is enabled.
hostname	string	The host name of the add-on
icon	boolean	`true` if icon is available
ingress	boolean	`true` if ingress is enabled
ingress_entry	string or null	The ingress entrypoint
ingress_panel	boolean or null	`true` if ingress_panel is enabled
ingress_port	int or null	The ingress port
ingress_url	string or null	The ingress URL
ip_address	string	The IP address of the add-on
kernel_modules	boolean	`true` if kernel module access is granted is enabled
logo	boolean	`true` if logo is available
long_description	string	The long add-on description
machine	list	A list of supported machine types for the add-on
name	string	The name of the add-on
network	dictionary or null	The network configuration for the add-on
network_description	dictionary or null	The description for the network configuration
options	dictionary	The add-on configuration
privileged	list	A list of hardwars/system attributes the add-onn has access to
protected	boolean	`true` if protection mode is enabled
rating	int	The addon rating
repository	string	The URL to the add-on repository
schema	dictionary or null	The schema for the add-on configuration
services_role	list	A list of services and the add-ons role for that service
slug	string	The add-on slug
stage	string	The add-on stage (stable, experimental, deprecated)
startup	string	The stage when the add-on is started (initialize, system, services, application, once)
state	string or null	The state of the add-on (started, stopped)
stdin	boolean	`true` if the add-on accepts stdin commands
translations	dictionary	A dictionary containing content of translation files for the add-on
udev	boolean	`true` if udev access is granted is enabled
update_available	boolean	`true` if an update is available
url	string or null	URL to more information about the add-on
usb	list	A list of attached USB devices
version	string	The installed version of the add-on
version_latest	string	The latest version of the add-on
video	boolean	`true` if video is enabled
watchdog	boolean	`true` if watchdog is enabled
webui	string or null	The URL to the web UI for the add-on
signed	boolean	True if the image is signed and trust

Example response:

{
  "advanced": false,
  "apparmor": "default",
  "arch": ["armhf", "aarch64", "i386", "amd64"],
  "audio_input": null,
  "audio_output": null,
  "audio": false,
  "auth_api": false,
  "auto_uart": false,
  "auto_update": false,
  "available": false,
  "boot": "auto",
  "build": false,
  "changelog": false,
  "description": "description",
  "detached": false,
  "devices": ["/dev/xy"],
  "devicetree": false,
  "discovery": ["service"],
  "dns": [],
  "docker_api": false,
  "documentation": false,
  "full_access": false,
  "gpio": false,
  "hassio_api": false,
  "hassio_role": "default",
  "homeassistant_api": false,
  "homeassistant": null,
  "host_dbus": false,
  "host_ipc": false,
  "host_network": false,
  "host_pid": false,
  "host_uts": false,
  "hostname": "awesome-addon",
  "icon": false,
  "ingress_entry": null,
  "ingress_panel": true,
  "ingress_port": 1337,
  "ingress_url": null,
  "ingress": false,
  "ip_address": "172.0.0.21",
  "kernel_modules": false,
  "logo": false,
  "long_description": "Long description",
  "machine": ["raspberrypi2", "tinker"],
  "name": "Awesome add-on",
  "network_description": "{}|null",
  "network": {},
  "options": {},
  "privileged": ["NET_ADMIN", "SYS_ADMIN"],
  "protected": false,
  "rating": "1-6",
  "repository": "12345678",
  "schema": {},
  "services_role": ["service:access"],
  "slug": "awesome_addon",
  "stage": "stable",
  "startup": "application",
  "state": "started",
  "stdin": false,
  "translations": {
    "en": {
      "configuration": {
        "lorem": "ipsum"
      }
    }
  },
  "udev": false,
  "update_available": false,
  "url": null,
  "usb": ["/dev/usb1"],
  "version_latest": "1.0.2",
  "version": "1.0.0",
  "video": false,
  "watchdog": true,
  "webui": "http://[HOST]:1337/xy/zx",
  "signed": false
}

Install an add-on

Deprecated! Use /store/addons/<addon>/install instead.

Get the add-on logo Set the protection mode on an add-on.

This function is not callable by itself and you can not use self as the slug here.

:::tip To reset customized network/audio/options, set it null. :::

Payload:

key	type	description
boot	string	(auto, manual)
auto_update	boolean	`true` if the add-on should auto update
network	dictionary	A map of network configuration.
options	dictionary	The add-on configuration
audio_output	float or null	The index of the audio output device
audio_input	float or null	The index of the audio input device
ingress_panel	boolean	`true` if ingress_panel is enabled
watchdog	boolean	`true` if watchdog is enabled

You need to supply at least one key in the payload.

Example payload:

{
  "boot": "manual",
  "auto_update": false,
  "network": {
    "CONTAINER": "1337"
  },
  "options": {
    "awesome": true
  },
  "watchdog": true
}

Run a configuration validation against the current stored add-on configuration or payload.

Payload:

Optional the raw add-on options.

Returned data:

key	type	description
message	string	Include the error message
valid	boolean	If config is valid or not
pwned	boolean	None

The Data endpoint to get his own rendered configuration. Rebuild the add-on, only supported for local build add-ons. Restart an add-on Set the protection mode on an add-on.

This function is not callable by itself and you can not use self as the slug here.

Payload:

key	type	description
protected	boolean	`true` if protection mode is on

Start an add-on

Returns a Stats model for the add-on.

Example response:

{
  "cpu_percent": 14.0,
  "memory_usage": 288888,
  "memory_limit": 322222,
  "memory_percent": 32.4,
  "network_tx": 110,
  "network_rx": 902,
  "blk_read": 12,
  "blk_write": 27
}

Write data to add-on stdin.

The payload you want to pass into the addon you give the endpoint as the body of the request.

Stop an add-on Uninstall an add-on Update an add-on

Deprecated! Use /store/addons/<addon>/update instead.

Audio

Set a profile as the default input profile

Payload:

key	type	optional	description
name	string	False	The name of the profile

Set a profile as the default output profile

Payload:

key	type	optional	description
name	string	False	The name of the profile

Return information about the audio plugin.

Returned data:

key	type	description
host	string	The IP address of the plugin
version	string	The installed observer version
version_latest	string	The latest published version
update_available	boolean	`true` if an update is available
audio	dictionary	An Audio model

Example response:

{
  "host": "172.0.0.19",
  "version": "1",
  "latest_version": "2",
  "update_available": true,
  "audio": {
    "card": [
      {
        "name": "Awesome card",
        "index": 1,
        "driver": "Awesome driver",
        "profiles": [
          {
            "name": "Awesome profile",
            "description": "My awesome profile",
            "active": false
          }
        ]
      }
    ],
    "input": [
      {
        "name": "Awesome device",
        "index": 0,
        "description": "My awesome device",
        "volume": 0.3,
        "mute": false,
        "default": false,
        "card": null,
        "applications": [
          {
            "name": "Awesome application",
            "index": 0,
            "stream_index": 0,
            "stream_type": "INPUT",
            "volume": 0.3,
            "mute": false,
            "addon": "awesome_addon"
          }
        ]
      }
    ],
    "output": [
      {
        "name": "Awesome device",
        "index": 0,
        "description": "My awesome device",
        "volume": 0.3,
        "mute": false,
        "default": false,
        "card": 1,
        "applications": [
          {
            "name": "Awesome application",
            "index": 0,
            "stream_index": 0,
            "stream_type": "INPUT",
            "volume": 0.3,
            "mute": false,
            "addon": "awesome_addon"
          }
        ]
      }
    ],
    "application": [
      {
        "name": "Awesome application",
        "index": 0,
        "stream_index": 0,
        "stream_type": "OUTPUT",
        "volume": 0.3,
        "mute": false,
        "addon": "awesome_addon"
      }
    ]
  }
}

Returns the raw container logs from docker. Mute input devices

Payload:

key	type	optional	description
index	string	False	The index of the device
active	boolean	False	`true` if muted

Mute input for a specific application

Payload:

key	type	optional	description
index	string	False	The index of the device
active	boolean	False	`true` if muted

Mute output devices

Payload:

key	type	optional	description
index	string	False	The index of the device
active	boolean	False	`true` if muted

Mute output for a specific application

Payload:

key	type	optional	description
index	string	False	The index of the device
active	boolean	False	`true` if muted

Create an audio profile

Payload:

key	type	optional	description
card	string	False	The name of the audio device
name	string	False	The name of the profile

Reload audio information Restart the audio plugin

Returns a Stats model for the audio plugin.

Example response:

{
  "cpu_percent": 14.0,
  "memory_usage": 288888,
  "memory_limit": 322222,
  "memory_percent": 32.4,
  "network_tx": 110,
  "network_rx": 902,
  "blk_read": 12,
  "blk_write": 27
}

Update the audio plugin

Payload:

key	type	description
version	string	The version you want to install, default is the latest version

Set the input volume

Payload:

key	type	optional	description
index	string	False	The index of the device
volume	float	False	The volume (between `0.0`and `1.0`)

Set the input volume for a specific application

Payload:

key	type	optional	description
index	string	False	The index of the device
volume	float	False	The volume (between `0.0`and `1.0`)

Set the output volume

Payload:

key	type	optional	description
index	string	False	The index of the device
volume	float	False	The volume (between `0.0`and `1.0`)

Set the output volume for a specific application

Payload:

key	type	optional	description
index	string	False	The index of the device
volume	float	False	The volume (between `0.0`and `1.0`)

Auth

You can do authentication against Home Assistant Core using Basic Authentication. Use the `X-Supervisor-Token` header to provide the Supervisor authentication token. See the corresponding POST method to provide JSON or urlencoded credentials. You can do authentication against Home Assistant Core. You can POST the data as JSON, as urlencoded (with `application/x-www-form-urlencoded` header) or by using use basic authentication. For using Basic authentication, you can use the `X-Supervisor-Token` for Supervisor authentication token.

Payload:

key	type	description
username	string	The username for the user
password	string	The password for the user

Set a new password for a Home Assistant Core user.

Payload:

key	type	description
username	string	The username for the user
password	string	The new password for the user

Reset internal authentication cache, this is useful if you have changed the password for a user and need to clear the internal cache.

Backup

Return a list of Backups

Example response:

{
  "backups": [
    {
      "slug": "skuwe823",
      "date": "2020-09-30T20:25:34.273Z",
      "name": "Awesome backup",
      "type": "partial",
      "size": 44,
      "protected": true,
      "location": "MountedBackups",
      "compressed": true,
      "content": {
        "homeassistant": true,
        "addons": ["awesome_addon"],
        "folders": ["ssl", "media"]
      }
    }
  ]
}

Return information about backup manager.

Returned data:

key	type	description
backups	list	A list of Backups
days_until_stale	int	Number of days until a backup is considered stale

Example response:

{
  "backups": [
    {
      "slug": "skuwe823",
      "date": "2020-09-30T20:25:34.273Z",
      "name": "Awesome backup",
      "type": "partial",
      "size": 44,
      "protected": true,
      "compressed": true,
      "location": null,
      "content": {
        "homeassistant": true,
        "addons": ["awesome_addon"],
        "folders": ["ssl", "media"]
      }
    }
  ],
  "days_until_stale": 30
}

Create a full backup.

Payload:

key	type	optional	description
name	string	True	The name you want to give the backup
password	string	True	The password you want to give the backup
compressed	boolean	True	`false` to create uncompressed backups
location	string or null	True	Name of a backup mount or `null` for /backup

Example response:

{
  "slug": "skuwe823"
}

Upload a backup.

Example response:

{
  "slug": "skuwe823"
}

Create a partial backup.

Payload:

key	type	optional	description
name	string	True	The name you want to give the backup
password	string	True	The password you want to give the backup
homeassistant	boolean	True	Add home assistant core settings to the backup
addons	list	True	A list of strings representing add-on slugs
folders	list	True	A list of strings representing directories
compressed	boolean	True	`false` to create uncompressed backups
location	string or null	True	Name of a backup mount or `null` for /backup

You need to supply at least one key in the payload.

Example response:

{
  "slug": "skuwe823"
}

Update options for backup manager, you need to supply at least one of the payload keys to the API call.

Payload:

key	type	description
days_until_stale	int	Set number of days until a backup is considered stale

You need to supply at least one key in the payload.

Reload backup from storage.

Download the backup file with the given slug.

Returns a Backup details model for the add-on.

Removes the backup file with the given slug.

Does a full restore of the backup with the given slug.

Payload:

key	type	optional	description
password	string	True	The password for the backup if any

Does a partial restore of the backup with the given slug.

Payload:

key	type	optional	description
homeassistant	boolean	True	`true` if Home Assistant should be restored
addons	list	True	A list of add-on slugs that should be restored
folders	list	True	A list of directories that should be restored
password	string	True	The password for the backup if any

You need to supply at least one key in the payload.

CLI

Returns information about the CLI plugin

Returned data:

key	type	description
version	string	The installed cli version
version_latest	string	The latest published version
update_available	boolean	`true` if an update is available

Example response:

{
  "version": "1",
  "version_latest": "2",
  "update_available": true
}

Returns a Stats model for the CLI plugin.

Example response:

{
  "cpu_percent": 14.0,
  "memory_usage": 288888,
  "memory_limit": 322222,
  "memory_percent": 32.4,
  "network_tx": 110,
  "network_rx": 902,
  "blk_read": 12,
  "blk_write": 27
}

Update the CLI plugin

Payload:

key	type	description
version	string	The version you want to install, default is the latest version

Core

Proxy GET API calls to the Home Assistant API Proxy POST API calls to the Home Assistant API Run a configuration check Returns information about the Home Assistant core

Returned data:

key	type	description
version	string	The installed core version
version_latest	string	The latest published version in the active channel
update_available	boolean	`true` if an update is available
arch	string	The architecture of the host (armhf, aarch64, i386, amd64)
machine	string	The machine type that is running the host
ip_address	string	The internal docker IP address to the supervisor
image	string	The container image that is running the core
boot	boolean	`true` if it should start on boot
port	int	The port Home Assistant is running on
ssl	boolean	`true` if Home Assistant is using SSL
watchdog	boolean	`true` if watchdog is enabled
wait_boot	int	Max time to wait during boot
audio_input	string or null	The description of the audio input device
audio_output	string or null	The description of the audio output device

Example response:

{
  "version": "0.117.0",
  "version_latest": "0.117.0",
  "update_available": true,
  "arch": "arch",
  "machine": "amd64",
  "ip_address": "172.0.0.15",
  "image": "homeassistant/home-assistant",
  "boot": true,
  "port": 8123,
  "ssl": false,
  "watchdog": true,
  "wait_boot": 800,
  "audio_input": "AMCP32",
  "audio_output": "AMCP32"
}

Returns the raw container logs from docker. Update options for Home Assistant, you need to supply at least one of the payload keys to the API call. You need to call `/core/restart` after updating the options.

:::tip Passing image, refresh_token, audio_input or audio_output with null resets the option. :::

Payload:

key	type	description
boot	boolean	Start Core on boot
image	string or null	Name of custom image
port	int	The port that Home Assistant run on
ssl	boolean	`true` to enable SSL
watchdog	boolean	`true` to enable the watchdog
wait_boot	int	Time to wait for Core to startup
refresh_token	string or null	Token to authenticate with Core
audio_input	string or null	Profile name for audio input
audio_output	string or null	Profile name for audio output

You need to supply at least one key in the payload.

Rebuild the Home Assistant core container Restart the Home Assistant core container Start the Home Assistant core container

Returns a Stats model for the Home Assistant core.

Example response:

{
  "cpu_percent": 14.0,
  "memory_usage": 288888,
  "memory_limit": 322222,
  "memory_percent": 32.4,
  "network_tx": 110,
  "network_rx": 902,
  "blk_read": 12,
  "blk_write": 27
}

Stop the Home Assistant core container Update Home Assistant core

Payload:

key	type	description
version	string	The version you want to install, default is the latest version
backup	boolean	Create a partial backup of core and core configuration before updating, default is false

Proxy to Home Assistant Core websocket.

Discovery

Return information about enabled discoveries.

Returned data:

key	type	description
discovery	list	A list of Discovery models
services	dictionary	A dictionary of services that contains a list of add-ons that have that service.

Example response:

{
  "discovery": [
    {
      "addon": "awesome_addon",
      "service": "awesome.service",
      "uuid": "fh874r-fj9o37yr3-fehsf7o3-fd798",
      "config": {}
    }
  ],
  "services": {
    "awesome": ["awesome_addon"]
  }
}

Create a discovery service

Payload:

key	type	optional	description
service	string	False	The name of the service
config	dictionary	False	The configuration of the service

Example response:

{
  "uuid": "uuid"
}

Get a discovery model for a UUID.

Delete a specific service.

DNS

Return information about the DNS plugin.

Returned data:

key	type	description
fallback	bool	Try fallback DNS on failure
host	string	The IP address of the plugin
llmnr	bool	Can resolve LLMNR hostnames
locals	list	A list of DNS servers
mdns	bool	Can resolve MulticastDNS hostnames
servers	list	A list of DNS servers
update_available	boolean	`true` if an update is available
version	string	The installed observer version
version_latest	string	The latest published version

Example response:

{
  "host": "127.0.0.18",
  "version": "1",
  "version_latest": "2",
  "update_available": true,
  "servers": ["dns://8.8.8.8"],
  "locals": ["dns://127.0.0.18"],
  "mdns": true,
  "llmnr": false,
  "fallback": true
}

Returns the raw container logs from docker. Set DNS options

Payload:

key	type	optional	description
fallback	bool	True	Enable/Disable fallback DNS
servers	list	True	A list of DNS servers

You need to supply at least one key in the payload.

Reset the DNS configuration. Restart the DNS plugin

Returns a Stats model for the dns plugin.

Example response:

{
  "cpu_percent": 14.0,
  "memory_usage": 288888,
  "memory_limit": 322222,
  "memory_percent": 32.4,
  "network_tx": 110,
  "network_rx": 902,
  "blk_read": 12,
  "blk_write": 27
}

Update the DNS plugin

Payload:

key	type	description
version	string	The version you want to install, default is the latest version

Docker

Returns information about the docker instance.

Returned data:

key	type	description
version	string	The version of the docker engine
storage	string	The storage type
logging	string	The logging type
registries	dictionary	A dictionary of dictionaries containing `username` and `password` keys for registries.

Example response:

{
  "version": "1.0.1",
  "storage": "overlay2",
  "logging": "journald",
  "registries": {}
}

Get all configured container registries, this returns a dict with the registry hostname as the key, and a dictionary containing the username configured for that registry.

Example response:

{
  "registry.example.com": {
    "username": "AwesomeUser"
  }
}

Add a new container registry.

Payload:

key	type	description
hostname	dictionary	A dictionary containing `username` and `password` keys for the registry.

Example payload:

{
  "registry.example.com": {
    "username": "AwesomeUser",
    "password": "MySuperStrongPassword!"
  }
}

:::note

To login to the default container registry (Docker Hub), use hub.docker.com as the registry.

:::

Delete a registry from the configured container registries.

Hardware

Get hardware information.

Example response:

{
    "devices": [
      {
        "name": "ttyACM0",
        "sysfs": "/sys/devices/usb/00:01",
        "dev_path": "/dev/ttyACM0",
        "by_id": "/dev/serial/by-id/usb-Silicon_Labs-RFUSB_9017F723B061A7C01410CFCF-if00-port1",
        "subsystem": "tty",
        "parent": null,
        "attributes": {
          "MINOR": "5"
        },
        "children": [
          "/sys/devices/soc/platform/00ef"
        ]
      }
    ]
}

Returned data:

key	description
devices	A list of Device models

Get audio devices

Example response:

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

Host

Return information about the host.

Returned data

key	type	description
agent_version	string or null	Agent version running on the Host
apparmor_version	string or null	The AppArmor version from host
boot_timestamp	int	The timestamp for the last boot in microseconds
broadcast_llmnr	bool or null	Host is broadcasting its LLMNR hostname
broadcast_mdns	bool or null	Host is broadcasting its MulticastDNS hostname
chassis	string or null	The chassis type
cpe	string or null	The local CPE
deployment	string or null	The deployment stage of the OS if any
disk_total	float	Total space of the disk in MB
disk_used	float	Used space of the disk in MB
disk_free	float	Free space of the disk in MB
features	list	A list of features available for the host
hostname	string or null	The hostname of the host
kernel	string or null	The kernel version on the host
llmnr_hostname	string or null	The hostname currently exposed on the network via LLMNR for host
operating_system	string	The operating system on the host
startup_time	float	The time in seconds it took for last boot

Example response:

{
  "agent_version": "1.2.0",
  "apparmor_version": "2.13.2",
  "chassis": "specific",
  "cpe": "xy",
  "deployment": "stable",
  "disk_total": 32.0,
  "disk_used": 30.0,
  "disk_free": 2.0,
  "features": ["shutdown", "reboot", "hostname", "services", "haos"],
  "hostname": "Awesome host",
  "llmnr_hostname": "Awesome host",
  "kernel": "4.15.7",
  "operating_system": "Home Assistant OS",
  "boot_timestamp": 1234567788,
  "startup_time": 12.345,
  "broadcast_llmnr": true,
  "broadcast_mdns": false
}

Get systemd Journal logs from the host. Returns log entries in plain text, one log record per line.

HTTP Request Headers

Header	optional	description
Accept	true	Type of data (currently only text/plain)
Range	true	Range of log entries. The format is `entries=cursor[[:num_skip]:num_entries]`

:::tip To get the last log entries the Range request header supports negative values as num_skip. E.g. Range: entries=:-9: returns the last 10 entries. Or Range: entries=:-200:100 to see 100 entries starting from the one 200 ago. :::

API returns the last 100 lines by default. Provide a value for Range to see logs further in the past.

Identical to /host/logs except it continuously returns new log entries.

Returns a list of syslog identifiers from the systemd journal that you can use with /host/logs/identifiers/<identifier> and /host/logs/boots/<bootid>/identifiers/<identifier>.

Get systemd Journal logs from the host for entries related to a specific log identifier. Some examples of useful identifiers here include

audit - If developing an apparmor profile shows you permission issues
NetworkManager - Shows NetworkManager logs when having network issues
bluetoothd - Shows bluetoothd logs when having bluetooth issues

A call to GET /host/logs/identifiers will show the complete list of possible values for identifier.

Otherwise it provides the same functionality as /host/logs.

Identical to /host/logs/identifiers/<identifier> except it continuously returns new log entries.

Returns a dictionary of boot IDs for this system that you can use with /host/logs/boots/<bootid> and /host/logs/boots/<bootid>/identifiers/<identifier>.

The key for each item in the dictionary is the boot offset. 0 is the current boot, a negative number denotes how many boots ago that boot was.

Get systemd Journal logs from the host for entries related to a specific boot. Call GET /host/info/boots to see the boot IDs. Alternatively you can provide a boot offset:

0 - The current boot
Negative number - Count backwards from current boot (-1 is previous boot)
Positive number - Count forward from last known boot (1 is last known boot)

Otherwise it provides the same functionality as /host/logs.

Identical to /host/logs/boots/<bootid> except it continuously returns new log entries.

Get systemd Journal logs entries for a specific log identifier and boot. A combination of /host/logs/boots/<bootid> and /host/logs/identifiers/<identifier>.

Identical to /host/logs/boots/<bootid>/identifiers/<identifier> except it continuously returns new log entries.

Set host options

Payload:

key	type	optional	description
hostname	string	True	A string that will be used as the new hostname

You need to supply at least one key in the payload.

Reboot the host Reload host information Start a service on the host. Stop a service on the host. Reload a service on the host. Get information about host services.

Returned data:

key	description
services	A dictionary of Host service models

Example response:

{
  "services": [
    {
      "name": "awesome.service",
      "description": "Just an awesome service",
      "state": "active"
    }
  ]
}

Shutdown the host

ingress

Returned data:

key	type	description
panels	dictionary	dictionary of Panel models

Example response:

{
  "panels": {
    "addon_slug": {
      "enable": true,
      "icon": "mdi:awesome-icon",
      "title": "Awesome add-on",
      "admin": true
    }
  }
}

Create a new session for access to the ingress service.

Returned data:

key	type	optional	description
session	string	False	The token for the ingress session

Validate an ingress session, extending it's validity period.

Payload:

key	type	optional	description
session	string	False	The token for the ingress session

Root

Returns information about available updates

Example response:

{
  "available_updates": [
  {
      "panel_path": "/update-available/core",
      "update_type": "core",
      "version_latest": "321",
    },
    {
      "panel_path": "/update-available/os",
      "update_type": "os",
      "version_latest": "321",
    },
    {
      "panel_path": "/update-available/supervisor",
      "update_type": "supervisor",
      "version_latest": "321",
    },
    {
      "name": "Awesome addon",
      "icon": "/addons/awesome_addon/icon",
      "panel_path": "/update-available/awesome_addon",
      "update_type": "addon",
      "version_latest": "321",
    }
  ]
}

Returned data:

key	type	description
update_type	string	`addon`, `os`, `core` or `supervisor`
name	string	Returns the name (only if the `update_type` is `addon`)
icon	string	Returns the path for the icon if any (only if the `update_type` is `addon`)
version_latest	string	Returns the available version
panel_path	string	Returns path where the UI can be loaded

This reloads information about add-on repositories and fetches new version files. Returns a dict with selected keys from other `/*/info` endpoints.

Returned data:

key	type	description
supervisor	string	The installed version of the supervisor
homeassistant	string	The installed version of Home Assistant
hassos	string or null	The version of Home Assistant OS or null
docker	string	The docker version on the host
hostname	string	The hostname on the host
operating_system	string	The operating system on the host
features	list	A list ov available features on the host
machine	string	The machine type
arch	string	The architecture on the host
supported_arch	list	A list of supported host architectures
supported	boolean	`true` if the environment is supported
channel	string	The active channel (stable, beta, dev)
logging	string	The active log level (debug, info, warning, error, critical)
state	string	The core state of the Supervisor.
timezone	string	The current timezone

Example response:

{
  "supervisor": "300",
  "homeassistant": "0.117.0",
  "hassos": "5.0",
  "docker": "24.17.2",
  "hostname": "Awesome Hostname",
  "operating_system": "Home Assistant OS",
  "features": ["shutdown", "reboot", "hostname", "services", "hassos"],
  "machine": "ova",
  "arch": "amd64",
  "supported_arch": ["amd64"],
  "supported": true,
  "channel": "stable",
  "logging": "info",
  "state": "running",
  "timezone": "Europe/Tomorrowland"
}

Mounts

Returns information about mounts configured in Supervisor

Returned data:

key	type	description
mounts	list	A list of Mounts
default_backup_mount	string or null	Name of a backup mount or `null` for /backup

Example response:

{
  "default_backup_mount": "my_share",
  "mounts": [
    {
      "name": "my_share",
      "usage": "media",
      "type": "cifs",
      "server": "server.local",
      "share": "media",
      "state": "active"
    }
  ]
}

Set mount manager options

Payload:

key	type	optional	description
default_backup_mount	string or null	True	Name of a backup mount or `null` for /backup

You need to supply at least one key in the payload.

Add a new mount in Supervisor and mount it

Payload:

Accepts a Mount

Value in name must be unique and can only consist of letters, numbers and underscores.

Example payload:

{
  "name": "my_share",
  "usage": "media",
  "type": "cifs",
  "server": "server.local",
  "share": "media",
  "username": "admin",
  "password": "password"
}

Update an existing mount in Supervisor and remount it

Payload:

Accepts a Mount.

The name field should be omitted. If included the value must match the existing name, it cannot be changed. Delete and re-add the mount to change the name.

Example payload:

{
  "usage": "media",
  "type": "nfs",
  "server": "server.local",
  "path": "/media/camera"
}

Unmount and delete an existing mount from Supervisor. Unmount and remount an existing mount in Supervisor using the same configuration.

Multicast

Returns information about the multicast plugin

Returned data:

key	type	description
version	string	The installed multicast version
version_latest	string	The latest published version
update_available	boolean	`true` if an update is available

Example response:

{
  "version": "1",
  "version_latest": "2",
  "update_available": true
}

Returns the raw container logs from docker. Restart the multicast plugin.

Returns a Stats model for the multicast plugin.

Example response:

{
  "cpu_percent": 14.0,
  "memory_usage": 288888,
  "memory_limit": 322222,
  "memory_percent": 32.4,
  "network_tx": 110,
  "network_rx": 902,
  "blk_read": 12,
  "blk_write": 27
}

Update the multicast plugin

Payload:

key	type	description
version	string	The version you want to install, default is the latest version

Network

Get network information.

Returned data:

key	description
interfaces	A list of Network interface models
docker	Information about the internal docker network
host_internet	Boolean to indicate if the host can reach the internet.
supervisor_internet	Boolean to indicate if the Supervisor can reach the internet.

Example response:

{
  "interfaces": [
    {
      "interface": "eth0",
      "type": "ethernet",
      "primary": true,
      "enabled": true,
      "connected": true,
      "ipv4": {
        "method": "static",
        "ip_address": "192.168.1.100/24",
        "gateway": "192.168.1.1",
        "nameservers": ["192.168.1.1"],
      },
      "ipv6": null,
      "wifi": null,
      "vlan": null,
    }
  ],
  "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
}

Returns a Network interface model for a specific network interface.

Update all Network interface data.

Update the settings for a network interface.

Payload:

key	type	optional	description
enabled	bool	True	Enable/Disable an ethernet interface / VLAN got removed with disabled
ipv4	dict	True	A struct with ipv4 interface settings
ipv6	dict	True	A struct with ipv6 interface settings
wifi	dict	True	A struct with Wireless connection settings

ipv4 / ipv6:

key	type	optional	description
method	string	True	Set IP configuration method can be `auto` for DHCP or Router Advertisements (only IPv6), `static` or `disabled`
address	list	True	The new IP address for the interface in the X.X.X.X/XX format as list
nameservers	list	True	List of DNS servers to use
gateway	string	True	The gateway the interface should use

wifi:

key	type	optional	description
mode	string	True	Set the mode `infrastructure` (default), `mesh`, `adhoc` or `ap`
auth	string	True	Set the auth mode: `open` (default), `web`, `wpa-psk`
ssid	string	True	Set the SSID for connect into
psk	string	True	The shared key which is used with `web` or `wpa-psk`

Return a list of available Access Points on this Wireless interface.

This function only works with Wireless interfaces!

Returned data:

key	description
accesspoints	A list of Access Points

Example response:

{
  "accesspoints": [
    {
      "mode": "infrastructure",
      "ssid": "MY_TestWifi",
      "mac": "00:00:00:00",
      "frequency": 24675,
      "signal": 90
    }
  ]
}

Create a new VLAN id on this network interface.

This function only works with ethernet interfaces!

Payload:

key	type	optional	description
ipv4	dict	True	A struct with ipv4 interface settings
ipv6	dict	True	A struct with ipv6 interface settings

Observer

Returns information about the observer plugin

Returned data:

key	type	description
host	string	The IP address of the plugin
version	string	The installed observer version
version_latest	string	The latest published version
update_available	boolean	`true` if an update is available

Example response:

{
  "host": "172.0.0.17",
  "version": "1",
  "version_latest": "2",
  "update_available": true
}

Returns a Stats model for the observer plugin.

Example response:

{
  "cpu_percent": 14.0,
  "memory_usage": 288888,
  "memory_limit": 322222,
  "memory_percent": 32.4,
  "network_tx": 110,
  "network_rx": 902,
  "blk_read": 12,
  "blk_write": 27
}

Update the observer plugin

Payload:

key	type	description
version	string	The version you want to install, default is the latest version

OS

Load host configurations from a USB stick.

Returns information about the OS.

Returned data:

key	type	description
version	string	The current version of the OS
version_latest	string	The latest published version of the OS in the active channel
update_available	boolean	`true` if an update is available
board	string	The name of the board
boot	string	Which slot that are in use
data_disk	string	Device which is used for holding OS data persistent

Example response:

{
  "version": "4.3",
  "version_latest": "5.0",
  "update_available": true,
  "board": "ova",
  "boot": "slot1",
  "data_disk": "BJTD4R-0x123456789"
}

Update Home Assistant OS

Payload:

key	type	description
version	string	The version you want to install, default is the latest version

Returns possible targets for the new data partition.

Returned data:

key	type	description
devices	list	List of IDs of possible data disk targets
disks	list	List of disks which are possible data disk targets

Example response:

{
  "devices": [
    "Generic-Flash-Disk-123ABC456",
    "SSK-SSK-Storage-ABC123DEF"
  ],
  "disks": [
    {
      "name": "Generic Flash Disk (123ABC456)",
      "vendor": "Generic",
      "model": "Flash Disk",
      "serial": "123ABC456",
      "size": 8054112256,
      "id": "Generic-Flash-Disk-123ABC456",
      "dev_path": "/dev/sda"
    },
    {
      "name": "SSK SSK Storage (ABC123DEF)",
      "vendor": "SSK",
      "model": "SSK Storage",
      "serial": "ABC123DEF",
      "size": 250059350016,
      "id": "SSK-SSK-Storage-ABC123DEF",
      "dev_path": "/dev/sdb"
    }
  ]
}

Move datadisk to a new location, This will also reboot the device!

Payload:

key	type	description
device	string	ID of the disk device which should be used as the target for the data migration

Returns information about your board if it has features or settings that can be modified from Home Assistant. The value for board is the value in the board field returned by /os/info.

Boards with such options are documented below.

If running on a yellow board, returns current values for its settings.

Returned data:

key	type	description
disk_led	boolean	Is the disk LED enabled
heartbeat_led	boolean	Is the heartbeat LED enabled
power_led	boolean	Is the power LED enabled

Example response:

{
  "disk_led": true,
  "heartbeat_led": true,
  "power_led": false
}

If running on a yellow board, changes one or more of its settings.

Payload:

key	type	description
disk_led	boolean	Enable/disable disk LED enabled
heartbeat_led	boolean	Enable/disable the heartbeat LED enabled
power_led	boolean	Enable/disable the power LED enabled

Resolution

Returned data:

key	type	description
unsupported	list	A list of reasons why an installation is marked as unsupported (container, dbus, docker_configuration, docker_version, lxc, network_manager, os, privileged, systemd)
unhealthy	list	A list of reasons why an installation is marked as unhealthy (docker, supervisor, privileged, setup)
issues	list	A list of Issue models
suggestions	list	A list of Suggestion models actions
checks	list	A list of Check models

Example response:

{
  "unsupported": ["os"],
  "unhealthy": ["docker"],
  "issues": [
    {
      "uuid": "A89924620F9A11EBBDC3C403FC2CA371",
      "type": "free_space",
      "context": "system",
      "reference": null
     }
  ],
  "suggestions": [
    {
      "uuid": "B9923620C9A11EBBDC3C403FC2CA371",
      "type": "clear_backups",
      "context": "system",
      "reference": null,
      "auto": false
    }
  ],
  "checks": [
    {
      "slug": "free_space",
      "enabled": true
    }
  ]
}

Apply a suggested action

Dismiss a suggested action

Get suggestions that would fix an issue if applied.

Returned data:

key	type	description
suggestions	list	A list of Suggestion models actions

Example response:

{
  "suggestions": [
    {
      "uuid": "B9923620C9A11EBBDC3C403FC2CA371",
      "type": "clear_backups",
      "context": "system",
      "reference": null,
      "auto": false
    }
  ]
}

Dismiss an issue

Execute a healthcheck and autofix & notifcation.

Set options for this check.

Payload:

key	type	description
enabled	bool	If the check should be enabled or disabled

Execute a specific check right now.

Service

Returned data:

key	type	description
services	dictionary	dictionary of Service models

Example response:

{
  "services": [
    {
      "slug": "name",
      "available": true,
      "providers": ["awesome_addon"]
    }
  ]
}

Returned data:

key	type	description
addon	string	The add-on slug
host	string	The IP of the addon running the service
port	string	The port the service is running on
ssl	boolean	`true` if SSL is in use
username	string	The username for the service
password	string	The password for the service
protocol	string	The MQTT protocol

Example response:

{
  "addon": "awesome_mqtt",
  "host": "172.0.0.17",
  "port": "8883",
  "ssl": true,
  "username": "awesome_user",
  "password": "strong_password",
  "protocol": "3.1.1"
}

Create a service definition

Payload:

key	type	description
host	string	The IP of the addon running the service
port	string	The port the service is running on
ssl	boolean	`true` if SSL is in use
username	string	The username for the service
password	string	The password for the service
protocol	string	The MQTT protocol

Deletes the service definitions

Returned data:

key	type	description
addon	string	The add-on slug
host	string	The IP of the addon running the service
port	string	The port the service is running on
ssl	boolean	`true` if SSL is in use
username	string	The username for the service
password	string	The password for the service
protocol	string	The MQTT protocol

Example response:

{
  "addon": "awesome_mysql",
  "host": "172.0.0.17",
  "port": "8883",
  "username": "awesome_user",
  "password": "strong_password"
}

Create a service definition

Payload:

key	type	description
host	string	The IP of the addon running the service
port	string	The port the service is running on
username	string	The username for the service
password	string	The password for the service

Deletes the service definitions

Store

Returns add-on store information.

Example response:

{ "addons":
  [
    {
      "name": "Awesome add-on",
      "slug": "7kshd7_awesome",
      "description": "Awesome description",
      "repository": "https://example.com/addons",
      "version": "1.0.0",
      "installed": "1.0.0",
      "icon": false,
      "logo": true,
      "state": "started"
    }
  ],
  "repositories": [
    {
      "slug": "awesom_repository",
      "name": "Awesome Repository",
      "source": "https://example.com/addons",
      "url": "https://example.com/addons",
      "maintainer": "Awesome Maintainer"
    }
  ]
}

Returns a list of store add-ons

Example response:

[
  {
    "name": "Awesome add-on",
    "slug": "7kshd7_awesome",
    "description": "Awesome description",
    "repository": "https://example.com/addons",
    "version": "1.0.0",
    "installed": "1.0.0",
    "icon": false,
    "logo": true,
    "state": "started"
  }
]

Returns information about a store add-on

Example response:

{
  "advanced": false,
  "apparmor": "default",
  "arch": ["armhf", "aarch64", "i386", "amd64"],
  "auth_api": true,
  "available": true,
  "build": false,
  "description": "Awesome description",
  "detached": false,
  "docker_api": false,
  "documentation": true,
  "full_access": true,
  "hassio_api": false,
  "hassio_role": "manager",
  "homeassistant_api": true,
  "homeassistant": "2021.2.0b0",
  "host_network": false,
  "host_pid": false,
  "icon": false,
  "ingress": true,
  "installed": false,
  "logo": true,
  "long_description": "lorem ipsum",
  "name": "Awesome add-on",
  "rating": 5,
  "repository": "core",
  "signed": false,
  "slug": "7kshd7_awesome",
  "stage": "stable",
  "update_available": false,
  "url": "https://example.com/addons/tree/main/awesome_addon",
  "version_latest": "1.0.0",
  "version": "1.0.0"
}

Install an add-on from the store.

Update an add-on from the store.

Payload:

key	type	description
backup	boolean	Create a partial backup of the add-on, default is false

Get the changelog for an add-on. Get the documentation for an add-on. Get the add-on icon Get the add-on logo

Reloads the information stored about add-ons.

Returns a list of store repositories

Example response:

[
  {
    "slug": "awesom_repository",
    "name": "Awesome Repository",
    "source": "https://example.com/addons",
    "url": "https://example.com/addons",
    "maintainer": "Awesome Maintainer"
  }
]

Add an addon repository to the store

Payload:

key	type	description
repository	string	URL of the addon repository to add to the store.

Example payload:

{
  "repository": "https://example.com/addons"
}

Returns information about a store repository

Example response:

{
  "slug": "awesom_repository",
  "name": "Awesome Repository",
  "source": "https://example.com/addons",
  "url": "https://example.com/addons",
  "maintainer": "Awesome Maintainer"
}

Remove an unused addon repository from the store.

Security

Returns information about the security features

Returned data:

key	type	description
content_trust	bool	If content-trust is enabled or disabled on the backend
pwned	bool	If pwned check is enabled or disabled on the backend
force_security	bool	If force-security is enabled or disabled on the backend

Example response:

{
  "content_trust": true,
  "pwned": true,
  "force_security": false,
}

Payload:

key	type	description
content_trust	bool	Disable/Enable content-trust
pwned	bool	Disable/Enable pwned
force_security	bool	Disable/Enable force-security

Run a full platform integrity check.

Returned data:

key	type	description
supervisor	str	`pass`, `error`, `failed`, `untested`
core	str	`pass`, `error`, `failed`, `untested`
plugins	dict	A dictionary with key per plugin as `pass`, `error`, `failed`, `untested`
addons	dict	A dictionary with key per addon as `pass`, `error`, `failed`, `untested`

Example response:

{
  "supervisor": "pass",
  "core": "pass",
  "plugins": {
    "audio": "pass",
    "cli": "pass"
  },
  "addons": {
    "core_ssh": "untested",
    "xj3493_test": "pass"
  }
}

Supervisor

Returns information about the supervisor

Returned data:

key	type	description
version	string	The installed supervisor version
version_latest	string	The latest published version in the active channel
update_available	boolean	`true` if an update is available
arch	string	The architecture of the host (armhf, aarch64, i386, amd64)
channel	string	The active channel (stable, beta, dev)
timezone	string	The current timezone
healthy	bool	The supervisor is in a healthy state
supported	bool	The environment is supported
logging	string	The current log level (debug, info, warning, error, critical)
ip_address	string	The internal docker IP address to the supervisor
wait_boot	int	Max time to wait during boot
debug	bool	Debug is active
debug_block	bool	`true` if debug block is enabled
diagnostics	bool or null	Sending diagnostics is enabled
addons_repositories	list	A list of add-on repository URL's as strings
auto_update	bool	Is auto update enabled for supervisor

Example response:

{
  "version": "246",
  "version_latest": "version_latest",
  "update_available": true,
  "arch": "amd64",
  "channel": "dev",
  "timezone": "TIMEZONE",
  "healthy": true,
  "supported": false,
  "logging": "debug",
  "ip_address": "172.0.0.2",
  "wait_boot": 800,
  "debug": false,
  "debug_block": false,
  "diagnostics": null,
  "addons_repositories": ["https://example.com/addons"],
  "auto_update": true
}

Returns the raw container logs from docker.

Update options for the supervisor, you need to supply at least one of the payload keys to the API call. You need to call /supervisor/reload after updating the options.

Payload:

key	type	description
channel	string	Set the active channel (stable, beta, dev)
timezone	string	Set the timezone
wait_boot	int	Set the time to wait for boot
debug	bool	Enable debug
debug_block	bool	Enable debug block
logging	string	Set logging level
addons_repositories	list	Set a list of URL's as strings for add-on repositories
auto_update	bool	Enable/disable auto update for supervisor

Ping the supervisor to check if it can return a response.

Reload parts of the supervisor, this enable new options, and check for updates.

Restart the supervisor, can help to get the supervisor healthy again.

Repair docker overlay issues, and lost images.

Returns a Stats model for the supervisor.

Example response:

{
  "cpu_percent": 14.0,
  "memory_usage": 288888,
  "memory_limit": 322222,
  "memory_percent": 32.4,
  "network_tx": 110,
  "network_rx": 902,
  "blk_read": 12,
  "blk_write": 27
}

Update the supervisor

Payload:

key	type	description
version	string	The version you want to install, default is the latest version

Placeholders

Some of the endpoints uses placeholders indicated with <...> in the endpoint URL.

placeholder	description
addon	The slug for the addon, to get the slug you can call `/addons`, to call endpoints for the add-on calling the endpoints you can use `self`as the slug.
application	The name of an application, call `/audio/info` to get the correct name
interface	A valid interface name, example `eth0`, to get the interface name you can call `/network/info`. You can use `default` to get the primary interface
registry	A registry hostname defined in the container registry configuration, to get the hostname you can call `/docker/registries`
service	The service name for a service on the host.
backup	A valid backup slug, example `skuwe823`, to get the slug you can call `/backups`
suggestion	A valid suggestion, example `clear_full_backup`, to get the suggestion you can call `/resolution`
uuid	The UUID of a discovery service, to get the UUID you can call `/discovery`

90 KiB Raw Permalink Blame History

Addons

Audio

Auth

Backup

CLI

Core

Discovery

DNS

Docker

Hardware

Host

ingress

Root

Mounts

Multicast

Network

Observer

OS

Resolution

Service

Store

Security

Supervisor

Placeholders

90 KiB

Raw Permalink Blame History