Apps endpoints
Supervisor API endpoints for installed apps, their options, their state, and their logs.
These endpoints work on apps that are installed. To browse and install apps, use the store endpoints.
<app> is the slug of an installed app, like core_mosquitto or local_hello_world. Your app can always use self to mean itself. Calls to /addons/self/... need no extra permission, see what your app may call.
| Method | Path | Description |
|---|---|---|
GET |
/addons |
List installed apps |
POST |
/addons/reload |
Reload the app store |
GET |
/addons/<app>/info |
Details of an app |
POST |
/addons/<app>/options |
Change the options of an app |
POST |
/addons/<app>/options/validate |
Validate options |
GET |
/addons/<app>/options/config |
Read your own validated options |
POST |
/addons/<app>/sys_options |
Mark an app as managed by Home Assistant |
POST |
/addons/<app>/security |
Turn protection mode on or off |
POST |
/addons/<app>/start |
Start an app |
POST |
/addons/<app>/stop |
Stop an app |
POST |
/addons/<app>/restart |
Restart an app |
POST |
/addons/<app>/rebuild |
Rebuild a locally built app |
POST |
/addons/<app>/uninstall |
Uninstall an app |
POST |
/addons/<app>/stdin |
Write to the standard input of an app |
GET |
/addons/<app>/stats |
Resource usage of an app |
GET |
/addons/<app>/logs |
Logs of an app, and the other log endpoints |
POST |
/addons/<app>/install |
Older path for store install |
POST |
/addons/<app>/update |
Older path for store update |
GET |
/addons/<app>/icon |
Older path for the store icon |
GET |
/addons/<app>/logo |
Older path for the store logo |
GET |
/addons/<app>/changelog |
Older path for the store changelog |
GET |
/addons/<app>/documentation |
Older path for the store documentation |
Returns the installed apps.
| Key | Type | Description |
|---|---|---|
addons |
list | A list of app models |
{
"addons": [
{
"name": "Hello world",
"slug": "local_hello_world",
"description": "My first real app!",
"advanced": false,
"stage": "stable",
"version": "1.1.0",
"version_latest": "1.1.0",
"update_available": false,
"available": true,
"detached": false,
"homeassistant": null,
"state": "started",
"repository": "local",
"build": true,
"url": null,
"icon": false,
"logo": false,
"system_managed": false
}
]
}Reloads the app store: reads all repositories again and looks for new versions. Does the same as POST /store/reload.
Returns the details of an app. When the app is not installed, this falls back to the store information of the app, with state set to unknown and the default options.
| Key | Type | Description |
|---|---|---|
name |
string | Name of the app |
slug |
string | Slug of the app, including the repository prefix |
hostname |
string | Host name of the app on the internal network |
dns |
list | DNS names of the app |
description |
string | Short description |
long_description |
string or null | The content of README.md |
advanced |
boolean | Deprecated, always false |
stage |
string | stable, experimental, or deprecated |
repository |
string | Slug of the repository the app comes from |
version |
string | Installed version |
version_latest |
string | Latest available version |
update_available |
boolean | true if an update is available |
protected |
boolean | true if protection mode is on |
rating |
integer | Security rating, from 1 to 8 |
boot_config |
string | Boot mode from the app configuration: auto, manual, or manual_only |
boot |
string | Boot mode set by the user: auto or manual |
options |
dictionary | Options of the app. Empty when another app asks, unless that app has the manager or admin role. Options can hold passwords |
schema |
list or null | The options schema, prepared for the options form in the UI |
arch |
list | Supported architectures |
machine |
list | Supported machine types |
homeassistant |
string or null | Minimum Home Assistant version |
url |
string or null | Website of the app |
detached |
boolean | true if the app is no longer in any repository |
available |
boolean | true if the app can run on this system |
build |
boolean | true if the app is built locally |
network |
dictionary or null | Port mapping, container port to host port |
network_description |
dictionary or null | Description per port |
host_network |
boolean | Uses the host network |
host_pid |
boolean | Uses the host PID namespace |
host_ipc |
boolean | Uses the host IPC namespace |
host_uts |
boolean | Uses the host UTS namespace |
host_dbus |
boolean | Has access to the host D-Bus |
privileged |
list | Extra Linux capabilities |
full_access |
boolean | Has full hardware access |
apparmor |
string | disable, default, or profile |
icon |
boolean | Has an icon |
logo |
boolean | Has a logo |
changelog |
boolean | Has a changelog |
documentation |
boolean | Has documentation |
stdin |
boolean | Accepts input on stdin |
hassio_api |
boolean | Has access to the Supervisor API |
hassio_role |
string | Supervisor API role |
auth_api |
boolean | Can check user credentials |
homeassistant_api |
boolean | Has access to the Home Assistant Core API proxy |
gpio |
boolean | Has GPIO access |
usb |
boolean | Has USB access |
uart |
boolean | Has access to serial devices |
kernel_modules |
boolean | Has access to kernel modules |
devicetree |
boolean | Has access to the device tree |
udev |
boolean | Has access to the udev database |
docker_api |
boolean | Has access to the Docker API |
video |
boolean | Has access to video devices |
audio |
boolean | Uses the audio system |
startup |
string | initialize, system, services, application, or once |
services |
list | Services the app provides or uses, like mqtt:provide |
discovery |
list | Integrations the app can send discovery messages for |
translations |
dictionary | The translation files of the app, per language |
ingress |
boolean | Uses ingress |
ingress_entry |
string or null | Ingress path of the app |
ingress_url |
string or null | Full ingress URL, including the entry point |
ingress_port |
integer or null | Port the app listens on for ingress |
ingress_panel |
boolean or null | true if the app shows in the sidebar |
signed |
boolean | Always false, image signing is not checked |
state |
string | startup, started, stopped, unknown, or error |
webui |
string or null | URL of the web interface, with placeholders |
audio_input |
string or null | Selected audio input device |
audio_output |
string or null | Selected audio output device |
auto_update |
boolean | true if the app updates automatically |
ip_address |
string | IP address on the internal network |
watchdog |
boolean | true if the watchdog is on |
devices |
list | Device paths mapped into the app |
system_managed |
boolean | true if Home Assistant manages the app |
system_managed_config_entry |
string or null | ID of the config entry that manages the app |
Changes the settings of an app. Send only the keys you want to change. To reset network, audio_input, audio_output, or options to the default, send null.
| Key | Type | Required | Description |
|---|---|---|---|
boot |
string | No | auto or manual. Fails when the app uses manual_only |
auto_update |
boolean | No | Update the app automatically |
network |
dictionary or null | No | Port mapping, like "8000/tcp": 8000. A null port disables that mapping |
options |
dictionary or null | No | The app options, validated against the schema of the app |
audio_input |
string or null | No | Audio input device |
audio_output |
string or null | No | Audio output device |
ingress_panel |
boolean | No | Show the app in the sidebar |
watchdog |
boolean | No | Turn the watchdog on or off |
Options can use !secret name to refer to an entry in the secrets.yaml of Home Assistant. The Supervisor stores the reference and gives the app the resolved value.
{
"boot": "manual",
"options": {
"name": "world",
"beer": true
},
"watchdog": true
}Changes to options take effect the next time the app starts.
Validates options against the schema of the app. Send the options to check as the body, or send nothing to check the stored options. Also checks passwords against known leaks when that check is on, see /security.
| Key | Type | Description |
|---|---|---|
message |
string | What is wrong, or empty |
valid |
boolean | true if the options are valid |
pwned |
boolean or null | true if a password is known to be leaked, null if the check failed |
Returns the options of your own app, validated, with defaults filled in and !secret references resolved. Only works with self: no app can read the rendered options of another app.
Marks an app as managed by Home Assistant. Only Home Assistant Core can call this.
| Key | Type | Required | Description |
|---|---|---|---|
system_managed |
boolean | No | true if Home Assistant manages the app |
system_managed_config_entry |
string or null | No | ID of the config entry that manages the app |
Turns protection mode of an app on or off. Needs the admin role, also when an app calls it for itself with self.
| Key | Type | Required | Description |
|---|---|---|---|
protected |
boolean | No | true to turn protection mode on |
Starts an app. Waits until the app is running. Fails while the Supervisor is still starting up or restoring a backup.
Stops an app.
Restarts an app. Fails while the Supervisor is still starting up or restoring a backup.
Builds the image of a locally built app again and restarts it.
| Key | Type | Required | Description |
|---|---|---|---|
force |
boolean | No | Rebuild even if the app uses a prebuilt image. Default false |
Uninstalls an app.
| Key | Type | Required | Description |
|---|---|---|---|
remove_config |
boolean | No | Also delete the public configuration folder of the app (app_config). Default false |
Writes the raw request body to the standard input of the app. The app needs stdin: true in its configuration.
Returns the resource usage of the app as a stats model. Add the one_shot query parameter to get a single quick sample. In a one-shot sample, cpu_percent is null.
{
"cpu_percent": 14.0,
"cpu_usage": 3412000000,
"cpu_system_usage": 98231000000000,
"online_cpus": 4,
"memory_usage": 288888,
"memory_limit": 322222,
"memory_percent": 32.4,
"network_tx": 110,
"network_rx": 902,
"blk_read": 12,
"blk_write": 27
}Returns the logs of the app. The follow, latest, and boots variants are there too. They all work like the other log endpoints.