Log a reading session
log_reading_sessionLogs reading for a book in the reader's ReadingRate library: pages read, the page they reached, or a note. It sets the book's current page, adds the pages to today's entry in their reading journal, and adds the note to that entry. One journal entry per book per day: a second call the same day extends that day's pages and appends the note. A book on the want-to-read list moves to reading.
Use when the user says how many pages they read, which page they are on, or wants a thought about today's reading saved with it. For a book not yet in their library, use add_book_to_library first.
Give pages_read (pages read since the last log), current_page (the arabic page reached) or roman_page (a page of an introduction or preface numbered in roman numerals), only one of them; a note can be sent alone. Each call logs again, so do not repeat a call that succeeded.
Introductions numbered i, ii, iii… count. When the reader says their copy's introduction runs to a roman page (for example lx), send front_matter_ends_on with it, alone or with the page; the copy keeps it, and later arabic pages count after it. "0" means the copy has none, or the reader skipped it, which takes its pages back out.
Examples:
{"book_id": "", "pages_read": 30}
{"book_id": "", "current_page": 150}
{"book_id": "", "front_matter_ends_on": "lx", "roman_page": "liv"}
{"book_id": "", "notes": "The argument only lands once you have read the footnotes."}
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| notes | No | The reader's note on today's reading, added to today's journal entry | |
| book_id | Yes | The book's ReadingRate id or its library entry id | |
| pages_read | No | Pages read in this session, added to the current page | |
| roman_page | No | The page the reader is now on in the book's roman-numbered introduction or preface, such as "liv" | |
| current_page | No | The page the reader is now on, as printed in arabic numerals | |
| front_matter_ends_on | No | The last roman-numbered page of the reader's copy, such as "lx" (or 60); "0" when it has none or they skipped it |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| book | No | The book: id, slug, title, authors | |
| message | Yes | Human-readable result | |
| success | Yes | Whether the session was logged | |
| estimate | No | hours_remaining and description; null when the total pages are unknown | |
| progress | No | current_page (the stored position, counted from page i when the copy has roman front matter), page_label (the page as the book prints it, e.g. "liv" or "10"), front_matter_pages, total_pages (printed pages of the reader's copy, without a roman introduction: show page_label of total_pages), percent_complete and pages_remaining (over the whole copy) | |
| velocity_used | No | Pages per hour used for the estimate | |
| status_changed | No | Set when the book moved from want-to-read to reading |