Integrations & help

dashboard · account · admin · API docs

🔑 Getting started: household API keys

Everything below authenticates with a household API key — a token that machines (Home Assistant, scripts, calendar apps) use instead of your login.

  1. Go to Account → API keys (household admins only).
  2. Create a key — the full key (hp_…) is shown once; store it in Home Assistant's secrets.yaml.
  3. Send it as the X-API-Key header (or ?token= for the calendar feed). Keys are scoped to your household and can be revoked anytime.

🏠 Home Assistant

One rest_command is enough for every webhook. Add to configuration.yaml:

# secrets.yaml
homeplanner_api_key: hp_your_key_here

# configuration.yaml
rest_command:
  homeplanner_metric:
    url: "https://YOUR-APP/api/v1/integrations/home-assistant/metric"
    method: POST
    headers: { X-API-Key: !secret homeplanner_api_key }
    content_type: "application/json"
    payload: "{{ payload }}"
  homeplanner_energy:
    url: "https://YOUR-APP/api/v1/integrations/home-assistant/energy"
    method: POST
    headers: { X-API-Key: !secret homeplanner_api_key }
    content_type: "application/json"
    payload: "{{ payload }}"
  homeplanner_device:
    url: "https://YOUR-APP/api/v1/integrations/home-assistant/device-status"
    method: POST
    headers: { X-API-Key: !secret homeplanner_api_key }
    content_type: "application/json"
    payload: "{{ payload }}"

HomePlanner also exposes a flat sensor document back to HA — monthly cost, energy/water/solar this month, chores due, low batteries — for REST sensors:

sensor:
  - platform: rest
    name: HomePlanner
    resource: https://YOUR-APP/api/v1/integrations/home-assistant/sensors
    headers: { X-API-Key: !secret homeplanner_api_key }
    value_template: "{{ value_json.monthly_cost_total }}"
    json_attributes:
      - energy_month_kwh
      - water_month_l
      - solar_month_kwh
      - low_battery_devices
      - chores_due
      - next_renewal_name
      - next_renewal_days
    scan_interval: 900

⚡ Electricity & Nord Pool spot prices

  1. Pick your household's elområde (SE1–SE4) on the Economy tab — the daily cron fetches day-ahead spot prices for every area in use automatically.
  2. Push consumption from HA — each reading is priced from the spot price of its hour, and the dashboard chart follows:
- alias: "HomePlanner: hourly energy"
  trigger: [{ platform: time_pattern, minutes: 0 }]
  action:
    - service: rest_command.homeplanner_energy
      data:
        payload: >-
          {"kwh": {{ states('sensor.house_energy_hourly') }},
           "entity_id": "sensor.house_energy_hourly"}

Manual refresh / price queries: see API docs → energy (/energy/prices, /energy/prices/current).

💧 Water, ☀️ solar, 🔌 runtime & 🧪 air quality

The generic metric webhook takes any reading — one object or an array. Kinds: water (liters), solar (kWh), runtime (hours per appliance), radon, co2, humidity, temperature.

  • Water is costed from the household's Water price / m³ (Economy tab → Housing costs). Usage between 00:00–05:00 raises a possible leak warning in the daily digest.
  • Solar is valued at the Nord Pool spot price of the reading's hour.
  • Air quality readings bind to a room by name — the room row and the Home sensors card show the latest values. A 7-day radon average over 200 Bq/m³ (Swedish reference level) is warned about in the digest.
  • Runtime per appliance sums up on the dashboard — real wear, not calendar years.
- alias: "HomePlanner: hourly water"
  trigger: [{ platform: time_pattern, minutes: 0 }]
  action:
    - service: rest_command.homeplanner_metric
      data:
        payload: >-
          {"kind": "water", "value": {{ states('sensor.water_hourly_l') }}, "unit": "L"}

- alias: "HomePlanner: radon in the basement"
  trigger: [{ platform: time_pattern, hours: "/6" }]
  action:
    - service: rest_command.homeplanner_metric
      data:
        payload: >-
          {"kind": "radon", "value": {{ states('sensor.airthings_radon') }},
           "room": "Källare", "unit": "Bq/m3"}

- alias: "HomePlanner: dishwasher runtime"
  trigger:
    - platform: state
      entity_id: binary_sensor.dishwasher_running
      from: "on"
      to: "off"
  action:
    - service: rest_command.homeplanner_metric
      data:
        payload: >-
          {"kind": "runtime", "entity_id": "diskmaskin",
           "value": {{ ((as_timestamp(now()) - as_timestamp(trigger.from_state.last_changed)) / 3600) | round(2) }}}

🚨 Smoke & leak detector batteries

Report battery health; anything under 20% shows red on the dashboard, lands in the daily digest and auto-creates a "Byt batteri" chore (re-armed once the battery recovers).

- alias: "HomePlanner: smoke detector battery"
  trigger: [{ platform: time_pattern, hours: "/12" }]
  action:
    - service: rest_command.homeplanner_device
      data:
        payload: >-
          {"entity_id": "smoke_hall", "name": "Rökdetektor hallen",
           "kind": "smoke", "battery_pct": {{ states('sensor.smoke_hall_battery') }}}

🏷️ NFC tags & chores

  1. Register a tag on the Chores & NFC tab and link it to a chore (and optionally a default member).
  2. Any scan logs the chore and awards the points:
rest_command:
  homeplanner_nfc:
    url: "https://YOUR-APP/api/v1/nfc/scan"
    method: POST
    headers: { X-API-Key: !secret homeplanner_api_key }
    content_type: "application/json"
    payload: "{{ payload }}"

# HA tag reader
- alias: "HomePlanner: tag scanned"
  trigger: [{ platform: tag }]
  action:
    - service: rest_command.homeplanner_nfc
      data:
        payload: '{"tag_id": "{{ trigger.tag_id }}"}'

Phone shortcuts work too — POST /api/v1/nfc/scan with the tag id. Chores can also be completed by name via /integrations/home-assistant/chore-event ({"chore": "Diska", "member": "Anna"}) from buttons or voice.

Who gets the points?

An NFC chip can't tell who tapped it — it only carries an id. Attribution happens one of two ways:

  • A default member on the tag. When you register a tag you link it to a chore and (optionally) a member to credit — every scan of that tag credits that person. Best for "one tag per person" (e.g. each kid has their own tag for the same chore).
  • A member named in the scan. Pass "member" in the scan payload (id or name) to credit whoever actually did it — this overrides the tag default. Use it when the scanner knows the person (a per-user phone shortcut, or an HA automation that maps the scanning phone to a family member).

The scan itself is authenticated by the household API key, which identifies the household, not the individual — so one of the two above must supply the person. A scan with no default and no member is rejected.

🛒 Food, recipes & barcode scanning

The Food tab keeps the family's favorite recipes (with links) and a food inventory by location (Kyl/Frys/Skafferi).

Scanning barcodes

  1. Tap 📷 Scan barcode and point the camera at an EAN code. Scanning uses the browser's built-in detector — Chrome/Edge on desktop and Android work; on iPhone use Enter EAN and type the digits instead.
  2. An item you already have gets +1 quantity; a new item is looked up on Open Food Facts (name, brand, package size, photo) and added with quantity 1.
  3. Not found online? The item is still added as Vara <EAN> — rename it in the list.

Price checking

Swedish grocery stores don't offer public product APIs, so every inventory item links to a ready-made Willys and Coop search with the item name — one tap to compare prices.

Use-it-up reminders

Items with a bäst före date show red when 3 days remain, and the daily digest lists food to use up.

API: POST /api/v1/food/scan ({"barcode": "7310865004703"}), GET /api/v1/food/lookup/{ean}, plus normal CRUD on /api/v1/food and /api/v1/recipes — see API docs.

📅 Family calendar (iCal)

Chores due, contract renewals, loan rate-binding ends, warranty expirations and renovation end-of-life dates — one feed:

https://YOUR-APP/api/v1/calendar.ics?token=hp_your_key_here
  • Google Calendar: Settings → Add calendar → From URL.
  • Apple Calendar: File → New Calendar Subscription.

🔔 Alerts: Discord & email

Every user picks their own channel on Account → Alerts. The daily digest (07:00 UTC) contains chores due, renewals within 14 days, expiring warranties, leak/radon/battery warnings and — on your chosen day of month — the "time to pay" cost split.

Discord per user

  1. In your Discord server: channel → Edit → Integrations → Webhooks → New webhook → copy URL.
  2. Paste it on Account → Alerts → Discord webhook.
  3. Admins can set a bot name and a fallback webhook in the admin panel.

Email admin setup

A superadmin configures the provider in the admin panel → Mail settings: Resend (API key), MailChannels, or a custom JSON endpoint. Mail also powers invites, password resets, email verification and property-transfer notifications.

💳 Billing (PayPal) optional · superadmin

  1. Create a PayPal app + subscription plan, then set the secrets: PAYPAL_CLIENT_ID, PAYPAL_CLIENT_SECRET, PAYPAL_PLAN_ID, PAYPAL_WEBHOOK_ID (wrangler secret put …).
  2. Point a PayPal webhook at /api/v1/billing/webhook/paypal.
  3. Flip billing on in the admin panel → instance settings; trials, per-household exemptions and comps are managed there too.

📖 API reference

Everything on this page is plain API calls — the interactive reference lives at /docs (generated from openapi.json). Authenticate with Authorization: Bearer <jwt> or X-API-Key.