Books - ReadRealm

The Books API is the core of ReadRealm. It exposes endpoints for managing the book catalog, fetching details from OpenLibrary, streaming books by genre via Server-Sent Events, toggling bookmarks, and submitting reviews with AI-powered sentiment analysis.

Endpoint summary

Method	Path	Description
`GET`	`/book`	List all books in the local database
`POST`	`/book`	Create a book record
`GET`	`/book/search`	Search books via OpenLibrary
`GET`	`/book/details/:id`	Get enriched book details (OpenLibrary + AI summary)
`GET`	`/book/summary/:title`	Get an AI-generated 5-line summary
`GET`	`/book/genre/:genre`	Stream books by genre (SSE)
`GET`	`/book/:id`	Get a book by numeric ID
`PATCH`	`/book/:id`	Partially update a book
`DELETE`	`/book/:id`	Delete a book
`PUT`	`/book/bookmark`	Toggle a bookmark for a user
`GET`	`/book/bookmarks/:userId`	List all bookmarked books for a user
`POST`	`/book/ebook`	Generate TTS audio from book text
`GET`	`/book/tts/stream/:title`	Stream TTS audio for a book by title
`POST`	`/book/reviews/:id`	Submit a review for a book
`GET`	`/book/reviews/:id`	Get all reviews for a book
`GET`	`/book/user-reviews/:userId`	Get all reviews written by a user

GET /book

Returns all book records stored in the local MongoDB database.

curl http://localhost:3000/book

Response

[]

Book[]

Array of book objects.

Show Book properties

number

Numeric book ID (from OpenLibrary).

author

string

Primary author name.

title

string

Book title.

publicationYear

number

Year of first publication.

numOfPages

number

Median page count.

coverImage

string

URL to the cover image.

genre

string

Primary genre or subject.

link

string

EPUB download link, if available.

textData

string

Raw plain-text content of the book.

bookmarks

Bookmark[]

List of bookmarks on this book.

reviews

Review[]

Populated review objects.

averageRating

number

Mean rating (1–5) across all reviews.

totalReviews

number

Total number of reviews.

description

string

AI-generated or publisher description.

POST /book

Persists a new book record to the database. All fields from CreateBookDto are accepted.

Request body

number

required

Numeric book ID. Must be unique.

author

string

required

Primary author name.

title

string

required

Book title.

publicationDate

number

required

Year of publication.

numOfPages

number

required

Page count.

coverImage

string

required

URL to the cover image.

genre

string

required

Primary genre or subject.

textData

string

Raw plain-text content. Optional; used for TTS generation.

bookmarks

Bookmark[]

Initial bookmark list. Optional.

curl -X POST http://localhost:3000/book \
  -H 'Content-Type: application/json' \
  -d '{
    "id": 28520,
    "author": "Lewis Carroll",
    "title": "Alice in Wonderland",
    "publicationDate": 1865,
    "numOfPages": 96,
    "coverImage": "https://covers.openlibrary.org/b/id/8739161-M.jpg",
    "genre": "Fantasy"
  }'

Response

Returns the persisted Book document.

GET /book/search

Searches for books using the OpenLibrary search API. Returns up to 12 results.

Query parameters

string

required

Search query (title, author, ISBN, etc.).

curl 'http://localhost:3000/book/search?q=alice+in+wonderland'

Response

Array of lightweight book objects sourced from OpenLibrary:

title

string

Book title.

author

string

Primary author name.

publicationDate

number

Year of first publication.

numOfPages

number

Median page count.

coverImage

string

Cover image URL.

GET /book/details/:id

Fetches enriched book details. Checks the local database first; if not found, pulls data from the OpenLibrary Works API, generates an AI summary via Gemini, and upserts the result.

Path parameters

number

required

OpenLibrary numeric work ID (e.g. 28520 for OL28520W).

curl http://localhost:3000/book/details/28520

Response

Full Book document including description, link (EPUB), and populated reviews.

GET /book/summary/:title

Fetches the book text from Gutendex, then uses the Google Gemini API to produce a concise 5-line summary.

This endpoint makes external calls to Gutendex and Gemini. Latency can exceed several seconds for long books. Requires GEMINI_API_KEY to be configured on the server.

Path parameters

title

string

required

URL-encoded book title (e.g. alice%20in%20wonderland).

curl 'http://localhost:3000/book/summary/alice%20in%20wonderland'

Response

A plain-text string containing the AI-generated 5-line summary.

GET /book/genre/:genre

Streams books belonging to a genre via Server-Sent Events (SSE). Results are sourced from OpenLibrary subjects and cached for 15 minutes. The response is paginated with offset and limit.

Set an Accept: text/event-stream header or use the EventSource API in the browser. The connection closes automatically after all books in the page have been emitted.

Path parameters

genre

string

required

Genre/subject slug (e.g. fantasy, science_fiction, history). Use all to return an empty stream.

Query parameters

offset

number

default:"0"

Number of books to skip.

limit

number

default:"10"

Number of books to return. Capped at 50.

curl -H 'Accept: text/event-stream' \
  'http://localhost:3000/book/genre/fantasy?offset=0&limit=10'

Response

Each SSE event contains a JSON-serialised book object:

data: {"id":28520,"title":"...","author":"...","total":1200,"offset":0,"limit":10, ...}

data: {"id":12345, ...}

The total, offset, and limit fields are included in every event so clients can implement pagination.

GET /book/:id

Retrieves a single book from the local database by numeric ID.

Path parameters

number

required

Numeric book ID.

curl http://localhost:3000/book/28520

Response

A single Book document. Returns 404 if not found.

PATCH /book/:id

Partially updates a book. Any subset of CreateBookDto fields may be supplied.

Path parameters

number

required

Numeric book ID.

Request body

All fields are optional (partial update):

author

string

Updated author name.

title

string

Updated title.

publicationDate

number

Updated publication year.

numOfPages

number

Updated page count.

coverImage

string

Updated cover image URL.

genre

string

Updated genre.

textData

string

Updated plain-text content.

curl -X PATCH http://localhost:3000/book/28520 \
  -H 'Content-Type: application/json' \
  -d '{"genre": "Classic Fiction"}'

Response

The updated Book document. Returns 404 if not found.

DELETE /book/:id

Permanently removes a book from the database.

This operation is irreversible. Associated reviews and bookmarks stored on the book document will be deleted.

Path parameters

number

required

Numeric book ID.

curl -X DELETE http://localhost:3000/book/28520

Response

{ "deleted": true }

PUT /book/bookmark

Toggles a bookmark for a user on a given book. If the book does not yet exist in the local database, it is created automatically. If the user already has a bookmark, it is removed; otherwise it is added.

Request body

userId

string

required

The ID of the user toggling the bookmark.

book

object

required

A CreateBookDto object representing the book to bookmark.

Show book fields

book.id

number

required

Numeric book ID.

book.author

string

required

Author name.

book.title

string

required

Book title.

book.publicationDate

number

required

Publication year.

book.numOfPages

number

required

Page count.

book.coverImage

string

required

Cover image URL.

book.genre

string

required

Genre.

curl -X PUT http://localhost:3000/book/bookmark \
  -H 'Content-Type: application/json' \
  -d '{
    "userId": "user_abc123",
    "book": {
      "id": 28520,
      "author": "Lewis Carroll",
      "title": "Alice in Wonderland",
      "publicationDate": 1865,
      "numOfPages": 96,
      "coverImage": "https://covers.openlibrary.org/b/id/8739161-M.jpg",
      "genre": "Fantasy"
    }
  }'

Response

The updated Book document with the modified bookmarks array.

GET /book/bookmarks/:userId

Returns all books that a given user has bookmarked. Review data is stripped from the response for performance.

Path parameters

userId

string

required

The user ID to look up bookmarks for.

curl http://localhost:3000/book/bookmarks/user_abc123

Response

Array of Book documents where the bookmarks array contains an entry for the given userId. The reviews field is returned as an empty array.

POST /book/ebook

Generates TTS (text-to-speech) audio using Azure OpenAI from the textData field of the request body. Only the first 4,096 characters of the text are converted.

See Speech & Audio for full TTS documentation including the streaming endpoint.

Request body

number

required

Book ID.

author

string

required

Author name.

title

string

required

Book title.

publicationDate

number

required

Publication year.

numOfPages

number

required

Page count.

coverImage

string

required

Cover image URL.

genre

string

required

Genre.

textData

string

Plain-text content to convert to speech. If empty, a default CreateBookDto is substituted.

curl -X POST http://localhost:3000/book/ebook \
  -H 'Content-Type: application/json' \
  -d '{
    "id": 28520,
    "author": "Lewis Carroll",
    "title": "Alice in Wonderland",
    "publicationDate": 1865,
    "numOfPages": 96,
    "coverImage": "https://covers.openlibrary.org/b/id/8739161-M.jpg",
    "genre": "Fantasy",
    "textData": "Alice was beginning to get very tired of sitting by her sister..."
  }'

Response

A binary audio stream (audio/mpeg). Use a media player or write the response to a .mp3 file.

GET /book/tts/stream/:title

Fetches the book text from Gutendex by title, then streams the TTS audio as a chunked audio/mpeg response.

See Speech & Audio for full documentation of this endpoint.

Path parameters

title

string

required

URL-encoded book title (e.g. alice%20in%20wonderland).

curl -o book.mp3 \
  'http://localhost:3000/book/tts/stream/alice%20in%20wonderland'

POST /book/reviews/:id

Submits a review for a book. If the book does not exist in the local database, it is fetched from OpenLibrary and created automatically. The book’s averageRating and totalReviews fields are recalculated after every submission.

Path parameters

number

required

Numeric book ID. Returns 400 if missing or NaN.

Request body

userId

string

required

ID of the user submitting the review.

bookId

number

required

Must match the :id path parameter. Set automatically by the server from the path.

rating

number

required

Star rating between 1 and 5 (inclusive).

comment

string

required

Review text.

curl -X POST http://localhost:3000/book/reviews/28520 \
  -H 'Content-Type: application/json' \
  -d '{
    "userId": "user_abc123",
    "bookId": 28520,
    "rating": 5,
    "comment": "A timeless classic that never gets old."
  }'

Response

userId

string

ID of the reviewer.

bookId

number

Book ID the review belongs to.

rating

number

Submitted star rating (1–5).

comment

string

Review text.

emotion

string

Sentiment label: positive, negative, or neutral. Derived from the comment text.

createdAt

string

ISO 8601 timestamp of when the review was created.

GET /book/reviews/:id

Returns all reviews for a book, populated from the reviews reference on the book document.

Path parameters

number

required

Numeric book ID.

curl http://localhost:3000/book/reviews/28520

Response

Array of Review objects (see fields above). Returns an empty array [] if the book has no reviews or does not exist.

GET /book/user-reviews/:userId

Returns all reviews written by a specific user, sorted by createdAt descending. The emotion field is computed on retrieval using sentiment analysis.

Path parameters

userId

string

required

User ID. Returns 400 if empty.

curl http://localhost:3000/book/user-reviews/user_abc123

Response

Array of Review objects with the bookId field populated. Throws 404 if no reviews are found for the user.

Documentation Index

​Endpoint summary

​GET /book

​Response

​POST /book

​Request body

​Response

​GET /book/search

​Query parameters

​Response

​GET /book/details/:id

​Path parameters

​Response

​GET /book/summary/:title

​Path parameters

​Response

​GET /book/genre/:genre

​Path parameters

​Query parameters

​Response

​GET /book/:id

​Path parameters

​Response

​PATCH /book/:id

​Path parameters

​Request body

​Response

​DELETE /book/:id

​Path parameters

​Response

​PUT /book/bookmark

​Request body

​Response

​GET /book/bookmarks/:userId

​Path parameters

​Response

​POST /book/ebook

​Request body

​Response

​GET /book/tts/stream/:title

​Path parameters

​POST /book/reviews/:id

​Path parameters

​Request body

​Response

​GET /book/reviews/:id

​Path parameters

​Response

​GET /book/user-reviews/:userId

​Path parameters

​Response

Endpoint summary

GET /book

Response

POST /book

Request body

Response

GET /book/search

Query parameters

Response

GET /book/details/:id

Path parameters

Response

GET /book/summary/:title

Path parameters

Response

GET /book/genre/:genre

Path parameters

Query parameters

Response

GET /book/:id

Path parameters

Response

PATCH /book/:id

Path parameters

Request body

Response

DELETE /book/:id

Path parameters

Response

PUT /book/bookmark

Request body

Response

GET /book/bookmarks/:userId

Path parameters

Response

POST /book/ebook

Request body

Response

GET /book/tts/stream/:title

Path parameters

POST /book/reviews/:id

Path parameters

Request body

Response

GET /book/reviews/:id

Path parameters

Response

GET /book/user-reviews/:userId

Path parameters

Response