BookDetailResponse

Detailed book response with metadata

book objectrequired

Book data transfer object

analysisErrorstring | nullnullable

Error message if book analysis failed

Example: Failed to parse CBZ: invalid archive

analyzedbooleanrequired

Whether the book has been analyzed (page dimensions available)

Example: true

chapternumber,null<float>nullable

Chapter number from book metadata (may be fractional)

Example: 42.5

createdAtstring<date-time>required

When the book was added to the library

Example: 2024-01-01T00:00:00Z

deletedbooleanrequired

Whether the book has been soft-deleted

Example: false

fileFormatstringrequired

File format (cbz, cbr, epub, pdf)

Example: cbz

fileHashstringrequired

File hash for deduplication

Example: a1b2c3d4e5f6g7h8i9j0

fileSizeinteger<int64>required

File size in bytes

Example: 52428800

idstring<uuid>required

Book unique identifier

Example: 550e8400-e29b-41d4-a716-446655440001

koreaderHashstring | nullnullable

KOReader-compatible partial MD5 hash for sync

libraryIdstring<uuid>required

Library this book belongs to

Example: 550e8400-e29b-41d4-a716-446655440000

libraryNamestringrequired

Name of the library

Example: Comics

numberinteger,null<int32>nullable

Book number within the series

Example: 1

pageCountinteger<int32>required

Number of pages in the book

Example: 32

pathstringrequired

Filesystem path to the book file

Example: /media/comics/Batman/Batman - Year One 001.cbz

readProgress object

User's read progress for this book

bookIdstring<uuid>required

Book ID

Example: 550e8400-e29b-41d4-a716-446655440002

completedbooleanrequired

Whether the book is completed

Example: false

completedAtstring,null<date-time>nullable

When the book was completed (if completed)

Example: 2024-01-20T20:00:00Z

currentPageinteger<int32>required

Current page (1-indexed)

Example: 42

idstring<uuid>required

Progress record ID

Example: 550e8400-e29b-41d4-a716-446655440000

progressPercentagenumber,null<double>nullable

Progress as a percentage (0.0-1.0) For EPUBs, this is the stored percentage from reflowable content For other formats, this is calculated from current_page / total_pages

Example: 0.45

startedAtstring<date-time>required

When reading started

Example: 2024-01-10T14:30:00Z

updatedAtstring<date-time>required

When progress was last updated

Example: 2024-01-15T18:45:00Z

userIdstring<uuid>required

User ID

Example: 550e8400-e29b-41d4-a716-446655440001

readingDirectionstring | nullnullable

Effective reading direction (from series metadata, or library default if not set) Values: ltr, rtl, ttb or webtoon

Example: ltr

seriesIdstring<uuid>required

Series this book belongs to

Example: 550e8400-e29b-41d4-a716-446655440002

seriesNamestringrequired

Name of the series

Example: Batman: Year One

summarystring | nullnullable

Book summary/description from book_metadata (ComicInfo <Summary> or EPUB description). Surfaced on the list response so cards can show it on hover without fetching the full detail payload.

Example: Bruce Wayne returns to Gotham to begin his war on crime.

titlestringrequired

Book title

Example: Batman: Year One #1

titleSortstring | nullnullable

Title used for sorting (title_sort field)

Example: batman year one 001

updatedAtstring<date-time>required

When the book was last updated

Example: 2024-01-15T10:30:00Z

volumeinteger,null<int32>nullable

Volume number from book metadata

Example: 1

wantToReadboolean | nullnullable

Whether the requesting user has this book in their want-to-read queue.

None when not computed for this response; populated on book list and detail endpoints that have a user context.

Example: false

metadata object

Optional metadata from ComicInfo.xml or similar

authors object[]

Structured author information as JSON array

Array [

namestringrequired

Author's name

Example: Andy Weir

roleBookAuthorRole (string)required

Role of this author

Possible values: [author, co_author, editor, translator, illustrator, contributor, writer, penciller, inker, colorist, letterer, cover_artist]

sortNamestring | nullnullable

Sort name for ordering (e.g., "Weir, Andy")

Example: Weir, Andy

]

awards object[]

Awards information

Array [

categorystring | nullnullable

Award category

Example: Best Novel

namestringrequired

Name of the award

Example: Hugo Award

wonbooleanrequired

Whether the book won (true) or was just nominated (false)

Example: true

yearinteger,null<int32>nullable

Year the award was given/nominated

Example: 2015

]

blackAndWhiteboolean | nullnullable

Whether the book is black and white

Example: false

bookIdstring<uuid>required

Associated book ID

Example: 550e8400-e29b-41d4-a716-446655440001

bookTypeBookTypeDto (string)

Book type classification (comic, manga, novel, etc.)

Possible values: [comic, manga, novel, novella, anthology, artbook, oneshot, omnibus, graphic_novel, magazine]

chapternumber,null<float>nullable

Chapter number (may be fractional, e.g. 42.5 for side chapters)

Example: 42

coloristsstring[]required

Colorists

Example: ["Richmond Lewis"]

countinteger,null<int32>nullable

Total count in series

Example: 4

coverArtistsstring[]required

Cover artists

Example: ["David Mazzucchelli"]

customMetadataobject | nullnullable

Custom metadata JSON escape hatch

dayinteger,null<int32>nullable

Publication day (1-31)

Example: 1

editionstring | nullnullable

Edition information (e.g., "First Edition", "Revised Edition")

Example: First Edition

editorsstring[]required

Editors

Example: ["Dennis O'Neil"]

formatDetailstring | nullnullable

Format details

Example: Trade Paperback

genrestring | nullnullable

Genre

Example: Superhero

idstring<uuid>required

Metadata record ID

Example: 550e8400-e29b-41d4-a716-446655440003

imprintstring | nullnullable

Imprint name

Example: DC Black Label

inkersstring[]required

Inkers

Example: ["David Mazzucchelli"]

isbnsstring | nullnullable

ISBN(s)

Example: 978-1401207526

languageIsostring | nullnullable

ISO language code

Example: en

letterersstring[]required

Letterers

Example: ["Todd Klein"]

mangaboolean | nullnullable

Whether the book is manga format

Example: false

monthinteger,null<int32>nullable

Publication month (1-12)

Example: 2

numberstring | nullnullable

Issue/chapter number from metadata

Example: 1

originalTitlestring | nullnullable

Original title (for translated works)

Example: 火星の人

originalYearinteger,null<int32>nullable

Original publication year (for re-releases or translations)

Example: 2011

pageCountinteger,null<int32>nullable

Page count from metadata

Example: 32

pencillersstring[]required

Pencillers (line artists)

Example: ["David Mazzucchelli"]

publisherstring | nullnullable

Publisher name

Example: DC Comics

releaseDatestring,null<date-time>nullable

Release/publication date

Example: 1987-02-01T00:00:00Z

seriesstring | nullnullable

Series name from metadata

Example: Batman: Year One

seriesPositionnumber,null<double>nullable

Position in a series (e.g., 1.0, 2.5 for .5 volumes)

Example: 1

seriesTotalinteger,null<int32>nullable

Total number of books in the series

Example: 3

subjectsstring[]nullable

Subject/topic tags

Example: ["Science Fiction","Space Exploration","Survival"]

subtitlestring | nullnullable

Book subtitle

Example: A Novel

summarystring | nullnullable

Book summary/description

Example: Bruce Wayne returns to Gotham City after years abroad to begin his war on crime.

titlestring | nullnullable

Book title from metadata

Example: Batman: Year One #1

translatorstring | nullnullable

Translator name

Example: John Smith

volumeinteger,null<int32>nullable

Volume number

Example: 1

writersstring[]required

Writers/authors

Example: ["Frank Miller"]

yearinteger,null<int32>nullable

Publication year

Example: 1987

BookDetailResponse

{
  "book": {
    "analysisError": "Failed to parse CBZ: invalid archive",
    "analyzed": true,
    "chapter": 42.5,
    "createdAt": "2024-01-01T00:00:00Z",
    "deleted": false,
    "fileFormat": "cbz",
    "fileHash": "a1b2c3d4e5f6g7h8i9j0",
    "fileSize": 52428800,
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "koreaderHash": "string",
    "libraryId": "550e8400-e29b-41d4-a716-446655440000",
    "libraryName": "Comics",
    "number": 1,
    "pageCount": 32,
    "path": "/media/comics/Batman/Batman - Year One 001.cbz",
    "readProgress": {
      "bookId": "550e8400-e29b-41d4-a716-446655440002",
      "completed": false,
      "completedAt": "2024-01-20T20:00:00Z",
      "currentPage": 42,
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "progressPercentage": 0.45,
      "startedAt": "2024-01-10T14:30:00Z",
      "updatedAt": "2024-01-15T18:45:00Z",
      "userId": "550e8400-e29b-41d4-a716-446655440001"
    },
    "readingDirection": "ltr",
    "seriesId": "550e8400-e29b-41d4-a716-446655440002",
    "seriesName": "Batman: Year One",
    "summary": "Bruce Wayne returns to Gotham to begin his war on crime.",
    "title": "Batman: Year One #1",
    "titleSort": "batman year one 001",
    "updatedAt": "2024-01-15T10:30:00Z",
    "volume": 1,
    "wantToRead": false
  },
  "metadata": {
    "authors": [
      {
        "name": "Andy Weir",
        "role": "author",
        "sortName": "Weir, Andy"
      }
    ],
    "awards": [
      {
        "category": "Best Novel",
        "name": "Hugo Award",
        "won": true,
        "year": 2015
      }
    ],
    "blackAndWhite": false,
    "bookId": "550e8400-e29b-41d4-a716-446655440001",
    "bookType": "comic",
    "chapter": 42,
    "colorists": [
      "Richmond Lewis"
    ],
    "count": 4,
    "coverArtists": [
      "David Mazzucchelli"
    ],
    "customMetadata": "Unknown Type: object,null",
    "day": 1,
    "edition": "First Edition",
    "editors": [
      "Dennis O'Neil"
    ],
    "formatDetail": "Trade Paperback",
    "genre": "Superhero",
    "id": "550e8400-e29b-41d4-a716-446655440003",
    "imprint": "DC Black Label",
    "inkers": [
      "David Mazzucchelli"
    ],
    "isbns": "978-1401207526",
    "languageIso": "en",
    "letterers": [
      "Todd Klein"
    ],
    "manga": false,
    "month": 2,
    "number": "1",
    "originalTitle": "火星の人",
    "originalYear": 2011,
    "pageCount": 32,
    "pencillers": [
      "David Mazzucchelli"
    ],
    "publisher": "DC Comics",
    "releaseDate": "1987-02-01T00:00:00Z",
    "series": "Batman: Year One",
    "seriesPosition": 1,
    "seriesTotal": 3,
    "subjects": [
      "Science Fiction",
      "Space Exploration",
      "Survival"
    ],
    "subtitle": "A Novel",
    "summary": "Bruce Wayne returns to Gotham City after years abroad to begin his war on crime.",
    "title": "Batman: Year One #1",
    "translator": "John Smith",
    "volume": 1,
    "writers": [
      "Frank Miller"
    ],
    "year": 1987
  }
}