Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/aliammari1/readrealm/llms.txt

Use this file to discover all available pages before exploring further.

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

MethodPathDescription
GET/bookList all books in the local database
POST/bookCreate a book record
GET/book/searchSearch books via OpenLibrary
GET/book/details/:idGet enriched book details (OpenLibrary + AI summary)
GET/book/summary/:titleGet an AI-generated 5-line summary
GET/book/genre/:genreStream books by genre (SSE)
GET/book/:idGet a book by numeric ID
PATCH/book/:idPartially update a book
DELETE/book/:idDelete a book
PUT/book/bookmarkToggle a bookmark for a user
GET/book/bookmarks/:userIdList all bookmarked books for a user
POST/book/ebookGenerate TTS audio from book text
GET/book/tts/stream/:titleStream TTS audio for a book by title
POST/book/reviews/:idSubmit a review for a book
GET/book/reviews/:idGet all reviews for a book
GET/book/user-reviews/:userIdGet 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.

​
POST /book

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

​
Request body

​
id
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

​
q
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

​
id
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

​
id
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

​
id
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

​
id
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.
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

​
id
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

​
id
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

​
id
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us