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 pathBookId: name: id in: path required: true description: The ID of the book. 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 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 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'] 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' 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. 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. 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' 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' 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}/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: 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' '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/library/{id}/opml: parameters: - $ref: '#/components/parameters/pathLibraryId' get: operationId: getLibraryOpmlById summary: Get library OPML by ID description: Generate an OPML file for the library. This endpoint is only available for podcast libraries. tags: - Library responses: '200': description: OK content: application/xml: schema: type: string format: binary '403': $ref: '#/components/responses/podcastLibraryOnly' '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'