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.
Device triggers	Published	Ten of the bus events are offered in the visual automation editor on Home Keeper's own appliance and task devices.
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 and number — usage surfaces, as opposed to the admin-only panel.
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.
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.
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	Two authenticated routes for document and part-file upload and download — a binary can't ride a service call, so this is the one non-service mutation path.
Sidebar panel	Internal	The admin-only management UI, 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.
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.
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.
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).
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.
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.
source	Source	object	Opaque provenance owned by the integration that created the task. 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.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.

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). Ignored when Until is set.
until	Until	datetime	Defer the task to this exact date and time instead of a number of hours. Setting this leaves Hours unused.
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.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 a consumable

Link a task to an appliance consumable/part so completing it consumes one spare from the part's stock and fires a low-stock event at the reorder threshold. Omit asset_id and part_id to clear the link.

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	text	The id of the appliance the consumable belongs to. Omit to unlink. Its name works too. The panel shows the id.
part_id	Part name or ID	text	The id of the consumable/part to link. Omit to unlink. Its name works too. The panel shows the id.

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

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

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.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)	Which sections to export. Both by default.

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 (required)	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.
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.

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

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.

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. The recipe materializes one managed sensor task per entity matched by target integration and entity filters, with Jinja-templated 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. 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	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_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_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 recipe 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 recipe changes	declarative_companion	match_count
home_keeper_declarative_companion_removed	a declarative-companion recipe is deleted, along with every task it materialized	declarative_companion	match_count
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_skip_updated, home_keeper_task_skip_removed, home_keeper_task_overdue, home_keeper_task_due_soon.

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

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

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

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 recipe was seeded from, or None for one written by hand

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.

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

One list entity for the whole integration, named directly.

calendar

One list entity for the whole integration, named directly.

button

Entities: {task_name}Mark done (mark_done).

sensor

Entities: {task_name}Next due (next_due), Tasks (all_tasks), {profile} tasks (profile_tasks).

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

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

number

Entities: {part} spares (part_spares).

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

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
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.
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.
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}
unknown_area	Unknown area: {area_id}
unknown_document	Unknown document: {document_id}
unknown_part	Unknown appliance or part: {asset_id} / {part_id}
unknown_part_file	Unknown part or no attached file.
upload_requires_user	Uploads must come from a signed-in user. This request was authenticated by a shared link, which can only read files.