API reference
Every surface an integration or automation can build on, generated from the shipping code. Labels and descriptions are the same strings Home Assistant shows in its own dialogs, so this page and the UI never disagree.
New to this? Start with the integration guide, which walks through pushing a task and reacting to its completion.
Surface coverage
Every kind of integration surface Home Assistant offers, and where Home Keeper stands on it. The rows that say not applicable or deferred are the useful ones: a list of what exists cannot tell you what is missing.
| Surface | Status | Notes |
|---|---|---|
| Actions (services) | Published | Every operation that mutates or exports Home Keeper data ships as a home_keeper.* service — the interoperability contract. |
| Bus events | Published | Every observable state change fires a home_keeper_<noun>_<verb> event, built by a pure function so the shipped payload and the documented one are the same object. |
| Triggers | Published | Each bus event with a payload is also a Home Keeper trigger (trigger: home_keeper.<event>) in the automation editor. A task, part or appliance trigger takes a target: an entity, device, area, floor or label. |
| Device triggers | Published | Ten of the bus events are offered as device triggers on Home Keeper's own appliance and task devices. Automations that use them keep working. |
| Device conditions | Not applicable | Task state is readable from the per-task sensor and binary_sensor, so a separate condition platform would add a second way to ask one question. |
| Device actions | Not applicable | The services cover every device-scoped operation and take a task or asset id directly. |
| Entity platforms | Published | todo, calendar, sensor, binary_sensor, button, number and event — usage surfaces, next to the panel. |
| Event entities | Published | 1 global event entity gets each bus event with a payload, for history and for the Event received trigger. home_keeper_register_companions is not mirrored: it asks companions to announce themselves and is not a state change. |
| Entity attributes | Published | The per-task sensors carry enough state that an automation rarely needs to call a service to read anything. |
| Config entry options | Published | Three surfaces write them — the options flow, the set_options service and the panel — through one merge path. |
| Config flow | Published | A single-instance UI setup flow with an options flow; no YAML configuration. |
| Errors | Published | User-facing failures raise localized exceptions keyed into strings.json, so they read in the user's language wherever they surface. |
| Diagnostics | Published | Config entry and device diagnostics download from the integration page, with serial numbers, notes and completion detail redacted. |
| Companion discovery | Published | Integrations that work with Home Keeper self-register via register_companion, or are detected from a curated catalog. |
| Companion panel tabs | Published | A companion integration adds a tab to the panel with the in-process Python API panel_tabs.async_register_panel_tab; the registry is memory for the Home Assistant run, not store state, so a change fires no bus event. |
| Test helper | Published | home_keeper.testing ships a fake store built on the same event builders, so an integrator tests against the shipped payloads. |
| Lovelace card | Published | The dashboard task card registers itself as a Lovelace resource on storage-mode installs. |
| Data portability | Published | Tasks and appliances move as one YAML document with a published JSON Schema, which export_data writes and import_data reads, upserting on a stated primary key. A companion with the import_export capability adds its own section, and a bundle (a zip file) adds the uploaded files and the settings. |
| WebSocket commands | Internal | A latency optimization for the panel that delegates to the same store methods; build on the services instead, which are the contract. |
| HTTP views | Internal | Authenticated routes for document, part-file and task-photo upload and download, and for the bundle download and the import upload — a binary can't ride a service call, so these are the non-service paths. |
| Sidebar panel | Internal | The management UI, open to every user, with its write controls shown only to an admin. It is served from a static path; it is a client of the surfaces above, not one itself. |
| Dispatcher signals | Deferred | SIGNAL_TASK_CONTRIBUTION is reserved for a future upsert/reconcile contribution API and is not connected to anything yet; SIGNAL_DECLARATIVE_SPECS_CHANGED is internal, between the store and the declarative-companion reconciler. |
| Intents | Deferred | Voice control would go through the intent platform; not built, and the services are reachable from a script in the meantime. |
| Repairs | Deferred | No repair issues are raised yet; problems surface as localized exceptions and log entries. |
| Conversation | Not applicable | Home Keeper exposes no conversation agent of its own. |
| Backup platform | Not applicable | State is one JSON document under .storage, which Home Assistant's own backup already covers. |
| Media source | Not applicable | Uploaded documents are served by the integration's own authenticated view, not browsable as media. |
Actions
Every operation that changes or exports Home Keeper data is a Home
Assistant action, so automations, scripts, voice assistants and other
integrations all reach it the same way. Guard each call with
hass.services.has_service("home_keeper", "<action>") so your
integration still works when Home Keeper isn't installed.
home_keeper.add_task
Add task
Create a new maintenance task or chore.
Can return a response
| Field | Label | Selector | Description |
|---|---|---|---|
name (required) | Name | text | Display name of the task. |
notes | Notes | text (multiline) | Optional free-text notes. Markdown is rendered in the Home Keeper panel. |
recurrence_type | Recurrence type | select (floating, fixed, one-off, triggered, sensor, use) | floating (measured from completion), fixed (anchored schedule), or one-off (do-once, uses a due date). Omit it and the type is inferred from the schedule fields you passed. A name on its own makes a one-off due today. |
interval | Interval | number (min 1) | Repeat every N units (floating) or steps (fixed). |
unit | Unit | select (days, weeks, months) | For floating tasks: days, weeks, or months. |
freq | Frequency | select (DAILY, WEEKLY, MONTHLY) | For fixed tasks: DAILY, WEEKLY, or MONTHLY. |
rrule | Rule | text | For fixed tasks: an iCalendar RRULE, such as FREQ=WEEKLY;BYDAY=TU,FR or FREQ=MONTHLY;BYDAY=1TU. Use it in place of freq and interval. COUNT and UNTIL are not allowed. |
anchor | Anchor | text | For fixed tasks: ISO datetime of the first occurrence (sets the time of day). |
due | Due date | text | For one-off tasks: ISO datetime the task is due. Optional. Defaults to now (due today). |
sensor | Sensor trigger | object | For sensor tasks: a mapping with the bound entity, entity_id, mode (usage, threshold or state), and the mode's fields. |
last_completed | Last completed | datetime | Optional 'last done' date. Seeds an initial completion so a floating task starts measured from this date (next due = last done + interval) instead of being due immediately. Omit for a task that has never been done. |
device_id | Device | device | Optional device to attach this task to. |
area_id | Area | area | Optional area to associate with this task. |
labels | Labels | label (multiple) | Optional Home Assistant labels to tag this task with. Used by the dashboard card's label filter (which also matches labels on the attached device or area). |
card_links | Card links | object | Appliance links to surface on this task's dashboard-card row: a list of (asset_id, entry_id) objects pointing at an appliance's document or metadata links. Usually set from the panel's task editor. |
task_chips | Task chips | object | Integration-provided metadata chips shown in the task list and dashboard card: a list of (label, icon?, url?) objects. Not user-editable in the panel. |
tag_id | Tag | text | Id of a Home Assistant tag (from the Tags panel) whose scan completes this task. Scanning it marks the task as done. |
require_tag_scan | Require tag scan | boolean | Only let the linked tag complete this task. Every other way of marking it done is refused. Needs a tag. |
snooze_hours | Snooze length | number (min 1, max 8760) | Hours that Snooze moves this task. The snooze dialog starts on this length, and the Snooze button on a notification uses it. Leave empty to use the usual lengths. |
active_season | Active season | object | Restrict this task to one or more date ranges each year. Outside the active windows the next due date moves to the nearest upcoming window start. Each object has start and end as MM-DD strings. Pass a list or a single object. Wrapping seasons (Nov through Mar) are supported. Null clears the season. |
enabled | Enabled | boolean | Disable or enable this task. A disabled task keeps its history and its settings, and its due date stays where it was. Home Keeper keeps it out of your reminders and your lists until you enable it again. |
source | Source | object | Opaque provenance owned by the integration that created the task. Home Keeper stores and echoes it verbatim and never inspects it. See docs/INTEGRATING.md. |
completion_detail | Completion detail | select (none, optional, required) | How much context to capture when this task is completed. none skips the prompt entirely, while optional offers the note/cost/photo/who fields and required makes them mandatory (see completion_required_fields). Panel-only capture prompt. |
completion_required_fields | Required completion fields | select (note, cost, photo, who) | Which completion-metadata fields the panel makes mandatory when completion detail is required: any of note, cost, photo, who. |
home_keeper.update_task
Update task
Update fields of an existing task.
| Field | Label | Selector | Description |
|---|---|---|---|
task_id (required) | Task name or ID | text | The id of the task to update. Its name works too. The panel shows the id. |
name | Name | text | New display name. |
notes | Notes | text (multiline) | New notes. Markdown is rendered in the Home Keeper panel. |
recurrence_type | Recurrence type | select (floating, fixed, one-off, triggered, sensor, use) | floating, fixed, or one-off (do-once). |
interval | Interval | number (min 1) | Repeat every N units/steps. |
unit | Unit | select (days, weeks, months) | days, weeks, or months (floating). |
freq | Frequency | select (DAILY, WEEKLY, MONTHLY) | DAILY, WEEKLY, or MONTHLY (fixed). |
rrule | Rule | text | For fixed tasks: an iCalendar RRULE, such as FREQ=WEEKLY;BYDAY=TU,FR or FREQ=MONTHLY;BYDAY=1TU. Use it in place of freq and interval. COUNT and UNTIL are not allowed. |
anchor | Anchor | text | ISO datetime of the first occurrence (fixed). |
due | Due date | text | ISO datetime the task is due (one-off). |
sensor | Sensor trigger | object | Sensor binding for a sensor task, entity_id, mode (usage, threshold or state), and the mode's fields (replaces the whole binding). |
device_id | Device | device | Device to attach this task to. |
area_id | Area | area | Area to associate with this task. |
labels | Labels | label (multiple) | Home Assistant labels to tag this task with (replaces the current set). Used by the dashboard card's label filter. |
card_links | Card links | object | Appliance links to surface on this task's dashboard-card row (replaces the current set): a list of (asset_id, entry_id) objects. Usually set from the panel's task editor. |
task_chips | Task chips | object | Integration-provided metadata chips (replaces the current set): a list of (label, icon?, url?) objects. See add_task for the full schema. |
tag_id | Tag | text | Id of the Home Assistant tag whose scan completes this task. Send an empty value to unlink it, which fails while a tag scan is required. |
require_tag_scan | Require tag scan | boolean | Only let the linked tag complete this task. Needs a tag. |
snooze_hours | Snooze length | number (min 1, max 8760) | Hours that Snooze moves this task. Send an empty value to use the usual lengths again. |
active_season | Active season | object | Restrict this task to one or more date ranges each year. Each object has start and end as MM-DD strings. Pass a list or a single object. Send null to clear the season. |
enabled | Enabled | boolean | Disable or enable this task. A disabled task keeps its history and its settings, and its due date stays where it was. Home Keeper keeps it out of your reminders and your lists until you enable it again. |
source | Source | object | Opaque provenance owned by the integration that created the task. Each namespace replaces the stored namespace of the same name. A namespace with the value null is removed. See docs/INTEGRATING.md. |
completion_detail | Completion detail | select (none, optional, required) | How much context to capture on completion: none, optional, or required (see add_task). Panel-only capture prompt. |
completion_required_fields | Required completion fields | select (note, cost, photo, who) | Which completion-metadata fields the panel makes mandatory when completion detail is required: any of note, cost, photo, who. |
home_keeper.delete_task
Delete task
Delete a task.
| Field | Label | Selector | Description |
|---|---|---|---|
task_id (required) | Task name or ID | text | The id of the task to delete. Its name works too. The panel shows the id. |
force | Force | boolean | Bypass deletion protection for a task managed by another integration. Use this to clean up a task whose managing integration was uninstalled or is misbehaving and can't remove it itself. |
home_keeper.delete_orphaned_tasks
Delete orphaned tasks
Delete every task that an integration manages when that integration is not loaded (removed, disabled or not set up). Admin-only. Returns the IDs of the deleted tasks under "deleted".
Admin only · Can return a response
Takes no fields.
home_keeper.complete_task
Complete task
Mark a task complete and advance its recurrence.
| Field | Label | Selector | Description |
|---|---|---|---|
task_id (required) | Task name or ID | text | The id of the task to complete. Its name works too. The panel shows the id. |
completed_at | Completed at | datetime | Optional completion timestamp (defaults to now). |
origin | Origin | text | Optional free-form marker echoed back in the home_keeper_task_completed event so a contributing integration can recognise and ignore the completion it triggered (loop prevention), and Home Keeper never interprets it. |
note | Note | text (multiline) | Optional free-form note recorded with this completion. |
cost | Cost | number (min 0) | Optional cost recorded with this completion (your HA currency). |
photo | Photo | text | Optional Home Assistant image-upload id to attach as the completion photo (the panel sets this when you upload from the completion dialog). |
who | Who | entity | Optional person who performed the task (a person entity id). |
reading | Meter reading | number | For a sensor task in usage or threshold mode, the bound sensor's value when the work was done. Omit it and Home Keeper reads the sensor live. Pass it explicitly when back-dating, because the meter has moved since. On a usage task it also becomes the new baseline. |
home_keeper.update_completion
Update completion
Amend the metadata (note, cost, photo, who) of an already-recorded completion, identified by its timestamp. Does not change the schedule or due date.
| Field | Label | Selector | Description |
|---|---|---|---|
task_id (required) | Task name or ID | text | The id of the task whose completion you are editing. Its name works too. The panel shows the id. |
ts (required) | Completion timestamp | text | The ISO timestamp (ts) of the completion entry to edit. |
note | Note | text (multiline) | New note (omit or leave blank to clear it). |
cost | Cost | number (min 0) | New cost (omit or leave blank to clear it). |
photo | Photo | text | New image-upload id (omit or leave blank to clear it). |
who | Who | entity | New person entity id (omit or leave blank to clear it). |
reading | Meter reading | number | New sensor reading for this completion (omit or leave blank to clear it). Only valid for a sensor task in usage or threshold mode. |
home_keeper.delete_completion
Delete completion
Remove one completion from a task's history (undo an accidental “done”), identified by its timestamp.
| Field | Label | Selector | Description |
|---|---|---|---|
task_id (required) | Task name or ID | text | The id of the task whose completion you are removing. Its name works too. The panel shows the id. |
ts (required) | Completion timestamp | text | The ISO timestamp (ts) of the completion entry to remove. |
origin | Origin | text | Optional free-form marker echoed back in the home_keeper_task_uncompleted event so a contributing integration can recognise and ignore the undo it triggered (loop prevention), and Home Keeper never interprets it. |
home_keeper.move_completion
Move completion
Re-timestamp an already-recorded completion (back-date or correct it), identified by its current timestamp. Unlike Update completion, this changes the completion's date/time and re-derives the task's last-completed and next-due dates from the result.
| Field | Label | Selector | Description |
|---|---|---|---|
task_id (required) | Task name or ID | text | The id of the task whose completion you are moving. Its name works too. The panel shows the id. |
old_ts (required) | Current completion timestamp | text | The ISO timestamp (ts) of the completion entry to move. |
new_completed_at (required) | New completed at | datetime | The new date/time to record the completion at. |
home_keeper.delete_archived_completion
Delete archived completion
Remove one completion from an appliance's archived task history, identified by the originating task id and completion timestamp.
Admin only
| Field | Label | Selector | Description |
|---|---|---|---|
asset_id (required) | Appliance name or ID | text | The id of the appliance whose archived history you are editing. Its name works too. The panel shows the id. |
task_id (required) | Task name or ID | text | The id of the original task the archived completion belongs to. Its name works too. The panel shows the id. |
ts (required) | Completion timestamp | text | The ISO timestamp (ts) of the archived completion to remove. |
home_keeper.trigger_task
Trigger task
Arm a condition-driven (triggered) task so it reads as due now. This is the owner-facing counterpart to Complete task (which clears it back to dormant). Idempotent. Only valid for triggered tasks.
| Field | Label | Selector | Description |
|---|---|---|---|
task_id (required) | Task name or ID | text | The id of the triggered task to arm. Its name works too. The panel shows the id. |
home_keeper.set_task_meter
Set task meter
Re-anchor a usage (meter) sensor task's baseline without recording a completion. Use it when the work was done before Home Keeper was watching, or when the bound meter itself was replaced or zeroed. Omit baseline to anchor to the sensor's current reading. Only valid for a sensor task in usage mode.
| Field | Label | Selector | Description |
|---|---|---|---|
task_id (required) | Task name or ID | text | The id of the usage sensor task to re-anchor. Its name works too. The panel shows the id. |
baseline | Baseline | number | The meter reading to count from. Leave empty to use the bound sensor's current reading. |
home_keeper.snooze_task
Snooze task
Defer a task's due date without recording a completion or advancing its recurrence.
| Field | Label | Selector | Description |
|---|---|---|---|
task_id (required) | Task name or ID | text | The id of the task to snooze. Its name works too. The panel shows the id. |
hours | Hours | number (min 1, max 8760) | How many hours to defer the task (defaults to 24). Do not set Hours and Until in the same call. |
until | Until | datetime | Defer the task to this exact date and time instead of a number of hours. Do not set Hours and Until in the same call. |
origin | Origin | text | Optional free-form marker echoed back in the home_keeper_task_snoozed event so a contributing integration can recognise and ignore the snooze it triggered (loop prevention), and Home Keeper never interprets it. |
home_keeper.skip_task
Skip task
Advance a task to its next occurrence without recording a completion. Home Keeper logs the skip separately from the completions, so it is never counted as a completion.
| Field | Label | Selector | Description |
|---|---|---|---|
task_id (required) | Task name or ID | text | The id of the task to skip. Its name works too. The panel shows the id. |
note | Note | text (multiline) | Why this occurrence was skipped. |
who | Who | text | Who decided to skip it. |
reading | Meter reading | number | The bound sensor's value at the moment of the skip, for a usage task. |
origin | Origin | text | Optional free-form marker echoed back in the home_keeper_task_skipped event so a contributing integration can recognise and ignore the skip it triggered (loop prevention), and Home Keeper never interprets it. |
home_keeper.set_due_today
Set task due today
Move a task's due date to now, whatever its periodic schedule says, without recording a completion or changing its recurrence.
| Field | Label | Selector | Description |
|---|---|---|---|
task_id (required) | Task name or ID | text | The id of the task to move. Its name works too. The panel shows the id. |
origin | Origin | text | Optional free-form marker echoed back in the home_keeper_task_due_today_set event so a contributing integration can recognise and ignore the change it triggered (loop prevention), and Home Keeper never interprets it. |
home_keeper.move_occurrence
Move one date
Move one date of a fixed task's schedule to a new date and time, and keep the other dates as they are. To undo a move, move the date back to its original time.
| Field | Label | Selector | Description |
|---|---|---|---|
task_id (required) | Task name or ID | text | The id of the task. Its name works too. The panel shows the id. |
occurrence (required) | Date | datetime | The date and time on the schedule to move. |
to (required) | New date | datetime | The new date and time. It must be in the future. |
origin | Origin | text | Optional free-form marker echoed back in the home_keeper_task_occurrence_moved event so a contributing integration can recognise and ignore the change it triggered (loop prevention), and Home Keeper never interprets it. |
home_keeper.update_skip
Update skip
Amend a recorded skip's detail, identified by its timestamp. The skip keeps its date, and the schedule of the task does not change.
| Field | Label | Selector | Description |
|---|---|---|---|
task_id (required) | Task name or ID | text | The id of the task whose skip you are editing. Its name works too. The panel shows the id. |
ts (required) | Skip timestamp | text | The ISO timestamp (ts) of the skip entry to edit. |
note | Note | text (multiline) | Why this occurrence was skipped. An empty value clears it. |
who | Who | text | Who decided to skip it. An empty value clears it. |
reading | Meter reading | number | The bound sensor's value at the moment of the skip, for a usage task. |
home_keeper.delete_skip
Delete skip
Remove a recorded skip, identified by its timestamp. Removal of the skip that last reset a usage meter restores that meter.
| Field | Label | Selector | Description |
|---|---|---|---|
task_id (required) | Task name or ID | text | The id of the task whose skip you are removing. Its name works too. The panel shows the id. |
ts (required) | Skip timestamp | text | The ISO timestamp (ts) of the skip entry to remove. |
home_keeper.move_skip
Move skip
Re-date a recorded skip, identified by its current timestamp. The date of the skip changes, and the schedule of the task does not.
| Field | Label | Selector | Description |
|---|---|---|---|
task_id (required) | Task name or ID | text | The id of the task whose skip you are moving. Its name works too. The panel shows the id. |
old_ts (required) | Current skip timestamp | text | The ISO timestamp (ts) of the skip entry to move. |
new_ts (required) | New date | datetime | The new date and time to record the skip at. |
home_keeper.set_task_consumable
Link task to consumables
Link a task to 1 or more appliance consumables or parts. Each completion takes the amount of each part from its stock. A part that drops to its reorder threshold fires a low-stock event. Send the parts list. Send an empty parts list to clear the links.
| Field | Label | Selector | Description |
|---|---|---|---|
task_id (required) | Task name or ID | text | The id of the task to link (or unlink). Its name works too. The panel shows the id. |
asset_id | Appliance name or ID (deprecated) | text | The appliance of the 1 part to link. An id or a name works. This field is deprecated and will be removed in a later release. Use parts instead. |
part_id | Part name or ID (deprecated) | text | The 1 part to link. Its name works too. Use parts in its place. This deprecated field goes away in a later release. |
quantity | Quantity (deprecated) | number (min 0.01) | How much of the part 1 completion takes. A later release removes this deprecated field. Put the quantity in parts instead. |
parts | Parts | object | The full list of parts that the task takes. Each item has asset_id and part_id, and can have a quantity. An id or a name works for both. The list replaces the links of the task. An empty list clears them. |
home_keeper.notify
Notify what's due
Send an actionable push notification for what's currently due: name a saved notification or profile, optionally overriding the notify target.
Can return a response
| Field | Label | Selector | Description |
|---|---|---|---|
notification | Notification | text | Name or id of a saved notification (uses its profile + delivery). |
profile | Profile | text | Name or id of a saved profile (filter) to send. |
target | Target | text (multiple) | Notify services to send to, overriding the profile. Must be companion-app services (e.g. mobile_app_phone) or persistent_notification. |
status | Status | select (overdue, due_soon, all, none) | Overrides the profile's own status for this call. Use overdue, due_soon or all to widen the filter. Use none to match no task, which sends the all-clear notification on demand. |
when_empty | When nothing matches | select (skip, all_clear) | What a call sends if the filter matches no task. Defaults to skip, so the call sends nothing. Set it to all_clear to send the all-clear notification instead. |
home_keeper.list_tasks
List tasks
Return all tasks as a response.
Returns a response
Takes no fields.
home_keeper.list_profiles
List profiles
Return the saved profiles (named task filters) as a response.
Returns a response
Takes no fields.
home_keeper.add_asset
Add appliance
Register an appliance/asset. By default Home Keeper creates a virtual device for it. Set kind to existing to attach metadata to a device from another integration.
Admin only
| Field | Label | Selector | Description |
|---|---|---|---|
name | Name | text | Display name (required for a new virtual device). |
kind | Kind | select (virtual, existing) | virtual (Home Keeper creates the device) or existing (attach to one). |
device_id | Device | device | Existing device to attach metadata to (required when kind is existing). |
area_id | Area | area | Optional area for the appliance. |
manufacturer | Manufacturer | text | Maker of the appliance. |
model | Model | text | Model name or number. |
serial_number | Serial number | text | Serial number (shown in the appliance's device-page info block). |
notes | Notes | text (multiline) | Optional free-text notes about the appliance. Markdown is rendered in the Home Keeper panel. |
cost | Cost | number (min 0) | Replacement cost. The appliance report totals it. |
documents | Documents | object | Manuals/warranties/receipts: a list of links or uploaded files. This service adds link documents (name + url). Upload files from the panel. |
icon | Icon | icon | Optional mdi icon (e.g. mdi:piano). |
metadata | Metadata | object | Free-form metadata entries (label, type text/link/date, value). A date with track:true also becomes a sensor. |
parts | Parts | object | Structured parts/wear items. Wear items with an interval drive a maintenance task. |
parent_asset_id | Parent appliance | text | Make this a subdevice of another appliance. Give its name or its id. |
related_device_ids | Related devices | device (multiple) | Other registry devices to associate with this appliance. |
home_keeper.update_asset
Update appliance
Update fields of an existing appliance/asset.
Admin only
| Field | Label | Selector | Description |
|---|---|---|---|
asset_id (required) | Appliance name or ID | text | The id of the asset to update. Its name works too. The panel shows the id. |
name | Name | text | New display name. |
device_id | Device | device | Re-target an existing-device asset. |
area_id | Area | area | Area for the appliance. |
manufacturer | Manufacturer | text | Maker of the appliance. |
model | Model | text | Model name or number. |
serial_number | Serial number | text | Serial number (shown in the appliance's device-page info block). |
notes | Notes | text (multiline) | New notes. Markdown is rendered in the Home Keeper panel. |
cost | Cost | number (min 0) | Replacement cost. The appliance report totals it. |
documents | Documents | object | Documents (links/files) on the appliance (see add_asset). |
icon | Icon | icon | Optional mdi icon (e.g. mdi:piano). |
metadata | Metadata | object | Free-form metadata entries (see add_asset). |
parts | Parts | object | Structured parts/wear items. Wear items with an interval drive a maintenance task. |
parent_asset_id | Parent appliance | text | Make this a subdevice of another appliance. Give its name or its id. |
related_device_ids | Related devices | device (multiple) | Other registry devices to associate with this appliance. |
home_keeper.update_managed_asset
Update managed appliance
Update the name and the part list of an appliance that another integration manages. The stock fields on each part do not change.
Admin only
| Field | Label | Selector | Description |
|---|---|---|---|
asset_id (required) | Appliance name or ID | text | The id of the appliance to update. Its name works too. The panel shows the id. |
name | Name | text | A new name for the appliance. |
parts | Parts | object | The full part list, matched to the stored parts by id. Home Keeper keeps a part that is not in the list if the part has a stock count. |
home_keeper.delete_asset
Delete appliance
Delete an appliance/asset. Its virtual device (if any) is removed and tasks attached to it become standalone.
Admin only
| Field | Label | Selector | Description |
|---|---|---|---|
asset_id (required) | Appliance name or ID | text | The id of the asset to delete. Its name works too. The panel shows the id. |
force | Force | boolean | Delete an appliance that an integration protects. Use this only if that integration is gone. |
home_keeper.archive_asset
Archive appliance
Hide an appliance/asset from the default view without deleting its data. Its device, entities, and attached tasks are left untouched. restore_asset undoes it.
Admin only
| Field | Label | Selector | Description |
|---|---|---|---|
asset_id (required) | Appliance name or ID | text | The id of the asset to archive. Its name works too. The panel shows the id. |
home_keeper.restore_asset
Restore appliance
Undo archive_asset, returning an archived appliance to the default view.
Admin only
| Field | Label | Selector | Description |
|---|---|---|---|
asset_id (required) | Appliance name or ID | text | The id of the asset to restore. Its name works too. The panel shows the id. |
home_keeper.list_assets
List appliances
Return all appliances/assets as a response.
Returns a response
Takes no fields.
home_keeper.adjust_part_stock
Adjust part stock
Change a part's on-hand spare quantity by a signed delta (clamped at zero). Decimals are allowed. When a decrease reaches or crosses the reorder threshold, a low-stock event fires.
Admin only · Can return a response
| Field | Label | Selector | Description |
|---|---|---|---|
asset_id (required) | Appliance name or ID | text | The id of the appliance the part belongs to. Its name works too. The panel shows the id. |
part_id (required) | Part name or ID | text | The id of the part whose stock to adjust. Its name works too. The panel shows the id. |
delta (required) | Delta | number | Signed change to apply to the spare quantity, decimals allowed (e.g. -1 to consume a spare, -250 for 250 ml, 2 to restock). |
home_keeper.remove_part_file
Remove part file
Detach a part's attached file (receipt/spec sheet/photo), deleting its on-disk blob. Upload/replace a file from the panel. This service handles removal only.
Admin only
| Field | Label | Selector | Description |
|---|---|---|---|
asset_id (required) | Appliance name or ID | text | The id of the appliance the part belongs to. Its name works too. The panel shows the id. |
part_id (required) | Part name or ID | text | The id of the part whose file to remove. Its name works too. The panel shows the id. |
home_keeper.add_asset_document
Add appliance document
Attach a link document (manual/warranty/receipt) to an appliance. Upload files from the panel. This service handles links only.
Admin only
| Field | Label | Selector | Description |
|---|---|---|---|
asset_id (required) | Appliance name or ID | text | The id of the appliance to attach the document to. Its name works too. The panel shows the id. |
document (required) | Document | object | The document to add is an object with name and url. |
home_keeper.remove_asset_document
Remove appliance document
Detach a document from an appliance. An uploaded file's stored copy is deleted from disk too.
Admin only
| Field | Label | Selector | Description |
|---|---|---|---|
asset_id (required) | Appliance name or ID | text | The id of the appliance the document belongs to. Its name works too. The panel shows the id. |
document_id (required) | Document name or ID | text | The id of the document to remove. Its name works too. The panel shows the id. |
home_keeper.update_asset_document
Update appliance document
Edit an existing document on an appliance: rename it, or (for link documents) change its URL. Uploaded file documents can only be renamed.
Admin only
| Field | Label | Selector | Description |
|---|---|---|---|
asset_id (required) | Appliance name or ID | text | The id of the appliance the document belongs to. Its name works too. The panel shows the id. |
document_id (required) | Document name or ID | text | The id of the document to edit. Its name works too. The panel shows the id. |
changes (required) | Changes | object | The fields to change are an object with an optional name and (for link documents) an optional url. |
home_keeper.sign_document_url
Sign document URL
Mint a short-lived URL (no auth header needed) an external caller can fetch the file document's bytes from, e.g. an MCP-connected agent.
Returns a response
| Field | Label | Selector | Description |
|---|---|---|---|
asset_id (required) | Appliance name or ID | text | The id of the appliance the document belongs to. Its name works too. The panel shows the id. |
document_id (required) | Document name or ID | text | The id of the document to sign a URL for. Its name works too. The panel shows the id. |
home_keeper.sign_part_file_url
Sign part file URL
Mint a short-lived URL (no auth header needed) an external caller can fetch a part's attached file bytes from, e.g. an MCP-connected agent.
Returns a response
| Field | Label | Selector | Description |
|---|---|---|---|
asset_id (required) | Appliance name or ID | text | The id of the appliance the part belongs to. Its name works too. The panel shows the id. |
part_id (required) | Part name or ID | text | The id of the part whose attached file to sign a URL for. Its name works too. The panel shows the id. |
home_keeper.remove_task_photo
Remove task photo
Remove a photo from a task and delete its file. Add photos in the panel. A service call cannot send a file.
| Field | Label | Selector | Description |
|---|---|---|---|
task_id (required) | Task name or ID | text | The id of the task that has the photo. Its name works too. The panel shows the id. |
photo_id (required) | Photo ID | text | The id of the photo. The list_tasks service gives it in the photos of the task. |
home_keeper.set_task_photo_cover
Set task photo cover
Make a photo the cover of its task. The cover is the first photo. It shows on the task list, the task page and the completion dialog.
| Field | Label | Selector | Description |
|---|---|---|---|
task_id (required) | Task name or ID | text | The id of the task that has the photo. Its name works too. The panel shows the id. |
photo_id (required) | Photo ID | text | The id of the photo. The list_tasks service gives it in the photos of the task. |
home_keeper.sign_task_photo_url
Sign task photo URL
Mint a short-lived URL (no auth header needed) that gives the bytes of a task photo. Use it to show the photo in a notification.
Returns a response
| Field | Label | Selector | Description |
|---|---|---|---|
task_id (required) | Task name or ID | text | The id of the task that has the photo. Its name works too. The panel shows the id. |
photo_id (required) | Photo ID | text | The id of the photo. The list_tasks service gives it in the photos of the task. |
thumbnail | Thumbnail | boolean | Sign the URL of the small copy, at most 256 pixels on its long side. |
home_keeper.export_appliance_report
Export appliance report
Return the appliance report as a response (one row per appliance plus totals), with a ready-to-save CSV under the "csv" key.
Admin only · Returns a response
Takes no fields.
home_keeper.export_data
Export data
Return every task and appliance as one portable document, with the same document as a ready-to-save YAML file under the "yaml" key.
Admin only · Returns a response
| Field | Label | Selector | Description |
|---|---|---|---|
include | Include | select (appliances, tasks, settings) | Which sections to export: appliances, tasks, settings or a companion domain. All by default. |
kind | Kind | select (data, bundle) | "data" returns the YAML document. "bundle" writes a zip file with the uploaded files and the settings to the home_keeper_exports folder, and returns its path. |
home_keeper.import_data
Import data
Read a portable document and create or update the tasks and appliances in it. The whole document is checked first, so a document with an error writes nothing.
Admin only · Returns a response
| Field | Label | Selector | Description |
|---|---|---|---|
document | Document | object | The document to read, in the shape export_data returns. Give it as a mapping, or as the whole file in one string. |
bundle | Bundle | text | The name of a bundle file in the home_keeper_exports folder. Use it in place of the document. |
dry_run | Preview only | boolean | Check the document and report what would change, without writing anything. |
match | Match | select (auto, none) | How to find the record a document record refers to. "auto" matches on id, then external_id, then name. "none" creates every record. |
include_settings | Include settings | boolean | Also import the profiles, the notifications and the options of the document. |
home_keeper.set_options
Set options
Update Home Keeper's integration options: the same settings as the panel's Settings tab and the options flow. Only the fields you pass change.
Admin only
| Field | Label | Selector | Description |
|---|---|---|---|
sync_problem_sensors | Sync problem sensors as tasks | boolean | |
one_off_retention_days | One-off retention (days) | number (min 0, max 3650) | Auto-delete a completed one-off task this many days after completion. 0 keeps them forever. |
shopping_list_entity | Shopping list | entity | An existing to-do list to sync auto-buy reminders onto. Ticking an item off there completes the Home Keeper reminder and restocks the part. Leave empty to turn the sync off. |
shopping_line_style | Shopping list line text | select (with_verb, product_only) | How a buy reminder reads on the shopping list. with_verb (the default) shows the reminder name, such as "Buy fabric softener". product_only shows only the part name. |
due_time_mode | Due time | select (completion, set_time) | When a task that repeats after each completion is due. completion (the default) keeps the time of the last completion, snooze or skip. set_time makes it due at due_time on its due date. |
due_time | Set due time | time | The local time of day (HH:MM) for set_time. The default is 08:00. |
problem_sensor_exclude_entities | Excluded sensors | entity (multiple) | |
problem_sensor_exclude_devices | Excluded devices | device (multiple) | |
problem_sensor_exclude_areas | Excluded areas | area (multiple) | |
problem_sensor_exclude_labels | Excluded labels | label (multiple) | |
dismissed_companions | Dismissed companions | text (multiple) | Glue integration domains to hide from the Settings → Companions "Suggested" list. Dismissing only silences a suggestion. A connected pairing is always shown. |
hidden_panel_tabs | Hidden panel tabs | text (multiple) | The IDs of the companion tabs that the panel does not show. |
cost_windows | Spend windows (days) | object | The windows for the maintenance spend totals, in days. 1 to 4 numbers from 1 to 3650. Each window gets a sensor. |
cost_summary_panel | Show spend in the panel | boolean | Show the spend totals above the task list in the panel. |
task_device_entities | Enable task entities on device pages | boolean | Enable the Mark done button and the next-due and overdue sensors that each task adds to its device page. Off disables them and keeps their entity ids. |
home_keeper.register_companion
Register companion
Announce another integration that works with Home Keeper so it appears in the panel's Settings → Companions section. Home Keeper stores the descriptor verbatim and never imports the companion.
Admin only · Can return a response
| Field | Label | Selector | Description |
|---|---|---|---|
domain (required) | Domain | text | The companion integration's domain. |
name (required) | Name | text | Display name shown in the Companions list. |
icon | Icon | icon | An mdi icon for the row. |
description | Description | text | One line describing what the companion does with Home Keeper. |
config_entry_id | Config entry id | text | The companion's config entry id, so the panel's "Configure" button can deep-link to its options page. |
docs_url | Docs URL | text | A link to the companion's documentation. |
capabilities | Capabilities | text (multiple) | Free-form capability tags (e.g. care_schedules, battery_replacement). |
home_keeper.list_companions
List companions
Return the merged companion list (self-registered integrations plus detected upstreams whose glue isn't installed yet) as a response.
Returns a response
Takes no fields.
home_keeper.add_declarative_companion
Add declarative companion
Register a declarative companion. It makes one managed sensor task for each entity that its target integration and entity filters match, with a Jinja template for the task name and notes. Admin-only.
Admin only · Returns a response
Takes no fields.
home_keeper.update_declarative_companion
Update declarative companion
Update fields of a stored declarative-companion spec by id. A change to the task labels adds and removes those labels on the tasks that the companion already made. Admin-only.
Admin only · Returns a response
| Field | Label | Selector | Description |
|---|---|---|---|
id (required) | Companion id | text | The spec's stable uuid, from list_declarative_companions. |
home_keeper.delete_declarative_companion
Delete declarative companion
Remove a declarative-companion spec and every managed task it materialized. Admin-only.
Admin only
| Field | Label | Selector | Description |
|---|---|---|---|
id (required) | Companion id | text | The spec's stable uuid, from list_declarative_companions. |
home_keeper.list_declarative_companions
List declarative companions
Return every stored declarative-companion spec as a response.
Returns a response
Takes no fields.
Events
Home Keeper fires a bus event for every observable state change. Names
follow home_keeper_<noun>_<verb>. For when each one fires in context —
edge triggering, what a restart replays, worked automations — see the
events guide.
| Event | Fires when | Payload | Adds |
|---|---|---|---|
home_keeper_task_created | a task is created, from the panel, a service, a contributing integration, or as a wear-part task generated from an appliance | task | |
home_keeper_task_updated | a task actually changes, including a photo added, removed or made the cover | task | changed_fields |
home_keeper_task_deleted | a task is removed, directly or because its appliance or part was | task | |
home_keeper_task_completed | a task is completed from any surface: the to-do checkbox, a device button, a tag scan, or complete_task | task | completed_at, origin, note, cost, photo, who, reading |
home_keeper_task_uncompleted | a completion is undone and next_due is re-derived; undoing a timestamp that isn't in the history changes nothing and fires nothing | task | ts, origin |
home_keeper_task_completion_updated | a recorded completion's detail is edited after the fact; the schedule is untouched | task | ts, meter_baseline |
home_keeper_task_triggered | a condition-driven or sensor-based task is armed, moving from dormant to due-now | task | |
home_keeper_task_snoozed | a task's due date is deferred without recording a completion; only next_due moves, the recurrence is untouched | task | snoozed_until, origin |
home_keeper_task_skipped | a task is advanced to its next occurrence without recording a completion; the skip itself is logged, and a usage task's meter is reset | task | ts, origin |
home_keeper_task_due_today_set | a task's due date is moved to now without recording a completion; only next_due moves, the recurrence is untouched — the mirror of a snooze | task | origin |
home_keeper_task_occurrence_moved | one date of a fixed task's schedule moves, or a move is undone; the other dates of the schedule do not change | task | occurrence, to, previous_to, origin |
home_keeper_task_skip_updated | a recorded skip's detail or date is edited after the fact; the schedule is untouched | task | ts, meter_baseline |
home_keeper_task_skip_removed | a recorded skip is undone; a usage task's meter returns to the baseline the skip replaced | task | ts |
home_keeper_task_overdue | a task passes its due date, at most once per due date while HA runs | task | days_overdue |
home_keeper_task_due_soon | a task enters the three-day due-soon window, at most once per due date | task | due_in_hours |
home_keeper_task_overdue_resolved | a task that announced overdue is no longer overdue: completed, skipped, snoozed, moved, disabled or cleared by its sensor; once per overdue event | task | overdue_since, days_overdue |
home_keeper_part_low_stock | a part's on-hand stock crosses down to its reorder threshold | stock | |
home_keeper_part_out_of_stock | a part's stock reaches zero; this wins over low stock on a single step | stock | |
home_keeper_part_restocked | a part's stock rises back above its reorder threshold | stock | |
home_keeper_asset_created | an appliance is created | asset | |
home_keeper_asset_updated | an appliance changes, including its documents, parts and archived history | asset | changed_fields |
home_keeper_asset_deleted | an appliance is removed | asset | |
home_keeper_asset_archived | an appliance is archived, hiding it without deleting its data | asset | |
home_keeper_asset_restored | an archived appliance is restored | asset | |
home_keeper_companion_connected | a companion integration newly becomes connected, by self-registering or by a known glue being detected installed | companion | |
home_keeper_companion_suggested | a curated upstream is newly detected installed while its glue isn't | companion | |
home_keeper_declarative_companion_added | a declarative companion is created; the tasks it materializes fire the ordinary task events on their own | declarative_companion | match_count |
home_keeper_declarative_companion_updated | a declarative companion changes | declarative_companion | match_count |
home_keeper_declarative_companion_removed | a declarative companion is deleted, along with every task it materialized | declarative_companion | match_count |
home_keeper_data_exported | export_data, its websocket twin or the bundle download writes an export, with the companion sections in it | data_transfer | |
home_keeper_data_imported | an import is applied; a dry run fires nothing. The records it writes also fire their own created and updated events | data_transfer | |
home_keeper_register_companions | Home Keeper has set up and asks companions to re-announce themselves by calling register_companion; carries no payload | none |
Home Keeper also listens for events it does not own:
| Event | Home Keeper's reaction |
|---|---|
tag_scanned | Home Assistant's own tag integration fired a scan; Home Keeper completes the task bound to that tag_id |
Payloads
Events sharing a payload shape are interchangeable in one automation template. Per-event additions from the table above merge onto these.
Task payload
Carried by home_keeper_task_created, home_keeper_task_updated, home_keeper_task_deleted, home_keeper_task_completed, home_keeper_task_uncompleted, home_keeper_task_completion_updated, home_keeper_task_triggered, home_keeper_task_snoozed, home_keeper_task_skipped, home_keeper_task_due_today_set, home_keeper_task_occurrence_moved, home_keeper_task_skip_updated, home_keeper_task_skip_removed, home_keeper_task_overdue, home_keeper_task_due_soon, home_keeper_task_overdue_resolved.
| Field | Type | Notes |
|---|---|---|
task_id | str | |
name | str | |
device_id | str | None | the task's registry device id, or None when it's a standalone task (its entities then live on a self-owned device) |
area_id | str | None | |
recurrence_type | str | floating / fixed / one-off / triggered / sensor / use |
next_due | str | None | ISO; None for a dormant triggered/sensor task or a completed one-off |
enabled | bool | |
labels | list[str] | HA label-registry ids attached to the task (empty when none) |
source | dict | None | opaque provenance, echoed verbatim |
managed_by | dict | None | well-known ownership block, or None |
task_chips | list[dict] | integration-provided metadata chips; each has label, optional icon (mdi: name) and optional url (http(s)://) |
tag_id | str | None | the HA tag whose scan completes the task, or None when none is linked |
active_season | list[dict] | None | the date ranges the task is scheduled in, each a {"start": "MM-DD", "end": "MM-DD"} window, or None when it runs all year |
entity_id | str | None | the Home Keeper to-do list entity, so the logbook shows the event on it, or None before the entity is registered |
Stock payload
Carried by home_keeper_part_low_stock, home_keeper_part_out_of_stock, home_keeper_part_restocked.
| Field | Type | Notes |
|---|---|---|
asset_id | str | |
asset_name | str | |
device_id | str | None | |
part_id | str | |
part_name | str | |
part_number | str | |
vendor | str | |
stock | float | on-hand quantity; can be fractional |
reorder_at | float | the low-stock threshold |
unit | str | what the part counts itself in ("ml", "bottles"), or "" for whole spares |
source | dict | None | the appliance's opaque provenance |
managed_by | dict | None | the appliance's ownership block, or None |
Asset payload
Carried by home_keeper_asset_created, home_keeper_asset_updated, home_keeper_asset_deleted, home_keeper_asset_archived, home_keeper_asset_restored.
| Field | Type | Notes |
|---|---|---|
asset_id | str | |
asset_name | str | |
device_id | str | None | None until a virtual appliance's device is provisioned |
source | dict | None | opaque provenance, echoed verbatim |
managed_by | dict | None | well-known ownership block, or None |
Companion payload
Carried by home_keeper_companion_connected, home_keeper_companion_suggested.
| Field | Type | Notes |
|---|---|---|
domain | str | |
name | str | |
status | str | connected / suggested |
config_entry_id | str | None | the companion's config entry, for a connected companion |
upstream_domain | str | None | the detected upstream, for a catalog-suggested glue |
Declarative_companion payload
Carried by home_keeper_declarative_companion_added, home_keeper_declarative_companion_updated, home_keeper_declarative_companion_removed.
| Field | Type | Notes |
|---|---|---|
spec_id | str | |
name | str | |
enabled | bool | |
preset_id | str | None | the bundled preset the declarative companion was seeded from, or None for one written by hand |
Data_transfer payload
Carried by home_keeper_data_exported, home_keeper_data_imported.
| Field | Type | Notes |
|---|---|---|
kind | str | data (a YAML document) / bundle (a zip file) |
sections | dict | a count for each section: the number of records in an export; created / updated in an import, and for a companion section the counts that the companion returned |
Triggers
In the automation editor, Add trigger offers these by name, by target
and in its search. Each is 1 of the events above. A task, part or
appliance trigger takes a target: an entity, device, area, floor or label.
The trigger variables hold the bus event as trigger.event.
| Trigger | Shown as | Event | Target |
|---|---|---|---|
home_keeper.task_created | Task created | home_keeper_task_created | tasks |
home_keeper.task_updated | Task updated | home_keeper_task_updated | tasks |
home_keeper.task_deleted | Task deleted | home_keeper_task_deleted | tasks |
home_keeper.task_completed | Task completed | home_keeper_task_completed | tasks |
home_keeper.task_uncompleted | Completion removed | home_keeper_task_uncompleted | tasks |
home_keeper.task_completion_updated | Completion updated | home_keeper_task_completion_updated | tasks |
home_keeper.task_triggered | Task triggered | home_keeper_task_triggered | tasks |
home_keeper.task_snoozed | Task snoozed | home_keeper_task_snoozed | tasks |
home_keeper.task_skipped | Task skipped | home_keeper_task_skipped | tasks |
home_keeper.task_due_today_set | Task set due today | home_keeper_task_due_today_set | tasks |
home_keeper.task_occurrence_moved | Task occurrence moved | home_keeper_task_occurrence_moved | tasks |
home_keeper.task_skip_updated | Skip updated | home_keeper_task_skip_updated | tasks |
home_keeper.task_skip_removed | Skip removed | home_keeper_task_skip_removed | tasks |
home_keeper.task_overdue | Task became overdue | home_keeper_task_overdue | tasks |
home_keeper.task_due_soon | Task due soon | home_keeper_task_due_soon | tasks |
home_keeper.task_overdue_resolved | Task no longer overdue | home_keeper_task_overdue_resolved | tasks |
home_keeper.part_low_stock | Spare part low on stock | home_keeper_part_low_stock | parts |
home_keeper.part_out_of_stock | Spare part out of stock | home_keeper_part_out_of_stock | parts |
home_keeper.part_restocked | Spare part restocked | home_keeper_part_restocked | parts |
home_keeper.asset_created | Appliance added | home_keeper_asset_created | appliances |
home_keeper.asset_updated | Appliance updated | home_keeper_asset_updated | appliances |
home_keeper.asset_deleted | Appliance deleted | home_keeper_asset_deleted | appliances |
home_keeper.asset_archived | Appliance archived | home_keeper_asset_archived | appliances |
home_keeper.asset_restored | Appliance restored | home_keeper_asset_restored | appliances |
home_keeper.companion_connected | Companion connected | home_keeper_companion_connected | none |
home_keeper.companion_suggested | Companion suggested | home_keeper_companion_suggested | none |
home_keeper.declarative_companion_added | Declarative companion added | home_keeper_declarative_companion_added | none |
home_keeper.declarative_companion_updated | Declarative companion updated | home_keeper_declarative_companion_updated | none |
home_keeper.declarative_companion_removed | Declarative companion deleted | home_keeper_declarative_companion_removed | none |
home_keeper.data_exported | Data exported | home_keeper_data_exported | none |
home_keeper.data_imported | Data imported | home_keeper_data_imported | none |
Device triggers
On a Home Keeper device, Add automation → When offers these by name, so an automation can be built without knowing any event name. They are the same events as above, filtered to that one device. The triggers above replace them for a new automation.
| Trigger | Shown as | Event | Offered on |
|---|---|---|---|
task_completed | Task completed | home_keeper_task_completed | devices with tasks |
task_overdue | Task became overdue | home_keeper_task_overdue | devices with tasks |
task_due_soon | Task due soon | home_keeper_task_due_soon | devices with tasks |
task_created | Task created | home_keeper_task_created | devices with tasks |
task_updated | Task updated | home_keeper_task_updated | devices with tasks |
task_snoozed | Task snoozed | home_keeper_task_snoozed | devices with tasks |
task_skipped | Task skipped | home_keeper_task_skipped | devices with tasks |
part_low_stock | Spare part low on stock | home_keeper_part_low_stock | appliances |
part_out_of_stock | Spare part out of stock | home_keeper_part_out_of_stock | appliances |
part_restocked | Spare part restocked | home_keeper_part_restocked | appliances |
Entities
Task and appliance state is readable as ordinary entities, so most
automations never need to call an action to find something out. Entity
names are templates: Home Assistant fills {task_name} and {part} in
from the task or spare part the entity belongs to.
todo
Entities: Tasks (tasks).
calendar
Entities: Upcoming tasks (upcoming_tasks).
button
Entities: {task_name}Mark done (mark_done).
sensor
Entities: {task_name}Next due (next_due), Tasks (all_tasks), {profile} tasks (profile_tasks), Maintenance spend {days} days (spend_window), Maintenance spend all time (spend_all), Appliance purchases total (purchases_total).
State attributes:
| Field | Type | Notes |
|---|---|---|
task_id | str | next-due sensor |
task_name | str | next-due sensor |
recurrence_type | str | |
last_completed | str | None | ISO |
completions_count | int | |
last_completion_* | str | float | one key per recorded detail on the latest completion: last_completion_note / _cost / _photo / _who / _reading |
usage_* | float | str | meter progress on a usage sensor task: usage_target, usage_unit, usage_baseline, usage_consumed, usage_remaining, usage_percent, plus backstop_due; and the usage between past completions as usage_last_interval, usage_avg_interval, usage_min_interval and usage_max_interval, once two completions carry a reading; absent on every other task |
total | int | count sensors; every active scheduled task the profile scopes to, whatever its status tier |
overdue | int | count sensors |
due_soon | int | count sensors; due within the three-day window and not yet overdue, so a due-soon profile's state is overdue + due_soon |
due_today | int | count sensors; next_due falls on today's local calendar date |
next_due | str | None | count sensors; ISO, the earliest task in the profile's scope |
next_task_name | str | None | count sensors |
next_task_id | str | None | count sensors |
most_overdue_days | float | None | count sensors; days past due for the most overdue task, to one decimal place; absent value when nothing is overdue |
count | int | cost sensors; the completions with a cost in the total, or the appliances with a purchase cost |
first | str | None | all-time spend sensor; ISO, the oldest completion with a cost |
binary_sensor
Entities: {task_name}Overdue (overdue), {part} low stock (part_low_stock).
State attributes:
| Field | Type | Notes |
|---|---|---|
task_id | str | overdue sensor |
due_soon | bool | overdue sensor; within the three-day window |
next_due | str | None | overdue sensor; ISO |
asset_id | str | part low-stock sensor |
part_id | str | part low-stock sensor |
stock | float | part low-stock sensor |
reorder_at | float | part low-stock sensor |
unit | str | part low-stock sensor |
event
Entities: Events (home_keeper_events).
State attributes:
| Field | Type | Notes |
|---|---|---|
event_type | str | the bus event name without the home_keeper_ prefix, for example task_completed |
* | the bus event payload, without the keys in EVENT_ENTITY_DROPPED_FIELDS |
number
Entities: {part} spares (part_spares).
State attributes:
| Field | Type | Notes |
|---|---|---|
asset_id | str | |
part_id | str | |
reorder_at | float | None | the low-stock threshold, if set |
restock_quantity | float | None | what a Buy task adds when it is ticked, if set |
status | str | ok, low, out or untracked |
Config entry options
Readable and writable through the set_options action. The ones marked
Configure dialog also appear on the integration's options form; the rest
are edited in the Home Keeper panel.
| Option | Label | Where | Notes |
|---|---|---|---|
sync_problem_sensors | Sync problem sensors as tasks | Configure dialog | A synced task clears only when the source integration resolves the problem, not when you tap Done. Reminders for one offer Snooze in place of Mark done. |
allow_snooze | Panel | ||
allow_skip | Panel | ||
allow_due_today | Panel | ||
task_device_entities | Panel | ||
due_time_mode | Due time | Configure dialog | When a task that repeats after each completion is due. With a set time, the task is due at that time on its due date. A snooze also ends at that time. |
due_time | Set due time | Configure dialog | The local time of day that these tasks are due. Used only when the due time is a set time. |
one_off_retention_days | One-off retention (days) | Configure dialog | Auto-delete a completed one-off task this many days after it is completed. 0 keeps completed one-offs forever. |
shopping_list_entity | Shopping list | Configure dialog | Sync auto-buy reminders onto this to-do list. Ticking an item off there completes the Home Keeper reminder and restocks the part. Leave empty to turn the sync off. |
shopping_line_style | Shopping list line text | Configure dialog | How a buy reminder reads on the shopping list. Product only shows the part name without the verb, such as "Fabric softener" in place of "Buy fabric softener". |
profiles | Panel | ||
notifications | Panel | ||
problem_sensor_exclude_entities | Excluded sensors | Configure dialog | |
problem_sensor_exclude_devices | Excluded devices | Configure dialog | |
problem_sensor_exclude_areas | Excluded areas | Configure dialog | |
problem_sensor_exclude_labels | Excluded labels | Configure dialog | |
dismissed_companions | Panel | ||
hidden_panel_tabs | Panel | ||
cost_windows | Panel | ||
cost_summary_panel | Panel |
Errors
A rejected action raises a localized Home Assistant error. The key is stable; the message shown is in the user's language.
| Key | English message |
|---|---|
archived_completion_not_found | The appliance has no archived completion of {task_id} at {ts}. |
asset_ambiguous | Several appliances are named {name}. Use an id instead: {ids} |
asset_not_found | Asset not found: {asset_id} |
complete_failed | {error} |
declarative_companion_not_found | Declarative companion not found: {spec_id} |
document_ambiguous | Several documents are named {name}. Use an id instead: {ids} |
expected_multipart_upload | Expected a multipart upload. |
failed_to_store_file | Failed to store the file. |
file_too_large | File exceeds the {mb} MB limit. |
import_needs_document | Give a document or a bundle to import. |
import_not_text | The file is not a zip file or UTF-8 text. |
integration_not_loaded | Home Keeper isn't loaded right now. Please try again in a moment. |
invalid_asset | {error} |
invalid_completed_at | Invalid completed_at timestamp. |
invalid_declarative_companion | {error} |
invalid_task | {error} |
link_documents_only | Only link documents can be added here. |
meter_has_no_reading | The bound sensor has no numeric reading now. Add a baseline to the call. |
meter_requires_usage_task | Only a task with a usage sensor binding has a meter. |
no_file_in_upload | No file part in upload. |
no_instance_url | Could not determine a URL for this Home Assistant instance to build a signed document/part-file URL. Configure an internal or external URL under Settings > System > Network. |
notify_invalid_target | Notify target(s) {target} are not supported. Home Keeper sends actionable notifications through the companion app, so each target must be a {prefix}* notify service (or {persistent}). |
notify_no_targets | This notification has no target to send to. Add a "Send to" device in Settings → Notifications, or pass target: when calling the service. |
notify_notification_not_found | No notification named {notification}. |
notify_profile_not_found | No notification profile named {profile}. |
part_ambiguous | Several parts are named {name}. Use an id instead: {ids} |
profile_in_use | Home Keeper cannot delete these profiles: {profiles}. These notifications use them: {notifications}. Change or delete each notification, and then save again. |
task_ambiguous | Several tasks are named {name}. Use an id instead: {ids} |
task_not_found | Task not found: {task_id} |
unauthorized_transfer | Only an admin user can export or import Home Keeper data. |
unknown_area | Unknown area: {area_id} |
unknown_document | Unknown document: {document_id} |
unknown_export_section | Home Keeper cannot export these sections: {sections}. |
unknown_part | Unknown appliance or part: {asset_id} / {part_id} |
unknown_part_file | Unknown part or no attached file. |
unknown_task_photo | Unknown photo: {photo_id} |
upload_field_too_large | A form field of the upload is larger than the {kb} KB limit. |
upload_requires_user | Uploads must come from a signed-in user. This request was authenticated by a shared link, which can only read files. |