audiobookshelf/docs/newRoot.yaml

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
  schemas:
    itemId:
      type: string
      description: A unique ID for the item. This ID is unique across all tables.
      format: uuid
    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
    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.
    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
    hasFeedOpen:
      type: boolean
      description: Whether the item has an open feed.
    rssFeed:
      type: string
      description: The RSS feed of the podcast.
      nullable: true
    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.
    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'
    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'
    libraryBook:
      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'
    libraryPodcast:
      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
    libraryPodcastEpisode:
      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'
    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'
  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.
tags:
  - name: Book
    description: Book endpoints
paths:
  /api/book/{id}:
    parameters:
      - name: id
        in: path
        required: true
        description: The ID of the book.
        schema:
          type: string
          format: uuid
    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:
      - name: id
        in: path
        required: true
        description: The ID of the book.
        schema:
          type: string
          format: uuid
    delete:
      operationId: hardDeleteBookById
      summary: Hard delete book by ID
      description: Hard delete the book and associated entries from the database. This deletes the book's files from the filesystem. This action cannot be undone.
      tags:
        - Book
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bookObject'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
  /api/book/{id}/download:
    parameters:
      - name: id
        in: path
        required: true
        description: The ID of the book.
        schema:
          type: string
          format: uuid
    get:
      operationId: downloadBookById
      summary: Download book by ID
      description: Download the book by its ID. This endpoint will return the book's files as a zip archive.
      tags:
        - Book
      responses:
        '200':
          description: OK
          content:
            application/zip:
              schema:
                type: string
                format: binary
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
  /api/book/{id}/cover:
    parameters:
      - name: id
        in: path
        required: true
        description: The ID of the book.
        schema:
          type: string
          format: uuid
    get:
      operationId: getBookCoverById
      summary: Get book cover by ID
      description: Get the book cover by its ID. This endpoint will return the book's cover image. If no query parameters are provided, the image will be returned in the original format with the original dimensions.
      tags:
        - Book
      parameters:
        - name: width
          in: query
          required: false
          description: The width of the image in pixels.
          schema:
            type: integer
            minimum: 1
        - name: height
          in: query
          required: false
          description: The height of the image in pixels. If this parameter is not provided, the image will be scaled proportionally to the width.
          schema:
            type: integer
            minimum: 1
        - name: format
          in: query
          required: false
          description: The format of the image. If not provided, the image will be returned in the original format.
          schema:
            type: string
            enum: ['jpeg', 'png', 'webp']
            default: 'jpeg'
      responses:
        '200':
          description: OK
          content:
            image/jpeg:
              schema:
                type: string
                format: binary
            image/png:
              schema:
                type: string
                format: binary
            image/webp:
              schema:
                type: string
                format: binary
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
    post:
      operationId: uploadBookCoverById
      summary: Upload book cover by ID
      description: Upload the book cover image to the book by the book ID. This endpoint will replace the book's cover image with the provided image. The image should be in JPEG, PNG, or WebP format. Alternatively, the image can be provided as a URL to download the image from.
      tags:
        - Book
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                cover:
                  type: string
                  format: binary
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  description: The URL to download the image from.
                  format: uri
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                properties:
                  coverPath:
                    $ref: '#/components/schemas/imagePath'
                  success:
                    type: boolean
        '400':
          $ref: '#/components/responses/badRequest'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
    patch:
      operationId: updateBookCoverById
      summary: Update book cover by ID
      description: Update the book cover to be an existing image in the database. This endpoint will replace the book's cover image with the provided image. The image should be in JPEG, PNG, or WebP format.
      tags:
        - Book
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                coverId:
                  $ref: '#/components/schemas/itemId'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                properties:
                  coverPath:
                    $ref: '#/components/schemas/imagePath'
                  success:
                    type: boolean
        '400':
          $ref: '#/components/responses/badRequest'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
    delete:
      operationId: deleteBookCoverById
      summary: Remove book cover by ID
      description: Remove the book cover image from the book. The cover image file is not deleted but is no longer associated with the book.
      tags:
        - Book
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                properties:
                  coverPath:
                    $ref: '#/components/schemas/imagePath'
                  success:
                    type: boolean
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
  /api/book/{id}/match:
    parameters:
      - name: id
        in: path
        required: true
        description: The ID of the book.
        schema:
          type: string
          format: uuid
    post:
      operationId: matchBookById
      summary: Match book by ID
      description: Match the book selected by ID against an online database. This performs a quick match against the online database and returns the best match. Quick match will apply the cover from the first match and fill empty metadata fields. Metadata fields are not overwritten unless the "Prefer Matched Metadata" setting is enabled or the "force" query is set.
      tags:
        - Book
      parameters:
        - in: query
          name: force
          required: false
          description: Whether to force the match and overwrite all metadata fields.
          schema:
            type: boolean
            default: false
        - in: query
          name: provider
          required: false
          description: The provider to use for the match. If not provided, the default library provider will be used.
          schema:
            type: string
            enum: ['google', 'openlibrary', 'goodreads']
        - in: query
          name: title
          required: false
          description: The title of the book to match.
          schema:
            type: string
        - in: query
          name: author
          required: false
          description: The author of the book to match.
          schema:
            type: string
        - in: query
          name: isbn
          required: false
          description: The ISBN of the book to match.
          schema:
            type: string
        - in: query
          name: asin
          required: false
          description: The ASIN of the book to match. Note that this needs to match the Audible page, not the Amazon page.
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/bookObject'
                  - type: object
                    properties:
                      updated:
                        type: boolean
                        description: Whether the book was updated with the match.
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
  /api/book/{id}/tracks:
    parameters:
      - name: id
        in: path
        required: true
        description: The ID of the book.
        schema:
          type: string
          format: uuid
    patch:
      operationId: updateBookTracksById
      summary: Update book tracks
      description: Update the book's audio tracks based on the provided file IDs. This endpoint will replace the book's audio tracks with the provided tracks. The tracks should be in the correct order.
      tags:
        - Book
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                trackIds:
                  type: array
                  description: The IDs of the audio files to use as tracks.
                  items:
                    $ref: '#/components/schemas/itemId'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/bookObject'
        '400':
          $ref: '#/components/responses/badRequest'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
  /api/book/{id}/scan:
    parameters:
      - name: id
        in: path
        required: true
        description: The ID of the book.
        schema:
          type: string
          format: uuid
    post:
      operationId: scanBookById
      summary: Scan book by ID
      description: Scan the book by its ID. This endpoint will scan the book's files and update the book's metadata based on the files found according to the metadata priority settings.
      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:
      - name: id
        in: path
        required: true
        description: The ID of the podcast.
        schema:
          type: string
          format: uuid
    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:
      - name: id
        in: path
        required: true
        description: The ID of the podcast.
        schema:
          type: string
          format: uuid
    delete:
      operationId: hardDeletePodcastById
      summary: Hard delete podcast by ID
      description: Hard delete the podcast and associated entries from the database. This deletes the podcast's files from the filesystem. This action cannot be undone.
      tags:
        - Podcast
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/podcastObject'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
  /api/podcast/{id}/download:
    parameters:
      - name: id
        in: path
        required: true
        description: The ID of the podcast.
        schema:
          type: string
          format: uuid
    get:
      operationId: downloadPodcastById
      summary: Download podcast by ID
      description: Download the podcast by its ID. This endpoint will return the podcast's files as a zip archive.
      tags:
        - Podcast
      responses:
        '200':
          description: OK
          content:
            application/zip:
              schema:
                type: string
                format: binary
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
  /api/podcast/{id}/cover:
    parameters:
      - name: id
        in: path
        required: true
        description: The ID of the podcast.
        schema:
          type: string
          format: uuid
    get:
      operationId: getPodcastCoverById
      summary: Get podcast cover by ID
      description: Get the podcast cover by its ID. This endpoint will return the podcast's cover image. If no query parameters are provided, the image will be returned in the original format with the original dimensions.
      tags:
        - Podcast
      parameters:
        - name: width
          in: query
          required: false
          description: The width of the image in pixels.
          schema:
            type: integer
            minimum: 1
        - name: height
          in: query
          required: false
          description: The height of the image in pixels. If this parameter is not provided, the image will be scaled proportionally to the width.
          schema:
            type: integer
            minimum: 1
        - name: format
          in: query
          required: false
          description: The format of the image. If not provided, the image will be returned in the original format.
          schema:
            type: string
            enum: ['jpeg', 'png', 'webp']
            default: 'jpeg'
      responses:
        '200':
          description: OK
          content:
            image/jpeg:
              schema:
                type: string
                format: binary
            image/png:
              schema:
                type: string
                format: binary
            image/webp:
              schema:
                type: string
                format: binary
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
    post:
      operationId: uploadPodcastCoverById
      summary: Upload podcast cover by ID
      description: Upload the podcast cover image to the podcast by the podcast ID. This endpoint will replace the podcast's cover image with the provided image. The image should be in JPEG, PNG, or WebP format. Alternatively, the image can be provided as a URL to download the image from.
      tags:
        - Podcast
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                cover:
                  type: string
                  format: binary
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  description: The URL to download the image from.
                  format: uri
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                properties:
                  coverPath:
                    $ref: '#/components/schemas/imagePath'
                  success:
                    type: boolean
        '400':
          $ref: '#/components/responses/badRequest'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
    patch:
      operationId: updatePodcastCoverById
      summary: Update podcast cover by ID
      description: Update the podcast cover to be an existing image in the database. This endpoint will replace the podcast's cover image with the provided image. The image should be in JPEG, PNG, or WebP format.
      tags:
        - Podcast
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                coverId:
                  $ref: '#/components/schemas/itemId'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                properties:
                  coverPath:
                    $ref: '#/components/schemas/imagePath'
                  success:
                    type: boolean
        '400':
          $ref: '#/components/responses/badRequest'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
    delete:
      operationId: deletePodcastCoverById
      summary: Remove podcast cover by ID
      description: Remove the podcast cover image from the podcast. The cover image file is not deleted but is no longer associated with the podcast.
      tags:
        - Podcast
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                properties:
                  coverPath:
                    $ref: '#/components/schemas/imagePath'
                  success:
                    type: boolean
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
  /api/podcast/{id}/match:
    parameters:
      - name: id
        in: path
        required: true
        description: The ID of the podcast.
        schema:
          type: string
          format: uuid
    post:
      operationId: matchPodcastById
      summary: Match podcast by ID
      description: Match the podcast selected by ID against an online database. This returns an array of possible matches. The user can select the best match from the list and select which metadata fields should be kept.
      tags:
        - Podcast
      parameters:
        - in: query
          name: provider
          required: false
          description: The provider to use for the match. If not provided, the default library provider will be used.
          schema:
            type: string
            enum: ['itunes', 'google', 'podcastindex']
        - in: query
          name: rssFeed
          required: false
          description: The RSS feed of the podcast to match.
          schema:
            type: string
        - in: query
          name: title
          required: false
          description: The title of the podcast to match.
          schema:
            type: string
        - in: query
          name: itunesId
          required: false
          description: The iTunes ID of the podcast to match.
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/podcastMatchObject'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
  /api/podcast/{id}/tracks:
    parameters:
      - name: id
        in: path
        required: true
        description: The ID of the podcast.
        schema:
          type: string
          format: uuid
    get:
      operationId: getPodcastTracksById
      summary: Get podcast tracks by ID
      description: Get the podcast's audio tracks by its ID. This endpoint will return the podcast's audio tracks.
      tags:
        - Podcast
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/audioTrack'
        '404':
          $ref: '#/components/responses/notFound'
    patch:
      operationId: updatePodcastTracksById
      summary: Update podcast tracks by ID
      description: Update the podcast's audio tracks based on the provided file IDs. This endpoint will replace the podcast's audio tracks with the provided tracks. The tracks should be in the correct order.
      tags:
        - Podcast
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                trackIds:
                  type: array
                  description: The IDs of the audio files to use as tracks.
                  items:
                    $ref: '#/components/schemas/itemId'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/podcastObject'
        '400':
          $ref: '#/components/responses/badRequest'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
  /api/podcast/{id}/scan:
    parameters:
      - name: id
        in: path
        required: true
        description: The ID of the podcast.
        schema:
          type: string
          format: uuid
    post:
      operationId: scanPodcastById
      summary: Scan podcast by ID
      description: Scan the podcast by its ID. This endpoint will scan the podcast's files and update the podcast's metadata based on the files found according to the metadata priority settings.
      tags:
        - Podcast
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/podcastObject'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
  /api/podcast/{id}/episodes:
    parameters:
      - name: id
        in: path
        required: true
        description: The ID of the podcast.
        schema:
          type: string
          format: uuid
    get:
      operationId: getPodcastEpisodesById
      summary: Get podcast episodes by ID
      description: Get the podcast's episodes by its ID. This endpoint will return the podcast's episodes.
      tags:
        - Podcast
      parameters:
        - in: query
          name: limit
          required: true
          description: The maximum number of episodes to return. This defines the page size
          schema:
            type: integer
            minimum: 1
            default: 20
        - in: query
          name: page
          required: true
          description: The page of episodes to return. This is used in conjunction with the limit parameter.
          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/library/{id}/books:
    parameters:
      - name: id
        in: path
        required: true
        description: The ID of the library.
        schema:
          type: string
          format: uuid
    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:
        - in: query
          name: limit
          required: true
          description: The maximum number of books to return. This defines the page size
          schema:
            type: integer
            minimum: 1
            default: 20
        - in: query
          name: page
          required: true
          description: The page of books 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 books by.
          schema:
            type: string
            enum: ['title', 'publishYear', 'author', 'narrator', 'series', 'seriesSequence', 'size', 'duration', 'progress']
            default: 'title'
        - in: query
          name: filter
          required: false
          description: A key-value pair of how to filter books. 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: ['genre', 'tag', 'author', 'narrator', 'series', 'seriesSequence', 'publishYear', 'publisher', 'isbn', 'asin', 'progress', 'all']
      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/libraryBook'
        '404':
          $ref: '#/components/responses/notFound'
  /api/library/{id}/podcasts:
    parameters:
      - name: id
        in: path
        required: true
        description: The ID of the library.
        schema:
          type: string
          format: uuid
    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:
        - in: query
          name: limit
          required: true
          description: The maximum number of podcasts to return. This defines the page size
          schema:
            type: integer
            minimum: 1
            default: 20
        - in: query
          name: page
          required: true
          description: The page of podcasts 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 podcasts by.
          schema:
            type: string
            enum: ['title', 'author', 'releaseDate', 'type', 'rssFeed', 'autoDownloadEnabled', 'autoDownloadSchedule', 'lastEpisodeCheck', 'maxEpisodesToKeep', 'maxNewEpisodestoDownload']
            default: 'title'
        - in: query
          name: filter
          required: false
          description: A key-value pair of how to filter podcasts. 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: ['genre', 'tag', 'author', 'rssFeed', 'type', 'autoDownloadEnabled', 'autoDownloadSchedule', 'lastEpisodeCheck', 'maxEpisodesToKeep', 'maxNewEpisodestoDownload', 'all']
      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/libraryPodcast'
        '404':
          $ref: '#/components/responses/notFound'
  /api/library/{id}/podcast-episodes:
    parameters:
      - name: id
        in: path
        required: true
        description: The ID of the library.
        schema:
          type: string
          format: uuid
    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:
        - in: query
          name: limit
          required: true
          description: The maximum number of podcast 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 podcast 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 podcast episodes by.
          schema:
            type: string
            enum: ['releaseDate', 'title', 'duration', 'size', 'episodeNumber', 'seasonNumber']
            default: 'releaseDate'
        - 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/libraryPodcastEpisode'
        '404':
          $ref: '#/components/responses/notFound'