Skip to main content

Endpoints

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.

Add-ons​

get
/addons
🔒

Return overview information about installed add-ons.

Payload:

keytypedescription
addonslistA 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,
"system_managed": false
}
]
}
post
/addons/reload
🔒

Reloads the information stored about add-ons.

get
/addons/<addon>/changelog
🔒

Get the changelog for an add-on.

get
/addons/<addon>/documentation
🔒

Get the documentation for an add-on.

get
/addons/<addon>/logs
🔒

Get logs for an add-on via the Systemd journal backend.

The endpoint accepts the same headers and provides the same functionality as /host/logs.

get
/addons/<addon>/logs/follow
🔒

Identical to /addons/<addon>/logs except it continuously returns new log entries.

get
/addons/<addon>/logs/boots/<bootid>
🔒

Get logs for an add-on related to a specific boot.

The bootid parameter is interpreted in the same way as in /host/logs/boots/<bootid> and the endpoint otherwise provides the same functionality as /host/logs.

get
/addons/<addon>/logs/boots/<bootid>/follow
🔒

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

get
/addons/<addon>/icon
🔒

Get the add-on icon

get
/addons/<addon>/info
🔒

Get details about an add-on

Returned data:

keytypedescription
advancedbooleantrue if advanced mode is enabled
apparmorstringdisabled, default or the name of the profile
archlistA list of supported architectures for the add-on
audiobooleantrue if audio is enabled
audio_inputfloat or nullThe device index
audio_outputfloat or nullThe device index
auth_apibooleantrue if auth api access is granted is enabled
auto_uartbooleantrue if auto_uart access is granted is enabled
auto_updatebooleantrue if auto update is enabled
availablebooleantrue if the add-on is available
bootstring"auto" or "manual"
boot_configstringDefault boot mode of addon or "manual_only" if boot mode cannot be auto
buildbooleantrue if local add-on
changelogbooleantrue if changelog is available
descriptionstringThe add-on description
detachedbooleantrue if the add-on is running detached
deviceslistA list of attached devices
devicetreebooleantrue if devicetree access is granted is enabled
discoverylistA list of discovery services
dnslistA list of DNS servers used by the add-on
docker_apibooleantrue if docker_api access is granted is enabled
documentationbooleantrue if documentation is available
full_accessbooleantrue if full access access is granted is enabled
gpiobooleantrue if gpio access is granted is enabled
hassio_apibooleantrue if hassio api access is granted is enabled
hassio_rolestringThe hassio role (default, homeassistant, manager, admin)
homeassistantstring or nullThe minimum Home Assistant Core version
homeassistant_apibooleantrue if homeassistant api access is granted is enabled
host_dbusbooleantrue if host dbus access is granted is enabled
host_ipcbooleantrue if host ipc access is granted is enabled
host_networkbooleantrue if host network access is granted is enabled
host_pidbooleantrue if host pid access is granted is enabled
host_utsbooleantrue if host UTS namespace access is enabled.
hostnamestringThe host name of the add-on
iconbooleantrue if icon is available
ingressbooleantrue if ingress is enabled
ingress_entrystring or nullThe ingress entrypoint
ingress_panelboolean or nulltrue if ingress_panel is enabled
ingress_portint or nullThe ingress port
ingress_urlstring or nullThe ingress URL
ip_addressstringThe IP address of the add-on
kernel_modulesbooleantrue if kernel module access is granted is enabled
logobooleantrue if logo is available
long_descriptionstringThe long add-on description
machinelistA list of supported machine types for the add-on
namestringThe name of the add-on
networkdictionary or nullThe network configuration for the add-on
network_descriptiondictionary or nullThe description for the network configuration
optionsdictionaryThe add-on configuration
privilegedlistA list of hardwars/system attributes the add-onn has access to
protectedbooleantrue if protection mode is enabled
ratingintThe addon rating
repositorystringThe URL to the add-on repository
schemadictionary or nullThe schema for the add-on configuration
services_rolelistA list of services and the add-ons role for that service
slugstringThe add-on slug
stagestringThe add-on stage (stable, experimental, deprecated)
startupstringThe stage when the add-on is started (initialize, system, services, application, once)
statestring or nullThe state of the add-on (started, stopped)
stdinbooleantrue if the add-on accepts stdin commands
system_managedbooleanIndicates whether the add-on is managed by Home Assistant
system_managed_config_entrystringProvides the configuration entry ID if the add-on is managed by Home Assistant
translationsdictionaryA dictionary containing content of translation files for the add-on
udevbooleantrue if udev access is granted is enabled
update_availablebooleantrue if an update is available
urlstring or nullURL to more information about the add-on
usblistA list of attached USB devices
versionstringThe installed version of the add-on
version_lateststringThe latest version of the add-on
videobooleantrue if video is enabled
watchdogbooleantrue if watchdog is enabled
webuistring or nullThe URL to the web UI for the add-on
signedbooleanTrue 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",
"boot_config": "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,
"system_managed": true,
"system_managed_config_entry": "abc123",
"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
}
post
/addons/<addon>/install
🔒

Install an add-on

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

get
/addons/<addon>/logo
🔒

Get the add-on logo

post
/addons/<addon>/options
🔒

Set the options for an add-on.

tip

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

Payload:

keytypedescription
bootstring(auto, manual)
auto_updatebooleantrue if the add-on should auto update
networkdictionaryA map of network configuration.
optionsdictionaryThe add-on configuration
audio_outputfloat or nullThe index of the audio output device
audio_inputfloat or nullThe index of the audio input device
ingress_panelbooleantrue if ingress_panel is enabled
watchdogbooleantrue 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
}
post
/addons/<addon>/sys_options
🔒

Change options specific to system managed addons.

This endpoint is only callable by Home Assistant and not by any other client.

Payload

keytypedescription
system_managedbooleantrue if managed by Home Assistant
system_managed_config_entrybooleanID of config entry managing addon

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

Example payload:

{
"system_managed": true,
"system_managed_config_entry": "abc123"
}
post
/addons/<addon>/options/validate
🔒

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

Payload:

Optional the raw add-on options.

Returned data:

keytypedescription
messagestringInclude the error message
validbooleanIf config is valid or not
pwnedbooleanNone
get
/addons/<addon>/options/config
🔒

The Data endpoint to get his own rendered configuration.

post
/addons/<addon>/rebuild
🔒

Rebuild the add-on, only supported for local build add-ons.

post
/addons/<addon>/restart
🔒

Restart an add-on

post
/addons/<addon>/security
🔒

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:

keytypedescription
protectedbooleantrue if protection mode is on
post
/addons/<addon>/start
🔒

Start an add-on

get
/addons/<addon>/stats
🔒

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
}
post
/addons/<addon>/stdin
🔒

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.

post
/addons/<addon>/stop
🔒

Stop an add-on

post
/addons/<addon>/uninstall
🔒

Uninstall an add-on

Payload:

keytypeoptionaldescription
remove_configbooleanTrueDelete addon's config folder (if used)
post
/addons/<addon>/update
🔒

Update an add-on

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

Audio​

post
/audio/default/input
🔒

Set a profile as the default input profile

Payload:

keytypeoptionaldescription
namestringFalseThe name of the profile
post
/audio/default/output
🔒

Set a profile as the default output profile

Payload:

keytypeoptionaldescription
namestringFalseThe name of the profile
get
/audio/info
🔒

Return information about the audio plugin.

Returned data:

keytypedescription
hoststringThe IP address of the plugin
versionstringThe installed observer version
version_lateststringThe latest published version
update_availablebooleantrue if an update is available
audiodictionaryAn 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"
}
]
}
}
get
/audio/logs
🔒

Get logs for the audio plugin container via the Systemd journal backend.

The endpoint accepts the same headers and provides the same functionality as /host/logs.

get
/audio/logs/follow
🔒

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

get
/audio/logs/boots/<bootid>
🔒

Get logs for the audio plugin container related to a specific boot.

The bootid parameter is interpreted in the same way as in /host/logs/boots/<bootid> and the endpoint otherwise provides the same functionality as /host/logs.

get
/audio/logs/boots/<bootid>/follow
🔒

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

post
/audio/mute/input
🔒

Mute input devices

Payload:

keytypeoptionaldescription
indexstringFalseThe index of the device
activebooleanFalsetrue if muted
post
/audio/mute/input/<application>
🔒

Mute input for a specific application

Payload:

keytypeoptionaldescription
indexstringFalseThe index of the device
activebooleanFalsetrue if muted
post
/audio/mute/output
🔒

Mute output devices

Payload:

keytypeoptionaldescription
indexstringFalseThe index of the device
activebooleanFalsetrue if muted
post
/audio/mute/output/<application>
🔒

Mute output for a specific application

Payload:

keytypeoptionaldescription
indexstringFalseThe index of the device
activebooleanFalsetrue if muted
post
/audio/profile
🔒

Create an audio profile

Payload:

keytypeoptionaldescription
cardstringFalseThe name of the audio device
namestringFalseThe name of the profile
post
/audio/reload
🔒

Reload audio information

post
/audio/restart
🔒

Restart the audio plugin

get
/audio/stats
🔒

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
}
post
/audio/update
🔒

Update the audio plugin

Payload:

keytypedescription
versionstringThe version you want to install, default is the latest version
post
/audio/volume/input
🔒

Set the input volume

Payload:

keytypeoptionaldescription
indexstringFalseThe index of the device
volumefloatFalseThe volume (between 0.0and 1.0)
post
/audio/volume/input/<application>
🔒

Set the input volume for a specific application

Payload:

keytypeoptionaldescription
indexstringFalseThe index of the device
volumefloatFalseThe volume (between 0.0and 1.0)
post
/audio/volume/output
🔒

Set the output volume

Payload:

keytypeoptionaldescription
indexstringFalseThe index of the device
volumefloatFalseThe volume (between 0.0and 1.0)
post
/audio/volume/output/<application>
🔒

Set the output volume for a specific application

Payload:

keytypeoptionaldescription
indexstringFalseThe index of the device
volumefloatFalseThe volume (between 0.0and 1.0)

Auth​

get
/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.

post
/auth
🔒

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:

keytypedescription
usernamestringThe username for the user
passwordstringThe password for the user
post
/auth/reset
🔒

Set a new password for a Home Assistant Core user.

Payload:

keytypedescription
usernamestringThe username for the user
passwordstringThe new password for the user
delete
/auth/cache
🔒

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

get
/auth/list
🔒

List all users in Home Assistant to help with credentials recovery. Requires an admin level authentication token.

Payload:

keytypedescription
userslistList of the Home Assistant users.

Backup​

get
/backups
🔒

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"]
}
}
]
}
get
/backups/info
🔒

Return information about backup manager.

Returned data:

keytypedescription
backupslistA list of Backups
days_until_staleintNumber 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
}
post
/backups/new/full
🔒

Create a full backup.

Payload:

keytypeoptionaldescription
namestringTrueThe name you want to give the backup
passwordstringTrueThe password you want to give the backup
compressedbooleanTruefalse to create uncompressed backups
locationstring or nullTrueName of a backup mount or null for /backup
homeassistant_exclude_databasebooleanTrueExclude the Home Assistant database file from backup
backgroundbooleanTrueReturn job_id immediately, do not wait for backup to complete. Clients must check job for status and slug.

Example response:

{
"slug": "skuwe823"
}
post
/backups/new/upload
🔒

Upload a backup.

Example response:

{
"slug": "skuwe823",
"job_id": "abc123"
}
note

Error responses from this API may also include a job_id if the message alone cannot accurately describe what happened. Callers should direct users to review the job or supervisor logs to get an understanding of what occurred.

post
/backups/new/partial
🔒

Create a partial backup.

Payload:

keytypeoptionaldescription
namestringTrueThe name you want to give the backup
passwordstringTrueThe password you want to give the backup
homeassistantbooleanTrueAdd home assistant core settings to the backup
addonslistTrueA list of strings representing add-on slugs
folderslistTrueA list of strings representing directories
compressedbooleanTruefalse to create uncompressed backups
locationstring or nullTrueName of a backup mount or null for /backup
homeassistant_exclude_databasebooleanTrueExclude the Home Assistant database file from backup
backgroundbooleanTrueReturn job_id immediately, do not wait for backup to complete. Clients must check job for status and slug.

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

Example response:

{
"slug": "skuwe823",
"job_id": "abc123"
}
note

Error responses from this API may also include a job_id if the message alone cannot accurately describe what happened. Callers should direct users to review the job or supervisor logs to get an understanding of what occurred.

post
/backups/options
🔒

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

Payload:

keytypedescription
days_until_staleintSet number of days until a backup is considered stale

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

post
/backups/reload
🔒

Reload backup from storage.

post
/backups/freeze
🔒

Put Supervisor in a freeze state and prepare Home Assistant and addons for an external backup.

note

This does not take a backup. It prepares Home Assistant and addons for one but the expectation is that the user is using an external tool to make the backup. Such as the snapshot feature in KVM or Proxmox. The caller should call /backups/thaw when done.

Payload:

keytypeoptionaldescription
timeoutintTrueSeconds before freeze times out and thaw begins automatically (default: 600).
post
/backups/thaw
🔒

End a freeze initiated by /backups/freeze and resume normal behavior in Home Assistant and addons.

get
/backups/<backup>/download
🔒

Download the backup file with the given slug.

get
/backups/<backup>/info
🔒

Returns a Backup details model for the add-on.

delete
/backups/<backup>
🔒

Removes the backup file with the given slug.

post
/backups/<backup>/restore/full
🔒

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

Payload:

keytypeoptionaldescription
passwordstringTrueThe password for the backup if any
backgroundbooleanTrueReturn job_id immediately, do not wait for restore to complete. Clients must check job for status.

Example response:

{
"job_id": "abc123"
}
note

Error responses from this API may also include a job_id if the message alone cannot accurately describe what happened. Callers should direct users to review the job or supervisor logs to get an understanding of what occurred.

post
/backups/<backup>/restore/partial
🔒

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

Payload:

keytypeoptionaldescription
homeassistantbooleanTruetrue if Home Assistant should be restored
addonslistTrueA list of add-on slugs that should be restored
folderslistTrueA list of directories that should be restored
passwordstringTrueThe password for the backup if any
backgroundbooleanTrueReturn job_id immediately, do not wait for restore to complete. Clients must check job for status.

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

Example response:

{
"job_id": "abc123"
}
note

Error responses from this API may also include a job_id if the message alone cannot accurately describe what happened. Callers should direct users to review the job or supervisor logs to get an understanding of what occurred.

CLI​

get
/cli/info
🔒

Returns information about the CLI plugin

Returned data:

keytypedescription
versionstringThe installed cli version
version_lateststringThe latest published version
update_availablebooleantrue if an update is available

Example response:

{
"version": "1",
"version_latest": "2",
"update_available": true
}
get
/cli/stats
🔒

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
}
post
/cli/update
🔒

Update the CLI plugin

Payload:

keytypedescription
versionstringThe version you want to install, default is the latest version

Core​

get
/core/api
🔒

Proxy GET API calls to the Home Assistant API

post
/core/api
🔒

Proxy POST API calls to the Home Assistant API

post
/core/check
🔒

Run a configuration check

get
/core/info
🔒

Returns information about the Home Assistant core

Returned data:

keytypedescription
versionstringThe installed core version
version_lateststringThe latest published version in the active channel
update_availablebooleantrue if an update is available
archstringThe architecture of the host (armhf, aarch64, i386, amd64)
machinestringThe machine type that is running the host
ip_addressstringThe internal docker IP address to the supervisor
imagestringThe container image that is running the core
bootbooleantrue if it should start on boot
portintThe port Home Assistant is running on
sslbooleantrue if Home Assistant is using SSL
watchdogbooleantrue if watchdog is enabled
wait_bootintMax time to wait during boot
audio_inputstring or nullThe description of the audio input device
audio_outputstring or nullThe description of the audio output device
backups_exclude_databasebooleanBackups exclude Home Assistant database file by default

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"
}
get
/core/logs
🔒

Get logs for the Home Assistant Core container via the Systemd journal backend.

The endpoint accepts the same headers and provides the same functionality as /host/logs.

get
/core/logs/follow
🔒

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

get
/core/logs/boots/<bootid>
🔒

Get logs for the Home Assistant Core container related to a specific boot.

The bootid parameter is interpreted in the same way as in /host/logs/boots/<bootid> and the endpoint otherwise provides the same functionality as /host/logs.

get
/core/logs/boots/<bootid>/follow
🔒

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

post
/core/options
🔒

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:

keytypedescription
bootbooleanStart Core on boot
imagestring or nullName of custom image
portintThe port that Home Assistant run on
sslbooleantrue to enable SSL
watchdogbooleantrue to enable the watchdog
wait_bootintTime to wait for Core to startup
refresh_tokenstring or nullToken to authenticate with Core
audio_inputstring or nullProfile name for audio input
audio_outputstring or nullProfile name for audio output
backups_exclude_databasebooleantrue to exclude Home Assistant database file from backups

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

post
/core/rebuild
🔒

Rebuild the Home Assistant core container

Payload:

keytypeoptionaldescription
safe_modebooleanTrueRebuild Core into safe mode
forcebooleanTrueForce rebuild during a Home Assistant offline db migration
post
/core/restart
🔒

Restart the Home Assistant core container

Payload:

keytypeoptionaldescription
safe_modebooleanTrueRestart Core into safe mode
forcebooleanTrueForce restart during a Home Assistant offline db migration
post
/core/start
🔒

Start the Home Assistant core container

get
/core/stats
🔒

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
}
post
/core/stop
🔒

Stop the Home Assistant core container

Payload:

keytypeoptionaldescription
forcebooleanTrueForce stop during a Home Assistant offline db migration
post
/core/update
🔒

Update Home Assistant core

Payload:

keytypedescription
versionstringThe version you want to install, default is the latest version
backupbooleanCreate a partial backup of core and core configuration before updating, default is false
get
/core/websocket
🔒

Proxy to Home Assistant Core websocket.

Discovery​

get
/discovery
🔒

Return information about enabled discoveries.

Returned data:

keytypedescription
discoverylistA list of Discovery models
servicesdictionaryA 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"]
}
}
post
/discovery
🔒

Create a discovery service

Payload:

keytypeoptionaldescription
servicestringFalseThe name of the service
configdictionaryFalseThe configuration of the service

Example response:

{
"uuid": "uuid"
}
get
/discovery/<uuid>
🔒

Get a discovery model for a UUID.

delete
/discovery/<uuid>
🔒

Delete a specific service.

DNS​

get
/dns/info
🔒

Return information about the DNS plugin.

Returned data:

keytypedescription
fallbackboolTry fallback DNS on failure
hoststringThe IP address of the plugin
llmnrboolCan resolve LLMNR hostnames
localslistA list of DNS servers
mdnsboolCan resolve MulticastDNS hostnames
serverslistA list of DNS servers
update_availablebooleantrue if an update is available
versionstringThe installed observer version
version_lateststringThe 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
}
get
/dns/logs
🔒

Get logs for the DNS plugin container via the Systemd journal backend.

The endpoint accepts the same headers and provides the same functionality as /host/logs.

get
/dns/logs/follow
🔒

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

get
/dns/logs/boots/<bootid>
🔒

Get logs for the DNS plugin container related to a specific boot.

The bootid parameter is interpreted in the same way as in /host/logs/boots/<bootid> and the endpoint otherwise provides the same functionality as /host/logs.

get
/dns/logs/boots/<bootid>/follow
🔒

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

post
/dns/options
🔒

Set DNS options

Payload:

keytypeoptionaldescription
fallbackboolTrueEnable/Disable fallback DNS
serverslistTrueA list of DNS servers

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

post
/dns/reset
🔒

Reset the DNS configuration.

post
/dns/restart
🔒

Restart the DNS plugin

get
/dns/stats
🔒

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
}
post
/dns/update
🔒

Update the DNS plugin

Payload:

keytypedescription
versionstringThe version you want to install, default is the latest version

Docker​

get
/docker/info
🔒

Returns information about the docker instance.

Returned data:

keytypedescription
versionstringThe version of the docker engine
storagestringThe storage type
loggingstringThe logging type
registriesdictionaryA dictionary of dictionaries containing username and password keys for registries.

Example response:

{
"version": "1.0.1",
"storage": "overlay2",
"logging": "journald",
"registries": {}
}
get
/docker/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"
}
}
post
/docker/registries
🔒

Add a new container registry.

Payload:

keytypedescription
hostnamedictionaryA 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
/docker/registries/<registry>
🔒

Delete a registry from the configured container registries.

Hardware​

get
/hardware/info
🔒

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"
]
}
],
"drives": [
{
"vendor": "Generic",
"model": "Flash Disk",
"revision": "8.07",
"serial": "AABBCCDD",
"id": "Generic-Flash-Disk-AABBCCDD",
"size": 8054112256,
"time_detected": "2023-02-15T21:44:22.504878+00:00",
"connection_bus": "usb",
"seat": "seat0",
"removable": true,
"ejectable": true,
"filesystems": [
{
"device": "/dev/sda1",
"id": "by-uuid-1122-1ABA",
"size": 67108864,
"name": "",
"system": false,
"mount_points": []
}
]
}
]
}

Returned data:

keydescription
devicesA list of Device models
drivesA list of Drive models
get
/hardware/audio
🔒

Get audio devices

Example response:

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

Host​

get
/host/info
🔒

Return information about the host.

Returned data

keytypedescription
agent_versionstring or nullAgent version running on the Host
apparmor_versionstring or nullThe AppArmor version from host
boot_timestampintThe timestamp for the last boot in microseconds
broadcast_llmnrbool or nullHost is broadcasting its LLMNR hostname
broadcast_mdnsbool or nullHost is broadcasting its MulticastDNS hostname
chassisstring or nullThe chassis type
virtualizationstring or nullVirtualization hypervisor in use (if any)
cpestring or nullThe local CPE
deploymentstring or nullThe deployment stage of the OS if any
disk_totalfloatTotal space of the disk in MB
disk_usedfloatUsed space of the disk in MB
disk_freefloatFree space of the disk in MB
featureslistA list of features available for the host
hostnamestring or nullThe hostname of the host
kernelstring or nullThe kernel version on the host
llmnr_hostnamestring or nullThe hostname currently exposed on the network via LLMNR for host
operating_systemstringThe operating system on the host
startup_timefloatThe 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
/host/logs
🔒

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

HTTP Request Headers

Headeroptionaldescription
AccepttrueType of data (text/plain or text/x-log)
RangetrueRange 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.

The Accept header can be set to text/x-log to get logs annotated with extra information, such as the timestamp and Systemd unit name. If no identifier is specified (i.e. for the host logs containing logs for multiple identifiers/units), this option is ignored - these logs are always annotated.

get
/host/logs/follow
🔒

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

/host/logs/identifiers
🔒

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
/host/logs/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.

get
/host/logs/identifiers/<identifier>/follow
🔒

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

/host/logs/boots
🔒

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
/host/logs/boots/<bootid>
🔒

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.

get
/host/logs/boots/<bootid>/follow
🔒

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

get
/host/logs/boots/<bootid>/identifiers/<identifier>
🔒

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

get
/host/logs/boot/<bootid>/<identifier>/entries/follow
🔒

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

post
/host/options
🔒

Set host options

Payload:

keytypeoptionaldescription
hostnamestringTrueA string that will be used as the new hostname

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

post
/host/reboot
🔒

Reboot the host

Payload:

keytypeoptionaldescription
forcebooleanTrueForce reboot during a Home Assistant offline db migration
post
/host/reload
🔒

Reload host information

post
/host/service/<service>/start
🔒

Start a service on the host.

post
/host/service/<service>/stop
🔒

Stop a service on the host.

post
/host/service/<service>/reload
🔒

Reload a service on the host.

get
/host/services
🔒

Get information about host services.

Returned data:

keydescription
servicesA dictionary of Host service models

Example response:

{
"services": [
{
"name": "awesome.service",
"description": "Just an awesome service",
"state": "active"
}
]
}
post
/host/shutdown
🔒

Shutdown the host

Payload:

keytypeoptionaldescription
forcebooleanTrueForce shutdown during a Home Assistant offline db migration

Ingress​

get
/ingress/panels
🔒

Returned data:

keytypedescription
panelsdictionarydictionary of Panel models

Example response:

{
"panels": {
"addon_slug": {
"enable": true,
"icon": "mdi:awesome-icon",
"title": "Awesome add-on",
"admin": true
}
}
}
post
/ingress/session
🔒

Create a new session for access to the ingress service.

Payload:

keytypeoptionaldescription
user_idstringTrueThe ID of the user authenticated for the new session

Returned data:

keytypeoptionaldescription
sessionstringFalseThe token for the ingress session
post
/ingress/validate_session
🔒

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

Payload:

keytypeoptionaldescription
sessionstringFalseThe token for the ingress session

Jobs​

get
/jobs/info
🔒

Returns info on ignored job conditions and currently running jobs

Returned data:

keytypedescription
ignore_conditionslistList of job conditions being ignored
jobslistList of currently running Jobs

Example response:

{
"ignore_conditions": [],
"jobs": [{
"name": "backup_manager_full_backup",
"reference": "a01bc3",
"uuid": "123456789",
"progress": 0,
"stage": "addons",
"done": false,
"child_jobs": []
}]
}
post
/jobs/options
🔒

Set options for job manager

Payload:

keytypedescription
ignore_conditionslistList of job conditions to ignore (replaces existing list)
post
/jobs/reset
🔒

Reset job manager to defaults (stops ignoring any ignored job conditions)

Root​

get
/available_updates
🔒

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:

keytypedescription
update_typestringaddon, os, core or supervisor
namestringReturns the name (only if the update_type is addon)
iconstringReturns the path for the icon if any (only if the update_type is addon)
version_lateststringReturns the available version
panel_pathstringReturns path where the UI can be loaded
post
/refresh_updates
🔒

This reloads information about add-on repositories and fetches new version files.

get
/info
🔒

Returns a dict with selected keys from other /*/info endpoints.

Returned data:

keytypedescription
supervisorstringThe installed version of the supervisor
homeassistantstringThe installed version of Home Assistant
hassosstring or nullThe version of Home Assistant OS or null
dockerstringThe docker version on the host
hostnamestringThe hostname on the host
operating_systemstringThe operating system on the host
featureslistA list ov available features on the host
machinestringThe machine type
archstringThe architecture on the host
supported_archlistA list of supported host architectures
supportedbooleantrue if the environment is supported
channelstringThe active channel (stable, beta, dev)
loggingstringThe active log level (debug, info, warning, error, critical)
statestringThe core state of the Supervisor.
timezonestringThe 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​

get
/mounts
🔒

Returns information about mounts configured in Supervisor

Returned data:

keytypedescription
mountslistA list of Mounts
default_backup_mountstring or nullName 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",
"read_only": false
}
]
}
post
/mounts/options
🔒

Set mount manager options

Payload:

keytypeoptionaldescription
default_backup_mountstring or nullTrueName of a backup mount or null for /backup

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

post
/mounts
🔒

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",
"read_only": false
}
put
/mounts/<name>
🔒

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",
"read_only": true
}
delete
/mounts/<name>
🔒

Unmount and delete an existing mount from Supervisor.

post
/mounts/<name>/reload
🔒

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

Multicast​

get
/multicast/info
🔒

Returns information about the multicast plugin

Returned data:

keytypedescription
versionstringThe installed multicast version
version_lateststringThe latest published version
update_availablebooleantrue if an update is available

Example response:

{
"version": "1",
"version_latest": "2",
"update_available": true
}
get
/multicast/logs
🔒

Get logs for the multicast plugin via the Systemd journal backend.

The endpoint accepts the same headers and provides the same functionality as /host/logs.

get
/multicast/logs/follow
🔒

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

get
/multicast/logs/boots/<bootid>
🔒

Get logs for the multicast plugin related to a specific boot.

The bootid parameter is interpreted in the same way as in /host/logs/boots/<bootid> and the endpoint otherwise provides the same functionality as /host/logs.

get
/multicast/logs/boots/<bootid>/follow
🔒

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

post
/multicast/restart
🔒

Restart the multicast plugin.

get
/multicast/stats
🔒

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
}
post
/multicast/update
🔒

Update the multicast plugin

Payload:

keytypedescription
versionstringThe version you want to install, default is the latest version

Network​

get
/network/info
🔒

Get network information.

Returned data:

keydescription
interfacesA list of Network interface models
dockerInformation about the internal docker network
host_internetBoolean to indicate if the host can reach the internet.
supervisor_internetBoolean 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
}
get
/network/interface/<interface>/info
🔒

Returns a Network interface model for a specific network interface.

post
/network/reload
🔒

Update all Network interface data.

post
/network/interface/<interface>/update
🔒

Update the settings for a network interface.

Payload:

keytypeoptionaldescription
enabledboolTrueEnable/Disable an ethernet interface / VLAN got removed with disabled
ipv4dictTrueA struct with ipv4 interface settings
ipv6dictTrueA struct with ipv6 interface settings
wifidictTrueA struct with Wireless connection settings

ipv4 / ipv6:

keytypeoptionaldescription
methodstringTrueSet IP configuration method can be auto for DHCP or Router Advertisements (only IPv6), static or disabled
addresslistTrueThe new IP address for the interface in the X.X.X.X/XX format as list
nameserverslistTrueList of DNS servers to use
gatewaystringTrueThe gateway the interface should use

wifi:

keytypeoptionaldescription
modestringTrueSet the mode infrastructure (default), mesh, adhoc or ap
authstringTrueSet the auth mode: open (default), web, wpa-psk
ssidstringTrueSet the SSID for connect into
pskstringTrueThe shared key which is used with web or wpa-psk
get
/network/interface/<interface>/accesspoints
🔒

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

This function only works with Wireless interfaces!

Returned data:

keydescription
accesspointsA list of Access Points

Example response:

{
"accesspoints": [
{
"mode": "infrastructure",
"ssid": "MY_TestWifi",
"mac": "00:00:00:00",
"frequency": 24675,
"signal": 90
}
]
}
post
/network/interface/<interface>/vlan/<id>
🔒

Create a new VLAN id on this network interface.

This function only works with ethernet interfaces!

Payload:

keytypeoptionaldescription
ipv4dictTrueA struct with ipv4 interface settings
ipv6dictTrueA struct with ipv6 interface settings

Observer​

get
/observer/info
🔒

Returns information about the observer plugin

Returned data:

keytypedescription
hoststringThe IP address of the plugin
versionstringThe installed observer version
version_lateststringThe latest published version
update_availablebooleantrue if an update is available

Example response:

{
"host": "172.0.0.17",
"version": "1",
"version_latest": "2",
"update_available": true
}
get
/observer/stats
🔒

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
}
post
/observer/update
🔒

Update the observer plugin

Payload:

keytypedescription
versionstringThe version you want to install, default is the latest version

OS​

post
/os/config/sync
🔒

Load host configurations from a USB stick.

get
/os/info
🔒

Returns information about the OS.

Returned data:

keytypedescription
versionstringThe current version of the OS
version_lateststringThe latest published version of the OS in the active channel
update_availablebooleantrue if an update is available
boardstringThe name of the board
bootstringWhich slot that are in use
data_diskstringDevice which is used for holding OS data persistent
boot_slotsdictDictionary of boot slots keyed by name

Example response:

{
"version": "4.3",
"version_latest": "5.0",
"update_available": true,
"board": "ova",
"boot": "slot1",
"data_disk": "BJTD4R-0x123456789",
"boot_slots": {
"A": {
"state": "inactive",
"status": "good",
"version": "10.1"
},
"B": {
"state": "active",
"status": "good",
"version": "10.2"
}
}
}
post
/os/update
🔒

Update Home Assistant OS

Payload:

keytypedescription
versionstringThe version you want to install, default is the latest version
post
/os/boot-slot
🔒

Change the active boot slot, This will also reboot the device!

Payload:

keytypedescription
boot_slotstringBoot slot to change to. See options in boot_slots from /os/info API.
get
/os/datadisk/list
🔒

Returns possible targets for the new data partition.

Returned data:

keytypedescription
deviceslistList of IDs of possible data disk targets
diskslistList 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"
}
]
}
post
/os/datadisk/move
🔒

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

Payload:

keytypedescription
devicestringID of the disk device which should be used as the target for the data migration
post
/os/datadisk/wipe
🔒

Wipe the datadisk including all user data and settings, This will also reboot the device! This API requires an admin token

This API will wipe all config/settings for addons, Home Assistant and the Operating System and any locally stored data in config, backups, media, etc. The machine will reboot during this.

After the reboot completes the latest stable version of Home Assistant and Supervisor will be downloaded. Once the process is complete the user will see onboarding, like during initial setup.

This wipe also includes network settings. So after the reboot the user may need to reconfigure those in order to access Home Assistant again.

The operating system version as well as its boot configuration will be preserved.

get
/os/boards/{board}
🔒

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.

get
/os/boards/yellow
🔒

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

Returned data:

keytypedescription
disk_ledbooleanIs the disk LED enabled
heartbeat_ledbooleanIs the heartbeat LED enabled
power_ledbooleanIs the power LED enabled

Example response:

{
"disk_led": true,
"heartbeat_led": true,
"power_led": false
}
post
/os/boards/yellow
🔒

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

Payload:

keytypedescription
disk_ledbooleanEnable/disable the disk LED
heartbeat_ledbooleanEnable/disable the heartbeat LED
power_ledbooleanEnable/disable the power LED
get
/os/boards/green
🔒

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

Returned data:

keytypedescription
activity_ledbooleanIs the green activity LED enabled
power_ledbooleanIs the white power LED enabled
system_health_ledbooleanIs the yellow system health LED enabled

Example response:

{
"activity_led": true,
"power_led": true,
"system_health_led": false
}
post
/os/boards/green
🔒

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

Payload:

keytypedescription
activity_ledbooleanEnable/disable the green activity LED
power_ledbooleanEnable/disable the white power LED
system_health_ledbooleanEnable/disable the yellow system health LED

Resolution​

get
/resolution/info
🔒

Returned data:

keytypedescription
unsupportedlistA list of reasons why an installation is marked as unsupported (container, dbus, docker_configuration, docker_version, lxc, network_manager, os, privileged, systemd)
unhealthylistA list of reasons why an installation is marked as unhealthy (docker, supervisor, privileged, setup)
issueslistA list of Issue models
suggestionslistA list of Suggestion models actions
checkslistA 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
}
]
}
post
/resolution/suggestion/<uuid>
🔒

Apply a suggested action

delete
/resolution/suggestion/<uuid>
🔒

Dismiss a suggested action

get
/resolution/issue/<uuid>/suggestions
🔒

Get suggestions that would fix an issue if applied.

Returned data:

keytypedescription
suggestionslistA list of Suggestion models actions

Example response:

{
"suggestions": [
{
"uuid": "B9923620C9A11EBBDC3C403FC2CA371",
"type": "clear_backups",
"context": "system",
"reference": null,
"auto": false
}
]
}
delete
/resolution/issue/<uuid>
🔒

Dismiss an issue

post
/resolution/healthcheck
🔒

Execute a healthcheck and autofix & notifcation.

post
/resolution/check/<slug>/options
🔒

Set options for this check.

Payload:

keytypedescription
enabledboolIf the check should be enabled or disabled
post
/resolution/check/<slug>/run
🔒

Execute a specific check right now.

Service​

get
/services
🔒

Returned data:

keytypedescription
servicesdictionarydictionary of Service models

Example response:

{
"services": [
{
"slug": "name",
"available": true,
"providers": ["awesome_addon"]
}
]
}
get
/services/mqtt
🔒

Returned data:

keytypedescription
addonstringThe add-on slug
hoststringThe IP of the addon running the service
portstringThe port the service is running on
sslbooleantrue if SSL is in use
usernamestringThe username for the service
passwordstringThe password for the service
protocolstringThe 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"
}
post
/services/mqtt
🔒

Create a service definition

Payload:

keytypedescription
hoststringThe IP of the addon running the service
portstringThe port the service is running on
sslbooleantrue if SSL is in use
usernamestringThe username for the service
passwordstringThe password for the service
protocolstringThe MQTT protocol
delete
/services/mqtt
🔒

Deletes the service definitions

get
/services/mysql
🔒

Returned data:

keytypedescription
addonstringThe add-on slug
hoststringThe IP of the addon running the service
portstringThe port the service is running on
sslbooleantrue if SSL is in use
usernamestringThe username for the service
passwordstringThe password for the service
protocolstringThe MQTT protocol

Example response:

{
"addon": "awesome_mysql",
"host": "172.0.0.17",
"port": "8883",
"username": "awesome_user",
"password": "strong_password"
}
post
/services/mysql
🔒

Create a service definition

Payload:

keytypedescription
hoststringThe IP of the addon running the service
portstringThe port the service is running on
usernamestringThe username for the service
passwordstringThe password for the service
delete
/services/mysql
🔒

Deletes the service definitions

Store​

get
/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"
}
]
}
get
/store/addons
🔒

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"
}
]
get
/store/addons/<addon>
🔒

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"
}
post
/store/addons/<addon>/install
🔒

Install an add-on from the store.

post
/store/addons/<addon>/update
🔒

Update an add-on from the store.

Payload:

keytypedescription
backupbooleanCreate a partial backup of the add-on, default is false
get
/store/addons/<addon>/changelog
🔒

Get the changelog for an add-on.

get
/store/addons/<addon>/documentation
🔒

Get the documentation for an add-on.

get
/store/addons/<addon>/icon
🔒

Get the add-on icon

get
/store/addons/<addon>/logo
🔒

Get the add-on logo

post
/store/reload
🔒

Reloads the information stored about add-ons.

get
/store/repositories
🔒

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"
}
]
post
/store/repositories
🔒

Add an addon repository to the store

Payload:

keytypedescription
repositorystringURL of the addon repository to add to the store.

Example payload:

{
"repository": "https://example.com/addons"
}
get
/store/repositories/<repository>
🔒

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"
}
delete
/store/repositories/<repository>
🔒

Remove an unused addon repository from the store.

Security​

get
/security/info
🔒

Returns information about the security features

Returned data:

keytypedescription
content_trustboolIf content-trust is enabled or disabled on the backend
pwnedboolIf pwned check is enabled or disabled on the backend
force_securityboolIf force-security is enabled or disabled on the backend

Example response:

{
"content_trust": true,
"pwned": true,
"force_security": false,
}
post
/security/options
🔒

Payload:

keytypedescription
content_trustboolDisable/Enable content-trust
pwnedboolDisable/Enable pwned
force_securityboolDisable/Enable force-security
post
/security/integrity
🔒

Run a full platform integrity check.

Returned data:

keytypedescription
supervisorstrpass, error, failed, untested
corestrpass, error, failed, untested
pluginsdictA dictionary with key per plugin as pass, error, failed, untested
addonsdictA 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​

get
/supervisor/info
🔒

Returns information about the supervisor

Returned data:

keytypedescription
versionstringThe installed supervisor version
version_lateststringThe latest published version in the active channel
update_availablebooleantrue if an update is available
archstringThe architecture of the host (armhf, aarch64, i386, amd64)
channelstringThe active channel (stable, beta, dev)
timezonestringThe current timezone
healthyboolThe supervisor is in a healthy state
supportedboolThe environment is supported
loggingstringThe current log level (debug, info, warning, error, critical)
ip_addressstringThe internal docker IP address to the supervisor
wait_bootintMax time to wait during boot
debugboolDebug is active
debug_blockbooltrue if debug block is enabled
diagnosticsbool or nullSending diagnostics is enabled
addons_repositorieslistA list of add-on repository URL's as strings
auto_updateboolIs 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
}
get
/supervisor/logs
🔒

Get logs for the Supervisor container via the Systemd journal backend. If the Systemd journal gateway fails to provide the logs, raw Docker container logs are returned as the fallback.

The endpoint accepts the same headers and provides the same functionality as /host/logs.

get
/supervisor/logs/follow
🔒

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

get
/supervisor/logs/boots/<bootid>
🔒

Get logs for the Supervisor container related to a specific boot.

The bootid parameter is interpreted in the same way as in /host/logs/boots/<bootid> and the endpoint otherwise provides the same functionality as /host/logs.

get
/supervisor/logs/boots/<bootid>/follow
🔒

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

post
/supervisor/options
🔒

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:

keytypedescription
channelstringSet the active channel (stable, beta, dev)
timezonestringSet the timezone
wait_bootintSet the time to wait for boot
debugboolEnable debug
debug_blockboolEnable debug block
loggingstringSet logging level
addons_repositorieslistSet a list of URL's as strings for add-on repositories
auto_updateboolEnable/disable auto update for supervisor
get
/supervisor/ping
🔓

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

post
/supervisor/reload
🔒

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

post
/supervisor/restart
🔒

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

post
/supervisor/repair
🔒

Repair docker overlay issues, and lost images.

get
/supervisor/stats
🔒

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
}
post
/supervisor/update
🔒

Update the supervisor

Payload:

keytypedescription
versionstringThe version you want to install, default is the latest version

Placeholders​

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

placeholderdescription
addonThe 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 selfas the slug.
applicationThe name of an application, call /audio/info to get the correct name
interfaceA valid interface name, example eth0, to get the interface name you can call /network/info. You can use default to get the primary interface
registryA registry hostname defined in the container registry configuration, to get the hostname you can call /docker/registries
serviceThe service name for a service on the host.
backupA valid backup slug, example skuwe823, to get the slug you can call /backups
suggestionA valid suggestion, example clear_full_backup, to get the suggestion you can call /resolution
uuidThe UUID of a discovery service, to get the UUID you can call /discovery