Home Assistant¶
Run Prism as a Home Assistant add-on, show it in the sidebar, or use Prism's data in your automations.
Install covers the add-on. Below are the other two:
- Show Prism in the Home Assistant sidebar as a Webpage dashboard.
- Use Prism's data in Home Assistant sensors, through its REST API.
1. Showing Prism in the HA sidebar¶
Home Assistant can show any web page as a sidebar entry. Prism only lets a site show it inside a frame if that site is on its allowlist, so this takes two steps.
Allow Home Assistant to show Prism¶
Add the address you open Home Assistant at, exactly as the browser shows it (scheme, host and port):
- Home Assistant add-on: Settings → Add-ons → Prism → Configuration, set allowed_frame_ancestors to your Home Assistant address (for example
http://homeassistant.local:8123), save, and restart the add-on. - Docker: set
ALLOWED_FRAME_ANCESTORSin your.env, thendocker compose up -d app:
If you reach Home Assistant at more than one address, list them all, separated by commas:
Add the sidebar entry¶
In Home Assistant: Settings → Dashboards → Add dashboard → Webpage. Give it a title and icon, and set the URL to Prism's address, for example http://homeassistant.local:3000. To open one particular dashboard, use its own address, such as http://homeassistant.local:3000/d/kitchen. Leave Show in sidebar on.
Older guides use panel_iframe in configuration.yaml. Home Assistant replaced it with Webpage dashboards in 2024.4.
Limits¶
- You can't mix https and http. If you open Home Assistant over
https://(through Nabu Casa or a reverse proxy, for example), the browser won't show a plainhttp://Prism inside it, so Prism needs anhttps://address too. - The sidebar entry gives you no remote access. Your browser loads the page from Prism's own address, so it only works where that address can be reached, usually on your home network.
- Wall displays should open Prism at its own address and skip Home Assistant, so the on-screen keyboard, screensaver and full-screen mode work as usual.
2. Creating an API Token¶
An API token lets Home Assistant call Prism's REST API without logging in with a PIN.
- Open Prism Settings (gear icon)
- Go to Security
- Under API Tokens, enter a name (e.g. "Home Assistant")
- Choose a scope: Voice API only (the default, and the one to pick; it covers the Voice API and the read-only REST sensors below) or Full access (legacy) if you also need to call write endpoints directly
- Click Generate Token
- Copy the token straight away, because Prism shows it only once
- Store it in your HA
secrets.yaml:
Token scopes¶
Each token has the scope you chose when you generated it:
- Voice API only (default, recommended): reaches the Voice API (
/api/v1/voice/*) and the read-only REST sensors in Section 3. Most HA setups need nothing more. - Full access (legacy): every endpoint, including writes and admin routes. Pick this only if an automation calls a write endpoint directly instead of going through the Voice API.
The read sensors below (calendar, chores, shopping, meals) work with a Voice API only token, since they only make read-only GET requests. Write actions, such as adding a shopping item or completing a chore, go through the Voice API endpoints (see Section 5), which a voice-scoped token can also reach.
- Tokens never expire, and you can revoke one from Settings at any time.
- Each request updates the token's "Last used" time.
3. REST Sensor Examples¶
HA's REST sensor can read data from Prism.
Upcoming calendar events¶
sensor:
- platform: rest
name: "Prism Next Event"
resource: "http://prism.local:3000/api/events?limit=1"
headers:
Authorization: !secret prism_bearer
value_template: "{{ value_json.events[0].title if value_json.events else 'None' }}"
json_attributes_path: "$.events[0]"
json_attributes:
- startTime
- endTime
- location
scan_interval: 300
In secrets.yaml:
Pending chores count¶
sensor:
- platform: rest
name: "Prism Pending Chores"
resource: "http://prism.local:3000/api/chores"
headers:
Authorization: !secret prism_bearer
value_template: >
{{ value_json.chores | selectattr('enabled', 'true') | list | length }}
scan_interval: 600
Shopping list item count¶
{% raw %}
sensor:
- platform: rest
name: "Prism Shopping Items"
resource: "http://prism.local:3000/api/shopping-lists?includeItems=true"
headers:
Authorization: !secret prism_bearer
value_template: >
{% set total = 0 %}
{% for list in value_json.lists %}
{% set total = total + (list.items | rejectattr('checked', 'true') | list | length) %}
{% endfor %}
{{ total }}
scan_interval: 600
Today's meals¶
{% raw %}
sensor:
- platform: rest
name: "Prism Dinner Tonight"
resource: "http://prism.local:3000/api/meals?weekOf={{ now().strftime('%Y-%m-%d') }}"
headers:
Authorization: !secret prism_bearer
value_template: >
{% set today = now().strftime('%A') | lower %}
{% set dinner = value_json.meals | selectattr('dayOfWeek', 'equalto', today) | selectattr('mealType', 'equalto', 'dinner') | list %}
{{ dinner[0].name if dinner else 'Not planned' }}
scan_interval: 3600
4. Automation Examples¶
Announce dinner on smart speaker¶
automation:
- alias: "Announce tonight's dinner at 4pm"
trigger:
- platform: time
at: "16:00:00"
action:
- service: tts.speak
target:
entity_id: media_player.kitchen_speaker
data:
message: >
Tonight's dinner is {{ states('sensor.prism_dinner_tonight') }}.
Notify when shopping list grows¶
automation:
- alias: "Notify when shopping list has 10+ items"
trigger:
- platform: numeric_state
entity_id: sensor.prism_shopping_items
above: 10
action:
- service: notify.mobile_app
data:
title: "Shopping List"
message: "You have {{ states('sensor.prism_shopping_items') }} items on the shopping list."
5. Voice API (recommended surface)¶
Prism has a Voice API under /api/v1/voice/* built for this job, and it is the supported way to connect Home Assistant and voice assistants. Each endpoint returns a spoken field, a sentence ready to read aloud, next to the structured data, so you don't have to build sentences from raw fields in Jinja templates. A token with the Voice API only scope (the default) is all these endpoints need.
The endpoints include:
GET /api/v1/voice/calendar/todayand/calendar/upcoming: today's and upcoming eventsGET /api/v1/voice/chores/today: chores due todayGET /api/v1/voice/tasks/today: tasks due todayGET /api/v1/voice/meals/today: today's planned mealsGET /api/v1/voice/weather/today: today's weatherGET /api/v1/voice/birthdays/upcoming: upcoming birthdaysGET /api/v1/voice/bus/status: bus tracking statusGET /api/v1/voice/family: family membersGET /api/v1/voice/message/recentandPOST /api/v1/voice/message/post: read/post messagesPOST /api/v1/voice/shopping/add: add a shopping itemPOST /api/v1/voice/chore/complete: mark a chore complete
Here is a REST sensor that uses the spoken response:
sensor:
- platform: rest
name: "Prism Meals Today"
resource: "http://prism.local:3000/api/v1/voice/meals/today"
headers:
Authorization: !secret prism_bearer
value_template: "{{ value_json.spoken }}"
scan_interval: 3600
The write endpoints (shopping/add, chore/complete) are part of the Voice API, so a Voice API only token can call them too, and you don't need a Full access token for them.
docs/voice-api.md has the full endpoint reference, the request and response shapes, and more examples.
Troubleshooting¶
"Authentication required" error
- Check that the Authorization header has Bearer (with a space) before the token.
- Check that the token hasn't been revoked in Settings → Security → API Tokens.
Sidebar page is blank or "refused to connect"
- Check that the allowlist is set (the add-on option allowed_frame_ancestors, or ALLOWED_FRAME_ANCESTORS in .env) and that Prism was restarted after.
- The entry must match the address in your browser's address bar exactly, including http or https and the port.
- If Home Assistant is on https:// and Prism on http://, the browser blocks it (see Limits above).
Sensors show "unknown"
- Check that the Prism container is running: docker ps
- Test the endpoint by hand: curl -H "Authorization: Bearer $PRISM_TOKEN" http://prism.local:3000/api/chores, with PRISM_TOKEN set to the token from step 2
- Look for connection errors in the HA logs.
Google Calendar won't connect: "must end with a public top-level domain" - The add-on runs on a private LAN address, and Google won't accept that as an OAuth redirect URI (the address Google sends you back to after sign-in). Either put Prism behind a public HTTPS URL, or use the method that needs no public URL, where you paste a refresh token from Google's OAuth Playground. See Calendar → Google Calendar without a public URL.