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 calling a service and reacting to its event.

Surface coverage

Every kind of integration surface Home Assistant offers, and the status of each one here. 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	Each operation that changes or exports library data is a home_keeper_library.* service.
Bus events	Published	Each state change fires a home_keeper_library_<noun>_<verb> event with a payload from a pure builder.
Device triggers	Not applicable	The library has 1 service device and no device per book for a trigger.
Device conditions	Not applicable	The sensors and the to-do lists give the state that a condition reads.
Device actions	Not applicable	The services cover each operation and take a book id directly.
Entity platforms	Published	A sensor platform with library and per-person counts, and a per-person todo list of the books to read.
Entity attributes	Published	The per-person sensors give the yearly goal, the pages and the titles.
Config entry options	Published	The currency of the prices and values of the copies. The Open Library account is in the entry data, not in the options.
Config flow	Published	A single-instance setup flow with a currency field. The options flow has a menu: the currency, and the Archive.org S3 keys of an Open Library account.
Websocket commands	Internal	The tab and the card read the state and call the twin of each service.
HTTP routes	Internal	A static path for the bundles, and the cover upload and cover views.
Diagnostics	Published	The config entry gives a diagnostics download, with names and notes redacted.
Reauth / reconfigure flows	Not applicable	The storage is local. The admin sets the Open Library keys again in the options flow, and a send with refused keys says so.
Repairs / issue registry	Published	An issue shows when Home Keeper is missing, not set up or too old for the tab.
Discovery	Not applicable	No device or service on the network is a library.
Home Keeper panel tab	Internal	The admin UI is a tab in the Home Keeper panel, registered through the Python API of Home Keeper.

Actions

Every operation that changes or exports 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_library", "<action>") so your integration still works when this one is not installed.

home_keeper_library.add_room

Add room

Add a room to the library.

Admin only · Can return a response

Field	Label	Selector	Description
name (required)	Name	text	The display name.
area_id	Area	area	The Home Assistant area of the room.
order	Order	number (min 0, max 100000)	The sort position. Lower comes first.

home_keeper_library.update_room

Update room

Change a room.

Admin only · Can return a response

Field	Label	Selector	Description
room_id (required)	Room	text	The ID of the room.
name	Name	text	The display name.
area_id	Area	area	The Home Assistant area of the room.
order	Order	number (min 0, max 100000)	The sort position. Lower comes first.

home_keeper_library.delete_room

Delete room

Delete a room. A room with bookcases needs force.

Admin only · Can return a response

Field	Label	Selector	Description
room_id (required)	Room	text	The ID of the room.
force	Force	boolean	Also delete the contents. The copies move to no shelf.

home_keeper_library.add_bookcase

Add bookcase

Add a bookcase to a room.

Admin only · Can return a response

Field	Label	Selector	Description
room_id (required)	Room	text	The ID of the room.
name (required)	Name	text	The display name.
note	Note	text (multiline)	A short note.
order	Order	number (min 0, max 100000)	The sort position. Lower comes first.

home_keeper_library.update_bookcase

Update bookcase

Change a bookcase or move it to another room.

Admin only · Can return a response

Field	Label	Selector	Description
bookcase_id (required)	Bookcase	text	The ID of the bookcase.
room_id	Room	text	The ID of the room.
name	Name	text	The display name.
note	Note	text (multiline)	A short note.
order	Order	number (min 0, max 100000)	The sort position. Lower comes first.

home_keeper_library.delete_bookcase

Delete bookcase

Delete a bookcase. A bookcase with shelves needs force.

Admin only · Can return a response

Field	Label	Selector	Description
bookcase_id (required)	Bookcase	text	The ID of the bookcase.
force	Force	boolean	Also delete the contents. The copies move to no shelf.

home_keeper_library.add_shelf

Add shelf

Add a shelf to a bookcase.

Admin only · Can return a response

Field	Label	Selector	Description
bookcase_id (required)	Bookcase	text	The ID of the bookcase.
name (required)	Name	text	The display name.
order	Order	number (min 0, max 100000)	The sort position. Lower comes first.

home_keeper_library.update_shelf

Update shelf

Change a shelf or move it to another bookcase.

Admin only · Can return a response

Field	Label	Selector	Description
shelf_id (required)	Shelf	text	The ID of the shelf. Empty for no shelf.
bookcase_id	Bookcase	text	The ID of the bookcase.
name	Name	text	The display name.
order	Order	number (min 0, max 100000)	The sort position. Lower comes first.

home_keeper_library.delete_shelf

Delete shelf

Delete a shelf. A shelf with copies needs force.

Admin only · Can return a response

Field	Label	Selector	Description
shelf_id (required)	Shelf	text	The ID of the shelf. Empty for no shelf.
force	Force	boolean	Also delete the contents. The copies move to no shelf.

home_keeper_library.lookup_isbn

Look up ISBN

Read the details of an ISBN from Open Library. The library stays the same.

Admin only · Returns a response

Field	Label	Selector	Description
isbn (required)	ISBN	text	An ISBN-10 or an ISBN-13.

home_keeper_library.add_book

Add book

Add a book. If a book has the same ISBN, the service returns that book.

Admin only · Can return a response

Field	Label	Selector	Description
title	Title	text	The title of the book.
subtitle	Subtitle	text	The subtitle of the book.
authors	Authors	text (multiple)	The authors, in order.
isbn	ISBN	text	An ISBN-10 or an ISBN-13.
isbn13	ISBN-13	text	The 13-digit ISBN.
isbn10	ISBN-10	text	The 10-digit ISBN.
publisher	Publisher	text	The publisher of the book.
published	Published	text	The publication date, usually a year.
pages	Pages	number (min 0, max 100000)	The number of pages.
language	Language	text	The language code, such as en.
subjects	Subjects	text (multiple)	The subjects of the book.
series	Series	text	The series name, or a name and a number.
description	Description	text (multiline)	The description of the book.
tags	Tags	text (multiple)	The tags of the book.
shared_notes	Shared notes	text (multiline)	Notes that each user can read, in Markdown.
needs_details	Needs details	boolean	Mark the book as incomplete.
lookup	Look up	boolean	Read the details from Open Library.

home_keeper_library.update_book

Update book

Change the details of a book.

Admin only · Can return a response

Field	Label	Selector	Description
book_id (required)	Book	text	The ID of the book.
title	Title	text	The title of the book.
subtitle	Subtitle	text	The subtitle of the book.
authors	Authors	text (multiple)	The authors, in order.
isbn	ISBN	text	An ISBN-10 or an ISBN-13.
isbn13	ISBN-13	text	The 13-digit ISBN.
isbn10	ISBN-10	text	The 10-digit ISBN.
publisher	Publisher	text	The publisher of the book.
published	Published	text	The publication date, usually a year.
pages	Pages	number (min 0, max 100000)	The number of pages.
language	Language	text	The language code, such as en.
subjects	Subjects	text (multiple)	The subjects of the book.
series	Series	text	The series name, or a name and a number.
description	Description	text (multiline)	The description of the book.
tags	Tags	text (multiple)	The tags of the book.
shared_notes	Shared notes	text (multiline)	Notes that each user can read, in Markdown.
needs_details	Needs details	boolean	Mark the book as incomplete.

home_keeper_library.delete_book

Delete book

Delete a book with its copies, reading status, loans and cover.

Admin only · Can return a response

Field	Label	Selector	Description
book_id (required)	Book	text	The ID of the book.

home_keeper_library.refresh_book

Update from Open Library

Fill the empty fields of a book from Open Library.

Admin only · Can return a response

Field	Label	Selector	Description
book_id (required)	Book	text	The ID of the book.

home_keeper_library.send_to_catalog

Send to Open Library

Add a book that Open Library does not have, with the connected Open Library account, then link the book.

Admin only · Can return a response

Field	Label	Selector	Description
book_id (required)	Book	text	The ID of the book.
fields	Fields	select (publisher, published, isbn)	Add publisher, published or isbn to send those details too. The title and the first author always go.
include_cover	Send cover	boolean	Also send the custom cover of the book.

home_keeper_library.link_catalog

Link to Open Library

Link a book to an Open Library edition and fill its empty fields.

Admin only · Can return a response

Field	Label	Selector	Description
book_id (required)	Book	text	The ID of the book.
record (required)	Edition	text	An edition key, such as OL123M, or the URL of the edition page.

home_keeper_library.skip_catalog

Skip Open Library

Remove a book from the list of books that are not on Open Library, or put it back.

Admin only · Can return a response

Field	Label	Selector	Description
book_id (required)	Book	text	The ID of the book.
skip	Skip	boolean	Turn off to put the book back in the list.

home_keeper_library.disconnect_catalog

Disconnect Open Library

Remove the keys of the Open Library account.

Admin only · Can return a response

Takes no fields.

home_keeper_library.scan_isbn

Scan ISBN

Add a scanned book to a shelf.

Admin only · Can return a response

Field	Label	Selector	Description
isbn (required)	ISBN	text	An ISBN-10 or an ISBN-13.
shelf_id	Shelf	text	The ID of the shelf. Empty for no shelf.
format	Format	select (hardcover, paperback, ebook, audiobook, other)	The format of the copy.
on_duplicate	If a copy exists	select (ask, add_copy, move, skip)	The action if the library has a copy of the book.

home_keeper_library.add_copy

Add copy

Add a copy of a book.

Admin only · Can return a response

Field	Label	Selector	Description
book_id (required)	Book	text	The ID of the book.
shelf_id	Shelf	text	The ID of the shelf. Empty for no shelf.
format	Format	select (hardcover, paperback, ebook, audiobook, other)	The format of the copy.
condition	Condition	select (new, fine, good, fair, poor)	The condition of the copy.
acquired	Acquired	date	The date when the copy was acquired.
acquired_from	Acquired from	text	The shop or the person.
price	Price	number (min 0, max 1000000000)	The price that was paid.
value	Value	number (min 0, max 1000000000)	The value of the copy now.
signed	Signed	boolean	The copy is signed.
first_edition	First edition	boolean	The copy is a first edition.
note	Note	text (multiline)	A short note.

home_keeper_library.update_copy

Update copy

Change a copy.

Admin only · Can return a response

Field	Label	Selector	Description
copy_id (required)	Copy	text	The ID of the copy.
shelf_id	Shelf	text	The ID of the shelf. Empty for no shelf.
format	Format	select (hardcover, paperback, ebook, audiobook, other)	The format of the copy.
condition	Condition	select (new, fine, good, fair, poor)	The condition of the copy.
acquired	Acquired	date	The date when the copy was acquired.
acquired_from	Acquired from	text	The shop or the person.
price	Price	number (min 0, max 1000000000)	The price that was paid.
value	Value	number (min 0, max 1000000000)	The value of the copy now.
signed	Signed	boolean	The copy is signed.
first_edition	First edition	boolean	The copy is a first edition.
note	Note	text (multiline)	A short note.

home_keeper_library.move_copy

Move copy

Move a copy to a shelf.

Admin only · Can return a response

Field	Label	Selector	Description
copy_id (required)	Copy	text	The ID of the copy.
shelf_id	Shelf	text	The ID of the shelf. Empty for no shelf.

home_keeper_library.delete_copy

Delete copy

Delete a copy.

Admin only · Can return a response

Field	Label	Selector	Description
copy_id (required)	Copy	text	The ID of the copy.

home_keeper_library.set_cover

Set cover

Set the cover of a book.

Admin only · Can return a response

Field	Label	Selector	Description
book_id (required)	Book	text	The ID of the book.
kind (required)	Cover type	select (openlibrary, custom, none)	The source of the cover.
file_id	File ID	text	The ID from the cover upload.

home_keeper_library.set_reading

Set reading status

Set the reading status of a book for a person. A non-admin user can set only their own status.

Open, for the caller's own person · Can return a response

Field	Label	Selector	Description
book_id (required)	Book	text	The ID of the book.
person_id	Person	text	The ID of the Home Assistant person.
status	Status	select (want, reading, read, dnf, none)	The reading status.
rating	Rating	number (min 1, max 5)	A rating from 1 to 5.
page	Page	number (min 0, max 100000)	The current page.
started	Started	date	The start date.
finished	Finished	date	The date when the book was finished.
read_count	Read count	number (min 0, max 100000)	The number of times that the book was read.
private_notes	Private notes	text (multiline)	Notes that only the person can read.

home_keeper_library.lend_book

Lend book

Lend a copy to another person.

Admin only · Can return a response

Field	Label	Selector	Description
copy_id (required)	Copy	text	The ID of the copy.
party (required)	Other person	text	The name of the other person of the loan.
started	Started	date	The start date.
due	Due	date	The due date.
note	Note	text (multiline)	A short note.
add_task	Add task	boolean	Add a Home Keeper task on the due date.

home_keeper_library.borrow_book

Add borrowed book

Record a book that a person borrowed.

Admin only · Can return a response

Field	Label	Selector	Description
book_id	Book	text	The ID of the book.
isbn	ISBN	text	An ISBN-10 or an ISBN-13.
title	Title	text	The title of the book.
authors	Authors	text (multiple)	The authors, in order.
party (required)	Other person	text	The name of the other person of the loan.
started	Started	date	The start date.
due	Due	date	The due date.
note	Note	text (multiline)	A short note.
add_task	Add task	boolean	Add a Home Keeper task on the due date.
person_id (required)	Person	text	The ID of the Home Assistant person.
format	Format	select (hardcover, paperback, ebook, audiobook, other)	The format of the copy.

home_keeper_library.return_loan

Return loan

Record the return of a loan.

Admin only · Can return a response

Field	Label	Selector	Description
loan_id (required)	Loan	text	The ID of the loan.
returned	Returned	date	The return date. The default is today.

home_keeper_library.update_loan

Update loan

Change a loan.

Admin only · Can return a response

Field	Label	Selector	Description
loan_id (required)	Loan	text	The ID of the loan.
party	Other person	text	The name of the other person of the loan.
started	Started	date	The start date.
due	Due	date	The due date.
note	Note	text (multiline)	A short note.
format	Format	select (hardcover, paperback, ebook, audiobook, other)	The format of the copy.

home_keeper_library.delete_loan

Delete loan

Delete a loan and its Home Keeper task.

Admin only · Can return a response

Field	Label	Selector	Description
loan_id (required)	Loan	text	The ID of the loan.

home_keeper_library.add_to_wishlist

Add to wishlist

Put a book on the wishlist of a person.

Admin only · Can return a response

Field	Label	Selector	Description
book_id	Book	text	The ID of the book.
isbn	ISBN	text	An ISBN-10 or an ISBN-13.
title	Title	text	The title of the book.
authors	Authors	text (multiple)	The authors, in order.
person_id (required)	Person	text	The ID of the Home Assistant person.
buy	Buy	boolean	Put the book on the wishlist to-do list of the person.

home_keeper_library.update_wishlist

Update wishlist

Change a wishlist entry.

Admin only · Can return a response

Field	Label	Selector	Description
book_id (required)	Book	text	The ID of the book.
buy	Buy	boolean	Put the book on the wishlist to-do list of the person.
person_id	Person	text	The ID of the Home Assistant person.

home_keeper_library.remove_from_wishlist

Remove from wishlist

Take a book off the wishlist.

Admin only · Can return a response

Field	Label	Selector	Description
book_id (required)	Book	text	The ID of the book.

home_keeper_library.got_wishlist_book

Got wishlist book

Add a copy of a wishlist book and take it off the wishlist.

Admin only · Can return a response

Field	Label	Selector	Description
book_id (required)	Book	text	The ID of the book.
shelf_id	Shelf	text	The ID of the shelf. Empty for no shelf.
format	Format	select (hardcover, paperback, ebook, audiobook, other)	The format of the copy.

home_keeper_library.set_person_settings

Set person settings

Set the library settings of a person. A non-admin user can set only their own sharing and goal.

Open, for the caller's own person · Can return a response

Field	Label	Selector	Description
person_id (required)	Person	text	The ID of the Home Assistant person.
share_reading	Share reading status	boolean	Other users can see the status. When off, the sensors and the to-do list of the person are unavailable.
yearly_goal	Yearly goal	number (min 0, max 100000)	The number of books to read this year.
wishlist_todo	Wishlist list	entity	The to-do list for the books to buy.

home_keeper_library.set_settings

Set library settings

Set the currency of the prices and values of the copies.

Admin only · Can return a response

Field	Label	Selector	Description
currency (required)	Currency	text	A code of 3 letters, such as EUR or USD.

home_keeper_library.import_csv

Import CSV

Import books from Goodreads, StoryGraph or a library export.

Admin only · Can return a response

Field	Label	Selector	Description
content (required)	CSV content	text (multiline)	The CSV text. At most 5 MB.
source (required)	Source	select (goodreads, storygraph, library)	The app that made the CSV file.
person_id (required)	Person	text	The ID of the Home Assistant person.
shelf_id	Shelf	text	The ID of the shelf. Empty for no shelf.
import_notes	Import notes	boolean	Import the reviews and notes as private notes.
replace_reading	Replace reading status	boolean	Replace a reading status that exists.
dry_run	Dry run	boolean	Only report the changes of the import.

home_keeper_library.export_csv

Export CSV

Export the library as CSV text.

Admin only · Returns a response

Field	Label	Selector	Description
person_id	Person	text	The ID of the Home Assistant person.
format	File format	select (goodreads, library)	goodreads or library.

home_keeper_library.export_data

Export data

Export the library section of the Home Keeper export.

Admin only · Returns a response

Field	Label	Selector	Description
files_dir	Files directory	text	The directory of a bundle for the cover files. It must be below .storage/home_keeper_import_export.

home_keeper_library.import_data

Import data

Import the library section of a Home Keeper export. Records that match are updated, and no record is deleted.

Admin only · Returns a response

Field	Label	Selector	Description
document (required)	Library section	object	The data of the library section of the export.
dry_run	Dry run	boolean	Only report the changes of the import.
files_dir	Files directory	text	The directory of a bundle for the cover files. It must be below .storage/home_keeper_import_export.

home_keeper_library.list_books

List books

Return the books that match the filters.

Returns a response

Field	Label	Selector	Description
query	Search	text	Text in the title, the authors, the ISBN or the tags.
room_id	Room	text	The ID of the room.
shelf_id	Shelf	text	The ID of the shelf. Empty for no shelf.
owned	Owned	boolean	Only books with a copy, or only books with no copy.
status	Status	select (want, reading, read, dnf)	The reading status.
person_id	Person	text	The ID of the Home Assistant person.
limit	Limit	number (min 0, max 100000)	The maximum number of books.

home_keeper_library.get_book

Get book

Return a book with its copies and loans.

Returns a response

Field	Label	Selector	Description
book_id (required)	Book	text	The ID of the book.

home_keeper_library.list_locations

List locations

Return the rooms, bookcases and shelves.

Returns a response

Takes no fields.

home_keeper_library.list_loans

List loans

Return the loans.

Returns a response

Field	Label	Selector	Description
status	Loan status	select (open, returned, all)	open, returned or all.
direction	Direction	select (out, in)	out for a lent book, in for a borrowed book.

home_keeper_library.list_people

List people

Return the people and their library settings.

Returns a response

Takes no fields.

Events

The integration fires a bus event for every observable state change. Names follow home_keeper_library_<noun>_<verb>. For when each one fires in context, and worked automations, see the events guide.

Event	Fires when	Payload	Adds
home_keeper_library_room_added	A room was added.	room
home_keeper_library_room_updated	A room changed.	room	changed_fields
home_keeper_library_room_removed	A room was deleted.	room
home_keeper_library_bookcase_added	A bookcase was added.	bookcase
home_keeper_library_bookcase_updated	A bookcase changed.	bookcase	changed_fields
home_keeper_library_bookcase_removed	A bookcase was deleted.	bookcase
home_keeper_library_shelf_added	A shelf was added.	shelf
home_keeper_library_shelf_updated	A shelf changed.	shelf	changed_fields
home_keeper_library_shelf_removed	A shelf was deleted.	shelf
home_keeper_library_book_added	A book was added.	book
home_keeper_library_book_updated	The fields, the cover or the wishlist entry of a book changed.	book	changed_fields
home_keeper_library_book_removed	A book was deleted, with its copies, reading rows and loans.	book
home_keeper_library_copy_added	A copy of a book was added.	book	copy_id, shelf_id
home_keeper_library_copy_moved	A copy moved to another shelf, or off its shelf.	book	copy_id, shelf_id, previous_shelf_id
home_keeper_library_copy_updated	The fields of a copy changed, other than its shelf.	book	copy_id, shelf_id, changed_fields
home_keeper_library_copy_removed	A copy was deleted.	book	copy_id, shelf_id
home_keeper_library_reading_changed	The reading row of a person changed. status is None for a removed row.	book	status, previous_status
home_keeper_library_reading_updated	The rating, page, dates, count or notes of a reading row changed, and the status stayed. Names the fields, never the notes.	book	status, changed_fields
home_keeper_library_book_finished	The reading status of a person became read.	book	finished, rating, read_count
home_keeper_library_loan_started	A book was lent or borrowed.	book	loan_id, direction, copy_id, party, started, due, returned
home_keeper_library_loan_returned	A loan was returned.	book	loan_id, direction, copy_id, party, started, due, returned
home_keeper_library_loan_updated	The party, the dates, the format or the note of a loan changed.	book	loan_id, direction, copy_id, party, started, due, returned, changed_fields
home_keeper_library_loan_removed	A loan was deleted.	book	loan_id, direction, copy_id, party, started, due, returned
home_keeper_library_loan_overdue	An open loan passed its due date. Fires once for each due date.	book	loan_id, direction, copy_id, party, started, due, returned
home_keeper_library_wishlist_added	A book was added to a wishlist.	book	buy, bought
home_keeper_library_wishlist_removed	A book left the wishlist.	book	buy, bought
home_keeper_library_import_completed	A CSV import was written.	import
home_keeper_library_data_imported	The library section of a Home Keeper import was written.	data_import
home_keeper_library_person_settings_updated	The library settings of a person changed. Names the settings only.	person_settings
home_keeper_library_settings_updated	The options of the library changed, such as the currency.	settings

The integration also listens for events it does not own:

Event	Reaction
home_keeper_task_completed	A completed loan task returns its loan.
home_keeper_task_deleted	A deleted loan task clears the task id of its loan.
home_keeper_register_companions	The library registers as a companion again.

Payloads

Events sharing a payload shape are interchangeable in one automation template. Per-event additions from the table above merge onto these.

Room payload

Carried by home_keeper_library_room_added, home_keeper_library_room_updated, home_keeper_library_room_removed.

Field	Type	Notes
room_id	str
name	str
origin	str | None	The origin marker of the caller.

Bookcase payload

Carried by home_keeper_library_bookcase_added, home_keeper_library_bookcase_updated, home_keeper_library_bookcase_removed.

Field	Type	Notes
bookcase_id	str
room_id	str
name	str
origin	str | None	The origin marker of the caller.

Shelf payload

Carried by home_keeper_library_shelf_added, home_keeper_library_shelf_updated, home_keeper_library_shelf_removed.

Field	Type	Notes
shelf_id	str
bookcase_id	str
name	str
origin	str | None	The origin marker of the caller.

Book payload

Carried by home_keeper_library_book_added, home_keeper_library_book_updated, home_keeper_library_book_removed, home_keeper_library_copy_added, home_keeper_library_copy_moved, home_keeper_library_copy_updated, home_keeper_library_copy_removed, home_keeper_library_reading_changed, home_keeper_library_reading_updated, home_keeper_library_book_finished, home_keeper_library_loan_started, home_keeper_library_loan_returned, home_keeper_library_loan_updated, home_keeper_library_loan_removed, home_keeper_library_loan_overdue, home_keeper_library_wishlist_added, home_keeper_library_wishlist_removed.

Field	Type	Notes
book_id	str	Stable id. A rename keeps it.
title	str	The title at the time of the event.
person_id	str | None	The Home Assistant person, if any.
origin	str | None	The origin marker of the caller.

Import payload

Carried by home_keeper_library_import_completed.

Field	Type	Notes
person_id	str | None
source	str	goodreads, storygraph or library.
rows	int
books_added	int
books_matched	int
copies_added	int
reading_set	int
wishlist_added	int
errors	int
origin	str | None	The origin marker of the caller.

Data_import payload

Carried by home_keeper_library_data_imported.

Field	Type	Notes
counts	dict[str, dict[str, int]]	created, updated and skipped for each section.
origin	str | None	The origin marker of the caller.

Person_settings payload

Carried by home_keeper_library_person_settings_updated.

Field	Type	Notes
person_id	str	The Home Assistant person.
changed_fields	list[str]	The names of the changed settings.
origin	str | None	The origin marker of the caller.

Settings payload

Carried by home_keeper_library_settings_updated.

Field	Type	Notes
changed_fields	list[str]	The changed options.
currency	str	The currency code now.
origin	str | None	The origin marker of the caller.

Entities

The integration's state is readable as ordinary entities, so most automations never need to call an action to find something out.

sensor

Entities: Books (books), Loans out (loans_out), Loans overdue (loans_overdue), {person} books read this year (books_read_this_year), {person} reading now (reading_now).

State attributes:

Field	Type	Notes
goal	int | None	Books read this year: the yearly goal.
pages	int	Books read this year: the pages read.
year	int	Books read this year: the year.
books	list[str]	Reading now: at most 10 titles.
person_id	str	The person of a per-person sensor.

todo

Entities: {person} to read (to_read).

State attributes:

Field	Type	Notes
person_id	str	The person of the list.

Config entry options

The options of the config entry. The ones marked Configure dialog are on the options form of the integration. The set_settings action writes the currency too.

Option	Label	Where	Notes
currency	Currency	Configure dialog	A code of 3 letters, such as EUR or USD.

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
admin_required	Only an admin user can do this.
already_on_wishlist	The book is already on a wishlist.
book_not_found	No book has the ID {id}.
bookcase_not_empty	The bookcase has {count} shelves. Use force to delete them too.
bookcase_not_found	No bookcase has the ID {id}.
copy_not_found	No copy has the ID {id}.
copy_on_loan	The copy is lent out. Return the loan first.
csv_too_large	The CSV text is too large. The maximum is {mb} MB.
csv_unreadable	The CSV text has no {column} column.
due_before_start	The due date is before the start date.
duplicate_isbn	Another book has the ISBN {isbn}.
expected_multipart_upload	The upload must be a multipart form.
field_required	{field} is required.
field_too_long	{field} is too long. The maximum is {max}.
file_too_large	The file is too large. The maximum is {mb} MB.
files_dir_invalid	The files directory must be below .storage/home_keeper_import_export.
image_unreadable	The image cannot be read.
import_area_not_found	No area matches {name}.
import_cover_unreadable	The cover file {file} is not a valid image.
import_format_too_new	The document has format {format}. This version reads format {max} or lower.
import_not_a_list	{field} must be a list.
import_not_an_object	{field} must be an object.
import_person_not_found	No person matches {name}.
import_reference_missing	{field} {id} is not in the document or in the library.
import_todo_not_found	No to-do list matches {name}.
invalid_choice	{field} must be one of: {options}.
invalid_currency	{currency} is not a currency code of 3 letters.
invalid_date	{field} must be a date in the form YYYY-MM-DD.
invalid_field	The value of {field} is not valid.
invalid_isbn	{isbn} is not a valid ISBN.
invalid_openlibrary_edition	{edition} is not an Open Library edition key or URL.
isbn_or_title_required	Give a book ID, an ISBN or a title.
loan_not_found	No loan has the ID {id}.
lookup_unavailable	Open Library is not available. Try again later.
no_file_in_upload	The upload has no file.
no_openlibrary_cover	Open Library has no cover for this book.
no_person	Your user has no Home Assistant person. Link a person to the user.
not_loaded	Home Keeper Library is not loaded.
not_on_wishlist	The book is not on a wishlist.
openlibrary_already_linked	This book is already linked to Open Library.
openlibrary_ambiguous	Open Library found more than 1 work that can be this book. Add the book on the Open Library website.
openlibrary_login_failed	Open Library did not accept the account keys. Connect the account again.
openlibrary_needs_author	Add an author to the book before you send it.
openlibrary_not_connected	Connect an Open Library account in the library settings first.
openlibrary_not_found	Open Library has no edition {edition}.
out_of_range	{field} must be from {low} to {high}.
person_not_found	No person has the ID {id}.
room_not_empty	The room has {count} bookcases. Use force to delete them too.
room_not_found	No room has the ID {id}.
shelf_not_empty	The shelf has {count} copies. Use force to move them to no shelf.
shelf_not_found	No shelf has the ID {id}.
todo_entity_not_found	{entity_id} is not a to-do list.
todo_not_allowed	Only {person} or an admin user can change this to-do list.
unsupported_image	The file must be a JPEG, PNG or WebP image.
upload_not_found	No uploaded cover has the ID {file_id}.
upload_requires_user	An upload needs a signed-in user.