API v1

VirexBooks Docs

Overview of the current application API for auth, books, reading, audiobooks, profiles, and user settings.

Base path

/api/v1

Auth model

Public routes use existing Supabase RLS. Private routes require the current session cookie.

Auth

GET/api/v1/auth/me

Returns the current authenticated user, linked profile, and merged user settings.

POST/api/v1/auth/logout

Signs out the current session.

Profiles

GET/api/v1/profiles/:username

Returns a public profile plus basic publishing stats.

Books

GET/api/v1/books

List published books with optional filters for search, genre, featured, originals, staff picks, audiobook-only, sort, and limit.

GET/api/v1/books/:bookId

Returns book metadata, author data, chapter list, and audiobook counters.

GET/api/v1/books/:bookId/chapters

Returns published chapter metadata. Use `includeContent=true` to include full chapter text.

GET/api/v1/read/progress?bookId=:bookId

Returns the authenticated user's reading progress for one book.

PUT/api/v1/read/progress

Creates or updates reading progress using `book_id`, `chapter_id`, and `scroll_position`.

Audiobooks

GET/api/v1/audiobooks

Lists books with at least one published chapter that has an audio file.

GET/api/v1/audiobooks/:bookId

Returns audiobook metadata and all published audio chapters for a book.

GET/api/v1/audiobooks/:bookId/stream/:chapterId

Redirects with `307` to the real audio file URL for the selected chapter.

Settings

GET/api/v1/settings

Returns the authenticated user's preferences merged with defaults.

PATCH/api/v1/settings

Updates language, theme, autoplay, mail, analytics, privacy, and reading-preference fields.

Progress Payload

Example body for updating reading progress.

{
  "book_id": "uuid",
  "chapter_id": "uuid",
  "scroll_position": 0.42
}

Settings Payload

Allowed fields for `PATCH /api/v1/settings`.

{
  "preferred_language": "de",
  "theme": "system",
  "autoplay_audio": false,
  "email_notifications": true,
  "marketing_emails": false,
  "analytics_enabled": true,
  "public_profile": true,
  "show_reading_activity": true,
  "mature_content": false
}