Supervisor API

The Supervisor runs a REST API on the internal network. Home Assistant Core uses it, the CLI uses it, and so can your app: to read its own configuration, find an MQTT broker, make a backup, or restart Home Assistant. This section is the reference for that API.

The paths still use the old name: apps live under /addons and /store/addons. That is the real API, so that is what you call.

From inside an app container, the API is at http://supervisor/. The Supervisor gives every app its own token in the SUPERVISOR_TOKEN environment variable. Send it with every request:

curl -sSL \
  -H "Authorization: Bearer ${SUPERVISOR_TOKEN}" \
  http://supervisor/info

The Supervisor accepts the token in any of these headers, checked in this order:

• X-Supervisor-Token: <token>
• X-Hassio-Key: <token> (legacy)
• Authorization: Bearer <token>

The same token is also available as HASSIO_TOKEN, the old name of the variable. Use SUPERVISOR_TOKEN in new code.

If you write your app scripts in Bash, Bashio wraps most of this API in functions like bashio::app.option and bashio::services. It handles the token for you.

Which endpoints your app can reach depends on its configuration in config.yaml. See Talk to Home Assistant and the Supervisor for the full picture, and the configuration reference for the options.

Every app can call these endpoints with its token, even without hassio_api:

self is an alias: wherever a path takes an app slug, your app can use self to mean itself.

Set hassio_api: true in config.yaml to get access to more of the API. What exactly depends on the role you set with hassio_role:

Only ask for the role your app needs. The manager and admin roles lower the security rating of your app.

Some paths are off limits for every app, whatever its role:

• /addons/<app>/sys_options and /os/ssh/authorized_keys only accept calls from Home Assistant Core.
• /core/api/hassio... and /homeassistant/api/hassio... are blocked for everyone. Through these Core endpoints, a caller would act as the Supervisor itself.
• Through the WebSocket proxy, commands that start with supervisor/ or hassio/ are refused.

GET /supervisor/ping needs no token. Calls to the Home Assistant Core proxy are not checked against your role either: the proxy checks your token itself, and only lets you through when your app has homeassistant_api: true.

Most endpoints answer with JSON in the same envelope. A successful call:

{
  "result": "ok",
  "data": {}
}

data holds the response of the endpoint. The response tables in this reference describe what is inside data. Endpoints that only do something, like a restart, return an empty data.

A failed call:

{
  "result": "error",
  "message": "App my_app does not exist",
  "error_key": "app_not_found_error",
  "extra_fields": {}
}

Some endpoints do not use the envelope. Logs, changelogs, and documentation come back as plain text. Icons and logos come back as PNG images. Backup downloads come back as a tar file. When those fail, the error is plain text too.

Long operations, like installing an app or making a backup, run as jobs. Several endpoints take a background option. With background: true, the call returns right away with a job_id, and you follow the progress with GET /jobs/<job_id>.

Apps, Home Assistant Core, the Supervisor, the plugins, and the host all have log endpoints that work the same way. They read from the systemd journal of the host and return plain text.

<bootid> is either a boot ID from GET /host/logs/boots, or an offset: 0 is the current boot, -1 the one before, and so on. A positive number counts from the oldest boot the journal still has.

The log endpoints take these query parameters and headers:

The response has an X-First-Cursor header with the journal cursor of the first line. Pass it in a Range header to page back through older lines.

Check that the Supervisor is up. This one needs no token:

curl -sSL http://supervisor/supervisor/ping

{
  "result": "ok",
  "data": {}
}

Get the network configuration of the host. Your app needs hassio_api: true for this one, any role will do:

curl -sSL \
  -H "Authorization: Bearer ${SUPERVISOR_TOKEN}" \
  http://supervisor/network/info

Read the options of your own app, validated against its schema:

curl -sSL \
  -H "Authorization: Bearer ${SUPERVISOR_TOKEN}" \
  http://supervisor/addons/self/options/config

{
  "result": "ok",
  "data": {
    "name": "world",
    "beer": true
  }
}

• Apps: installed apps, their options, state, and logs.
• Store: apps that can be installed, and app repositories.
• Backups: make, restore, and manage backups.
• Home Assistant Core: control Core, and the proxy to its REST and WebSocket API.
• Host and OS: the host, Home Assistant OS, hardware, network, time, mounts, and Docker.
• Plugins: audio, CLI, DNS, multicast, and observer.
• Supervisor: the Supervisor itself, updates, jobs, resolution, and security.
• Services, discovery, auth, and ingress: what apps use to work together and with Home Assistant.
• Models: the objects that several endpoints return.

The Supervisor also has a second version of this API under /v2, where apps are under /apps and /store/apps instead of /addons and /store/addons. It is only there when the supervisor_v2_api development feature flag is on, and it is still changing. This reference covers the API without /v2, the one every installation has.