FullBookResponse

Full book response including book data and complete metadata with locks

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

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

filePathstringrequired

Filesystem path to the book file

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

fileSizeinteger<int64>required

File size in bytes

Example: 52428800

genres object[]required

Genres assigned to this book

Array [

createdAtstring<date-time>required

When the genre was created

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

idstring<uuid>required

Genre ID

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

namestringrequired

Genre name

Example: Action

seriesCountinteger,null<int64>nullable

Number of series with this genre

Possible values: >= 0

Example: 42

]

idstring<uuid>required

Book unique identifier

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

libraryIdstring<uuid>required

Library this book belongs to

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

libraryNamestringrequired

Name of the library

Example: Comics

metadata objectrequired

Complete book metadata with lock states

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

bookType object

oneOf

• null
• BookTypeDto

null

coloriststring | nullnullable

Colorist(s)

Example: Richmond Lewis

coloristsstring[]required

Colorists as array

countinteger,null<int32>nullable

Total count in series

Example: 4

coverArtiststring | nullnullable

Cover artist(s)

Example: David Mazzucchelli

coverArtistsstring[]required

Cover artists as array

createdAtstring<date-time>required

When the metadata was created

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

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

editorstring | nullnullable

Editor(s)

Example: Dennis O'Neil

editorsstring[]required

Editors as array

formatDetailstring | nullnullable

Format details

Example: Trade Paperback

genrestring | nullnullable

Genre

Example: Superhero

imprintstring | nullnullable

Imprint name

Example: DC Black Label

inkerstring | nullnullable

Inker(s)

Example: David Mazzucchelli

inkersstring[]required

Inkers as array

isbnsstring | nullnullable

ISBN(s)

Example: 978-1401207526

languageIsostring | nullnullable

ISO language code

Example: en

lettererstring | nullnullable

Letterer(s)

Example: Todd Klein

letterersstring[]required

Letterers as array

locks objectrequired

Book metadata lock states

Indicates which metadata fields are locked (protected from automatic updates). When a field is locked, the scanner will not overwrite user-edited values.

authorsJsonLockbooleanrequired

Whether authors_json is locked

Example: false

awardsJsonLockbooleanrequired

Whether awards_json is locked

Example: false

blackAndWhiteLockbooleanrequired

Whether black_and_white is locked

Example: false

bookTypeLockbooleanrequired

Whether book_type is locked

Example: false

coloristLockbooleanrequired

Whether colorist is locked

Example: false

countLockbooleanrequired

Whether count is locked

Example: false

coverArtistLockbooleanrequired

Whether cover artist is locked

Example: false

coverLockbooleanrequired

Whether cover is locked (prevents auto-updates)

Example: false

customMetadataLockbooleanrequired

Whether custom_metadata is locked

Example: false

dayLockbooleanrequired

Whether day is locked

Example: false

editionLockbooleanrequired

Whether edition is locked

Example: false

editorLockbooleanrequired

Whether editor is locked

Example: false

formatDetailLockbooleanrequired

Whether format_detail is locked

Example: false

genreLockbooleanrequired

Whether genre is locked

Example: false

imprintLockbooleanrequired

Whether imprint is locked

Example: false

inkerLockbooleanrequired

Whether inker is locked

Example: false

isbnsLockbooleanrequired

Whether isbns is locked

Example: false

languageIsoLockbooleanrequired

Whether language_iso is locked

Example: false

lettererLockbooleanrequired

Whether letterer is locked

Example: false

mangaLockbooleanrequired

Whether manga is locked

Example: false

monthLockbooleanrequired

Whether month is locked

Example: false

numberLockbooleanrequired

Whether number is locked

Example: false

originalTitleLockbooleanrequired

Whether original_title is locked

Example: false

originalYearLockbooleanrequired

Whether original_year is locked

Example: false

pencillerLockbooleanrequired

Whether penciller is locked

Example: false

publisherLockbooleanrequired

Whether publisher is locked

Example: true

seriesPositionLockbooleanrequired

Whether series_position is locked

Example: false

seriesTotalLockbooleanrequired

Whether series_total is locked

Example: false

subjectsLockbooleanrequired

Whether subjects is locked

Example: false

subtitleLockbooleanrequired

Whether subtitle is locked

Example: false

summaryLockbooleanrequired

Whether summary is locked

Example: false

titleLockbooleanrequired

Whether title is locked

Example: false

titleSortLockbooleanrequired

Whether title_sort is locked

Example: false

translatorLockbooleanrequired

Whether translator is locked

Example: false

volumeLockbooleanrequired

Whether volume is locked

Example: false

writerLockbooleanrequired

Whether writer is locked

Example: false

yearLockbooleanrequired

Whether year is locked

Example: true

mangaboolean | nullnullable

Whether the book is manga format

Example: false

monthinteger,null<int32>nullable

Publication month (1-12)

Example: 2

numberstring | nullnullable

Chapter/book number

Example: 1

originalTitlestring | nullnullable

Original title (for translated works)

Example: 火星の人

originalYearinteger,null<int32>nullable

Original publication year (for re-releases or translations)

Example: 2011

pencillerstring | nullnullable

Penciller(s)

Example: David Mazzucchelli

pencillersstring[]required

Pencillers as array

publisherstring | nullnullable

Publisher name

Example: DC Comics

releaseDatestring,null<date-time>nullable

Release/publication date

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

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.

titlestring | nullnullable

Book title from metadata

Example: Batman: Year One #1

titleSortstring | nullnullable

Sort title for ordering

Example: batman year one 001

translatorstring | nullnullable

Translator name

Example: John Smith

updatedAtstring<date-time>required

When the metadata was last updated

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

volumeinteger,null<int32>nullable

Volume number

Example: 1

writerstring | nullnullable

Writer(s)

Example: Frank Miller

writersstring[]required

Writers as array

yearinteger,null<int32>nullable

Publication year

Example: 1987

numberinteger,null<int32>nullable

Book number within the series

Example: 1

pageCountinteger<int32>required

Number of pages in the book

Example: 32

readProgress object

oneOf

• null
• ReadProgressResponse

null

readingDirectionstring | nullnullable

Effective reading direction (from series metadata, or library default)

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

tags object[]required

Tags assigned to this book

Array [

createdAtstring<date-time>required

When the tag was created

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

idstring<uuid>required

Tag ID

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

namestringrequired

Tag name

Example: Completed

seriesCountinteger,null<int64>nullable

Number of series with this tag

Possible values: >= 0

Example: 15

]

titlestringrequired

Book title (display name)

Example: Batman: Year One #1

titleSortstring | nullnullable

Title used for sorting

Example: batman year one 001

updatedAtstring<date-time>required

When the book was last updated

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

FullBookResponse

{
  "analysisError": "Failed to parse CBZ: invalid archive",
  "analyzed": true,
  "createdAt": "2024-01-01T00:00:00Z",
  "deleted": false,
  "fileFormat": "cbz",
  "fileHash": "a1b2c3d4e5f6g7h8i9j0",
  "filePath": "/media/comics/Batman/Batman - Year One 001.cbz",
  "fileSize": 52428800,
  "genres": [
    {
      "createdAt": "2024-01-01T00:00:00Z",
      "id": "550e8400-e29b-41d4-a716-446655440010",
      "name": "Action",
      "seriesCount": 42
    }
  ],
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "libraryId": "550e8400-e29b-41d4-a716-446655440000",
  "libraryName": "Comics",
  "metadata": {
    "authors": [
      {
        "name": "Andy Weir",
        "role": "author",
        "sortName": "Weir, Andy"
      }
    ],
    "awards": [
      {
        "category": "Best Novel",
        "name": "Hugo Award",
        "won": true,
        "year": 2015
      }
    ],
    "blackAndWhite": false,
    "bookType": "null",
    "colorist": "Richmond Lewis",
    "colorists": [
      "string"
    ],
    "count": 4,
    "coverArtist": "David Mazzucchelli",
    "coverArtists": [
      "string"
    ],
    "createdAt": "2024-01-01T00:00:00Z",
    "customMetadata": "Unknown Type: object,null",
    "day": 1,
    "edition": "First Edition",
    "editor": "Dennis O'Neil",
    "editors": [
      "string"
    ],
    "formatDetail": "Trade Paperback",
    "genre": "Superhero",
    "imprint": "DC Black Label",
    "inker": "David Mazzucchelli",
    "inkers": [
      "string"
    ],
    "isbns": "978-1401207526",
    "languageIso": "en",
    "letterer": "Todd Klein",
    "letterers": [
      "string"
    ],
    "locks": {
      "authorsJsonLock": false,
      "awardsJsonLock": false,
      "blackAndWhiteLock": false,
      "bookTypeLock": false,
      "coloristLock": false,
      "countLock": false,
      "coverArtistLock": false,
      "coverLock": false,
      "customMetadataLock": false,
      "dayLock": false,
      "editionLock": false,
      "editorLock": false,
      "formatDetailLock": false,
      "genreLock": false,
      "imprintLock": false,
      "inkerLock": false,
      "isbnsLock": false,
      "languageIsoLock": false,
      "lettererLock": false,
      "mangaLock": false,
      "monthLock": false,
      "numberLock": false,
      "originalTitleLock": false,
      "originalYearLock": false,
      "pencillerLock": false,
      "publisherLock": true,
      "seriesPositionLock": false,
      "seriesTotalLock": false,
      "subjectsLock": false,
      "subtitleLock": false,
      "summaryLock": false,
      "titleLock": false,
      "titleSortLock": false,
      "translatorLock": false,
      "volumeLock": false,
      "writerLock": false,
      "yearLock": true
    },
    "manga": false,
    "month": 2,
    "number": "1",
    "originalTitle": "火星の人",
    "originalYear": 2011,
    "penciller": "David Mazzucchelli",
    "pencillers": [
      "string"
    ],
    "publisher": "DC Comics",
    "releaseDate": "1987-02-01T00:00:00Z",
    "seriesPosition": 1,
    "seriesTotal": 3,
    "subjects": [
      "Science Fiction",
      "Space Exploration",
      "Survival"
    ],
    "subtitle": "A Novel",
    "summary": "Bruce Wayne returns to Gotham City after years abroad.",
    "title": "Batman: Year One #1",
    "titleSort": "batman year one 001",
    "translator": "John Smith",
    "updatedAt": "2024-01-15T10:30:00Z",
    "volume": 1,
    "writer": "Frank Miller",
    "writers": [
      "string"
    ],
    "year": 1987
  },
  "number": 1,
  "pageCount": 32,
  "readProgress": "null",
  "readingDirection": "ltr",
  "seriesId": "550e8400-e29b-41d4-a716-446655440002",
  "seriesName": "Batman: Year One",
  "tags": [
    {
      "createdAt": "2024-01-01T00:00:00Z",
      "id": "550e8400-e29b-41d4-a716-446655440020",
      "name": "Completed",
      "seriesCount": 15
    }
  ],
  "title": "Batman: Year One #1",
  "titleSort": "batman year one 001",
  "updatedAt": "2024-01-15T10:30:00Z"
}