Change a book's status
update_book_statusMoves a book that is already in the reader's ReadingRate library to another status: "reading" (sets the start date if there is none), "read" (sets the finish date, with an optional rating), "stopped", or "want_to_read" (clears the finish date). It replaces the book's current status, and for "read" its rating and finish date. Marking a book read also adds it to the reader's ReadingRate activity feed. Other readers see that they finished it while the reader's profile is public and shows finished books (new accounts start private, and finished books start hidden): on the profile, and for people who follow the reader in their feed and on the book's page.
Use when the user says they started, finished, stopped or gave up a book in their library, wants to rate a finished book, or wants a book back on their want-to-read list. For a book not yet in their library, use add_book_to_library.
Examples:
{"book_id": "", "status": "reading"}
{"book_id": "", "status": "read", "rating": 5}
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| rating | No | Rating from 1 to 5, only with status "read" | |
| status | Yes | The new status | |
| book_id | Yes | The book's ReadingRate id or its library entry id | |
| date_finished | No | Finish date, YYYY-MM-DD, only with status "read" (default: today) |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| book | No | The book: id, slug, title, authors | |
| rating | No | The rating recorded, when finishing | |
| message | Yes | Human-readable result | |
| success | Yes | Whether the status changed | |
| new_status | No | The status after the change | |
| old_status | No | The status before the change | |
| date_started | No | Start date, when the status is reading | |
| date_finished | No | Finish date, when the status is read |