Books

Fields marked * are required. Updates keep every field they are not given. An AI app can ask vritto_describe for the same details, filtered to what its connection may use.

Book`book`

A book in the user's library, with status, progress, and rating. The same operations reach its reading timeline, one read with its dates each (type 'reading_log').

books_findFindthrough vritto_find

Read Books: with no filter what the user is reading now and the want-to-read shortlist; query and status search the library; reads in a period (type 'reading_log' with from/to); counts and pages (view 'stats'); what one person recommended (personId); one book by id. Compact rows unless detail is 'full'.

Note: With no filter: what the user is reading now and the want-to-read shortlist. type 'reading_log' with from/to reads what was read in a period; view 'stats' counts.

Field	Type	Description
type	one of book, reading_log	Record type: 'book' (default) a book in the library; 'reading_log' one entry on the reading timeline, a read with its start and finish dates.
id	string	Return just this saved book.
view	one of list, stats	'stats': totals, status breakdown, pages read, books finished by year, and ratings. Default 'list'.
query	string	Text matched against title, authors, categories, and shelves.
status	one of want_to_read, reading, read, dnf	Books with this reading status.
from	string	Reading logs finished ON or AFTER this YYYY-MM-DD date (started date for logs without a finish).
to	string	Reading logs finished ON or BEFORE this YYYY-MM-DD date. ALWAYS pass from/to when the question concerns a period (a year, a month, 'recently').
year	string	With view 'stats': only this four-digit year.
bookId	string	Reading logs of one book.
personId	string	Vritto People record id: the books they recommended.
detail	one of summary, full	'summary' (default) compact rows; 'full' every field incl. review, notes and description.
limit	integer	Max rows (books 50, reading logs 100 by default).
cursor	string	Pagination cursor from a previous nextCursor.

Example input

{
  "status": "reading"
}

books_addCreate or Updatethrough vritto_create or vritto_update

Add to Books: a book by Google Books providerId (imports full metadata; a re-import keeps the user's status, rating, review and progress), a manual book body, or a past read on the reading timeline (type 'reading_log'). A bookId with a book body edits that book, omitted fields kept.

Note: Pass providerId from vritto_lookup (book_catalog) to save a book with full details. type 'reading_log' backfills a past read.

Field	Type	Description
type	one of book, reading_log	Record type: 'book' (default) a book in the library; 'reading_log' one entry on the reading timeline, a read with its start and finish dates.
providerId	string	Google Books volume id: pass this alone to import and save with metadata.
bookId	string	An existing saved book to update with book; defaults to a provider-derived id.
book	object	Book record body. Fields you omit keep their stored values (key-presence merge), so send only what should change.
book.providerRef*	object	Provider reference identifying the book.
book.title*	string	Book title.
book.subtitle	string
book.authors	list of string	Author names.
book.description	string
book.thumbnailUrl	string	Cover image URL.
book.pageCount	integer
book.categories	list of string
book.publishedDate	string	Publication date (may be partial, e.g. '2019').
book.publisher	string
book.language	string
book.status	one of want_to_read, reading, read, dnf	Defaults to "want_to_read".
book.format	one of paperback, hardcover, ebook, audiobook
book.currentPage	integer	Current page number (reading progress).
book.startedOn	string	YYYY-MM-DD the current read started.
book.finishedOn	string	YYYY-MM-DD the book was finished.
book.rereadCount	integer	Completed re-reads beyond the first read.
book.rating	integer
book.review	string	Personal review.
book.notes	string
book.shelves	list of string	Shelf tags.
book.favorite	boolean
book.recommendedByPersonIds	list of string	Vritto People record IDs who recommended this book.
readingLogId	string	A reading log: an explicit id. Defaults to a new one.
log	object	Type 'reading_log': a read of a saved book, a start and/or finish date, optional rating and notes.
log.bookId*	string	Saved book record id, from books_find.
log.startedOn	string	Date started, YYYY-MM-DD.
log.finishedOn	string	Date finished, YYYY-MM-DD.
log.rating	integer
log.notes	string

Example input

{
  "providerId": "zyTCAlFPjgYC"
}

books_changeUpdatethrough vritto_update

Change one book by bookId: currentPage (progress; finishing stamps the finish date), status alone, rating and review, personIds (who recommended it), or patch (shelves, format, notes, favorite, dates). Or one reading-timeline entry (type 'reading_log', its id and log). Omitted fields keep their values.

Note: Send only what changes: currentPage, status, rating and review, personIds (replaces the whole list) or patch. type 'reading_log' edits a timeline entry.

Field	Type	Description
type	one of book, reading_log	Record type: 'book' (default) a book in the library; 'reading_log' one entry on the reading timeline, a read with its start and finish dates.
id	string	The book, or with type 'reading_log' the entry, to change.
bookId	string	The book to change (same as id).
currentPage	integer	Current page number.
status	one of want_to_read, reading, read, dnf	New reading status; with currentPage it applies with the progress.
rating	integer	1-5 stars, or null to clear.
review	string	Personal review text.
personIds	list of string	Vritto People record IDs: the complete recommender set (also keeps the 'Recommended by' shelves).
patch	object	Loose fields to change; omitted fields keep their values.
patch.format	one of paperback, hardcover, ebook, audiobook
patch.shelves	list of string
patch.notes	string
patch.favorite	boolean
patch.startedOn	string
patch.finishedOn	string
patch.rating	integer	1-5 stars, or null to clear.
patch.recommendedByPersonIds	list of string	Prefer personIds, which also keeps shelves.
expectedRevision	integer	Optimistic concurrency guard.
readingLogId	string	Type 'reading_log': the entry (same as id).
log	object	Type 'reading_log': the fields to change.
log.startedOn	string	Date started, YYYY-MM-DD (empty string clears it).
log.finishedOn	string	Date finished, YYYY-MM-DD (empty string clears it).
log.rating	integer	1-5 stars, or null to clear.
log.notes	string

Example input

{
  "bookId": "book_dune",
  "currentPage": 212
}

books_removeDeletethrough vritto_delete

Remove one saved book with its reading timeline, or one timeline entry (type 'reading_log'). Only for explicit removals; to correct an entry, change it.

Note: type 'reading_log' removes one timeline entry instead.

Field	Type	Description
type	one of book, reading_log	Record type: 'book' (default) a book in the library; 'reading_log' one entry on the reading timeline, a read with its start and finish dates.
id	string	The book, or with type 'reading_log' the entry, to remove.
bookId	string	Older name for a book's id.
readingLogId	string	Older name for a reading log's id.

Book Catalog`book_catalog`

Google Books reference data, for saving a book with full details.

books_getBookDetailsLook Upthrough vritto_lookup

Fetch full Google Books details (description, page count, categories) for one volume by its Google Books id.

Field	Type	Description
providerId*	string	Google Books volume id.

books_searchBooksLook Upthrough vritto_lookup

Search Google Books by title, author, or keyword. Returns provider metadata, not the user's saved library: use books_find for saved books.

Field	Type	Description
query*	string	Search text.
limit	integer	Max results (default 20).

Books

Bookbook

Book Catalogbook_catalog

Book`book`

Book Catalog`book_catalog`