description:Get a book by its ID. This endpoint returns all of the information needed for the book details page and editing.
tags:
- Book
responses:
'200':
description:OK
content:
application/json:
schema:
$ref:'#/components/schemas/bookObject'
'404':
$ref:'#/components/responses/notFound'
post:
operationId:updateBookById
summary:Update book by ID
description:Update a book by its ID. The request body should contain only the fields that need to be updated. If a field should be cleared, the field should exist and have a value of `null`. At least one field must be present.
tags:
- Book
requestBody:
content:
application/json:
schema:
type:object
properties:
title:
$ref:'#/components/schemas/titleNullable'
subtitle:
$ref:'#/components/schemas/subtitle'
authors:
$ref:'#/components/schemas/authorNameArray'
narrators:
$ref:'#/components/schemas/narratorNameArray'
description:
$ref:'#/components/schemas/description'
genres:
$ref:'#/components/schemas/genreArray'
tags:
$ref:'#/components/schemas/tagArray'
series:
$ref:'#/components/schemas/seriesSequenceArray'
publishYear:
$ref:'#/components/schemas/publishYear'
publisher:
$ref:'#/components/schemas/publisher'
isbn:
$ref:'#/components/schemas/isbn'
asin:
$ref:'#/components/schemas/asin'
required:true
responses:
'200':
description:OK
content:
application/json:
schema:
$ref:'#/components/schemas/bookObject'
'400':
$ref:'#/components/responses/badRequest'
'403':
$ref:'#/components/responses/forbidden'
'404':
$ref:'#/components/responses/notFound'
delete:
operationId:deleteBookById
summary:Remove book by ID
description:Remove the book and associated entries from the database. This does not delete any files from the filesystem. If files should be deleted, use the `/api/book/{id}/hardDelete` endpoint instead.
tags:
- Book
responses:
'200':
description:OK
content:
application/json:
schema:
$ref:'#/components/schemas/bookObject'
'403':
$ref:'#/components/responses/forbidden'
'404':
$ref:'#/components/responses/notFound'
/api/book/{id}/hardDelete:
parameters:
- name:id
in:path
required:true
description:The ID of the book.
schema:
type:string
format:uuid
delete:
operationId:hardDeleteBookById
summary:Hard delete book by ID
description:Hard delete the book and associated entries from the database. This deletes the book's files from the filesystem. This action cannot be undone.
tags:
- Book
responses:
'200':
description:OK
content:
application/json:
schema:
$ref:'#/components/schemas/bookObject'
'403':
$ref:'#/components/responses/forbidden'
'404':
$ref:'#/components/responses/notFound'
/api/book/{id}/download:
parameters:
- name:id
in:path
required:true
description:The ID of the book.
schema:
type:string
format:uuid
get:
operationId:downloadBookById
summary:Download book by ID
description:Download the book by its ID. This endpoint will return the book's files as a zip archive.
tags:
- Book
responses:
'200':
description:OK
content:
application/zip:
schema:
type:string
format:binary
'403':
$ref:'#/components/responses/forbidden'
'404':
$ref:'#/components/responses/notFound'
/api/book/{id}/cover:
parameters:
- name:id
in:path
required:true
description:The ID of the book.
schema:
type:string
format:uuid
get:
operationId:getBookCoverById
summary:Get book cover by ID
description:Get the book cover by its ID. This endpoint will return the book's cover image. If no query parameters are provided, the image will be returned in the original format with the original dimensions.
tags:
- Book
parameters:
- name:width
in:query
required:false
description:The width of the image in pixels.
schema:
type:integer
minimum:1
- name:height
in:query
required:false
description:The height of the image in pixels. If this parameter is not provided, the image will be scaled proportionally to the width.
schema:
type:integer
minimum:1
- name:format
in:query
required:false
description:The format of the image. If not provided, the image will be returned in the original format.
schema:
type:string
enum:['jpeg','png','webp']
default:'jpeg'
responses:
'200':
description:OK
content:
image/jpeg:
schema:
type:string
format:binary
image/png:
schema:
type:string
format:binary
image/webp:
schema:
type:string
format:binary
'403':
$ref:'#/components/responses/forbidden'
'404':
$ref:'#/components/responses/notFound'
post:
operationId:uploadBookCoverById
summary:Upload book cover by ID
description:Upload the book cover image to the book by the book ID. This endpoint will replace the book's cover image with the provided image. The image should be in JPEG, PNG, or WebP format. Alternatively, the image can be provided as a URL to download the image from.
tags:
- Book
requestBody:
content:
multipart/form-data:
schema:
type:object
properties:
cover:
type:string
format:binary
application/json:
schema:
type:object
properties:
url:
type:string
description:The URL to download the image from.
format:uri
required:true
responses:
'200':
description:OK
content:
application/json:
schema:
properties:
coverPath:
$ref:'#/components/schemas/imagePath'
success:
type:boolean
'400':
$ref:'#/components/responses/badRequest'
'403':
$ref:'#/components/responses/forbidden'
'404':
$ref:'#/components/responses/notFound'
patch:
operationId:updateBookCoverById
summary:Update book cover by ID
description:Update the book cover to be an existing image in the database. This endpoint will replace the book's cover image with the provided image. The image should be in JPEG, PNG, or WebP format.
tags:
- Book
requestBody:
content:
application/json:
schema:
type:object
properties:
coverId:
$ref:'#/components/schemas/itemId'
required:true
responses:
'200':
description:OK
content:
application/json:
schema:
properties:
coverPath:
$ref:'#/components/schemas/imagePath'
success:
type:boolean
'400':
$ref:'#/components/responses/badRequest'
'403':
$ref:'#/components/responses/forbidden'
'404':
$ref:'#/components/responses/notFound'
delete:
operationId:deleteBookCoverById
summary:Remove book cover by ID
description:Remove the book cover image from the book. The cover image file is not deleted but is no longer associated with the book.
tags:
- Book
responses:
'200':
description:OK
content:
application/json:
schema:
properties:
coverPath:
$ref:'#/components/schemas/imagePath'
success:
type:boolean
'403':
$ref:'#/components/responses/forbidden'
'404':
$ref:'#/components/responses/notFound'
/api/book/{id}/match:
parameters:
- name:id
in:path
required:true
description:The ID of the book.
schema:
type:string
format:uuid
post:
operationId:matchBookById
summary:Match book by ID
description:Match the book selected by ID against an online database. This performs a quick match against the online database and returns the best match. Quick match will apply the cover from the first match and fill empty metadata fields. Metadata fields are not overwritten unless the "Prefer Matched Metadata" setting is enabled or the "force" query is set.
tags:
- Book
parameters:
- in:query
name:force
required:false
description:Whether to force the match and overwrite all metadata fields.
schema:
type:boolean
default:false
- in:query
name:provider
required:false
description:The provider to use for the match. If not provided, the default library provider will be used.
schema:
type:string
enum:['google','openlibrary','goodreads']
- in:query
name:title
required:false
description:The title of the book to match.
schema:
type:string
- in:query
name:author
required:false
description:The author of the book to match.
schema:
type:string
- in:query
name:isbn
required:false
description:The ISBN of the book to match.
schema:
type:string
- in:query
name:asin
required:false
description:The ASIN of the book to match. Note that this needs to match the Audible page, not the Amazon page.
schema:
type:string
responses:
'200':
description:OK
content:
application/json:
schema:
allOf:
- $ref:'#/components/schemas/bookObject'
- type:object
properties:
updated:
type:boolean
description:Whether the book was updated with the match.
'403':
$ref:'#/components/responses/forbidden'
'404':
$ref:'#/components/responses/notFound'
/api/book/{id}/tracks:
parameters:
- name:id
in:path
required:true
description:The ID of the book.
schema:
type:string
format:uuid
patch:
operationId:updateBookTracksById
summary:Update book tracks
description:Update the book's audio tracks based on the provided file IDs. This endpoint will replace the book's audio tracks with the provided tracks. The tracks should be in the correct order.
tags:
- Book
requestBody:
content:
application/json:
schema:
type:object
properties:
trackIds:
type:array
description:The IDs of the audio files to use as tracks.
items:
$ref:'#/components/schemas/itemId'
required:true
responses:
'200':
description:OK
content:
application/json:
schema:
$ref:'#/components/schemas/bookObject'
'400':
$ref:'#/components/responses/badRequest'
'403':
$ref:'#/components/responses/forbidden'
'404':
$ref:'#/components/responses/notFound'
/api/book/{id}/scan:
parameters:
- name:id
in:path
required:true
description:The ID of the book.
schema:
type:string
format:uuid
post:
operationId:scanBookById
summary:Scan book by ID
description:Scan the book by its ID. This endpoint will scan the book's files and update the book's metadata based on the files found according to the metadata priority settings.
description:Get a podcast by its ID. This endpoint returns all of the information needed for the podcast details page and editing, but does not include file information or podcast episode information.
tags:
- Podcast
responses:
'200':
description:OK
content:
application/json:
schema:
$ref:'#/components/schemas/podcastObject'
'404':
$ref:'#/components/responses/notFound'
post:
operationId:updatePodcastById
summary:Update podcast by ID
description:Update a podcast by its ID. The request body should contain only the fields that need to be updated. If a field should be cleared, the field should exist and have a value of `null`. At least one field must be present.
tags:
- Podcast
requestBody:
content:
application/json:
schema:
type:object
properties:
title:
$ref:'#/components/schemas/titleNullable'
author:
type:string
description:The author or publisher of the podcast.
description:Remove the podcast and associated entries from the database. This does not delete any files from the filesystem.
tags:
- Podcast
responses:
'200':
description:OK
content:
application/json:
schema:
$ref:'#/components/schemas/podcastObject'
'403':
$ref:'#/components/responses/forbidden'
'404':
$ref:'#/components/responses/notFound'
/api/podcast/{id}/hardDelete:
parameters:
- name:id
in:path
required:true
description:The ID of the podcast.
schema:
type:string
format:uuid
delete:
operationId:hardDeletePodcastById
summary:Hard delete podcast by ID
description:Hard delete the podcast and associated entries from the database. This deletes the podcast's files from the filesystem. This action cannot be undone.
tags:
- Podcast
responses:
'200':
description:OK
content:
application/json:
schema:
$ref:'#/components/schemas/podcastObject'
'403':
$ref:'#/components/responses/forbidden'
'404':
$ref:'#/components/responses/notFound'
/api/podcast/{id}/download:
parameters:
- name:id
in:path
required:true
description:The ID of the podcast.
schema:
type:string
format:uuid
get:
operationId:downloadPodcastById
summary:Download podcast by ID
description:Download the podcast by its ID. This endpoint will return the podcast's files as a zip archive.
tags:
- Podcast
responses:
'200':
description:OK
content:
application/zip:
schema:
type:string
format:binary
'403':
$ref:'#/components/responses/forbidden'
'404':
$ref:'#/components/responses/notFound'
/api/podcast/{id}/cover:
parameters:
- name:id
in:path
required:true
description:The ID of the podcast.
schema:
type:string
format:uuid
get:
operationId:getPodcastCoverById
summary:Get podcast cover by ID
description:Get the podcast cover by its ID. This endpoint will return the podcast's cover image. If no query parameters are provided, the image will be returned in the original format with the original dimensions.
tags:
- Podcast
parameters:
- name:width
in:query
required:false
description:The width of the image in pixels.
schema:
type:integer
minimum:1
- name:height
in:query
required:false
description:The height of the image in pixels. If this parameter is not provided, the image will be scaled proportionally to the width.
schema:
type:integer
minimum:1
- name:format
in:query
required:false
description:The format of the image. If not provided, the image will be returned in the original format.
schema:
type:string
enum:['jpeg','png','webp']
default:'jpeg'
responses:
'200':
description:OK
content:
image/jpeg:
schema:
type:string
format:binary
image/png:
schema:
type:string
format:binary
image/webp:
schema:
type:string
format:binary
'403':
$ref:'#/components/responses/forbidden'
'404':
$ref:'#/components/responses/notFound'
post:
operationId:uploadPodcastCoverById
summary:Upload podcast cover by ID
description:Upload the podcast cover image to the podcast by the podcast ID. This endpoint will replace the podcast's cover image with the provided image. The image should be in JPEG, PNG, or WebP format. Alternatively, the image can be provided as a URL to download the image from.
tags:
- Podcast
requestBody:
content:
multipart/form-data:
schema:
type:object
properties:
cover:
type:string
format:binary
application/json:
schema:
type:object
properties:
url:
type:string
description:The URL to download the image from.
format:uri
required:true
responses:
'200':
description:OK
content:
application/json:
schema:
properties:
coverPath:
$ref:'#/components/schemas/imagePath'
success:
type:boolean
'400':
$ref:'#/components/responses/badRequest'
'403':
$ref:'#/components/responses/forbidden'
'404':
$ref:'#/components/responses/notFound'
patch:
operationId:updatePodcastCoverById
summary:Update podcast cover by ID
description:Update the podcast cover to be an existing image in the database. This endpoint will replace the podcast's cover image with the provided image. The image should be in JPEG, PNG, or WebP format.
tags:
- Podcast
requestBody:
content:
application/json:
schema:
type:object
properties:
coverId:
$ref:'#/components/schemas/itemId'
required:true
responses:
'200':
description:OK
content:
application/json:
schema:
properties:
coverPath:
$ref:'#/components/schemas/imagePath'
success:
type:boolean
'400':
$ref:'#/components/responses/badRequest'
'403':
$ref:'#/components/responses/forbidden'
'404':
$ref:'#/components/responses/notFound'
delete:
operationId:deletePodcastCoverById
summary:Remove podcast cover by ID
description:Remove the podcast cover image from the podcast. The cover image file is not deleted but is no longer associated with the podcast.
tags:
- Podcast
responses:
'200':
description:OK
content:
application/json:
schema:
properties:
coverPath:
$ref:'#/components/schemas/imagePath'
success:
type:boolean
'403':
$ref:'#/components/responses/forbidden'
'404':
$ref:'#/components/responses/notFound'
/api/podcast/{id}/match:
parameters:
- name:id
in:path
required:true
description:The ID of the podcast.
schema:
type:string
format:uuid
post:
operationId:matchPodcastById
summary:Match podcast by ID
description:Match the podcast selected by ID against an online database. This returns an array of possible matches. The user can select the best match from the list and select which metadata fields should be kept.
tags:
- Podcast
parameters:
- in:query
name:provider
required:false
description:The provider to use for the match. If not provided, the default library provider will be used.
schema:
type:string
enum:['itunes','google','podcastindex']
- in:query
name:rssFeed
required:false
description:The RSS feed of the podcast to match.
schema:
type:string
- in:query
name:title
required:false
description:The title of the podcast to match.
schema:
type:string
- in:query
name:itunesId
required:false
description:The iTunes ID of the podcast to match.
schema:
type:string
responses:
'200':
description:OK
content:
application/json:
schema:
type:array
items:
$ref:'#/components/schemas/podcastMatchObject'
'403':
$ref:'#/components/responses/forbidden'
'404':
$ref:'#/components/responses/notFound'
/api/podcast/{id}/tracks:
parameters:
- name:id
in:path
required:true
description:The ID of the podcast.
schema:
type:string
format:uuid
get:
operationId:getPodcastTracksById
summary:Get podcast tracks by ID
description:Get the podcast's audio tracks by its ID. This endpoint will return the podcast's audio tracks.
tags:
- Podcast
responses:
'200':
description:OK
content:
application/json:
schema:
type:array
items:
$ref:'#/components/schemas/audioTrack'
'404':
$ref:'#/components/responses/notFound'
patch:
operationId:updatePodcastTracksById
summary:Update podcast tracks by ID
description:Update the podcast's audio tracks based on the provided file IDs. This endpoint will replace the podcast's audio tracks with the provided tracks. The tracks should be in the correct order.
tags:
- Podcast
requestBody:
content:
application/json:
schema:
type:object
properties:
trackIds:
type:array
description:The IDs of the audio files to use as tracks.
items:
$ref:'#/components/schemas/itemId'
required:true
responses:
'200':
description:OK
content:
application/json:
schema:
$ref:'#/components/schemas/podcastObject'
'400':
$ref:'#/components/responses/badRequest'
'403':
$ref:'#/components/responses/forbidden'
'404':
$ref:'#/components/responses/notFound'
/api/podcast/{id}/scan:
parameters:
- name:id
in:path
required:true
description:The ID of the podcast.
schema:
type:string
format:uuid
post:
operationId:scanPodcastById
summary:Scan podcast by ID
description:Scan the podcast by its ID. This endpoint will scan the podcast's files and update the podcast's metadata based on the files found according to the metadata priority settings.
tags:
- Podcast
responses:
'200':
description:OK
content:
application/json:
schema:
$ref:'#/components/schemas/podcastObject'
'403':
$ref:'#/components/responses/forbidden'
'404':
$ref:'#/components/responses/notFound'
/api/podcast/{id}/episodes:
parameters:
- name:id
in:path
required:true
description:The ID of the podcast.
schema:
type:string
format:uuid
get:
operationId:getPodcastEpisodesById
summary:Get podcast episodes by ID
description:Get the podcast's episodes by its ID. This endpoint will return the podcast's episodes.
tags:
- Podcast
parameters:
- in:query
name:limit
required:true
description:The maximum number of episodes to return. This defines the page size
schema:
type:integer
minimum:1
default:20
- in:query
name:page
required:true
description:The page of episodes to return. This is used in conjunction with the limit parameter.
