openapi: 3.0.0 info: title: Audiobookshelf API version: 0.2.0 description: Audiobookshelf API with autogenerated OpenAPI doc license: name: GPL-3.0 url: 'https://www.gnu.org/licenses/gpl-3.0.html' servers: - url: http://abs.mydomain.com:13378 description: Development server security: - BearerAuth: [] components: securitySchemes: BearerAuth: description: Bearer authentication type: http scheme: bearer parameters: pathLibraryId: name: id in: path required: true description: The ID of the library. schema: type: string format: uuid pathUserId: name: id in: path required: true description: The ID of the user. schema: type: string format: uuid pathBookId: name: id in: path required: true description: The ID of the book. schema: type: string format: uuid pathSeriesId: name: id in: path required: true description: The ID of the series. schema: type: string format: uuid pathPodcastId: name: id in: path required: true description: The ID of the podcast. schema: type: string format: uuid pathPodcastEpisodeId: name: id in: path required: true description: The ID of the podcast episode. schema: type: string format: uuid pathItemId: name: id in: path required: true description: The ID of the item. This ID can be a book, series, or podcast episode. schema: type: string format: uuid pathItemSubId: name: itemId in: path required: true description: The ID of the sub-item. This ID can be a book, series, or podcast episode. schema: type: string format: uuid pathCollectionId: name: id in: path required: true description: The ID of the collection. schema: type: string format: uuid pathPlaylistId: name: id in: path required: true description: The ID of the playlist. schema: type: string format: uuid pathAuthorId: name: id in: path required: true description: The ID of the author. schema: type: string format: uuid pathNarratorId: name: id in: path required: true description: The ID of the narrator. schema: type: string format: uuid pathFeedId: name: id in: path required: true description: The ID of the feed. schema: type: string format: uuid pathFeedSlug: name: slug in: path required: true description: The slug of the feed. schema: type: string pathBackupId: name: id in: path required: true description: The ID of the backup. schema: type: string format: uuid queryLimit: name: limit in: query required: false description: The number of items per page. schema: type: integer minimum: 1 default: 20 queryPage: name: page in: query required: false description: The page number of items to return. The first page is 1, and the page size is determined by the limit parameter. schema: type: integer minimum: 1 default: 1 querySubObjectLimit: name: subObjectLimit in: query required: false description: The number of sub-objects to return. If null, return all sub-objects. schema: type: integer minimum: 1 queryDesc: name: desc in: query required: false description: Whether to sort the items in descending order. schema: type: boolean default: false queryFilterGenre: name: genre in: query required: false description: The genre ID to filter by. schema: type: string format: uuid queryFilterTag: name: tag in: query required: false description: The tag ID to filter by. schema: type: string format: uuid queryFilterAuthor: name: author in: query required: false description: The author ID to filter by. schema: type: string format: uuid queryFilterNarrator: name: narrator in: query required: false description: The narrator ID to filter by. schema: type: string format: uuid queryFilterPublisher: name: publisher in: query required: false description: The publisher name to filter by. schema: type: string queryFilterSeries: name: series in: query required: false description: The series ID to filter by. schema: type: string format: uuid queryFilterLanguage: name: language in: query required: false description: The language to filter by. schema: type: string queryFilterProgress: name: progress in: query required: false description: The progress to filter by. schema: type: string enum: ['not-started', 'in-progress', 'completed', 'not-completed'] queryHideContinueListening: name: hideFromContinueListening in: query required: false description: Do not include items which are removed from the "Continue Listening" list. True to hide, false to show. schema: type: boolean default: false queryProgressItemType: name: progressItemType in: query required: false description: The type of item to filter by progress. If not provided, return all items in progress. schema: type: string enum: ['book', 'series', 'podcast-episode'] queryFilterMissing: name: missing in: query required: false description: Which fields to filter by missing values. schema: type: string enum: ['asin', 'isbn', 'author', 'title', 'subtitle', 'publish-year', 'series', 'description', 'genre', 'tag', 'narrator', 'publisher', 'language', 'cover'] queryFilterTrackCount: name: trackCount in: query required: false description: Filter if the book has a single audio file, multiple audio files, or no audio files (ebook). schema: type: string enum: ['single', 'multiple', 'none'] queryFilterEbook: name: ebook in: query required: false description: Filter by presence or abscence of ebook files. schema: type: string enum: ['has-ebook', 'no-ebook', 'has-primary', 'no-primary', 'has-supplementary', 'no-supplementary'] queryFilterAbridged: name: abridged in: query required: false description: Filter by abridged or unabridged books. schema: type: boolean queryFilterExplicit: name: explicit in: query required: false description: Filter by explicit or non-explicit content. schema: type: boolean queryFilterIssues: name: issues in: query required: false description: Filter by books with issues. schema: type: boolean queryFilterFeedOpen: name: feedOpen in: query required: false description: Filter by books with open feeds. schema: type: boolean queryFilterShareOpen: name: shareOpen in: query required: false description: Filter by books with open shares. schema: type: boolean querySortBooks: name: sort in: query required: false description: The field to sort the books by. schema: type: string enum: ['title', 'publishYear', 'author-fl', 'author-lf', 'size', 'duration', 'progress', 'file-birthtime', 'file-mtime', 'random'] default: 'title' querySortPodcasts: name: sort in: query required: false description: The field to sort the podcasts by. schema: type: string enum: ['title', 'author', 'created', 'size', 'episodeCount', 'random'] default: 'title' querySortSeries: name: sort in: query required: false description: The field to sort the series by. schema: type: string enum: ['title', 'bookCount', 'duration', 'lastbook-added', 'lastbook-updated', 'createdAt', 'random'] default: 'title' querySortCollections: name: sort in: query required: false description: The field to sort the collections by. schema: type: string enum: ['title', 'bookCount', 'duration', 'lastbook-added', 'lastbook-updated', 'createdAt', 'random'] default: 'title' querySortPlaylists: name: sort in: query required: false description: The field to sort the playlists by. schema: type: string enum: ['title', 'bookCount', 'duration', 'lastbook-added', 'lastbook-updated', 'createdAt', 'random'] default: 'title' querySortAuthors: name: sort in: query required: false description: The field to sort the authors by. schema: type: string enum: ['author-fl', 'author-lf', 'bookCount', 'seriesCount', 'updatedAt', 'createdAt', 'random'] default: 'author-fl' querySortUsers: name: sort in: query required: false description: The field to sort the users by. schema: type: string enum: ['username', 'email', 'createdAt', 'updatedAt', 'hasOpenId', 'accountType', 'isEnabled'] default: 'username' querySortProgress: name: sort in: query required: false description: The field to sort the progress by. schema: type: string enum: ['progress', 'createdAt', 'updatedAt'] default: 'updatedAt' queryAuthorName: name: name in: query required: false description: The name of the author. schema: type: string queryAsin: name: asin in: query required: false description: The ASIN of the book or author. schema: type: string queryRegion: name: region in: query required: false description: The region to search for the book or author. schema: type: string schemas: itemId: type: string description: A unique ID for the item. This ID is unique across all tables. format: uuid mediaType: type: string description: The type of media that the library contains. Will be `book` or `podcast`. enum: ['book', 'podcast'] libraryProvider: type: string description: Preferred metadata provider for the library. createdAt: type: number description: The date and time the item was created in ms since POSIX epoch. updatedAt: type: number description: The date and time the item was last updated in ms since POSIX epoch. userPermissions: type: object description: The permissions of the user. properties: download: type: boolean description: Whether the user can download files. update: type: boolean description: Whether the user can update metadata. delete: type: boolean description: Whether the user can delete the item. upload: type: boolean description: Whether the user can upload files. accessAllLibraries: type: boolean description: Whether the user can access all libraries. accessAllTags: type: boolean description: Whether the user can access all tags. accessExplicitContent: type: boolean description: Whether the user can access explicit content. selectedTagsAccessible: type: boolean description: Whether the user can access selected tags. If false, invert so selected tags are not accessible. duration: type: number description: The length of the item in seconds. Will be 0 if no audio is associated with the item. bitrate: type: number description: The bitrate of the audio file. progress: type: number description: The user's progress through the media. Will be 1.0 if completed, and 0.0 or null if not started. nullable: true size: type: integer description: The size of the item in bytes. trackCount: type: integer description: The number of tracks in the podcast. title: type: string description: The title of the item. titleNullable: type: string description: The title of the item. nullable: true subtitle: type: string description: The subtitle of the item. nullable: true description: type: string description: The description of the item. nullable: true isExplicit: type: boolean description: Whether the item contains explicit content. isAbridged: type: boolean description: Whether the item is abridged. seriesSequence: type: object description: The series name and sequence number of the item. properties: seriesId: $ref: '#/components/schemas/itemId' title: $ref: '#/components/schemas/title' sequence: type: string description: The sequence number of the item in the series. If the item does not have a specific sequence, this will be null. nullable: true seriesSequenceArray: type: array description: An array of series names and sequence numbers associated with the item. nullable: true items: $ref: '#/components/schemas/seriesSequence' imagePath: type: string description: The absolute path of the image on the server. Null if no image is associated with the item. nullable: true folderPath: type: string description: The absolute path of the folder on the server. folderArray: type: array description: An array of folders associated with the item. items: $ref: '#/components/schemas/folderPath' filePath: type: string description: The absolute path of the file on the server. bookPerson: type: object description: A person associated with a book. properties: personId: $ref: '#/components/schemas/itemId' name: type: string description: The name of the person. authorObjectArray: type: array description: An array of author objects associated with a book. nullable: true items: $ref: '#/components/schemas/bookPerson' authorName: type: string description: The name of an author associated with a book. narratorName: type: string description: The name of a narrator associated with a book. authorNameArray: type: array description: An array of author names associated with a book. nullable: true items: type: string narratorObjectArray: type: array description: An array of narrator objects associated with a book. nullable: true items: $ref: '#/components/schemas/bookPerson' narratorNameArray: type: array description: An array of narrator names associated with a book. nullable: true items: type: string publisher: type: string description: The publisher of the book. nullable: true publishDate: type: string description: The date the item was published. nullable: true publishYear: type: integer description: The year the book was published. nullable: true isbn: type: string description: The ISBN of the book. nullable: true asin: type: string description: The ASIN of the book. nullable: true genre: type: string description: The genre of the item. nullable: true genreArray: type: array description: An array of genres associated with the item. nullable: true items: $ref: '#/components/schemas/genre' tag: type: string description: The tag of the item. nullable: true tagArray: type: array description: An array of tags associated with the item. nullable: true items: $ref: '#/components/schemas/tag' language: type: string description: The language of the item. nullable: true feedUrl: type: string description: The RSS feed hosted by ABS. feedItemType: type: string description: The type of media in the feed. enum: ['book', 'collection', 'series', 'podcast'] feedOwnerName: type: string description: The owner of the feed. feedOwnerEmail: type: string description: The email of the feed owner. feedPreventIndexing: type: boolean description: Whether the feed should be indexed by search engines. feedSlug: type: string description: The slug of the feed. By default this is a custom UUID, but can be any valid URL slug. hasFeedOpen: type: boolean description: Whether the item has an open feed. episodeUrl: type: string description: The URL of the podcast episode. format: uri rssFeed: type: string description: The RSS feed of the podcast. nullable: true imageUrl: type: string description: The URL of the image to download. format: uri itunesId: type: string description: The iTunes ID of the podcast. nullable: true podcastType: type: string description: The type of podcast. enum: ['episodic', 'serial'] episodeNumber: type: integer nullable: true description: The episode number of the podcast. seasonNumber: type: integer nullable: true description: The season number of the podcast. episodeType: type: string description: The type of episode. enum: ['full', 'trailer', 'bonus', 'teaser', 'sponsored', 'patron'] autoDownloadEnabled: type: boolean description: Whether auto-download is enabled for the podcast. autoDownloadSchedule: type: string description: The cron expression of when to check for new episodes to auto-download from the RSS feed for the podcast. example: '0 0 * * *' nullable: true lastEpisodeCheck: type: string description: The date and time the podcast was last checked for new episodes. nullable: true maxEpisodesToKeep: type: integer description: The maximum number of episodes to keep for the podcast. If zero, keep all episodes. default: 0 maxNewEpisodestoDownload: type: integer description: The maximum number of new episodes to download for the podcast. If zero, download all new episodes. default: 3 bookChapter: type: object description: A chapter in a book. properties: title: type: string description: The title of the chapter. start: type: number description: The start time of the chapter in seconds. end: type: number description: The end time of the chapter in seconds. chapterArray: type: array description: An array of chapters in a book. Will be null if the item has no chapters. nullable: true items: $ref: '#/components/schemas/bookChapter' fileType: type: string description: The type of file. enum: ['audio', 'image', 'ebook', 'metadata'] file: type: object description: Any media or image file associated with a book or podcast. properties: fileId: $ref: '#/components/schemas/itemId' path: $ref: '#/components/schemas/filePath' fileName: type: string description: The name of the file. size: $ref: '#/components/schemas/size' duration: $ref: '#/components/schemas/duration' fileType: $ref: '#/components/schemas/fileType' libraryIcon: type: string description: The icon of the library. enum: ['database', 'audiobookshelf', 'books-1', 'books-2', 'book-1', 'microphone-1', 'microphone-3', 'radio', 'podcast', 'rss', 'headphones', 'music', 'file-picture', 'rocket', 'power', 'star', 'heart'] libraryDisplayOrder: type: integer description: Display position of the library in the list of libraries. If the display order is higher than the number of libraries, the library will be placed at the end of the list. minimum: 1 libraryObject: type: object description: A library object which includes either books or podcasts. properties: id: $ref: '#/components/schemas/itemId' title: $ref: '#/components/schemas/title' folders: $ref: '#/components/schemas/folderArray' displayOrder: $ref: '#/components/schemas/libraryDisplayOrder' icon: $ref: '#/components/schemas/libraryIcon' mediaType: $ref: '#/components/schemas/mediaType' provider: $ref: '#/components/schemas/libraryProvider' settings: $ref: '#/components/schemas/librarySettings' librarySettings: type: object description: The settings for the library. properties: coverAspectRatio: type: number description: The aspect ratio of the cover image. default: 1 disableWatcher: type: boolean description: Whether to disable the folder watcher. skipMatchingMediaWithAsin: type: boolean description: Whether to skip matching media with an ASIN. skipMatchingMediaWithIsbn: type: boolean description: Whether to skip matching media with an ISBN. autoScanCronExpression: type: string description: The cron expression for when to automatically scan the library folders. nullable: true example: '0 1 * * *' audiobooksOnly: type: boolean description: Whether to only scan audiobooks. Ebook files cannot be primary, but can still be supplementary. epubsAllowScriptedContent: type: boolean description: Whether to allow scripted content in EPUB files. hideSingleBookSeries: type: boolean description: Whether to hide series with only one book. onlyShowLaterBooksInContinueSeries: type: boolean description: Whether to only show later books in a series when using the "Continue Series" option. metadataPrecedence: type: array description: The precedence of metadata sources. items: type: string enum: ['folderStructure', 'audioMetatags', 'nfoFile', 'txtFiles', 'opfFile', 'absMetadata'] podcastSearchRegion: type: string description: The region to use when searching for podcasts. example: 'us' audioFileCodec: type: string description: The codec of an audio file. audioTrack: type: object description: An audio track associated with a book. properties: fileId: $ref: '#/components/schemas/itemId' path: $ref: '#/components/schemas/filePath' fileName: type: string description: The name of the file. size: $ref: '#/components/schemas/size' duration: $ref: '#/components/schemas/duration' codec: $ref: '#/components/schemas/audioFileCodec' bitrate: $ref: '#/components/schemas/bitrate' ebookFile: type: object description: An ebook file associated with a book. properties: fileId: $ref: '#/components/schemas/itemId' path: $ref: '#/components/schemas/filePath' fileName: type: string description: The name of the file. isPrimary: type: boolean description: Whether the file is the primary ebook file. size: $ref: '#/components/schemas/size' displayBookObject: type: object description: A book object used for displaying items in a library. properties: bookId: $ref: '#/components/schemas/itemId' coverPath: $ref: '#/components/schemas/imagePath' title: $ref: '#/components/schemas/title' subtitle: $ref: '#/components/schemas/subtitle' authors: $ref: '#/components/schemas/authorNameArray' duration: $ref: '#/components/schemas/duration' size: $ref: '#/components/schemas/size' hasEbook: type: boolean description: Whether the book has an ebook example: true hasAudio: type: boolean description: Whether the book has audio example: true hasRss: $ref: '#/components/schemas/hasFeedOpen' explicit: $ref: '#/components/schemas/isExplicit' abridged: $ref: '#/components/schemas/isAbridged' extraInfo: type: string description: The extra info displayed when sorting or filtering. For example, the publish year. example: '2010' count: type: integer description: The number of books in the series when using the "Collapse Series" option. example: 4 progress: $ref: '#/components/schemas/progress' seriesDisplayObject: type: object description: A series object used for displaying items in a library. properties: seriesId: $ref: '#/components/schemas/itemId' title: $ref: '#/components/schemas/title' count: type: integer description: The number of books in the series. example: 10 books: type: array description: The books in the series. items: $ref: '#/components/schemas/displayBookObject' progress: $ref: '#/components/schemas/progress' bookCollectionDisplayObject: type: object description: A collection object used for displaying books in a library. properties: collectionId: $ref: '#/components/schemas/itemId' title: $ref: '#/components/schemas/title' count: type: integer description: The number of items in the collection. example: 10 duration: $ref: '#/components/schemas/duration' books: type: array description: The books in the collection. items: $ref: '#/components/schemas/displayBookObject' bookPlaylistDisplayObject: type: object description: A playlist object used for displaying books in a library. properties: playlistId: $ref: '#/components/schemas/itemId' title: $ref: '#/components/schemas/title' count: type: integer description: The number of items in the playlist. example: 10 duration: $ref: '#/components/schemas/duration' books: type: array description: The books in the playlist. items: $ref: '#/components/schemas/displayBookObject' podcastEpisodePlaylistDisplayObject: type: object description: A playlist object used for displaying episodes in a library. properties: playlistId: $ref: '#/components/schemas/itemId' title: $ref: '#/components/schemas/title' count: type: integer description: The number of items in the playlist. example: 10 duration: $ref: '#/components/schemas/duration' episodes: type: array description: The episodes in the playlist. items: $ref: '#/components/schemas/podcastEpisodeDisplayObject' podcastEpisodeCollectionDisplayObject: type: object description: A collection object used for displaying episodes in a library. properties: collectionId: $ref: '#/components/schemas/itemId' title: $ref: '#/components/schemas/title' count: type: integer description: The number of items in the collection. example: 10 duration: $ref: '#/components/schemas/duration' episodes: type: array description: The episodes in the collection. items: $ref: '#/components/schemas/podcastEpisodeDisplayObject' displayPodcastObject: type: object description: A podcast object used for displaying items in a library. properties: podcastId: $ref: '#/components/schemas/itemId' coverPath: $ref: '#/components/schemas/imagePath' title: $ref: '#/components/schemas/title' author: $ref: '#/components/schemas/authorName' explicit: $ref: '#/components/schemas/isExplicit' extraInfo: type: string description: The extra info displayed when sorting or filtering. For example, the publish year. example: '2010' count: type: integer description: The number of episodes in the podcast. example: 50 displayPodcastEpisodeObject: type: object description: A podcast episode object used for displaying episodes in a library. properties: episodeId: $ref: '#/components/schemas/itemId' podcastId: $ref: '#/components/schemas/itemId' coverPath: $ref: '#/components/schemas/imagePath' title: $ref: '#/components/schemas/title' description: $ref: '#/components/schemas/description' seasonNumber: $ref: '#/components/schemas/seasonNumber' episodeNumber: $ref: '#/components/schemas/episodeNumber' publishDate: type: integer description: The publish date of the podcast episode in ms since POSIX epoch. example: 1633522963509 duration: $ref: '#/components/schemas/duration' progress: $ref: '#/components/schemas/progress' authorObject: type: object description: Information about the author. properties: authorId: $ref: '#/components/schemas/itemId' name: $ref: '#/components/schemas/authorName' asin: $ref: '#/components/schemas/asin' description: $ref: '#/components/schemas/description' image: $ref: '#/components/schemas/imagePath' books: type: array description: The books written by the author. items: $ref: '#/components/schemas/displayBookObject' series: type: array description: The series written by the author. items: $ref: '#/components/schemas/seriesDisplayObject' authorDisplayObject: type: object description: An author object used for displaying in a library. properties: authorId: $ref: '#/components/schemas/itemId' name: $ref: '#/components/schemas/authorName' count: type: integer description: The number of books by the author. example: 10 narratorDisplayObject: type: object description: A narrator object used for displaying in a library. properties: narratorId: $ref: '#/components/schemas/itemId' name: type: string description: The name of the narrator. count: type: integer description: The number of books narrated by the narrator. example: 10 narratorObject: type: object description: Information about the narrator. properties: narratorId: $ref: '#/components/schemas/itemId' name: type: string description: The name of the narrator. books: type: array description: The books narrated by the narrator. items: $ref: '#/components/schemas/displayBookObject' bookObject: type: object description: Information about the book and its audio files. properties: coverPath: $ref: '#/components/schemas/imagePath' title: $ref: '#/components/schemas/title' subtitle: $ref: '#/components/schemas/subtitle' authors: $ref: '#/components/schemas/authorObjectArray' narrators: $ref: '#/components/schemas/narratorObjectArray' 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' language: $ref: '#/components/schemas/language' explicit: $ref: '#/components/schemas/isExplicit' abridged: $ref: '#/components/schemas/isAbridged' chapters: $ref: '#/components/schemas/chapterArray' files: type: array description: All files associated with the book. items: $ref: '#/components/schemas/file' audioTracks: type: array nullable: true description: The audio tracks of the book. Will be null if the book is an ebook. items: $ref: '#/components/schemas/audioTrack' ebookFiles: type: array nullable: true description: The ebook files of the book. Will be null if no ebooks are associated with the book. items: $ref: '#/components/schemas/ebookFile' hasFeedOpen: $ref: '#/components/schemas/hasFeedOpen' progress: $ref: '#/components/schemas/progress' duration: $ref: '#/components/schemas/duration' size: $ref: '#/components/schemas/size' podcastObject: type: object description: Information about the podcast. properties: coverPath: $ref: '#/components/schemas/imagePath' title: $ref: '#/components/schemas/title' author: type: string description: The author or publisher of the podcast. description: $ref: '#/components/schemas/description' duration: $ref: '#/components/schemas/duration' trackCount: $ref: '#/components/schemas/trackCount' size: $ref: '#/components/schemas/size' genres: $ref: '#/components/schemas/genreArray' tags: $ref: '#/components/schemas/tagArray' releaseDate: $ref: '#/components/schemas/publishDate' itunesId: type: string description: The iTunes ID of the podcast. language: $ref: '#/components/schemas/language' explicit: $ref: '#/components/schemas/isExplicit' hasFeedOpen: $ref: '#/components/schemas/hasFeedOpen' rssFeed: $ref: '#/components/schemas/rssFeed' type: $ref: '#/components/schemas/podcastType' autoDownloadEnabled: $ref: '#/components/schemas/autoDownloadEnabled' autoDownloadSchedule: $ref: '#/components/schemas/autoDownloadSchedule' lastEpisodeCheck: $ref: '#/components/schemas/lastEpisodeCheck' maxEpisodesToKeep: $ref: '#/components/schemas/maxEpisodesToKeep' maxNewEpisodestoDownload: $ref: '#/components/schemas/maxNewEpisodestoDownload' podcastMatchObject: type: object description: Match information for a podcast from an online provider. properties: id: type: integer description: The ID of the podcast. artistId: type: integer description: The ID of the artist. title: $ref: '#/components/schemas/title' artistName: $ref: '#/components/schemas/authorName' description: $ref: '#/components/schemas/description' releaseDate: $ref: '#/components/schemas/publishDate' genres: $ref: '#/components/schemas/genreArray' cover: $ref: '#/components/schemas/imagePath' trackCount: $ref: '#/components/schemas/trackCount' feedUrl: $ref: '#/components/schemas/rssFeed' pageUrl: type: string description: The URL of the podcast page. explicit: $ref: '#/components/schemas/isExplicit' podcastEpisodeDisplayObject: type: object description: An episode of a podcast, only includes the information needed to display the episode. properties: title: $ref: '#/components/schemas/title' description: $ref: '#/components/schemas/description' releaseDate: $ref: '#/components/schemas/publishDate' duration: $ref: '#/components/schemas/duration' size: $ref: '#/components/schemas/size' episodeNumber: $ref: '#/components/schemas/episodeNumber' seasonNumber: $ref: '#/components/schemas/seasonNumber' explicit: $ref: '#/components/schemas/isExplicit' coverPath: $ref: '#/components/schemas/imagePath' hasFeedOpen: $ref: '#/components/schemas/hasFeedOpen' progress: $ref: '#/components/schemas/progress' podcastEpisodeQueueObject: type: object description: An episode of a podcast, only includes the information needed to include the episode in the queue. properties: podcastId: $ref: '#/components/schemas/itemId' coverPath: $ref: '#/components/schemas/imagePath' episodeUrl: $ref: '#/components/schemas/episodeUrl' libraryId: $ref: '#/components/schemas/itemId' episodeTitle: $ref: '#/components/schemas/title' episodeNumber: $ref: '#/components/schemas/episodeNumber' releaseDate: $ref: '#/components/schemas/publishDate' podcastEpisodeObject: type: object description: An episode of a podcast. properties: episodeId: $ref: '#/components/schemas/itemId' podcastId: $ref: '#/components/schemas/itemId' title: $ref: '#/components/schemas/title' subtitle: $ref: '#/components/schemas/subtitle' description: $ref: '#/components/schemas/description' releaseDate: $ref: '#/components/schemas/publishDate' duration: $ref: '#/components/schemas/duration' size: $ref: '#/components/schemas/size' episodeType: $ref: '#/components/schemas/episodeType' episodeNumber: $ref: '#/components/schemas/episodeNumber' seasonNumber: $ref: '#/components/schemas/seasonNumber' explicit: $ref: '#/components/schemas/isExplicit' coverPath: $ref: '#/components/schemas/imagePath' rssFeed: $ref: '#/components/schemas/rssFeed' hasFeedOpen: $ref: '#/components/schemas/hasFeedOpen' ereaderName: type: string description: The name of the e-reader device. ereaderDeviceObject: type: object description: An e-reader device configured to receive EPUB through e-mail. properties: name: $ref: '#/components/schemas/ereaderName' email: type: string description: The email address associated with the e-reader device. availabilityOption: type: string description: The availability option for the device. enum: ['adminOrUp', 'userOrUp', 'guestOrUp', 'specificUsers'] users: type: array description: List of specific user ids allowed to access the device. items: type: string format: uuid required: - name - email - availabilityOption emailSettings: type: object description: The email settings for sending emails. properties: id: type: string description: The unique identifier for the email settings. Currently this is always `email-settings` enum: ['email-settings'] host: type: string description: The SMTP host address. nullable: true port: type: integer minimum: 1 description: The port number for the SMTP server. example: 465 secure: type: boolean description: Indicates if the connection should use SSL/TLS. rejectUnauthorized: type: boolean description: Indicates if unauthorized SSL/TLS certificates should be rejected. user: type: string description: The username for SMTP authentication. nullable: true pass: type: string description: The password for SMTP authentication. nullable: true testAddress: type: string description: The test email address used for sending test emails. nullable: true fromAddress: type: string description: The default "from" email address for outgoing emails. A formatted name can be included using the syntax of `Formatted Name `. nullable: true ereaderDevices: type: array description: List of configured e-reader devices. items: $ref: '#/components/schemas/ereaderDeviceObject' required: - id - port - secure - ereaderDevices rssFeedObject: type: object description: An RSS feed object hosted by ABS. properties: id: $ref: '#/components/schemas/itemId' feedUrl: $ref: '#/components/schemas/feedUrl' imageUrl: $ref: '#/components/schemas/imageUrl' title: $ref: '#/components/schemas/title' description: $ref: '#/components/schemas/description' feedPreventIndexing: $ref: '#/components/schemas/feedPreventIndexing' feedItemType: $ref: '#/components/schemas/feedItemType' feedOwnerName: $ref: '#/components/schemas/feedOwnerName' feedOwnerEmail: $ref: '#/components/schemas/feedOwnerEmail' feedUserId: $ref: '#/components/schemas/itemId' username: type: string description: The username of the user. userPassword: type: string description: The password of the user. Only used when creating the user or updating the password. userEmail: type: string nullable: true description: The email address of the user. userType: type: string description: The type of user. enum: ['root', 'admin', 'user', 'guest'] apiToken: type: string description: The API token of the user. seriesHideFromContinueListening: type: array description: The series that are hidden from the "Continue Listening" section. items: $ref: '#/components/schemas/itemId' userIsActive: type: boolean description: Whether the user is active. userIsLocked: type: boolean description: Whether the user is locked. userLastSeen: type: number description: The last time the user was seen in ms since POSIX epoch. userLibrariesAccessible: type: array description: The libraries the user has access to. nullable: true items: $ref: '#/components/schemas/itemId' userItemTagsSelected: type: array description: The tags the user has selected to filter items. nullable: true items: $ref: '#/components/schemas/tag' userLinkedToOpenId: type: boolean description: Whether the user is linked to an OpenID. openIdSub: type: string description: The sub claim of the OpenID token. userObject: type: object description: A user object. properties: id: $ref: '#/components/schemas/itemId' username: $ref: '#/components/schemas/username' email: $ref: '#/components/schemas/userEmail' type: $ref: '#/components/schemas/userType' token: $ref: '#/components/schemas/apiToken' seriesHideFromContinueListening: $ref: '#/components/schemas/seriesHideFromContinueListening' isActive: $ref: '#/components/schemas/userIsActive' isLocked: $ref: '#/components/schemas/userIsLocked' lastSeen: $ref: '#/components/schemas/userLastSeen' createdAt: $ref: '#/components/schemas/createdAt' permissions: $ref: '#/components/schemas/userPermissions' hasOpenIdLink: $ref: '#/components/schemas/userLinkedToOpenId' librariesAccessible: $ref: '#/components/schemas/userLibrariesAccessible' itemTagsSelected: $ref: '#/components/schemas/userItemTagsSelected' playMethod: type: integer description: The method used to play the media. enum: [0, 1, 2, 3] deviceInfo: type: object description: Information about the media player. properties: id: $ref: '#/components/schemas/itemId' userId: $ref: '#/components/schemas/itemId' deviceId: type: string description: The ID of the device. ipAddress: type: string description: The IP address of the device. clientVersion: type: string description: The version of the client. manufacturer: type: string description: The manufacturer of the device. model: type: string description: The model of the device. sdkVersion: type: string description: The SDK version of the device. clientName: type: string description: The name of the client. deviceName: type: string description: The name of the device. listeningSessionObject: type: object description: A listening session object. properties: id: $ref: '#/components/schemas/itemId' userId: $ref: '#/components/schemas/itemId' libraryId: $ref: '#/components/schemas/itemId' libraryItemId: $ref: '#/components/schemas/itemId' bookId: $ref: '#/components/schemas/itemId' episodeId: $ref: '#/components/schemas/itemId' mediaType: $ref: '#/components/schemas/mediaType' displayTitle: $ref: '#/components/schemas/title' displayAuthor: $ref: '#/components/schemas/authorName' mediaDuration: $ref: '#/components/schemas/duration' sessionStartTime: type: number description: The start time of the session in ms since POSIX epoch. sessionEndTime: type: number description: The end time of the session in ms since POSIX epoch. mediaStartTime: type: number description: The start time within the media. endTime: type: number description: The end time within the media. timeListened: type: number description: The time listened in seconds. playMethod: $ref: '#/components/schemas/playMethod' deviceInfo: $ref: '#/components/schemas/deviceInfo' audioProgress: type: number description: The progress of the item in seconds. audioProgressPercent: type: number description: The progress of the item as a percentage. ebookProgress: type: string description: The location in the ebook that the user has read to. ebookProgressPercent: type: number description: The progress of the item as a percentage. isFinished: type: boolean description: Whether the item is finished. finishedAt: type: number description: The time the item was finished in ms since POSIX epoch. hideFromContinueListening: type: boolean description: Whether the item is hidden from the "Continue Listening" section. lastPlayed: type: number description: The last time the item was played in ms since POSIX epoch. progressObject: type: object description: The user progress of an item. properties: userId: $ref: '#/components/schemas/itemId' itemId: $ref: '#/components/schemas/itemId' mediaType: $ref: '#/components/schemas/mediaType' audioProgress: $ref: '#/components/schemas/audioProgress' audioPercent: $ref: '#/components/schemas/audioProgressPercent' ebookProgress: $ref: '#/components/schemas/ebookProgress' ebookPercent: $ref: '#/components/schemas/ebookProgressPercent' isFinished: $ref: '#/components/schemas/isFinished' hideFromContinueListening: $ref: '#/components/schemas/hideFromContinueListening' finishedAt: $ref: '#/components/schemas/finishedAt' lastPlayed: $ref: '#/components/schemas/lastPlayed' backupObject: type: object description: A backup object. properties: id: $ref: '#/components/schemas/itemId' databaseType: type: string description: The type of database. example: sqlite backupTime: type: number description: The time the backup was created in ms since POSIX epoch. backupSize: $ref: '#/components/schemas/size' serverVersion: type: string description: The version of the server when the backup was created. example: 2.14.0 path: type: string description: The path to the backup file. fullPath: type: string description: The full path to the backup file. filename: type: string description: The name of the backup file. backupSettings: type: object description: The backup settings for the server. properties: automaticBackupsEnabled: type: boolean description: Whether automatic backups are enabled. backupSchedule: type: string description: The cron schedule for automatic backups. maxBackups: type: integer description: The maximum number of backups to keep. Use 0 for unlimited minimum: 0 default: 5 maxBackupSize: type: integer description: The maximum size of a backup in GB. Use 0 for unlimited minimum: 0 default: 1 responses: badRequest: description: Bad request. content: text/html: schema: type: string example: Bad request. forbidden: description: Forbidden. content: text/html: schema: type: string example: Forbidden. notFound: description: Item not found. content: text/html: schema: type: string example: Item not found. bookLibraryOnly: description: This endpoint is for book libraries only. content: text/html: schema: type: string example: This endpoint is for book libraries only. podcastLibraryOnly: description: This endpoint is for podcast libraries only. content: text/html: schema: type: string example: This endpoint is for podcast libraries only. tags: - name: Book description: Book endpoints paths: /api/book/{id}: parameters: - $ref: '#/components/parameters/pathBookId' get: operationId: getBookById summary: Get book by ID 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: - $ref: '#/components/parameters/pathBookId' 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: - $ref: '#/components/parameters/pathBookId' 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: - $ref: '#/components/parameters/pathBookId' 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: - $ref: '#/components/parameters/pathBookId' 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: - $ref: '#/components/parameters/pathBookId' 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: - $ref: '#/components/parameters/pathBookId' 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. 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/podcast/{id}: parameters: - $ref: '#/components/parameters/pathPodcastId' get: operationId: getPodcastById summary: Get podcast by ID 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: $ref: '#/components/schemas/description' genres: $ref: '#/components/schemas/genreArray' tags: $ref: '#/components/schemas/tagArray' releaseDate: $ref: '#/components/schemas/publishDate' itunesId: $ref: '#/components/schemas/itunesId' language: $ref: '#/components/schemas/language' explicit: $ref: '#/components/schemas/isExplicit' rssFeed: $ref: '#/components/schemas/rssFeed' type: $ref: '#/components/schemas/podcastType' autoDownloadEnabled: $ref: '#/components/schemas/autoDownloadEnabled' autoDownloadSchedule: $ref: '#/components/schemas/autoDownloadSchedule' maxEpisodesToKeep: $ref: '#/components/schemas/maxEpisodesToKeep' maxNewEpisodestoDownload: $ref: '#/components/schemas/maxNewEpisodestoDownload' 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' delete: operationId: deletePodcastById summary: Remove podcast by ID 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: - $ref: '#/components/parameters/pathPodcastId' 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: - $ref: '#/components/parameters/pathPodcastId' 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}/checknew: parameters: - $ref: '#/components/parameters/pathPodcastId' post: operationId: checkNewEpisodesById summary: Check for new episodes description: Check for new episodes for the podcast by its ID. This endpoint will check the podcast's RSS feed for new episodes and add them to the database. tags: - Podcast requestBody: content: application/json: schema: type: object properties: limit: type: integer description: The maximum number of new episodes to check for. Use 0 for unlimited. minimum: 0 default: 3 responses: '200': description: OK content: application/json: schema: type: object properties: newEpisodes: type: array description: The new episodes added to the download queue. items: $ref: '#/components/schemas/podcastEpisodeQueueObject' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/podcast/{id}/download-queue: parameters: - $ref: '#/components/parameters/pathPodcastId' get: operationId: getPodcastDownloadQueueById summary: Get podcast download queue by ID description: Get the podcast download queue by its ID. This endpoint will return the podcast's download queue, which includes the episodes that are queued for download. tags: - Podcast responses: '200': description: OK content: application/json: schema: type: object properties: downloadQueue: type: array description: The episodes queued for download. items: $ref: '#/components/schemas/podcastEpisodeQueueObject' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' post: operationId: addPodcastDownloadQueueById summary: Add podcast episode to download queue description: Add a podcast episode to the download queue by the podcast ID. This endpoint will add the episode to the end of the download queue. tags: - Podcast requestBody: content: application/json: schema: type: object properties: episodes: type: array description: The podcasts to add to the download queue. items: $ref: '#/components/schemas/podcastEpisodeQueueObject' required: true responses: '200': description: OK content: text/plain: schema: type: string example: Episodes added to download queue. '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' delete: operationId: clearPodcastDownloadQueueById summary: Clear podcast download queue by ID description: Clear the podcast download queue by its ID. This endpoint will remove all episodes from the podcast's download queue. tags: - Podcast responses: '200': description: OK content: application/json: schema: type: object properties: downloadQueue: type: array description: The episodes removed from the download queue. items: $ref: '#/components/schemas/podcastEpisodeQueueObject' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/podcast/{id}/cover: parameters: - $ref: '#/components/parameters/pathPodcastId' 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-episodes: parameters: - $ref: '#/components/parameters/pathPodcastId' post: operationId: quickMatchPodcastEpisodesById summary: Quick match podcast episodes description: Quick match all episodes in the podcast against an RSS feed. Quick match will fill empty metadata fields. Metadata fields are not overwritten unless the "Prefer Matched Metadata" setting is enabled or the "force" query is set. tags: - Podcast parameters: - in: query name: force required: false description: Whether to force the match and overwrite all metadata fields. schema: type: boolean default: false responses: '200': description: OK content: application/json: schema: allOf: - $ref: '#/components/schemas/podcastObject' - type: object properties: updated: type: boolean description: Whether the podcast was updated with the match. '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/podcast/{id}/match: parameters: - $ref: '#/components/parameters/pathPodcastId' 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: - $ref: '#/components/parameters/pathPodcastId' 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: - $ref: '#/components/parameters/pathPodcastId' 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: - $ref: '#/components/parameters/pathPodcastId' 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. schema: type: integer minimum: 1 default: 1 - in: query name: sort required: false description: The field to sort the episodes by. schema: type: string enum: ['releaseDate', 'title', 'duration', 'size', 'episodeNumber', 'seasonNumber'] default: 'releaseDate' - in: query name: filter required: false description: The field to filter the episodes by. schema: type: string enum: ['incomplete', 'complete', 'in-progress', 'all'] default: 'incomplete' responses: '200': description: OK content: application/json: schema: type: object properties: total: type: integer description: The total number of episodes. returnCount: type: integer description: The number of episodes returned. episodes: type: array items: $ref: '#/components/schemas/podcastEpisodeDisplayObject' '404': $ref: '#/components/responses/notFound' /api/podcast-episode/{id}: parameters: - $ref: '#/components/parameters/pathPodcastEpisodeId' get: operationId: getPodcastEpisodeById summary: Get podcast episode by ID description: Get a podcast episode by its ID. This endpoint returns all of the information needed for the podcast episode details page and editing. tags: - Podcast Episode responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/podcastEpisodeObject' '404': $ref: '#/components/responses/notFound' post: operationId: updatePodcastEpisodeById summary: Update podcast episode by ID description: Update a podcast episode 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 Episode requestBody: content: application/json: schema: type: object properties: title: $ref: '#/components/schemas/titleNullable' description: $ref: '#/components/schemas/description' releaseDate: $ref: '#/components/schemas/publishDate' episodeNumber: $ref: '#/components/schemas/episodeNumber' seasonNumber: $ref: '#/components/schemas/seasonNumber' explicit: $ref: '#/components/schemas/isExplicit' #coverPath: #$ref: '#/components/schemas/imagePath' #hasFeedOpen: #$ref: '#/components/schemas/hasFeedOpen' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/podcastEpisodeObject' '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' delete: operationId: deletePodcastEpisodeById summary: Remove podcast episode by ID description: Remove the podcast episode and associated entries from the database. This does not delete any files from the filesystem. tags: - Podcast Episode responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/podcastEpisodeObject' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/podcast-episode/{id}/hardDelete: parameters: - $ref: '#/components/parameters/pathPodcastEpisodeId' delete: operationId: hardDeletePodcastEpisodeById summary: Hard delete podcast episode by ID description: Hard delete the podcast episode and associated entries from the database. This deletes the podcast episode's files from the filesystem. This action cannot be undone. tags: - Podcast Episode responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/podcastEpisodeObject' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/podcast-episode/{id}/download: parameters: - $ref: '#/components/parameters/pathPodcastEpisodeId' get: operationId: downloadPodcastEpisodeById summary: Download podcast episode by ID description: Download the podcast episode by its ID. This endpoint will return the podcast episode file as a raw file. tags: - Podcast Episode responses: '200': description: OK content: application/octet-stream: schema: type: string format: binary '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/podcast-episode/{id}/match: parameters: - $ref: '#/components/parameters/pathPodcastEpisodeId' post: operationId: matchPodcastEpisodeById summary: Match podcast episode by ID description: Match the podcast episode 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 Episode parameters: - in: query name: title required: false description: The title of the podcast episode to match. schema: type: string responses: '200': description: OK content: application/json: schema: type: array items: # TODO, verify this schema $ref: '#/components/schemas/podcastEpisodeObject' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/library/{id}/books: parameters: - $ref: '#/components/parameters/pathLibraryId' get: operationId: getLibraryBooksById summary: Get books in library description: Get the books in the library by its ID. This endpoint will return the books in the library. tags: - Library parameters: - $ref: '#/components/parameters/queryLimit' - $ref: '#/components/parameters/queryPage' - $ref: '#/components/parameters/querySortBooks' - $ref: '#/components/parameters/queryDesc' - $ref: '#/components/parameters/queryFilterGenre' - $ref: '#/components/parameters/queryFilterTag' - $ref: '#/components/parameters/queryFilterAuthor' - $ref: '#/components/parameters/queryFilterNarrator' - $ref: '#/components/parameters/queryFilterSeries' - $ref: '#/components/parameters/queryFilterPublisher' - $ref: '#/components/parameters/queryFilterLanguage' - $ref: '#/components/parameters/queryFilterProgress' - $ref: '#/components/parameters/queryFilterMissing' - $ref: '#/components/parameters/queryFilterTrackCount' - $ref: '#/components/parameters/queryFilterEbook' - $ref: '#/components/parameters/queryFilterAbridged' - $ref: '#/components/parameters/queryFilterExplicit' - $ref: '#/components/parameters/queryFilterIssues' - $ref: '#/components/parameters/queryFilterFeedOpen' - $ref: '#/components/parameters/queryFilterShareOpen' responses: '200': description: OK content: application/json: schema: type: object properties: total: type: integer description: The total number of books. returnCount: type: integer description: The number of books returned. books: type: array items: $ref: '#/components/schemas/displayBookObject' '404': $ref: '#/components/responses/notFound' /api/library/{id}/authors: parameters: - $ref: '#/components/parameters/pathLibraryId' get: operationId: getLibraryAuthorsById summary: Get authors in library description: Get the authors in the library by its ID. This endpoint will return the authors in the library. tags: - Library parameters: - $ref: '#/components/parameters/queryLimit' - $ref: '#/components/parameters/queryPage' - $ref: '#/components/parameters/querySortAuthors' - $ref: '#/components/parameters/queryDesc' responses: '200': description: OK content: application/json: schema: type: object properties: total: type: integer description: The total number of authors. returnCount: type: integer description: The number of authors returned. authors: type: array items: $ref: '#/components/schemas/authorDisplayObject' '404': $ref: '#/components/responses/notFound' /api/library/{id}/podcasts: parameters: - $ref: '#/components/parameters/pathLibraryId' get: operationId: getLibraryPodcastsById summary: Get podcasts in library description: Get the podcasts in the library by its ID. This endpoint will return the podcasts in the library. tags: - Library parameters: - $ref: '#/components/parameters/queryLimit' - $ref: '#/components/parameters/queryPage' - $ref: '#/components/parameters/querySortPodcasts' - $ref: '#/components/parameters/queryDesc' - $ref: '#/components/parameters/queryFilterGenre' - $ref: '#/components/parameters/queryFilterTag' - $ref: '#/components/parameters/queryFilterLanguage' - $ref: '#/components/parameters/queryFilterIssues' responses: '200': description: OK content: application/json: schema: type: object properties: total: type: integer description: The total number of podcasts. returnCount: type: integer description: The number of podcasts returned. podcasts: type: array items: $ref: '#/components/schemas/displayPodcastObject' '400': $ref: '#/components/responses/podcastLibraryOnly' '404': $ref: '#/components/responses/notFound' post: operationId: addPodcastToLibraryById summary: Add podcast to library by ID description: Add a podcast to the library by its ID. This endpoint will add the podcast to the library. tags: - Library requestBody: content: application/json: schema: type: object properties: podcast: $ref: '#/components/schemas/podcastObject' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/displayPodcastObject' '400': $ref: '#/components/responses/podcastLibraryOnly' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/library/{id}/opml: parameters: - $ref: '#/components/parameters/pathLibraryId' get: operationId: getLibraryOpmlById summary: Get library OPML description: Get the library's OPML file by library ID. This endpoint will return the library's OPML file. tags: - Library responses: '200': description: OK content: application/xml: schema: type: string format: binary '400': $ref: '#/components/responses/podcastLibraryOnly' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' post: operationId: createPodcastByOpml summary: Create podcast by OPML description: Add podcasts to library by using an OPML file. This endpoint accepts a file upload or a link to an OPML file. tags: - Library requestBody: content: multipart/form-data: schema: type: object properties: opml: type: string format: binary application/json: schema: type: object properties: url: type: string description: The URL to download the OPML file from. format: uri required: true responses: '200': description: OK content: application/json: schema: type: object properties: total: type: integer description: The total number of podcasts imported. success: type: array description: The podcasts successfully imported. items: type: string description: The podcast name which was successfully imported. errors: type: array description: The podcasts that failed to import. items: type: string description: The podcast name which failed to import. '400': $ref: '#/components/responses/podcastLibraryOnly' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/library/{id}/podcast-episodes: parameters: - $ref: '#/components/parameters/pathLibraryId' get: operationId: getLibraryPodcastEpisodesById summary: Get podcast episodes in library description: Get the podcast episodes in the library by its ID. This endpoint will return the podcast episodes in the library. tags: - Library parameters: - $ref: '#/components/parameters/queryLimit' - $ref: '#/components/parameters/queryPage' - in: query name: sort required: false description: The field to sort the podcast episodes by. schema: type: string enum: ['releaseDate', 'title', 'duration', 'size', 'episodeNumber', 'seasonNumber'] default: 'releaseDate' - $ref: '#/components/parameters/queryDesc' - in: query name: filter required: false description: A key-value pair of how to filter podcast episodes. The key is the field to filter by and the value is the value to filter by. If the value is an array, the filter will be an OR filter. schema: type: string enum: ['incomplete', 'complete', 'in-progress', 'all'] default: 'incomplete' responses: '200': description: OK content: application/json: schema: type: object properties: total: type: integer description: The total number of podcast episodes. returnCount: type: integer description: The number of podcast episodes returned. episodes: type: array items: $ref: '#/components/schemas/displayPodcastEpisodeObject' '404': $ref: '#/components/responses/notFound' /api/author/{id}: parameters: - $ref: '#/components/parameters/pathAuthorId' get: operationId: getAuthorById summary: Get author by ID description: Get an author by its ID. This endpoint returns all of the information needed for the author details page and editing. tags: - Author responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/authorObject' '404': $ref: '#/components/responses/notFound' patch: operationId: updateAuthorById summary: Update author by ID description: Update an author 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: - Author requestBody: content: application/json: schema: type: object properties: name: $ref: '#/components/schemas/authorName' descrption: $ref: '#/components/schemas/description' asin: $ref: '#/components/schemas/asin' imageUrl: $ref: '#/components/schemas/imageUrl' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/authorObject' '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' delete: operationId: deleteAuthorById summary: Remove author by ID description: Remove the author and associated entries from the database. This does not delete any files from the filesystem. tags: - Author responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/authorObject' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/author/{id}/image: parameters: - $ref: '#/components/parameters/pathAuthorId' get: operationId: getAuthorImageById summary: Get author image by ID description: Get the author image by its ID. This endpoint will return the author's image. If no query parameters are provided, the image will be returned in the original format with the original dimensions. security: [] # No security for getting image tags: - Author 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: uploadAuthorImageById summary: Upload author image by ID description: Upload the author image to the author by the author ID. This endpoint will replace the author's 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: - Author requestBody: content: multipart/form-data: schema: type: object properties: image: 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: imageData: $ref: '#/components/schemas/file' success: type: boolean '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' delete: operationId: deleteAuthorImageById summary: Remove author image by ID description: Remove the author image from the author. The image file is not deleted but is no longer associated with the author. tags: - Author responses: '200': description: OK content: application/json: schema: properties: imageData: $ref: '#/components/schemas/file' success: type: boolean '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/author/{id}/match: parameters: - $ref: '#/components/parameters/pathAuthorId' post: operationId: matchAuthorById summary: Match author by ID description: Match the author selected by ID against an online database. tags: - Author parameters: - $ref: '#/components/parameters/queryAuthorName' - $ref: '#/components/parameters/queryAsin' - $ref: '#/components/parameters/queryRegion' responses: '200': description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/authorObject' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/library: get: operationId: getLibraries summary: Get libraries description: Get all libraries. This endpoint will return all libraries. tags: - Library responses: '200': description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/libraryObject' '403': $ref: '#/components/responses/forbidden' post: operationId: createLibrary summary: Create library description: Create a new library. The request body should contain the library's name. tags: - Library requestBody: content: application/json: schema: type: object properties: name: $ref: '#/components/schemas/title' folders: $ref: '#/components/schemas/folderArray' icon: $ref: '#/components/schemas/libraryIcon' mediaType: $ref: '#/components/schemas/mediaType' provider: $ref: '#/components/schemas/libraryProvider' settings: $ref: '#/components/schemas/librarySettings' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/libraryObject' '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden' /api/library/order: patch: operationId: updateLibraryOrder summary: Update library order description: Update the order of the libraries. The request body must contain all library IDs in the order they should be displayed. tags: - Library requestBody: content: application/json: schema: type: array items: $ref: '#/components/schemas/itemId' required: true responses: '200': description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/libraryObject' '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden' /api/library/{id}: parameters: - $ref: '#/components/parameters/pathLibraryId' get: operationId: getLibraryById summary: Get library by ID description: Get a library by its ID. This endpoint returns all of the information needed for the library details page and editing. tags: - Library responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/libraryObject' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' patch: operationId: updateLibraryById summary: Update library by ID description: Update a library 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: - Library requestBody: content: application/json: schema: type: object properties: name: $ref: '#/components/schemas/titleNullable' folders: $ref: '#/components/schemas/folderArray' displayOrder: $ref: '#/components/schemas/libraryDisplayOrder' icon: $ref: '#/components/schemas/libraryIcon' provider: $ref: '#/components/schemas/libraryProvider' settings: $ref: '#/components/schemas/librarySettings' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/libraryObject' '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' delete: operationId: deleteLibraryById summary: Remove library by ID description: Remove the library and associated entries from the database. This does not delete any files from the filesystem. tags: - Library responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/libraryObject' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/library/{id}/issues: parameters: - $ref: '#/components/parameters/pathLibraryId' delete: operationId: deleteLibraryIssuesById summary: Remove items with issues description: Remove all items with issues located in the library. This does not delete any files from the filesystem. A file with issues is defined as a file missing from the filesystem. tags: - Library responses: '200': description: OK content: application/json: schema: type: object properties: removed: type: integer description: The number of items removed. remaining: type: integer description: The number of items remaining after removing items with issues. '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/library/{id}/series: parameters: - $ref: '#/components/parameters/pathLibraryId' get: operationId: getLibrarySeriesById summary: Get series in library description: Get the series in the library by its ID. This endpoint will return the series in the library. tags: - Library parameters: - $ref: '#/components/parameters/queryLimit' - $ref: '#/components/parameters/queryPage' - $ref: '#/components/parameters/querySortSeries' - $ref: '#/components/parameters/querySubObjectLimit' - $ref: '#/components/parameters/queryDesc' responses: '200': description: OK content: application/json: schema: type: object properties: total: type: integer description: The total number of series. returnCount: type: integer description: The number of series returned. series: type: array items: $ref: '#/components/schemas/seriesDisplayObject' '403': $ref: '#/components/responses/bookLibraryOnly' '404': $ref: '#/components/responses/notFound' /api/library/{id}/book-collections: parameters: - $ref: '#/components/parameters/pathLibraryId' get: operationId: getLibraryBookCollectionsById summary: Get book collections in library description: Get the collections in the library by its ID. This endpoint will return the collections in the library. This endpoint will return an error if the library is not `books` media type. tags: - Library parameters: - $ref: '#/components/parameters/queryLimit' - $ref: '#/components/parameters/queryPage' - $ref: '#/components/parameters/querySortCollections' - $ref: '#/components/parameters/querySubObjectLimit' - $ref: '#/components/parameters/queryDesc' responses: '200': description: OK content: application/json: schema: type: object properties: total: type: integer description: The total number of collections. returnCount: type: integer description: The number of collections returned. collections: type: array items: $ref: '#/components/schemas/bookCollectionDisplayObject' '403': $ref: '#/components/responses/bookLibraryOnly' '404': $ref: '#/components/responses/notFound' /api/library/{id}/book-playlists: parameters: - $ref: '#/components/parameters/pathLibraryId' get: operationId: getLibraryBookPlaylistsById summary: Get book playlists in library description: Get the playlists in the library by its ID. This endpoint will return the playlists in the library for this user. This endpoint will return an error if the library is not `books` media type. tags: - Library parameters: - $ref: '#/components/parameters/queryLimit' - $ref: '#/components/parameters/queryPage' - $ref: '#/components/parameters/querySortPlaylists' - $ref: '#/components/parameters/querySubObjectLimit' - $ref: '#/components/parameters/queryDesc' responses: '200': description: OK content: application/json: schema: type: object properties: total: type: integer description: The total number of playlists. returnCount: type: integer description: The number of playlists returned. playlists: type: array items: $ref: '#/components/schemas/bookPlaylistDisplayObject' '403': $ref: '#/components/responses/bookLibraryOnly' '404': $ref: '#/components/responses/notFound' /api/library/{id}/podcast-episode-playlists: parameters: - $ref: '#/components/parameters/pathLibraryId' get: operationId: getLibraryPodcastEpisodePlaylistsById summary: Get podcast episode playlists in library description: Get the playlists in the library by its ID. This endpoint will return the playlists in the library for this user. This endpoint will return an error if the library is not `podcasts` media type. tags: - Library parameters: - $ref: '#/components/parameters/queryLimit' - $ref: '#/components/parameters/queryPage' - $ref: '#/components/parameters/querySortPlaylists' - $ref: '#/components/parameters/querySubObjectLimit' - $ref: '#/components/parameters/queryDesc' responses: '200': description: OK content: application/json: schema: type: object properties: total: type: integer description: The total number of playlists. returnCount: type: integer description: The number of playlists returned. playlists: type: array items: $ref: '#/components/schemas/podcastEpisodePlaylistDisplayObject' '403': $ref: '#/components/responses/podcastLibraryOnly' '404': $ref: '#/components/responses/notFound' /api/library/{id}/podcast-episode-collections: parameters: - $ref: '#/components/parameters/pathLibraryId' get: operationId: getLibraryPodcastEpisodeCollectionsById summary: Get podcast episode collections in library description: Get the collections in the library by its ID. This endpoint will return the collections in the library. This endpoint will return an error if the library is not `podcasts` media type. tags: - Library parameters: - $ref: '#/components/parameters/queryLimit' - $ref: '#/components/parameters/queryPage' - $ref: '#/components/parameters/querySortCollections' - $ref: '#/components/parameters/querySubObjectLimit' - $ref: '#/components/parameters/queryDesc' responses: '200': description: OK content: application/json: schema: type: object properties: total: type: integer description: The total number of collections. returnCount: type: integer description: The number of collections returned. collections: type: array items: $ref: '#/components/schemas/podcastEpisodeCollectionDisplayObject' '403': $ref: '#/components/responses/podcastLibraryOnly' '404': $ref: '#/components/responses/notFound' /api/library/{id}/feeds: parameters: - $ref: '#/components/parameters/pathLibraryId' get: operationId: getLibraryFeedsById summary: Get feeds in library description: Get the feeds in the library by its ID. This endpoint will return the feeds in the library. tags: - Library parameters: - $ref: '#/components/parameters/queryLimit' - $ref: '#/components/parameters/queryPage' responses: '200': description: OK content: application/json: schema: type: object properties: total: type: integer description: The total number of feeds. returnCount: type: integer description: The number of feeds returned. feeds: type: array items: $ref: '#/components/schemas/rssFeedObject' '404': $ref: '#/components/responses/notFound' /api/library/{id}/narrators: parameters: - $ref: '#/components/parameters/pathLibraryId' get: operationId: getLibraryNarratorsById summary: Get narrators in library description: Get the narrators in the library by its ID. This endpoint will return the narrators in the library. tags: - Library parameters: - $ref: '#/components/parameters/queryLimit' - $ref: '#/components/parameters/queryPage' - $ref: '#/components/parameters/queryDesc' responses: '200': description: OK content: application/json: schema: type: object properties: total: type: integer description: The total number of narrators. returnCount: type: integer description: The number of narrators returned. narrators: type: array items: $ref: '#/components/schemas/narratorDisplayObject' '404': $ref: '#/components/responses/notFound' /api/narrator/{id}: parameters: - $ref: '#/components/parameters/pathNarratorId' get: operationId: getNarratorById summary: Get narrator by ID description: Get a narrator by its ID. This endpoint returns all of the information needed for the narrator details page and editing. tags: - Narrator responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/narratorObject' '404': $ref: '#/components/responses/notFound' patch: operationId: updateNarratorById summary: Update narrator by ID description: Update a narrator 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: - Narrator requestBody: content: application/json: schema: type: object properties: name: $ref: '#/components/schemas/narratorName' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/narratorObject' '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' delete: operationId: deleteNarratorById summary: Remove narrator by ID description: Remove the narrator and associated entries from the database. This does not delete any files from the filesystem. tags: - Narrator responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/narratorObject' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/library/{id}/scan: parameters: - $ref: '#/components/parameters/pathLibraryId' post: operationId: scanLibraryById summary: Scan library by ID description: Scan the library by its ID. This will scan the library's folders for new media and update the database with the new media. tags: - Library requestBody: content: application/json: schema: type: object properties: folders: type: array description: An array of folder IDs in the library to scan for media. items: type: string format: uuid responses: '200': description: OK content: application/json: schema: type: object properties: added: type: integer description: The number of items added to the library. updated: type: integer description: The number of items updated in the library. removed: type: integer description: The number of items removed from the library. '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/library/{id}/match: parameters: - $ref: '#/components/parameters/pathLibraryId' post: operationId: matchLibraryById summary: Match library by ID description: Match all items in the library which do not have an ASIN or ISBN against an online database. If a provider is not specified, the default library provider will be used. Matched items will have missing details filled in by default and data will not be overwritten, unless the "Prefer matched metadata" setting is enabled. tags: - Library requestBody: content: application/json: schema: type: object properties: provider: $ref: '#/components/schemas/libraryProvider' required: false responses: '200': description: OK content: application/json: schema: type: object properties: updated: type: integer description: The number of items updated in the library. This will be equal to or less than `found`. found: type: integer description: The number of unmatched items found in the online database. notFound: type: integer description: The number of unmatched items not found in the online database. '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/email/settings: get: operationId: getEmailSettings summary: Get email settings description: Get the email settings for sending e-books to e-readers. tags: - Email responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/emailSettings' '403': $ref: '#/components/responses/forbidden' patch: operationId: updateEmailSettings summary: Update email settings description: Update the email settings for sending e-books to e-readers. 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: - Email requestBody: content: application/json: schema: type: object properties: emailSettings: $ref: '#/components/schemas/emailSettings' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/emailSettings' '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden' /api/email/test: post: operationId: testEmailSettings summary: Test email settings description: Test the email settings for sending e-books to e-readers. This will send a test email to the specified e-reader. tags: - Email requestBody: content: application/json: schema: type: object properties: ereader-name: $ref: '#/components/schemas/ereaderName' required: true responses: '200': description: OK content: application/json: schema: type: object properties: success: type: boolean '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden' /api/email/create-device: post: operationId: addEreaderDevice summary: Add e-reader device description: Add an e-reader device to the list of devices that can receive e-books via email. tags: - Email requestBody: content: application/json: schema: type: object properties: ereader: $ref: '#/components/schemas/ereaderDeviceObject' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ereaderDeviceObject' '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden' /api/email/delete-device: delete: operationId: deleteEreaderDevice summary: Remove e-reader device description: Remove an e-reader device from the list of devices that can receive e-books via email. tags: - Email requestBody: content: application/json: schema: type: object properties: ereader-name: $ref: '#/components/schemas/ereaderName' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/ereaderDeviceObject' '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden' /api/email/send-ebook: post: operationId: sendEbookToEreader summary: Send e-book to e-reader description: Send an e-book to an e-reader device. The e-reader device must be in the list of devices that can receive e-books via email for this user. tags: - Email requestBody: content: application/json: schema: type: object properties: ereader-name: $ref: '#/components/schemas/ereaderName' book-id: $ref: '#/components/schemas/itemId' required: true responses: '200': description: OK content: application/json: schema: type: object properties: success: type: boolean '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden' /api/feeds: get: operationId: getFeeds summary: Get feeds description: Get all feeds. This endpoint will return all feeds for the server. tags: - RSS Feed responses: '200': description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/rssFeedObject' '403': $ref: '#/components/responses/forbidden' post: operationId: createFeed summary: Create feed description: Create a new feed. The request body should contain the feed's slug and the ID of the object the feed corresponds to. tags: - RSS Feed requestBody: content: application/json: schema: type: object properties: entityId: $ref: '#/components/schemas/itemId' slug: $ref: '#/components/schemas/feedSlug' preventIndexing: $ref: '#/components/schemas/feedPreventIndexing' ownerName: $ref: '#/components/schemas/feedOwnerName' ownerEmail: $ref: '#/components/schemas/feedOwnerEmail' required: - entityId - slug - preventIndexing responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/rssFeedObject' '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden' /api/feeds/{id}: parameters: - $ref: '#/components/parameters/pathFeedId' get: operationId: getFeedById summary: Get feed object by ID description: Get a feed by its ID. This endpoint returns all of the information needed for the feed details page and editing. tags: - RSS Feed responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/rssFeedObject' '404': $ref: '#/components/responses/notFound' delete: operationId: deleteFeedById summary: Remove feed by ID description: Remove the feed and associated entries from the database. This does not delete any files from the filesystem. tags: - RSS Feed responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/rssFeedObject' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /feed/{slug}: parameters: - $ref: '#/components/parameters/pathFeedSlug' get: operationId: getFeedBySlug summary: Get RSS feed description: Get a feed by its slug. This endpoint returns the RSS feed as a string. tags: - RSS Feed responses: '200': description: OK content: application/xml: schema: type: string format: binary '404': $ref: '#/components/responses/notFound' /api/series/{id}: parameters: - $ref: '#/components/parameters/pathSeriesId' get: operationId: getSeriesById summary: Get series description: Get a series by its ID. This endpoint returns all of the information needed for the series page. tags: - Series responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/seriesDisplayObject' '404': $ref: '#/components/responses/notFound' patch: operationId: updateSeriesById summary: Update series description: Update a series 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: - Series requestBody: content: application/json: schema: type: object properties: name: $ref: '#/components/schemas/title' descrption: $ref: '#/components/schemas/description' imageUrl: $ref: '#/components/schemas/imageUrl' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/seriesDisplayObject' '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' delete: operationId: deleteSeriesById summary: Remove series description: Remove the series and associated entries from the database. This does not delete any files from the filesystem. tags: - Series responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/seriesDisplayObject' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/users: get: operationId: getUsers summary: Get users description: Get all users. This endpoint will return all users, with optional paging and sorting. tags: - User parameters: - $ref: '#/components/parameters/queryLimit' - $ref: '#/components/parameters/queryPage' - $ref: '#/components/parameters/querySortUsers' responses: '200': description: OK content: application/json: schema: type: array items: $ref: '#/components/schemas/userObject' '403': $ref: '#/components/responses/forbidden' post: operationId: createUser summary: Create user description: Create a new user. Only one root user can exist per server. tags: - User requestBody: content: application/json: schema: type: object properties: name: $ref: '#/components/schemas/username' email: $ref: '#/components/schemas/userEmail' password: $ref: '#/components/schemas/userPassword' type: $ref: '#/components/schemas/userType' isActive: $ref: '#/components/schemas/userIsActive' isLocked: $ref: '#/components/schemas/userIsLocked' permissions: $ref: '#/components/schemas/userPermissions' librariesAccesible: $ref: '#/components/schemas/userLibrariesAccessible' itemTagsSelected: $ref: '#/components/schemas/userItemTagsSelected' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/userObject' '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden' /api/user/{id}: parameters: - $ref: '#/components/parameters/pathUserId' get: operationId: getUserById summary: Get user by ID description: Get a user by its ID. This endpoint returns all of the information needed for the user details page and editing. tags: - User responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/userObject' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' patch: operationId: updateUserById summary: Update user by ID description: Update a user 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: - User requestBody: content: application/json: schema: type: object properties: name: $ref: '#/components/schemas/username' email: $ref: '#/components/schemas/userEmail' password: $ref: '#/components/schemas/userPassword' type: $ref: '#/components/schemas/userType' isActive: $ref: '#/components/schemas/userIsActive' isLocked: $ref: '#/components/schemas/userIsLocked' permissions: $ref: '#/components/schemas/userPermissions' librariesAccesible: $ref: '#/components/schemas/userLibrariesAccessible' itemTagsSelected: $ref: '#/components/schemas/userItemTagsSelected' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/userObject' '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' delete: operationId: deleteUserById summary: Remove user by ID description: Remove the user and associated entries from the database. This does not delete any files from the filesystem. tags: - User responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/userObject' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/user/{id}/openid-unlink: parameters: - $ref: '#/components/parameters/pathUserId' patch: operationId: unlinkOpenId summary: Unlink OpenID description: Unlink an OpenID account from a user account. tags: - User requestBody: content: application/json: schema: type: object properties: openIdSub: $ref: '#/components/schemas/openIdSub' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/userObject' '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/my: get: operationId: getMyUser summary: Get my user description: Get the user information for the currently logged in user. tags: - Myself responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/userObject' '403': $ref: '#/components/responses/forbidden' /api/my/listening-sessions: get: operationId: getMyListeningSessions summary: Get my listening sessions description: Get the listening sessions for the currently logged in user. tags: - Myself parameters: - $ref: '#/components/parameters/queryLimit' - $ref: '#/components/parameters/queryPage' responses: '200': description: OK content: application/json: schema: type: object properties: total: type: integer description: The total number of listening sessions. returnCount: type: integer description: The number of listening sessions returned. listeningSessions: type: array items: $ref: '#/components/schemas/listeningSessionObject' '403': $ref: '#/components/responses/forbidden' /api/my/progress/{id}: parameters: - $ref: '#/components/parameters/pathItemId' get: operationId: getMyProgress summary: Get my progress description: Get the progress for an item for the currently logged in user. The item ID can be a book, series, or podcast episode. tags: - Myself responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/progressObject' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' patch: operationId: updateMyProgress summary: Update my progress description: Update the progress for an item for the currently logged in user. 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: - Myself requestBody: content: application/json: schema: anyOf: - $ref: '#/components/schemas/audioProgress' - $ref: '#/components/schemas/audioProgressPercent' - $ref: '#/components/schemas/ebookProgress' - $ref: '#/components/schemas/ebookProgressPercent' - $ref: '#/components/schemas/isFinished' - $ref: '#/components/schemas/hideFromContinueListening' - $ref: '#/components/schemas/finishedAt' - $ref: '#/components/schemas/lastPlayed' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/progressObject' '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' delete: operationId: deleteMyProgress summary: Remove my progress description: Remove the progress for an item for the currently logged in user. tags: - Myself responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/progressObject' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/my/progress/batch-update: patch: operationId: updateMyProgressBatch summary: Update my progress in batch description: Update the progress for multiple items for the currently logged in user. The request body should contain an array of objects, each containing the item ID and 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: - Myself requestBody: content: application/json: schema: type: array items: anyOf: - $ref: '#/components/schemas/itemId' - $ref: '#/components/schemas/audioProgress' - $ref: '#/components/schemas/audioProgressPercent' - $ref: '#/components/schemas/ebookProgress' - $ref: '#/components/schemas/ebookProgressPercent' - $ref: '#/components/schemas/isFinished' - $ref: '#/components/schemas/hideFromContinueListening' - $ref: '#/components/schemas/finishedAt' - $ref: '#/components/schemas/lastPlayed' required: true responses: '200': description: OK content: application/json: schema: type: object properties: updated: type: integer description: The number of items updated. '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden' /api/my/progress: get: operationId: getMyItemsInProgress summary: Get all my items in progress description: Get the items in progress for the currently logged in user. This endpoint only returns the progress object and does not return the full media object for displaying. This endpoint will return all items in progress, with optional paging and sorting. This endpoint can be used to get rows for the home page. tags: - Myself parameters: - $ref: '#/components/parameters/queryLimit' - $ref: '#/components/parameters/queryPage' - $ref: '#/components/parameters/queryHideContinueListening' - $ref: '#/components/parameters/queryProgressItemType' - $ref: '#/components/parameters/querySortProgress' responses: '200': description: OK content: application/json: schema: type: object properties: total: type: integer description: The total number of items in progress. returnCount: type: integer description: The number of items in progress returned. itemsInProgress: type: array items: $ref: '#/components/schemas/progressObject' '403': $ref: '#/components/responses/forbidden' /api/my/password: patch: operationId: updateMyPassword summary: Update my password description: Update the password for the currently logged in user. The request body should contain the current password and the new password. tags: - Myself requestBody: content: application/json: schema: type: object properties: currentPassword: $ref: '#/components/schemas/userPassword' newPassword: $ref: '#/components/schemas/userPassword' required: true responses: '200': description: OK content: application/json: schema: type: object properties: success: type: boolean '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden' /api/collection/{id}/books: parameters: - $ref: '#/components/parameters/pathCollectionId' get: operationId: getCollectionBooksById summary: Get collection of books description: Get a collection by its ID. This endpoint returns all of the information needed for the collection details page and editing. tags: - Collection responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/bookCollectionDisplayObject' '400': $ref: '#/components/responses/bookLibraryOnly' '404': $ref: '#/components/responses/notFound' patch: operationId: updateBookCollectionById summary: Update book collection description: Update a collection 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: - Collection requestBody: content: application/json: schema: type: object properties: name: $ref: '#/components/schemas/title' description: $ref: '#/components/schemas/description' imageUrl: $ref: '#/components/schemas/imageUrl' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/bookCollectionDisplayObject' '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' delete: operationId: deleteBookCollectionById summary: Remove book collection description: Remove the collection and associated entries from the database. This does not delete any files from the filesystem. tags: - Collection responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/bookCollectionDisplayObject' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/collection/{id}/update-book: parameters: - $ref: '#/components/parameters/pathCollectionId' post: operationId: addOrUpdateBookToCollection summary: Add or update book in collection description: Add or update a book in a collection. The request body should contain the book ID and the position in the collection. If the position is not specified, the book is added to the end of the collection. tags: - Collection requestBody: content: application/json: schema: type: object properties: bookId: $ref: '#/components/schemas/itemId' position: type: integer description: The position in the collection to add the book. minimum: 0 nullable: true required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/bookCollectionDisplayObject' '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/collection/{id}/remove-book/{itemId}: parameters: - $ref: '#/components/parameters/pathCollectionId' - $ref: '#/components/parameters/pathItemSubId' delete: operationId: removeBookFromCollection summary: Remove book from collection description: Remove a book from a collection. tags: - Collection responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/bookCollectionDisplayObject' '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/collection/{id}/bulk/update-book: parameters: - $ref: '#/components/parameters/pathCollectionId' post: operationId: bulkUpdateCollectionBooks summary: Bulk update collection books description: Bulk update the books in a collection. The request body should contain an array of objects, each containing the book ID and the position in the collection. If the position is not specified, books are added to the end of the collection in the order they are specified in the request. tags: - Collection requestBody: content: application/json: schema: type: array items: type: object properties: bookId: $ref: '#/components/schemas/itemId' position: type: integer description: The position in the collection to add the book. minimum: 0 nullable: true required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/bookCollectionDisplayObject' '400': $ref: '#/components/responses/badRequest' /api/collection/{id}/bulk/remove-book: parameters: - $ref: '#/components/parameters/pathCollectionId' post: operationId: bulkRemoveBooksFromCollection summary: Bulk remove books from collection description: Bulk remove books from a collection. The request body should contain an array of book IDs to remove. tags: - Collection requestBody: content: application/json: schema: type: array items: $ref: '#/components/schemas/itemId' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/bookCollectionDisplayObject' '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/collection/{id}/podcast-episodes: parameters: - $ref: '#/components/parameters/pathCollectionId' get: operationId: getCollectionPodcastEpisodesById summary: Get collection of podcast episodes description: Get a collection by its ID. This endpoint returns all of the information needed for the collection details page and editing. tags: - Collection responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/podcastEpisodeCollectionDisplayObject' '400': $ref: '#/components/responses/podcastLibraryOnly' '404': $ref: '#/components/responses/notFound' patch: operationId: updatePodcastEpisodeCollectionById summary: Update podcast episode collection description: Update a collection 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: - Collection requestBody: content: application/json: schema: type: object properties: name: $ref: '#/components/schemas/title' description: $ref: '#/components/schemas/description' imageUrl: $ref: '#/components/schemas/imageUrl' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/podcastEpisodeCollectionDisplayObject' '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' delete: operationId: deletePodcastEpisodeCollectionById summary: Remove podcast episode collection description: Remove the collection and associated entries from the database. This does not delete any files from the filesystem. tags: - Collection responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/podcastEpisodeCollectionDisplayObject' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/collection/{id}/update-podcast-episode: parameters: - $ref: '#/components/parameters/pathCollectionId' post: operationId: addOrUpdatePodcastEpisodeToCollection summary: Add or update podcast episode in collection description: Add or update a podcast episode in a collection. The request body should contain the podcast episode ID and the position in the collection. If the position is not specified, the podcast episode is added to the end of the collection. tags: - Collection requestBody: content: application/json: schema: type: object properties: podcastEpisodeId: $ref: '#/components/schemas/itemId' position: type: integer description: The position in the collection to add the podcast episode. minimum: 0 nullable: true required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/podcastEpisodeCollectionDisplayObject' '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/collection/{id}/remove-podcast-episode/{itemId}: parameters: - $ref: '#/components/parameters/pathCollectionId' - $ref: '#/components/parameters/pathItemSubId' delete: operationId: removePodcastEpisodeFromCollection summary: Remove podcast episode from collection description: Remove a podcast episode from a collection. tags: - Collection responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/podcastEpisodeCollectionDisplayObject' '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/collection/{id}/bulk/update-podcast-episode: parameters: - $ref: '#/components/parameters/pathCollectionId' post: operationId: bulkUpdateCollectionPodcastEpisodes summary: Bulk update collection podcast episodes description: Bulk update the podcast episodes in a collection. The request body should contain an array of objects, each containing the podcast episode ID and the position in the collection. If the position is not specified, podcast episodes are added to the end of the collection in the order they are specified in the request. tags: - Collection requestBody: content: application/json: schema: type: array items: type: object properties: podcastEpisodeId: $ref: '#/components/schemas/itemId' position: type: integer description: The position in the collection to add the podcast episode. minimum: 0 nullable: true required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/podcastEpisodeCollectionDisplayObject' '400': $ref: '#/components/responses/badRequest' /api/collection/{id}/bulk/remove-podcast-episode: parameters: - $ref: '#/components/parameters/pathCollectionId' post: operationId: bulkRemovePodcastEpisodesFromCollection summary: Bulk remove podcast episodes from collection description: Bulk remove podcast episodes from a collection. The request body should contain an array of podcast episode IDs to remove. tags: - Collection requestBody: content: application/json: schema: type: array items: $ref: '#/components/schemas/itemId' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/podcastEpisodeCollectionDisplayObject' '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/playlist/{id}/books: parameters: - $ref: '#/components/parameters/pathPlaylistId' get: operationId: getPlaylistBooksById summary: Get playlist of books description: Get a playlist by its ID. This endpoint returns all of the information needed for the playlist details page and editing. tags: - Playlist responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/bookCollectionDisplayObject' '400': $ref: '#/components/responses/bookLibraryOnly' '404': $ref: '#/components/responses/notFound' patch: operationId: updateBookPlaylistById summary: Update book playlist description: Update a playlist 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: - Playlist requestBody: content: application/json: schema: type: object properties: name: $ref: '#/components/schemas/title' description: $ref: '#/components/schemas/description' imageUrl: $ref: '#/components/schemas/imageUrl' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/bookCollectionDisplayObject' '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' delete: operationId: deleteBookPlaylistById summary: Remove book playlist description: Remove the playlist and associated entries from the database. This does not delete any files from the filesystem. tags: - Playlist responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/bookCollectionDisplayObject' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/playlist/{id}/update-book: parameters: - $ref: '#/components/parameters/pathPlaylistId' post: operationId: addOrUpdateBookToPlaylist summary: Add or update book in playlist description: Add or update a book in a playlist. The request body should contain the book ID and the position in the playlist. If the position is not specified, the book is added to the end of the playlist. tags: - Playlist requestBody: content: application/json: schema: type: object properties: bookId: $ref: '#/components/schemas/itemId' position: type: integer description: The position in the playlist to add the book. minimum: 0 nullable: true required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/bookCollectionDisplayObject' '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/playlist/{id}/remove-book/{itemId}: parameters: - $ref: '#/components/parameters/pathPlaylistId' - $ref: '#/components/parameters/pathItemSubId' delete: operationId: removeBookFromPlaylist summary: Remove book from playlist description: Remove a book from a playlist. tags: - Playlist responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/bookCollectionDisplayObject' '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/playlist/{id}/bulk/update-book: parameters: - $ref: '#/components/parameters/pathPlaylistId' post: operationId: bulkUpdatePlaylistBooks summary: Bulk update playlist books description: Bulk update the books in a playlist. The request body should contain an array of objects, each containing the book ID and the position in the playlist. If the position is not specified, books are added to the end of the playlist in the order they are specified in the request. tags: - Playlist requestBody: content: application/json: schema: type: array items: type: object properties: bookId: $ref: '#/components/schemas/itemId' position: type: integer description: The position in the playlist to add the book. minimum: 0 nullable: true required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/bookCollectionDisplayObject' '400': $ref: '#/components/responses/badRequest' /api/playlist/{id}/bulk/remove-book: parameters: - $ref: '#/components/parameters/pathPlaylistId' post: operationId: bulkRemoveBooksFromPlaylist summary: Bulk remove books from playlist description: Bulk remove books from a playlist. The request body should contain an array of book IDs to remove. tags: - Playlist requestBody: content: application/json: schema: type: array items: $ref: '#/components/schemas/itemId' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/bookCollectionDisplayObject' '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/playlist/{id}/podcast-episodes: parameters: - $ref: '#/components/parameters/pathPlaylistId' get: operationId: getPlaylistPodcastEpisodesById summary: Get playlist of podcast episodes description: Get a playlist by its ID. This endpoint returns all of the information needed for the playlist details page and editing. tags: - Playlist responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/podcastEpisodeCollectionDisplayObject' '400': $ref: '#/components/responses/podcastLibraryOnly' '404': $ref: '#/components/responses/notFound' patch: operationId: updatePodcastEpisodePlaylistById summary: Update podcast episode playlist description: Update a playlist 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: - Playlist requestBody: content: application/json: schema: type: object properties: name: $ref: '#/components/schemas/title' description: $ref: '#/components/schemas/description' imageUrl: $ref: '#/components/schemas/imageUrl' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/podcastEpisodeCollectionDisplayObject' '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' delete: operationId: deletePodcastEpisodePlaylistById summary: Remove podcast episode playlist description: Remove the playlist and associated entries from the database. This does not delete any files from the filesystem. tags: - Playlist responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/podcastEpisodeCollectionDisplayObject' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/playlist/{id}/update-podcast-episode: parameters: - $ref: '#/components/parameters/pathPlaylistId' post: operationId: addOrUpdatePodcastEpisodeToPlaylist summary: Add or update podcast episode in playlist description: Add or update a podcast episode in a playlist. The request body should contain the podcast episode ID and the position in the playlist. If the position is not specified, the podcast episode is added to the end of the playlist. tags: - Playlist requestBody: content: application/json: schema: type: object properties: podcastEpisodeId: $ref: '#/components/schemas/itemId' position: type: integer description: The position in the playlist to add the podcast episode. minimum: 0 nullable: true required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/podcastEpisodeCollectionDisplayObject' '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/playlist/{id}/remove-podcast-episode/{itemId}: parameters: - $ref: '#/components/parameters/pathPlaylistId' - $ref: '#/components/parameters/pathItemSubId' delete: operationId: removePodcastEpisodeFromPlaylist summary: Remove podcast episode from playlist description: Remove a podcast episode from a playlist. tags: - Playlist responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/podcastEpisodeCollectionDisplayObject' '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/playlist/{id}/bulk/update-podcast-episode: parameters: - $ref: '#/components/parameters/pathPlaylistId' post: operationId: bulkUpdatePlaylistPodcastEpisodes summary: Bulk update playlist podcast episodes description: Bulk update the podcast episodes in a playlist. The request body should contain an array of objects, each containing the podcast episode ID and the position in the playlist. If the position is not specified, podcast episodes are added to the end of the playlist in the order they are specified in the request. tags: - Playlist requestBody: content: application/json: schema: type: array items: type: object properties: podcastEpisodeId: $ref: '#/components/schemas/itemId' position: type: integer description: The position in the playlist to add the podcast episode. minimum: 0 nullable: true required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/podcastEpisodeCollectionDisplayObject' '400': $ref: '#/components/responses/badRequest' /api/playlist/{id}/bulk/remove-podcast-episode: parameters: - $ref: '#/components/parameters/pathPlaylistId' post: operationId: bulkRemovePodcastEpisodesFromPlaylist summary: Bulk remove podcast episodes from playlist description: Bulk remove podcast episodes from a playlist. The request body should contain an array of podcast episode IDs to remove. tags: - Playlist requestBody: content: application/json: schema: type: array items: $ref: '#/components/schemas/itemId' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/podcastEpisodeCollectionDisplayObject' '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/backup: get: operationId: getAllBackups summary: Get all backups description: Get all backups. This endpoint returns all of the information needed for the backups page. tags: - Backup responses: '200': description: OK content: application/json: schema: type: object properties: backups: type: array items: $ref: '#/components/schemas/backupObject' '403': $ref: '#/components/responses/forbidden' patch: operationId: updateBackupSettings summary: Update backup settings description: Update the backup settings. The request body should contain the new settings. This endpoint will return a 400 error if the backup path is set by an environment variable. tags: - Backup requestBody: content: application/json: schema: $ref: '#/components/schemas/backupSettings' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/backupSettings' '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden' /api/backup/create: post: operationId: createBackup summary: Create backup description: Create a backup. This endpoint creates a backup of the database and files and returns the backup information. tags: - Backup responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/backupObject' '403': $ref: '#/components/responses/forbidden' /api/backup/{id}: parameters: - $ref: '#/components/parameters/pathBackupId' get: operationId: getBackupById summary: Get backup by ID description: Get a backup by its ID. This endpoint returns all of the information needed for the backup details page. tags: - Backup responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/backupObject' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' delete: operationId: deleteBackupById summary: Remove backup description: Remove a backup by its ID. This endpoint removes the backup from the database and deletes the backup files. tags: - Backup responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/backupObject' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/backup/{id}/apply: parameters: - $ref: '#/components/parameters/pathBackupId' post: operationId: applyBackupById summary: Apply backup description: Apply a backup by its ID. This endpoint restores the database and files from the backup. tags: - Backup responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/backupObject' '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/backup/{id}/download: parameters: - $ref: '#/components/parameters/pathBackupId' get: operationId: downloadBackupById summary: Download backup description: Download a backup by its ID. This endpoint returns the backup files as a zip archive. tags: - Backup responses: '200': description: OK content: application/zip: schema: type: string format: binary '403': $ref: '#/components/responses/forbidden' '404': $ref: '#/components/responses/notFound' /api/backup/upload: post: operationId: uploadBackup summary: Upload backup description: Upload a backup. This endpoint uploads a backup zip archive. tags: - Backup requestBody: content: multipart/form-data: schema: type: object properties: backup: type: string format: binary required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/backupObject' '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden' /api/backup/path: get: operationId: getBackupPath summary: Get backup path description: Get the path to the backup directory. tags: - Backup responses: '200': description: OK content: application/json: schema: type: object properties: path: type: string '403': $ref: '#/components/responses/forbidden' patch: operationId: updateBackupPath summary: Update backup path description: Update the path to the backup directory. The request body should contain the new path. This endpoint will return a 400 error if the backup path is set by an environment variable. tags: - Backup requestBody: content: application/json: schema: type: object properties: path: $ref: '#/components/schemas/folderPath' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/folderPath' '400': $ref: '#/components/responses/badRequest' '403': $ref: '#/components/responses/forbidden'