Skip to content

Home Assistant

Upstream docs: https://developers.home-assistant.io/docs/api/rest/

The Home Assistant service sends notifications through the REST API using a long-lived access token. By default it creates a persistent notification in the Home Assistant frontend. An optional service query parameter can target notify actions such as companion-app notifiers.

URL Format

homeassistant://token@host[:port][/basepath]

URL Fields

  • Token - Long-lived access token (Required)
    URL part: homeassistant://token@host:port/path
  • Host - Home Assistant hostname (Required)
    URL part: homeassistant://token@host:port/path
  • Port - Home Assistant port Default: empty
    URL part: homeassistant://token@host:port/path
  • Path - Reverse-proxy path prefix Default: empty
    URL part: homeassistant://token@host:port/path

Query/Param Props

Props can be either supplied using the params argument or through the URL using ?key=value&key=value etc.

  • disabletls - Disable TLS (use HTTP) Default: ❌ No

  • nid - Persistent notification ID Default: empty

  • service - Home Assistant action (domain.action or notify target) Default: empty

  • skiptlsverify - Skip TLS certificate verification Default: ❌ No

  • targets - Notify targets Default: empty

  • title - Notification title Default: empty

Getting Started

  1. Open your Home Assistant profile.
  2. Create a Long-Lived Access Token.
  3. Use the token as the URL username and your instance hostname as the host.

When the port is omitted, HTTPS uses port 443 and HTTP (disabletls=yes) uses port 8123.

HTTPS reverse proxy

homeassistant://[email protected]

LAN HTTP

homeassistant://[email protected]:8123/?disabletls=yes

disabletls=yes sends the long-lived Bearer token over HTTP. Use it only on a trusted, isolated network.

Replace an existing persistent notification

homeassistant://[email protected]:8123/?disabletls=yes&nid=watchtower&title=Update

disabletls=yes sends the long-lived Bearer token over HTTP. Use it only on a trusted, isolated network.

Companion app notifier

homeassistant://[email protected]?service=notify.mobile_app_phone

Parameters

  • title: Optional notification title. Omitted from the request when empty.
  • service: Home Assistant action. Empty defaults to persistent_notification.create. A value without a dot is sent as notify/<value>. A value with a dot is sent as <domain>/<action>.
  • targets: Comma-separated notify destinations. Sent as the Home Assistant target field and omitted for persistent notifications. Empty entries are dropped, and without any targets the field is omitted, so the selected action delivers to its own default recipients.
  • nid: Persistent notification ID. When set, Home Assistant overwrites the notification with that ID. Omitted when empty.
  • disabletls: Use HTTP instead of HTTPS.
  • skiptlsverify: Skip TLS certificate verification. Use only with self-signed certificates.

The request is POST /api/services/{domain}/{service} with Authorization: Bearer <token> and a JSON body containing message plus any optional fields above.

Webhook triggers that fire automations are not part of this service. Those endpoints do not use a long-lived access token.