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.
  • 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.