Books

List saved books a given Vritto person recommended.

Search the user's saved book library by text and/or reading status. Use this to resolve a bookId before a write.

Return the reading cockpit: currently-reading books with progress and the want-to-read shortlist.

No input.

Summarize the reading library: totals, status breakdown, pages read, books finished by year, and rating distribution. Prefer this for how-many-books questions.

Save a book to the library. Prefer passing providerId alone to import full Google Books metadata (existing status/rating/review/progress are preserved); pass book for manual entries or edits, where omitted fields keep their stored values.

Note: Pass providerId from vritto_lookup (book_catalog) to save a book with full details.

{
  "providerId": "zyTCAlFPjgYC"
}

Update loose fields on a saved book (shelves, format, notes, favorite, dates, rating, recommenders).

Set or clear a book's star rating and personal review.

{
  "bookId": "book_dune",
  "rating": 5,
  "review": "Worth every page."
}

Set the full list of Vritto People who recommended a book (replaces the current set). Also maintains 'Recommended by {name}' shelves.

Note: personIds replaces the whole list.

Set a book's reading status without touching page progress, e.g. mark it want-to-read or DNF.

{
  "bookId": "book_dune",
  "status": "read"
}

Record reading progress by page number (or set status directly). Moving to reading stamps a start date; marking read stamps a finish date and 100% progress.

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

Remove one saved book from the library. Only for explicit removals.

List reading-timeline entries (title, start/finish dates, rating), newest first, optionally scoped to one book. Supports a date range on the finish date (start date for still-open reads), ALWAYS pass from/to when the question concerns a period (a year, a month, 'recently'). Rows are compact summaries; pass detail 'full' only when the user needs full log notes.

Record a reading period for the timeline (a start and/or finish date, optional rating and notes). Completing a book normally logs this automatically; use this to backfill past reads or re-reads.

{
  "log": {
    "bookId": "book_dune",
    "startedOn": "2026-09-01",
    "finishedOn": "2026-09-24",
    "rating": 5
  }
}

Edit one existing reading-timeline entry (its dates, rating, or notes) in place. Fields you omit keep their stored values. Use this rather than deleting and re-adding, which loses the entry if the re-add fails.

Delete one reading-timeline entry. Only for explicit removals.

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

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