openapi: 3.0.0
info:
  title: Audiobookshelf API
  version: 0.1.0
  description: Audiobookshelf API with autogenerated OpenAPI doc
servers:
  - url: http://localhost:3000
    description: Development server
security:
  - BearerAuth: []
tags:
  - name: Authors
    description: Author endpoints
  - name: Libraries
    description: Library endpoints
  - name: Series
    description: Series endpoints
  - name: Email
    description: Email endpoints
  - name: Notification
    description: Notifications endpoints
  - name: Podcasts
    description: Podcast endpoints
  - name: Auth
    description: Authentication endpoints
  - name: Me
    description: User endpoints
  - name: Session
    description: Session endpoints
paths:
  /api/authors/{id}:
    parameters:
      - name: id
        in: path
        description: Author ID
        required: true
        schema:
          $ref: '#/components/schemas/authorId'
    get:
      operationId: getAuthorById
      summary: Get an author by ID
      description: Get an author by ID. The author's books and series can be included in the response.
      tags:
        - Authors
      parameters:
        - in: query
          name: include
          description: A comma separated list of what to include with the author. The options are `items` and `series`. `series` will only have an effect if `items` is included. For example, the value `items,series` will include both library items and series.
          allowReserved: true
          schema:
            type: string
          example: items,series
      responses:
        '200':
          description: getAuthorById OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/author'
        '404':
          $ref: '#/components/responses/author404'
    patch:
      operationId: updateAuthorById
      summary: Update an author by ID
      description: Update an author by ID. The author's name and description can be updated. This endpoint will merge two authors if the new author name matches another author name in the database.
      tags:
        - Authors
      requestBody:
        description: The author object to update.
        content:
          application/json:
            schema:
              properties:
                name:
                  $ref: '#/components/schemas/authorName'
                description:
                  $ref: '#/components/schemas/authorDescription'
                imagePath:
                  $ref: '#/components/schemas/authorImagePath'
                asin:
                  $ref: '#/components/schemas/authorAsin'
      responses:
        '200':
          description: updateAuthorById OK
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/author'
                  - $ref: '#/components/schemas/authorUpdated'
                  - $ref: '#/components/schemas/authorMerged'
        '404':
          $ref: '#/components/responses/author404'
    delete:
      operationId: deleteAuthorById
      summary: Delete an author by ID
      description: Delete an author by ID. This will remove the author from all books.
      tags:
        - Authors
      responses:
        '200':
          description: deleteAuthorById OK
          content:
            text/plain:
              schema:
                type: string
                example: Author deleted.
        '404':
          $ref: '#/components/responses/author404'
  /api/authors/{id}/image:
    parameters:
      - name: id
        in: path
        description: Author ID
        required: true
        schema:
          $ref: '#/components/schemas/authorId'
      - name: token
        in: query
        description: API token
        schema:
          type: string
      - name: ts
        in: query
        description: Updated at value
        schema:
          type: integer
    get:
      operationId: getAuthorImageById
      summary: Get an author image by author ID
      description: Get an author image by author ID. The image will be returned in the requested format and size.
      security: []
      tags:
        - Authors
      requestBody:
        required: false
        description: The author image to get.
        content:
          application/json:
            schema:
              properties:
                width:
                  $ref: '#/components/schemas/imageWidth'
                height:
                  $ref: '#/components/schemas/imageHeight'
                format:
                  $ref: '#/components/schemas/imageFormat'
                raw:
                  $ref: '#/components/schemas/imageRaw'
      responses:
        '200':
          description: getAuthorImageById OK
          content:
            image/webp:
              schema:
                type: string
                format: binary
            image/jpeg:
              schema:
                type: string
                format: binary
            image/*:
              schema:
                type: string
                format: binary
        '404':
          $ref: '#/components/responses/author404'
    post:
      operationId: addAuthorImageById
      summary: Add an author image to the server
      description: Add an author image to the server. The image will be downloaded from the provided URL and stored on the server.
      tags:
        - Authors
      requestBody:
        required: true
        description: The author image to add by URL.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/imageUrl'
      responses:
        '200':
          description: addAuthorImageById OK
          content:
            image/*:
              schema:
                type: string
                format: binary
        '404':
          $ref: '#/components/responses/author404'
    patch:
      operationId: updateAuthorImageById
      summary: Update an author image by author ID
      description: Update an author image by author ID. The image will be resized if the width, height, or format is provided.
      tags:
        - Authors
      requestBody:
        description: The author image to update.
        content:
          application/json:
            schema:
              properties:
                width:
                  $ref: '#/components/schemas/imageWidth'
                height:
                  $ref: '#/components/schemas/imageHeight'
                format:
                  $ref: '#/components/schemas/imageFormat'
                raw:
                  $ref: '#/components/schemas/imageRaw'
      responses:
        '200':
          description: updateAuthorImageById OK
          content:
            image/*:
              schema:
                type: string
                format: binary
        '404':
          $ref: '#/components/responses/author404'
    delete:
      operationId: deleteAuthorImageById
      summary: Delete an author image by author ID
      description: Delete an author image by author ID. This will remove the image from the server and the database.
      tags:
        - Authors
      responses:
        '200':
          description: deleteAuthorImageById OK
        '404':
          $ref: '#/components/responses/author404'
  /api/authors/{id}/match:
    parameters:
      - name: id
        in: path
        description: Author ID
        required: true
        schema:
          $ref: '#/components/schemas/authorId'
    post:
      operationId: matchAuthorById
      summary: Match the author against Audible using quick match
      description: Match the author against Audible using quick match. Quick match updates the author's description and image (if no image already existed) with information from audible. Either `asin` or `q` must be provided, with `asin` taking priority if both are provided.
      tags:
        - Authors
      requestBody:
        required: true
        description: The author object to match against an online provider.
        content:
          application/json:
            schema:
              type: object
              properties:
                q:
                  $ref: '#/components/schemas/authorSearchName'
                asin:
                  $ref: '#/components/schemas/authorAsin'
                region:
                  $ref: '#/components/schemas/region'
      responses:
        '200':
          description: matchAuthorById OK
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/author'
                  - $ref: '#/components/schemas/authorUpdated'
        '404':
          $ref: '#/components/responses/author404'
  /api/emails/settings:
    get:
      summary: Get email settings
      description: Get email settings for sending e-books to e-readers.
      operationId: getEmailSettings
      tags:
        - Email
      responses:
        '200':
          $ref: '#/components/responses/email200'
    patch:
      summary: Update email settings
      operationId: updateEmailSettings
      tags:
        - Email
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmailSettings'
      responses:
        '200':
          $ref: '#/components/responses/email200'
  /api/emails/test:
    post:
      summary: Send test email
      operationId: sendTestEmail
      tags:
        - Email
      responses:
        '200':
          description: Successful response
  /api/emails/ereader-devices:
    post:
      summary: Update e-reader devices
      operationId: updateEReaderDevices
      tags:
        - Email
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ereaderDevices:
                  type: array
                  items:
                    $ref: '#/components/schemas/EreaderDeviceObject'
      responses:
        '200':
          $ref: '#/components/responses/ereader200'
        '400':
          description: Invalid payload
  /api/emails/send-ebook-to-device:
    post:
      summary: Send ebook to device
      operationId: sendEBookToDevice
      tags:
        - Email
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                libraryItemId:
                  $ref: '#/components/schemas/libraryItemId'
                deviceName:
                  $ref: '#/components/schemas/ereaderName'
      responses:
        '200':
          description: Successful response
        '400':
          description: Invalid request
        '403':
          description: Forbidden
        '404':
          description: Not found
  /api/libraries:
    get:
      operationId: getLibraries
      summary: Get all libraries on server
      description: Get all libraries on server.
      tags:
        - Libraries
      responses:
        '200':
          description: getLibraries OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  libraries:
                    type: array
                    items:
                      $ref: '#/components/schemas/library'
    post:
      operationId: createLibrary
      summary: Create a new library on server
      description: Create a new library on server.
      tags:
        - Libraries
      requestBody:
        description: The library object to create.
        content:
          application/json:
            schema:
              type: object
              required:
                - name
                - folders
              properties:
                name:
                  $ref: '#/components/schemas/libraryName'
                folders:
                  $ref: '#/components/schemas/libraryFolders'
                displayOrder:
                  $ref: '#/components/schemas/libraryDisplayOrder'
                icon:
                  $ref: '#/components/schemas/libraryIcon'
                mediaType:
                  $ref: '#/components/schemas/libraryMediaType'
                provider:
                  $ref: '#/components/schemas/libraryProvider'
                settings:
                  $ref: '#/components/schemas/librarySettings'
      responses:
        '200':
          $ref: '#/components/responses/library200'
        '404':
          $ref: '#/components/responses/library404'
  /api/libraries/{id}:
    parameters:
      - name: id
        in: path
        description: The ID of the library.
        required: true
        schema:
          $ref: '#/components/schemas/libraryId'
    get:
      operationId: getLibraryById
      summary: Get a single library by ID on server
      description: Get a single library by ID on server.
      tags:
        - Libraries
      parameters:
        - in: query
          name: include
          description: A comma separated list of what to include with the library item. The only current option is filterdata.
          schema:
            type: string
        - $ref: '#/components/parameters/minified'
      responses:
        '200':
          $ref: '#/components/responses/library200'
        '404':
          $ref: '#/components/responses/library404'
    patch:
      operationId: updateLibraryById
      summary: Update a single library by ID on server
      description: Update a single library by ID on server.
      tags:
        - Libraries
      requestBody:
        required: true
        description: The library object to update.
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  $ref: '#/components/schemas/libraryName'
                folders:
                  $ref: '#/components/schemas/libraryFolders'
                displayOrder:
                  $ref: '#/components/schemas/libraryDisplayOrder'
                icon:
                  $ref: '#/components/schemas/libraryIcon'
                mediaType:
                  $ref: '#/components/schemas/libraryMediaType'
                provider:
                  $ref: '#/components/schemas/libraryProvider'
                settings:
                  $ref: '#/components/schemas/librarySettings'
      responses:
        '200':
          $ref: '#/components/responses/library200'
        '404':
          $ref: '#/components/responses/library404'
    delete:
      operationId: deleteLibraryById
      summary: Delete a single library by ID on server
      description: Delete a single library by ID on server and return the deleted object.
      tags:
        - Libraries
      responses:
        '200':
          $ref: '#/components/responses/library200'
        '404':
          $ref: '#/components/responses/library404'
  /api/libraries/{id}/authors:
    parameters:
      - name: id
        in: path
        description: The ID of the library.
        required: true
        schema:
          $ref: '#/components/schemas/libraryId'
    get:
      operationId: getLibraryAuthors
      summary: Get all authors in a library
      description: Get all authors in a library by ID on server.
      tags:
        - Libraries
      responses:
        '200':
          description: getLibraryAuthors OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  authors:
                    type: array
                    items:
                      $ref: '#/components/schemas/authorExpanded'
        '404':
          $ref: '#/components/responses/library404'
  /api/libraries/{id}/items:
    parameters:
      - name: id
        in: path
        description: The ID of the library.
        required: true
        schema:
          $ref: '#/components/schemas/libraryId'
    get:
      operationId: getLibraryItems
      summary: Get items in a library
      description: Get items in a library by ID on server.
      tags:
        - Libraries
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/page'
        - in: query
          name: sort
          description: The field to sort by from the request.
          example: numBooks
          schema:
            type: string
            default: name
        - $ref: '#/components/parameters/desc'
        - in: query
          name: filter
          description: The filter for the library.
          example: media.metadata.title
          schema:
            type: string
        - in: query
          name: include
          description: The fields to include in the response. The only current option is `rssfeed`.
          allowReserved: true
          example: rssfeed
          schema:
            type: string
        - $ref: '#/components/parameters/minified'
        - in: query
          name: collapseSeries
          description: Whether to collapse series into a single cover
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: getLibraryItems OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/libraryItemBase'
                  total:
                    $ref: '#/components/schemas/total'
                  limit:
                    $ref: '#/components/schemas/limit'
                  page:
                    $ref: '#/components/schemas/page'
                  sortBy:
                    $ref: '#/components/schemas/sortBy'
                  sortDesc:
                    $ref: '#/components/schemas/sortDesc'
                  filterBy:
                    $ref: '#/components/schemas/filterBy'
                  mediaType:
                    $ref: '#/components/schemas/mediaType'
                  minified:
                    $ref: '#/components/schemas/minified'
                  collapseSeries:
                    $ref: '#/components/schemas/collapseSeries'
                  include:
                    $ref: '#/components/schemas/libraryInclude'
        '404':
          $ref: '#/components/responses/library404'
  /api/libraries/{id}/issues:
    parameters:
      - name: id
        in: path
        description: The ID of the library.
        required: true
        schema:
          $ref: '#/components/schemas/libraryId'
    delete:
      operationId: deleteLibraryIssues
      summary: Delete items with issues in a library.
      description: Delete all items with issues in a library by library ID on the server. This only removes the items from the ABS database and does not delete media files.
      tags:
        - Libraries
      responses:
        '200':
          description: deleteLibraryIssues OK
          content:
            application/json:
              schema:
                type: string
                example: Issues deleted.
        '404':
          $ref: '#/components/responses/library404'
  /api/libraries/{id}/series:
    parameters:
      - name: id
        in: path
        description: The ID of the library.
        required: true
        schema:
          $ref: '#/components/schemas/libraryId'
    get:
      operationId: getLibrarySeries
      summary: Get library series
      description: Get series in a library. Filtering and sorting can be applied.
      tags:
        - Libraries
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/page'
        - in: query
          name: sort
          description: The field to sort by from the request.
          example: numBooks
          schema:
            type: string
            enum:
              - name
              - numBooks
              - totalDuration
              - addedAt
              - lastBookAdded
              - lastBookUpdated
            default: name
        - $ref: '#/components/parameters/desc'
        - in: query
          name: filter
          description: The filter for the library.
          example: media.metadata.title
          schema:
            type: string
        - in: query
          name: include
          description: The fields to include in the response. The only current option is `rssfeed`.
          allowReserved: true
          example: rssfeed
          schema:
            type: string
        - $ref: '#/components/parameters/minified'
      responses:
        '200':
          description: getLibrarySeries OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/seriesBooks'
                  total:
                    $ref: '#/components/schemas/total'
                  limit:
                    $ref: '#/components/schemas/limit'
                  page:
                    $ref: '#/components/schemas/page'
                  sortBy:
                    $ref: '#/components/schemas/sortBy'
                  sortDesc:
                    $ref: '#/components/schemas/sortDesc'
                  filterBy:
                    $ref: '#/components/schemas/filterBy'
                  minified:
                    $ref: '#/components/schemas/minified'
                  include:
                    $ref: '#/components/schemas/libraryInclude'
        '404':
          $ref: '#/components/responses/library404'
  /api/libraries/{id}/series/{seriesId}:
    parameters:
      - name: id
        in: path
        description: The ID of the library.
        required: true
        schema:
          $ref: '#/components/schemas/libraryId'
      - name: seriesId
        in: path
        description: The ID of the series.
        required: true
        schema:
          $ref: '#/components/schemas/seriesId'
    get:
      operationId: getLibrarySeriesById
      summary: Get single series in library
      description: Get a single series in a library by ID on server. This endpoint is deprecated and `/api/series/{id}` should be used instead.
      deprecated: true
      tags:
        - Libraries
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/page'
        - in: query
          name: sort
          description: The field to sort by from the request.
          example: numBooks
          schema:
            type: string
            enum:
              - name
              - numBooks
              - totalDuration
              - addedAt
              - lastBookAdded
              - lastBookUpdated
            default: name
        - $ref: '#/components/parameters/desc'
        - in: query
          name: filter
          description: The filter for the library.
          example: media.metadata.title
          schema:
            type: string
        - $ref: '#/components/parameters/minified'
        - in: query
          name: include
          description: The fields to include in the response. The only current option is `rssfeed`.
          allowReserved: true
          example: rssfeed
          schema:
            type: string
      responses:
        '200':
          description: getLibrarySeriesById OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/seriesWithProgressAndRSS'
        '404':
          $ref: '#/components/responses/library404'
  /api/notifications:
    get:
      operationId: getNotifications
      summary: Get notification settings
      description: Get all Apprise notification events and notification settings for server.
      tags:
        - Notification
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      events:
                        type: array
                        items:
                          $ref: '#/components/schemas/NotificationEvent'
                  settings:
                    $ref: '#/components/schemas/NotificationSettings'
        '404':
          $ref: '#/components/responses/notification404'
    patch:
      operationId: configureNotificationSettings
      summary: Update select notification settings
      description: Update the URL, max failed attempts, and maximum notifications that can be queued for Apprise.
      tags:
        - Notification
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                appriseApiUrl:
                  $ref: '#/components/schemas/appriseApiUrl'
                maxFailedAttempts:
                  $ref: '#/components/schemas/maxFailedAttempts'
                maxNotificationQueue:
                  $ref: '#/components/schemas/maxNotificationQueue'
      responses:
        '200':
          $ref: '#/components/responses/notification200'
        '404':
          $ref: '#/components/responses/notification404'
    post:
      operationId: createNotification
      summary: Create notification settings
      description: Create or update Notification settings.
      tags:
        - Notification
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                libraryId:
                  $ref: '#/components/schemas/libraryIdNullable'
                eventName:
                  $ref: '#/components/schemas/notificationEventName'
                urls:
                  $ref: '#/components/schemas/urls'
                titleTemplate:
                  $ref: '#/components/schemas/titleTemplate'
                bodyTemplate:
                  $ref: '#/components/schemas/bodyTemplate'
                enabled:
                  $ref: '#/components/schemas/enabled'
                type:
                  $ref: '#/components/schemas/notificationType'
              required:
                - eventName
                - urls
                - titleTemplate
                - bodyTemplate
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  settings:
                    $ref: '#/components/schemas/NotificationSettings'
        '404':
          $ref: '#/components/responses/notification404'
  /api/notificationdata:
    get:
      operationId: getNotificationEventData
      summary: Get notification event data
      description: Get all Apprise notification event data for the server.
      tags:
        - Notification
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  events:
                    type: array
                    items:
                      $ref: '#/components/schemas/NotificationEvent'
        '404':
          $ref: '#/components/responses/notification404'
  /api/notifications/test:
    get:
      operationId: sendDefaultTestNotification
      summary: Send general test notification
      description: Send a test notification.
      tags:
        - Notification
      parameters:
        - in: query
          name: fail
          description: Whether to intentionally cause the notification to fail. `0` for false, `1` for true.
          schema:
            type: integer
      responses:
        '200':
          $ref: '#/components/responses/notification200'
        '404':
          $ref: '#/components/responses/notification404'
  /api/notifications/{id}:
    parameters:
      - name: id
        in: path
        description: The ID of the notification.
        required: true
        schema:
          $ref: '#/components/schemas/notificationId'
    delete:
      operationId: deleteNotification
      summary: Delete a notification
      description: Delete the notification by ID and return the notification settings.
      tags:
        - Notification
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  settings:
                    $ref: '#/components/schemas/NotificationSettings'
        '404':
          $ref: '#/components/responses/notification404'
    patch:
      operationId: updateNotification
      summary: Update a notification
      description: Update an individual Notification by ID
      tags:
        - Notification
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                libraryId:
                  $ref: '#/components/schemas/libraryId'
                eventName:
                  $ref: '#/components/schemas/notificationEventName'
                urls:
                  $ref: '#/components/schemas/urls'
                titleTemplate:
                  $ref: '#/components/schemas/titleTemplate'
                bodyTemplate:
                  $ref: '#/components/schemas/bodyTemplate'
                enabled:
                  $ref: '#/components/schemas/enabled'
                type:
                  $ref: '#/components/schemas/notificationType'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  settings:
                    $ref: '#/components/schemas/NotificationSettings'
        '404':
          $ref: '#/components/responses/notification404'
  /api/notifications/{id}/test:
    parameters:
      - name: id
        in: path
        description: The ID of the notification.
        required: true
        schema:
          $ref: '#/components/schemas/notificationId'
    get:
      operationId: sendTestNotification
      summary: Send a test notification
      description: Send a test to the given notification by ID.
      tags:
        - Notification
      responses:
        '200':
          $ref: '#/components/responses/notification200'
        '404':
          $ref: '#/components/responses/notification404'
  /api/podcasts:
    post:
      summary: Create a new podcast
      operationId: createPodcast
      tags:
        - Podcasts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Podcast'
      responses:
        '200':
          description: Successfully created a podcast
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Podcast'
        '400':
          description: Bad request
        '403':
          description: Forbidden
        '404':
          description: Not found
  /api/podcasts/feed:
    post:
      summary: Get podcast feed
      operationId: getPodcastFeed
      tags:
        - Podcasts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                rssFeed:
                  type: string
                  description: The RSS feed URL of the podcast
      responses:
        '200':
          description: Successfully retrieved podcast feed
          content:
            application/json:
              schema:
                type: object
                properties:
                  podcast:
                    $ref: '#/components/schemas/Podcast'
        '400':
          description: Bad request
        '403':
          description: Forbidden
        '404':
          description: Not found
  /api/podcasts/opml/parse:
    post:
      summary: Get feeds from OPML text
      description: Parse OPML text and return an array of feeds
      operationId: getFeedsFromOPMLText
      tags:
        - Podcasts
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                opmlText:
                  type: string
      responses:
        '200':
          description: Successfully parsed OPML text and returned feeds
          content:
            application/json:
              schema:
                type: object
                properties:
                  feeds:
                    type: array
                    items:
                      type: object
                      properties:
                        title:
                          type: string
                        feedUrl:
                          type: string
        '400':
          description: Bad request, OPML text not provided
        '403':
          description: Forbidden, user is not admin
  /api/podcasts/opml/create:
    post:
      summary: Bulk create podcasts from OPML feed URLs
      operationId: bulkCreatePodcastsFromOpmlFeedUrls
      tags:
        - Podcasts
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                feeds:
                  type: array
                  items:
                    type: string
                libraryId:
                  $ref: '#/components/schemas/libraryId'
                folderId:
                  $ref: '#/components/schemas/folderId'
                autoDownloadEpisodes:
                  $ref: '#/components/schemas/autoDownloadEpisodes'
      responses:
        '200':
          description: Successfully created podcasts from feed URLs
        '400':
          description: Bad request, invalid request body
        '403':
          description: Forbidden, user is not admin
        '404':
          description: Folder not found
  /api/podcasts/{id}/checknew:
    parameters:
      - name: id
        in: path
        description: Podcast ID
        required: true
        schema:
          $ref: '#/components/schemas/podcastId'
    get:
      summary: Check and download new episodes
      operationId: checkNewEpisodes
      tags:
        - Podcasts
      parameters:
        - name: limit
          in: query
          description: Maximum number of episodes to download
          required: false
          schema:
            type: integer
      responses:
        '200':
          description: Successfully checked and downloaded new episodes
          content:
            application/json:
              schema:
                type: object
                properties:
                  episodes:
                    type: array
                    items:
                      $ref: '#/components/schemas/PodcastEpisode'
        '403':
          description: Forbidden
        '404':
          description: Not found
        '500':
          description: Server error
  /api/podcasts/{id}/clear-queue:
    parameters:
      - name: id
        in: path
        description: Podcast ID
        required: true
        schema:
          $ref: '#/components/schemas/podcastId'
    get:
      summary: Clear episode download queue
      operationId: clearEpisodeDownloadQueue
      tags:
        - Podcasts
      responses:
        '200':
          description: Successfully cleared download queue
        '403':
          description: Forbidden
  /api/podcasts/{id}/downloads:
    parameters:
      - name: id
        in: path
        description: Podcast ID
        required: true
        schema:
          $ref: '#/components/schemas/podcastId'
    get:
      summary: Get episode downloads
      operationId: getEpisodeDownloads
      tags:
        - Podcasts
      responses:
        '200':
          description: Successfully retrieved episode downloads
          content:
            application/json:
              schema:
                type: object
                properties:
                  downloads:
                    type: array
                    items:
                      $ref: '#/components/schemas/PodcastEpisode'
        '404':
          description: Not found
  /api/podcasts/{id}/search-episode:
    parameters:
      - name: id
        in: path
        description: Podcast ID
        required: true
        schema:
          $ref: '#/components/schemas/podcastId'
    get:
      summary: Find episode by title
      operationId: findEpisode
      tags:
        - Podcasts
      parameters:
        - name: title
          in: query
          description: Title of the episode to search for
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successfully found episodes
          content:
            application/json:
              schema:
                type: object
                properties:
                  episodes:
                    type: array
                    items:
                      $ref: '#/components/schemas/PodcastEpisode'
        '404':
          description: Not found
        '500':
          description: Server error
  /api/podcasts/{id}/download-episodes:
    parameters:
      - name: id
        in: path
        description: Podcast ID
        required: true
        schema:
          $ref: '#/components/schemas/podcastId'
    post:
      summary: Download podcast episodes
      operationId: downloadEpisodes
      tags:
        - Podcasts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
      responses:
        '200':
          description: Successfully started episode download
        '400':
          description: Bad request
        '403':
          description: Forbidden
  /api/podcasts/{id}/match-episodes:
    parameters:
      - name: id
        in: path
        description: Podcast ID
        required: true
        schema:
          $ref: '#/components/schemas/podcastId'
    post:
      summary: Quick match podcast episodes
      operationId: quickMatchEpisodes
      tags:
        - Podcasts
      parameters:
        - name: override
          in: query
          description: Override existing details if set to 1
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successfully matched episodes
          content:
            application/json:
              schema:
                type: object
                properties:
                  numEpisodesUpdated:
                    type: integer
        '403':
          description: Forbidden
  /api/podcasts/{id}/episode/{episodeId}:
    parameters:
      - name: id
        in: path
        description: Podcast ID
        required: true
        schema:
          $ref: '#/components/schemas/podcastId'
      - name: episodeId
        in: path
        description: Episode ID
        required: true
        schema:
          $ref: '#/components/schemas/podcastId'
    patch:
      summary: Update a podcast episode
      operationId: updateEpisode
      tags:
        - Podcasts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Successfully updated episode
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Podcast'
        '404':
          description: Not found
    get:
      summary: Get a specific podcast episode
      operationId: getEpisode
      tags:
        - Podcasts
      responses:
        '200':
          description: Successfully retrieved episode
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PodcastEpisode'
        '404':
          description: Not found
    delete:
      summary: Remove a podcast episode
      operationId: removeEpisode
      tags:
        - Podcasts
      parameters:
        - name: hard
          in: query
          description: Hard delete the episode if set to 1
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successfully removed episode
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Podcast'
        '404':
          description: Not found
        '500':
          description: Server error
  /api/series/{id}:
    parameters:
      - name: id
        in: path
        description: The ID of the series.
        required: true
        schema:
          $ref: '#/components/schemas/seriesId'
    get:
      operationId: getSeries
      tags:
        - Series
      summary: Get series
      description: Get a series by ID.
      requestBody:
        required: false
        description: A comma separated list of what to include with the series.
        content:
          application/json:
            schema:
              type: object
              properties:
                include:
                  type: string
                  description: A comma separated list of what to include with the series.
                  example: progress,rssfeed
                  enum:
                    - progress
                    - rssfeed
                    - progress,rssfeed
                    - rssfeed,progress
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/seriesWithProgressAndRSS'
        '404':
          $ref: '#/components/responses/series404'
    patch:
      operationId: updateSeries
      tags:
        - Series
      summary: Update series
      description: Update a series by ID.
      requestBody:
        required: true
        description: The series to update.
        content:
          application/json:
            schema:
              properties:
                name:
                  $ref: '#/components/schemas/seriesName'
                description:
                  $ref: '#/components/schemas/seriesDescription'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/series'
        '404':
          $ref: '#/components/responses/series404'
  /login:
    post:
      summary: Login to the server
      description: Logs in a client to the server, returning information about the user and server.
      operationId: login
      tags:
        - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  $ref: '#/components/schemas/username'
                password:
                  $ref: '#/components/schemas/password'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    $ref: '#/components/schemas/user'
        '401':
          description: Unauthorized - Invalid username or password.
          content:
            text/html:
              schema:
                type: string
                example: Unauthorized
  /logout:
    post:
      summary: Logout from the server
      description: Logs out a client from the server. If the socketId parameter is provided, the server removes the socket from the client list.
      operationId: logout
      tags:
        - Auth
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                socketId:
                  $ref: '#/components/schemas/socketId'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Success
        '401':
          description: Unauthorized
          content:
            text/html:
              schema:
                type: string
                example: Unauthorized
  /api/items/{id}:
    parameters:
      - name: id
        in: path
        description: The ID of the library item.
        required: true
        schema:
          $ref: '#/components/schemas/libraryItemId'
    get:
      operationId: getLibraryItem
      summary: Get a single library item by ID on server.
      description: Get a single library item by ID on server.
      tags:
        - LibraryItem
      parameters:
        - $ref: '#/components/parameters/include'
        - $ref: '#/components/parameters/expanded'
        - $ref: '#/components/parameters/episode'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                description: TODO
                oneOf:
                  - $ref: '#/components/schemas/libraryItem'
        '404':
          $ref: '#/components/responses/libraryItem404'
  /api/items/{id}/play:
    parameters:
      - name: id
        in: path
        description: The ID of the library item.
        required: true
        schema:
          $ref: '#/components/schemas/libraryItemId'
    post:
      operationId: playLibraryItem
      summary: Play a library item
      description: Play a library item by ID.
      tags:
        - LibraryItem
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                deviceInfo:
                  $ref: '#/components/schemas/deviceInfo'
                forceDirectPlay:
                  $ref: '#/components/schemas/forceDirectPlay'
                forceTranscode:
                  $ref: '#/components/schemas/forceTranscode'
                supportedMimeTypes:
                  $ref: '#/components/schemas/supportedMimeTypes'
                mediaPlayer:
                  $ref: '#/components/schemas/mediaPlayer'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/playbackSessionExpanded'
        '404':
          $ref: '#/components/responses/libraryItem404'
  /api/items/{id}/play/{episodeId}:
    parameters:
      - name: id
        in: path
        description: The ID of the library item.
        required: true
        schema:
          $ref: '#/components/schemas/libraryItemId'
      - name: episodeId
        in: path
        description: The ID of the episode to play.
        required: true
        schema:
          $ref: '#/components/schemas/podcastId'
    post:
      operationId: playLibraryItemPodcastEpisode
      summary: Play a podcast episode
      description: Play a podcast by library item ID and episode ID.
      tags:
        - LibraryItem
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                deviceInfo:
                  $ref: '#/components/schemas/deviceInfo'
                forceDirectPlay:
                  $ref: '#/components/schemas/forceDirectPlay'
                forceTranscode:
                  $ref: '#/components/schemas/forceTranscode'
                supportedMimeTypes:
                  $ref: '#/components/schemas/supportedMimeTypes'
                mediaPlayer:
                  $ref: '#/components/schemas/mediaPlayer'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/playbackSessionExpanded'
        '404':
          $ref: '#/components/responses/libraryItem404'
  /api/me:
    get:
      operationId: getMe
      summary: Get the current user.
      description: Get the current user.
      tags:
        - Me
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/user'
  /api/me/progress/{libraryItemId}:
    parameters:
      - name: libraryItemId
        in: path
        description: The ID of the library item.
        required: true
        schema:
          $ref: '#/components/schemas/libraryItemId'
    get:
      operationId: getProgressLibraryItem
      summary: Get the user's progress for a library item.
      description: Get the user's progress for a library item.
      tags:
        - Me
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/mediaProgress'
        '404':
          $ref: '#/components/responses/me404'
  /api/me/progress/{libraryItemId}/{episodeId}:
    parameters:
      - name: libraryItemId
        in: path
        description: The ID of the library item.
        required: true
        schema:
          $ref: '#/components/schemas/libraryItemId'
      - name: episodeId
        in: path
        description: The ID of the episode to get progress for.
        required: true
        schema:
          $ref: '#/components/schemas/podcastId'
    get:
      operationId: getProgressPodcastEpisode
      summary: Get the user's progress for a podcast episode.
      description: Get the user's progress for a podcast episode.
      tags:
        - Me
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/mediaProgressPodcastEpisode'
        '404':
          $ref: '#/components/responses/me404'
  /api/session/{id}/sync:
    post:
      operationId: syncOpenSession
      summary: Sync an open session.
      description: Sync an open session.
      tags:
        - Session
      parameters:
        - name: id
          in: path
          description: The ID of the session.
          required: true
          schema:
            $ref: '#/components/schemas/playbackSessionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                id:
                  $ref: '#/components/schemas/playbackSessionId'
                currentTime:
                  $ref: '#/components/schemas/durationSec'
                timeListened:
                  $ref: '#/components/schemas/durationSec'
                duration:
                  $ref: '#/components/schemas/durationSec'
      responses:
        '200':
          description: OK
          content:
            html/text:
              schema:
                type: string
                example: OK
        '404':
          description: No listening session with the provided ID is open, or the session belongs to another user.
          content:
            html/text:
              schema:
                type: string
                example: Not Found
        '500':
          description: There was an error syncing the session.
          content:
            html/text:
              schema:
                type: string
                example: Internal Server Error
  /api/sessions/{id}:
    delete:
      operationId: deleteSession
      summary: Delets a listening session.
      description: Deletes a listening session.
      tags:
        - Session
      parameters:
        - name: id
          in: path
          description: The ID of the session.
          required: true
          schema:
            $ref: '#/components/schemas/playbackSessionId'
      responses:
        '200':
          description: OK
          content:
            html/text:
              schema:
                type: string
                example: OK
        '403':
          description: A user with delete permissions is required to delete sessions.
          content:
            html/text:
              schema:
                type: string
                example: Forbidden
        '404':
          description: No listening session with the provided ID was found.
          content:
            html/text:
              schema:
                type: string
                example: Not Found
  /api/session/{id}/close:
    post:
      operationId: closeSession
      summary: Close a listening session.
      description: Close a listening session.
      tags:
        - Session
      parameters:
        - name: id
          in: path
          description: The ID of the session.
          required: true
          schema:
            $ref: '#/components/schemas/playbackSessionId'
        - name: currentTime
          in: query
          description: The current time of the session.
          required: false
          schema:
            $ref: '#/components/schemas/durationSec'
        - name: timeListened
          in: query
          description: The time listened to the session.
          required: false
          schema:
            $ref: '#/components/schemas/durationSec'
        - name: duration
          in: query
          description: The duration of the session.
          required: false
          schema:
            $ref: '#/components/schemas/durationSec'
      responses:
        '200':
          description: OK
          content:
            html/text:
              schema:
                type: string
                example: OK
        '404':
          description: No listening session with the provided ID is open, or the session belongs to another user.
          content:
            html/text:
              schema:
                type: string
                example: Not Found
  /api/session/{id}:
    get:
      operationId: getSession
      summary: Get a listening session.
      description: Get a listening session.
      tags:
        - Session
      parameters:
        - name: id
          in: path
          description: The ID of the session.
          required: true
          schema:
            $ref: '#/components/schemas/playbackSessionId'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/playbackSessionExpanded'
        '404':
          description: No listening session with the provided ID was found.
          content:
            html/text:
              schema:
                type: string
                example: Not Found
  /api/sessions:
    get:
      operationId: getSessions
      summary: Get all listening sessions.
      description: Get all listening sessions.
      tags:
        - Session
      parameters:
        - name: user
          in: query
          description: The ID of the user to filter listening sessions by.
          required: false
          schema:
            $ref: '#/components/schemas/userId'
        - name: itemsPerPage
          in: query
          description: The number of items to return.
          required: false
          schema:
            $ref: '#/components/schemas/limit'
        - name: page
          in: query
          description: The page number (zero indexed) to return.
          required: false
          schema:
            $ref: '#/components/schemas/page'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/libraryItemBase'
                  total:
                    $ref: '#/components/schemas/total'
                  itemsPerPage:
                    $ref: '#/components/schemas/limit'
                  numPages:
                    description: The number of pages.
                    type: integer
                    example: 10
                  userFilter:
                    description: If provided, the `user` parameter.
                  sessions:
                    type: array
                    items:
                      $ref: '#/components/schemas/playbackSession'
        '404':
          description: No listening sessions were found.
          content:
            html/text:
              schema:
                type: string
                example: Not Found
  /api/me/listening-sessions:
    get:
      operationId: getListeningSessions
      summary: Get all listening sessions for the current user.
      description: Get all listening sessions for the current user.
      tags:
        - Me
      parameters:
        - name: itemsPerPage
          in: query
          description: The number of items per page.
          required: true
          schema:
            $ref: '#/components/schemas/limit'
        - name: page
          in: query
          description: The page number (zero indexed) to return.
          required: true
          schema:
            $ref: '#/components/schemas/page'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    $ref: '#/components/schemas/total'
                  numPages:
                    description: The number of pages.
                    type: integer
                  itemsPerPage:
                    $ref: '#/components/schemas/limit'
                  sessions:
                    type: array
                    items:
                      $ref: '#/components/schemas/playbackSession'
  /api/me/listening-stats:
    get:
      operationId: getListeningStats
      summary: Get listening stats for the current user.
      description: Get listening stats for the current user.
      tags:
        - Me
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  totalTime:
                    $ref: '#/components/schemas/totalTime'
                  items:
                    type: object
                    description: A list of library items the user has listened to, keyed by their item IDs.
                    additionalProperties:
                      type: object
                      properties:
                        id:
                          type: string
                          description: The ID of the library item.
                        timeListening:
                          type: number
                          description: The time (in seconds) the user listened to this library item.
                        mediaMetadata:
                          oneOf:
                            - $ref: '#/components/schemas/bookMetadata'
                  days:
                    type: object
                    description: A mapping of days to total listening times.
                    additionalProperties:
                      type: number
                      description: The total time (in seconds) listened to on that day.
                  dayOfWeek:
                    type: object
                    description: A mapping of days of the week to total listening times.
                    additionalProperties:
                      type: number
                      description: The total time (in seconds) listened to on that day of the week.
                  today:
                    type: number
                    description: The time (in seconds) the user has listened to library items today.
                  recentSessions:
                    type: array
                    items:
                      $ref: '#/components/schemas/playbackSession'
  /api/session/local:
    post:
      operationId: createLocalSession
      summary: Create a local session.
      description: Create a local session.
      tags:
        - Session
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/playbackSession'
      responses:
        '200':
          description: OK
          content:
            html/text:
              schema:
                type: string
                example: OK
        '500':
          description: There was an error creating the session.
          content:
            html/text:
              schema:
                type: string
                example: Internal Server Error
  /api/local/session/local-all:
    post:
      operationId: createLocalSessionAll
      summary: Create a local session for all users.
      description: Create a local session for all users.
      tags:
        - Session
      requestBody:
        required: true
        content:
          application/json:
            schema:
              items:
                $ref: '#/components/schemas/playbackSession'
      responses:
        '200':
          description: OK
          content:
            html/text:
              schema:
                type: string
                example: OK
        '500':
          description: There was an error creating the session.
          content:
            html/text:
              schema:
                type: string
                example: Internal Server Error
components:
  securitySchemes:
    BearerAuth:
      description: Bearer authentication
      type: http
      scheme: bearer
  schemas:
    authorId:
      type: string
      description: The ID of the author.
      format: uuid
      example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b
    authorAsin:
      description: The Audible identifier (ASIN) of the author. Will be null if unknown. Not the Amazon identifier.
      type: string
      nullable: true
      example: B000APZOQA
    authorName:
      description: The name of the author.
      type: string
      example: Terry Goodkind
    authorDescription:
      description: The new description of the author.
      type: string
      nullable: true
      example: Terry Goodkind is a
    authorImagePath:
      description: The absolute path for the author image. This will be in the `metadata/` directory. Will be null if there is no image.
      type: string
      nullable: true
      example: /metadata/authors/aut_z3leimgybl7uf3y4ab.jpg
    addedAt:
      type: integer
      description: The time (in ms since POSIX epoch) when added to the server.
      example: 1633522963509
    updatedAt:
      type: integer
      description: The time (in ms since POSIX epoch) when last updated.
      example: 1633522963509
    libraryItemId:
      type: string
      description: The ID of library items after 2.3.0.
      format: uuid
      example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b
    oldLibraryItemId:
      description: The ID of library items on server version 2.2.23 and before.
      type: string
      nullable: true
      format: li_[a-z0-9]{18}
      example: li_o78uaoeuh78h6aoeif
    inode:
      description: The inode of the item in the file system.
      type: string
      format: '[0-9]*'
      example: '649644248522215260'
    libraryId:
      type: string
      description: The ID of the library.
      format: uuid
      example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b
    folderId:
      type: string
      description: The ID of the folder.
      format: uuid
      example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b
    mediaType:
      type: string
      description: The type of media, will be book or podcast.
      enum:
        - book
        - podcast
    bookCoverPath:
      description: The absolute path on the server of the cover file. Will be null if there is no cover.
      type: string
      nullable: true
      example: /audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/cover.jpg
    tags:
      description: Tags applied to items.
      type: array
      items:
        type: string
      example:
        - To Be Read
        - 'Genre: Nonfiction'
    size:
      description: The total size (in bytes) of the item or file.
      type: integer
      example: 268824228
    fileMetadata:
      type: object
      description: The metadata for a file, including the path, size, and unix timestamps of the file.
      nullable: true
      properties:
        filename:
          description: The filename of the file.
          type: string
          example: Wizards First Rule 01.mp3
        ext:
          description: The file extension of the file.
          type: string
          example: .mp3
        path:
          description: The absolute path on the server of the file.
          type: string
          example: /audiobooks/Terry Goodkind/Sword of Truth/Wizards First Rule/Terry Goodkind - SOT Bk01 - Wizards First Rule 01.mp3
        relPath:
          description: The path of the file, relative to the book's or podcast's folder.
          type: string
          example: Wizards First Rule 01.mp3
        size:
          $ref: '#/components/schemas/size'
        mtimeMs:
          description: The time (in ms since POSIX epoch) when the file was last modified on disk.
          type: integer
          example: 1632223180278
        ctimeMs:
          description: The time (in ms since POSIX epoch) when the file status was changed on disk.
          type: integer
          example: 1645978261001
        birthtimeMs:
          description: The time (in ms since POSIX epoch) when the file was created on disk. Will be 0 if unknown.
          type: integer
          example: 0
    durationSec:
      description: The total length (in seconds) of the item or file.
      type: number
      example: 33854.905
    bookChapter:
      type: object
      description: A book chapter. Includes the title and timestamps.
      nullable: true
      properties:
        id:
          description: The ID of the book chapter.
          type: integer
          example: 0
        start:
          description: When in the book (in seconds) the chapter starts.
          type: number
          example: 0
        end:
          description: When in the book (in seconds) the chapter ends.
          type: number
          example: 6004.6675
        title:
          description: The title of the chapter.
          type: string
          example: Wizards First Rule 01 Chapter 1
    audioMetaTags:
      description: ID3 metadata tags pulled from the audio file on import. Only non-null tags will be returned in requests.
      type: object
      properties:
        tagAlbum:
          type: string
          nullable: true
          example: SOT Bk01
        tagArtist:
          type: string
          nullable: true
          example: Terry Goodkind
        tagGenre:
          type: string
          nullable: true
          example: Audiobook Fantasy
        tagTitle:
          type: string
          nullable: true
          example: Wizards First Rule 01
        tagSeries:
          type: string
          nullable: true
        tagSeriesPart:
          type: string
          nullable: true
        tagTrack:
          type: string
          nullable: true
          example: 01/20
        tagDisc:
          type: string
          nullable: true
        tagSubtitle:
          type: string
          nullable: true
        tagAlbumArtist:
          type: string
          nullable: true
          example: Terry Goodkind
        tagDate:
          type: string
          nullable: true
        tagComposer:
          type: string
          nullable: true
          example: Terry Goodkind
        tagPublisher:
          type: string
          nullable: true
        tagComment:
          type: string
          nullable: true
        tagDescription:
          type: string
          nullable: true
        tagEncoder:
          type: string
          nullable: true
        tagEncodedBy:
          type: string
          nullable: true
        tagIsbn:
          type: string
          nullable: true
        tagLanguage:
          type: string
          nullable: true
        tagASIN:
          type: string
          nullable: true
        tagOverdriveMediaMarker:
          type: string
          nullable: true
        tagOriginalYear:
          type: string
          nullable: true
        tagReleaseCountry:
          type: string
          nullable: true
        tagReleaseType:
          type: string
          nullable: true
        tagReleaseStatus:
          type: string
          nullable: true
        tagISRC:
          type: string
          nullable: true
        tagMusicBrainzTrackId:
          type: string
          nullable: true
        tagMusicBrainzAlbumId:
          type: string
          nullable: true
        tagMusicBrainzAlbumArtistId:
          type: string
          nullable: true
        tagMusicBrainzArtistId:
          type: string
          nullable: true
    audioFile:
      type: object
      description: An audio file for a book. Includes audio metadata and track numbers.
      properties:
        index:
          description: The index of the audio file.
          type: integer
          example: 1
        ino:
          $ref: '#/components/schemas/inode'
        metadata:
          $ref: '#/components/schemas/fileMetadata'
        addedAt:
          $ref: '#/components/schemas/addedAt'
        updatedAt:
          $ref: '#/components/schemas/updatedAt'
        trackNumFromMeta:
          description: The track number of the audio file as pulled from the file's metadata. Will be null if unknown.
          type: integer
          nullable: true
          example: 1
        discNumFromMeta:
          description: The disc number of the audio file as pulled from the file's metadata. Will be null if unknown.
          type: string
          nullable: true
        trackNumFromFilename:
          description: The track number of the audio file as determined from the file's name. Will be null if unknown.
          type: integer
          nullable: true
          example: 1
        discNumFromFilename:
          description: The disc number of the audio file as determined from the file's name. Will be null if unknown.
          type: string
          nullable: true
        manuallyVerified:
          description: Whether the audio file has been manually verified by a user.
          type: boolean
        invalid:
          description: Whether the audio file is missing from the server.
          type: boolean
        exclude:
          description: Whether the audio file has been marked for exclusion.
          type: boolean
        error:
          description: Any error with the audio file. Will be null if there is none.
          type: string
          nullable: true
        format:
          description: The format of the audio file.
          type: string
          example: MP2/3 (MPEG audio layer 2/3)
        duration:
          $ref: '#/components/schemas/durationSec'
        bitRate:
          description: The bit rate (in bit/s) of the audio file.
          type: integer
          example: 64000
        language:
          description: The language of the audio file.
          type: string
          nullable: true
        codec:
          description: The codec of the audio file.
          type: string
          example: mp3
        timeBase:
          description: The time base of the audio file.
          type: string
          example: 1/14112000
        channels:
          description: The number of channels the audio file has.
          type: integer
          example: 2
        channelLayout:
          description: The layout of the audio file's channels.
          type: string
          example: stereo
        chapters:
          description: If the audio file is part of an audiobook, the chapters the file contains.
          type: array
          items:
            $ref: '#/components/schemas/bookChapter'
        embeddedCoverArt:
          description: The type of embedded cover art in the audio file. Will be null if none exists.
          type: string
          nullable: true
        metaTags:
          $ref: '#/components/schemas/audioMetaTags'
        mimeType:
          description: The MIME type of the audio file.
          type: string
          example: audio/mpeg
    ebookFile:
      type: object
      properties:
        ino:
          $ref: '#/components/schemas/inode'
        metadata:
          $ref: '#/components/schemas/fileMetadata'
        ebookFormat:
          description: The ebook format of the ebook file.
          type: string
          example: epub
        addedAt:
          $ref: '#/components/schemas/addedAt'
        updatedAt:
          $ref: '#/components/schemas/updatedAt'
    bookBase:
      type: object
      description: Base book schema
      properties:
        id:
          description: TODO
          type: string
          format: uuid
          example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b
        libraryItemId:
          $ref: '#/components/schemas/libraryItemId'
        coverPath:
          $ref: '#/components/schemas/bookCoverPath'
        tags:
          $ref: '#/components/schemas/tags'
        audioFiles:
          type: array
          items:
            $ref: '#/components/schemas/audioFile'
        chapters:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/bookChapter'
        missingParts:
          description: Any parts missing from the book by track index.
          type: array
          items:
            type: integer
        ebookFile:
          $ref: '#/components/schemas/ebookFile'
    bookMetadataBase:
      type: object
      description: The base book metadata object for minified, normal, and extended schemas to inherit from.
      properties:
        title:
          description: The title of the book. Will be null if unknown.
          type: string
          nullable: true
          example: Wizards First Rule
        subtitle:
          description: The subtitle of the book. Will be null if there is no subtitle.
          type: string
          nullable: true
        genres:
          description: The genres of the book.
          type: array
          items:
            type: string
          example:
            - Fantasy
            - Sci-Fi
            - 'Nonfiction: History'
        publishedYear:
          description: The year the book was published. Will be null if unknown.
          type: string
          nullable: true
          example: '2008'
        publishedDate:
          description: The date the book was published. Will be null if unknown.
          type: string
          nullable: true
        publisher:
          description: The publisher of the book. Will be null if unknown.
          type: string
          nullable: true
          example: Brilliance Audio
        description:
          description: A description for the book. Will be null if empty.
          type: string
          nullable: true
          example: The masterpiece that started Terry Goodkind's New York Times bestselling epic Sword of Truth In the aftermath of the brutal murder of his father, a mysterious woman, Kahlan Amnell, appears in Richard Cypher's forest sanctuary seeking help...and more. His world, his very beliefs, are shattered when ancient debts come due with thundering violence. In a dark age it takes courage to live, and more than mere courage to challenge those who hold dominion, Richard and Kahlan must take up that challenge or become the next victims. Beyond awaits a bewitching land where even the best of their hearts could betray them. Yet, Richard fears nothing so much as what secrets his sword might reveal about his own soul. Falling in love would destroy them - for reasons Richard can't imagine and Kahlan dare not say. In their darkest hour, hunted relentlessly, tormented by treachery and loss, Kahlan calls upon Richard to reach beyond his sword - to invoke within himself something more noble. Neither knows that the rules of battle have just changed...or that their time has run out. Wizard's First Rule is the beginning. One book. One Rule. Witness the birth of a legend.
        isbn:
          description: The ISBN of the book. Will be null if unknown.
          type: string
          nullable: true
        asin:
          description: The ASIN of the book. Will be null if unknown.
          type: string
          nullable: true
          example: B002V0QK4C
        language:
          description: The language of the book. Will be null if unknown.
          type: string
          nullable: true
        explicit:
          description: Whether the book has been marked as explicit.
          type: boolean
          example: false
        abridged:
          description: Whether the book is abridged.
          type: boolean
          example: false
    authorMinified:
      type: object
      description: Minified author object which only contains the author name and ID.
      properties:
        id:
          $ref: '#/components/schemas/authorId'
        name:
          $ref: '#/components/schemas/authorName'
    seriesId:
      type: string
      description: The ID of the series.
      format: uuid
      example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b
    seriesName:
      description: The name of the series.
      type: string
      example: Sword of Truth
    sequence:
      description: The position in the series the book is.
      type: string
      nullable: true
    seriesSequence:
      type: object
      description: A series object which includes the name and sequence of the series.
      properties:
        id:
          $ref: '#/components/schemas/seriesId'
        name:
          $ref: '#/components/schemas/seriesName'
        sequence:
          $ref: '#/components/schemas/sequence'
    bookMetadata:
      allOf:
        - $ref: '#/components/schemas/bookMetadataBase'
        - type: object
          properties:
            authors:
              type: array
              items:
                $ref: '#/components/schemas/authorMinified'
            narrators:
              type: array
              items:
                type: string
                example: Sam Tsoutsouvas
            series:
              type: array
              items:
                $ref: '#/components/schemas/seriesSequence'
    book:
      allOf:
        - $ref: '#/components/schemas/bookBase'
        - type: object
          properties:
            metadata:
              $ref: '#/components/schemas/bookMetadata'
    libraryItemBase:
      type: object
      description: Base library item schema
      properties:
        id:
          $ref: '#/components/schemas/libraryItemId'
        oldLibraryItemId:
          $ref: '#/components/schemas/oldLibraryItemId'
        ino:
          $ref: '#/components/schemas/inode'
        libraryId:
          $ref: '#/components/schemas/libraryId'
        folderId:
          $ref: '#/components/schemas/folderId'
        path:
          description: The path of the library item on the server.
          type: string
        relPath:
          description: The path, relative to the library folder, of the library item.
          type: string
        isFile:
          description: Whether the library item is a single file in the root of the library folder.
          type: boolean
        mtimeMs:
          description: The time (in ms since POSIX epoch) when the library item was last modified on disk.
          type: integer
        ctimeMs:
          description: The time (in ms since POSIX epoch) when the library item status was changed on disk.
          type: integer
        birthtimeMs:
          description: The time (in ms since POSIX epoch) when the library item was created on disk. Will be 0 if unknown.
          type: integer
        addedAt:
          $ref: '#/components/schemas/addedAt'
        updatedAt:
          $ref: '#/components/schemas/updatedAt'
        isMissing:
          description: Whether the library item was scanned and no longer exists.
          type: boolean
        isInvalid:
          description: Whether the library item was scanned and no longer has media files.
          type: boolean
        mediaType:
          $ref: '#/components/schemas/mediaType'
        media:
          $ref: '#/components/schemas/book'
    bookMetadataMinified:
      type: object
      description: The minified metadata for a book in the database.
      allOf:
        - $ref: '#/components/schemas/bookMetadataBase'
        - type: object
          properties:
            titleIgnorePrefix:
              description: The title of the book with any prefix moved to the end.
              type: string
            authorName:
              description: The name of the book's author(s).
              type: string
              example: Terry Goodkind
            authorNameLF:
              description: The name of the book's author(s) with last names first.
              type: string
              example: Goodkind, Terry
            narratorName:
              description: The name of the audiobook's narrator(s).
              type: string
              example: Sam Tsoutsouvas
            seriesName:
              description: The name of the book's series.
              type: string
              example: Sword of Truth
    bookMinified:
      type: object
      description: Minified book schema. Does not depend on `bookBase` because there's pretty much no overlap.
      properties:
        metadata:
          $ref: '#/components/schemas/bookMetadataMinified'
        coverPath:
          $ref: '#/components/schemas/bookCoverPath'
        tags:
          $ref: '#/components/schemas/tags'
        numTracks:
          description: The number of tracks the book's audio files have.
          type: integer
          example: 1
        numAudioFiles:
          description: The number of audio files the book has.
          type: integer
          example: 1
        numChapters:
          description: The number of chapters the book has.
          type: integer
          example: 1
        numMissingParts:
          description: The total number of missing parts the book has.
          type: integer
          example: 0
        numInvalidAudioFiles:
          description: The number of invalid audio files the book has.
          type: integer
          example: 0
        duration:
          $ref: '#/components/schemas/durationSec'
        size:
          $ref: '#/components/schemas/size'
        ebookFormat:
          description: The format of ebook of the book. Will be null if the book is an audiobook.
          type: string
          nullable: true
    mediaMinified:
      description: The minified media of the library item.
      oneOf:
        - $ref: '#/components/schemas/bookMinified'
    libraryItemMinified:
      type: object
      description: A single item on the server, like a book or podcast. Minified media format.
      allOf:
        - $ref: '#/components/schemas/libraryItemBase'
        - type: object
          properties:
            media:
              $ref: '#/components/schemas/mediaMinified'
    authorSeries:
      type: object
      description: Series and the included library items that an author has written.
      properties:
        id:
          $ref: '#/components/schemas/seriesId'
        name:
          $ref: '#/components/schemas/seriesName'
        items:
          description: The items in the series. Each library item's media's metadata will have a `series` attribute, a `Series Sequence`, which is the matching series.
          type: array
          items:
            $ref: '#/components/schemas/libraryItemMinified'
    author:
      description: An author object which includes a description and image path. The library items and series associated with the author are optionally included.
      type: object
      properties:
        id:
          $ref: '#/components/schemas/authorId'
        asin:
          $ref: '#/components/schemas/authorAsin'
        name:
          $ref: '#/components/schemas/authorName'
        description:
          $ref: '#/components/schemas/authorDescription'
        imagePath:
          $ref: '#/components/schemas/authorImagePath'
        addedAt:
          $ref: '#/components/schemas/addedAt'
        updatedAt:
          $ref: '#/components/schemas/updatedAt'
        libraryItems:
          description: The items associated with the author
          type: array
          items:
            $ref: '#/components/schemas/libraryItemMinified'
        series:
          description: The series associated with the author
          type: array
          items:
            $ref: '#/components/schemas/authorSeries'
    authorUpdated:
      description: Whether the author was updated without errors. Will not exist if author was merged.
      type: boolean
      nullable: true
    authorMerged:
      description: Whether the author was merged with another author. Will not exist if author was updated.
      type: boolean
      nullable: true
    imageWidth:
      description: The requested width of image in pixels.
      type: integer
      default: 400
      example: 400
    imageHeight:
      description: The requested height of image in pixels. If `null`, the height is scaled to maintain aspect ratio based on the requested width.
      type: integer
      nullable: true
      default: null
      example: 600
    imageFormat:
      description: The requested output format.
      type: string
      default: jpeg
      example: webp
    imageRaw:
      description: Return the raw image without scaling if true.
      type: boolean
      default: false
    imageUrl:
      description: The URL of the image to add to the server
      type: string
      format: uri
      example: https://images-na.ssl-images-amazon.com/images/I/51NoQTm33OL.__01_SX120_CR0,0,120,120__.jpg
    authorSearchName:
      description: The name of the author to use for searching.
      type: string
      example: Terry Goodkind
    region:
      description: The region used to search.
      type: string
      example: us
      default: us
    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 users allowed to access the device.
          items:
            type: string
      required:
        - name
        - email
        - availabilityOption
    EmailSettings:
      type: object
      description: The email settings configuration for the server. This includes the credentials to send e-books and an array of e-reader devices.
      properties:
        id:
          type: string
          description: The unique identifier for the email settings. Currently this is always `email-settings`
          example: email-settings
        host:
          type: string
          description: The SMTP host address.
          nullable: true
        port:
          type: integer
          format: int32
          description: The port number for the SMTP server.
          example: 465
        secure:
          type: boolean
          description: Indicates if the connection should use SSL/TLS.
          example: true
        rejectUnauthorized:
          type: boolean
          description: Indicates if unauthorized SSL/TLS certificates should be rejected.
          example: true
        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.
          nullable: true
        ereaderDevices:
          type: array
          description: List of configured e-reader devices.
          items:
            $ref: '#/components/schemas/EreaderDeviceObject'
      required:
        - id
        - port
        - secure
        - ereaderDevices
    libraryName:
      description: The name of the library.
      type: string
      example: My Audiobooks
    folder:
      type: object
      description: Folder used in library
      properties:
        id:
          $ref: '#/components/schemas/folderId'
        fullPath:
          description: The path on the server for the folder. (Read Only)
          type: string
          example: /podcasts
        libraryId:
          $ref: '#/components/schemas/libraryId'
        addedAt:
          $ref: '#/components/schemas/addedAt'
    librarySettings:
      description: The settings for the library.
      type: object
      properties:
        coverAspectRatio:
          description: Whether the library should use square book covers. Must be 0 (for false) or 1 (for true).
          type: integer
          example: 1
        disableWatcher:
          description: Whether to disable the folder watcher for the library.
          type: boolean
          example: false
        skipMatchingMediaWithAsin:
          description: Whether to skip matching books that already have an ASIN.
          type: boolean
          example: false
        skipMatchingMediaWithIsbn:
          description: Whether to skip matching books that already have an ISBN.
          type: boolean
          example: false
        autoScanCronExpression:
          description: The cron expression for when to automatically scan the library folders. If null, automatic scanning will be disabled.
          type: string
          nullable: true
          example: 0 0 0 * * *
        audiobooksOnly:
          description: Whether the library should ignore ebook files and only allow ebook files to be supplementary.
          type: boolean
          example: false
        hideSingleBookSeries:
          description: Whether to hide series with only one book.
          type: boolean
          example: false
        onlyShowLaterBooksInContinueSeries:
          description: Whether to only show books in a series after the highest series sequence.
          type: boolean
          example: false
        metadataPrecedence:
          description: The precedence of metadata sources. See Metadata Providers for a list of possible providers.
          type: array
          items:
            type: string
          example:
            - folderStructure
            - audioMetatags
            - nfoFile
            - txtFiles
            - opfFile
            - absMetadata
        podcastSearchRegion:
          description: The region to use when searching for podcasts.
          type: string
          example: us
    createdAt:
      type: integer
      description: The time (in ms since POSIX epoch) when was created.
      example: 1633522963509
    library:
      description: A library object which includes either books or podcasts.
      type: object
      properties:
        id:
          $ref: '#/components/schemas/libraryId'
        name:
          $ref: '#/components/schemas/libraryName'
        folders:
          description: The folders that belong to the library.
          type: array
          items:
            $ref: '#/components/schemas/folder'
        displayOrder:
          description: Display position of the library in the list of libraries. Must be >= 1.
          type: integer
          example: 1
        icon:
          description: The selected icon for the library. See Library Icons for a list of possible icons.
          type: string
          example: audiobookshelf
        mediaType:
          description: The type of media that the library contains. Will be `book` or `podcast`. (Read Only)
          type: string
          example: book
        provider:
          description: Preferred metadata provider for the library. See Metadata Providers for a list of possible providers.
          type: string
          example: audible
        settings:
          $ref: '#/components/schemas/librarySettings'
        createdAt:
          $ref: '#/components/schemas/createdAt'
        lastUpdate:
          $ref: '#/components/schemas/updatedAt'
    libraryFolders:
      description: The folders of the library. Only specify the fullPath.
      type: array
      items:
        $ref: '#/components/schemas/folder'
    libraryDisplayOrder:
      description: The display order of the library. Must be >= 1.
      type: integer
      minimum: 1
      example: 1
    libraryIcon:
      description: The icon of the library. See Library Icons for a list of possible icons.
      type: string
      example: audiobookshelf
    libraryMediaType:
      description: The type of media that the library contains. Must be `book` or `podcast`.
      type: string
      example: book
    libraryProvider:
      description: Preferred metadata provider for the library. See Metadata Providers for a list of possible providers.
      type: string
      example: audible
    authorExpanded:
      type: object
      description: The author schema with the total number of books in the library.
      allOf:
        - $ref: '#/components/schemas/author'
        - type: object
          properties:
            numBooks:
              description: The number of books associated with the author in the library.
              type: integer
              example: 1
    total:
      description: The total number of items in the response.
      type: integer
      example: 100
    limit:
      description: The number of items to return. If 0, no items are returned.
      type: integer
      example: 10
      default: 0
    page:
      description: The page number (zero indexed) to return. If no limit is specified, then page will have no effect.
      type: integer
      example: 1
      default: 0
    sortBy:
      type: string
      description: The field to sort by from the request.
      example: media.metadata.title
    sortDesc:
      description: Whether to sort in descending order.
      type: boolean
      example: true
    filterBy:
      type: string
      description: The field to filter by from the request. TODO
      example: media.metadata.title
    minified:
      description: Return minified items if true.
      type: boolean
      example: true
      default: false
    collapseSeries:
      type: boolean
      description: Whether collapse series was set in the request.
      example: true
    libraryInclude:
      description: The fields to include in the response. The only current option is `rssfeed`.
      type: string
      example: rssfeed
    libraryItemSequence:
      type: object
      description: A single item on the server, like a book or podcast. Includes series sequence information.
      allOf:
        - $ref: '#/components/schemas/libraryItemBase'
        - type: object
          properties:
            sequence:
              $ref: '#/components/schemas/sequence'
    seriesBooks:
      type: object
      description: A series object which includes the name and books in the series.
      properties:
        id:
          $ref: '#/components/schemas/seriesId'
        name:
          $ref: '#/components/schemas/seriesName'
        addedAt:
          $ref: '#/components/schemas/addedAt'
        nameIgnorePrefix:
          description: The name of the series with any prefix moved to the end.
          type: string
        nameIgnorePrefixSort:
          description: The name of the series with any prefix removed.
          type: string
        type:
          description: Will always be `series`.
          type: string
        books:
          description: The library items that contain the books in the series. A sequence attribute that denotes the position in the series the book is in, is tacked on.
          type: array
          items:
            $ref: '#/components/schemas/libraryItemSequence'
        totalDuration:
          description: The combined duration (in seconds) of all books in the series.
          type: number
    seriesDescription:
      description: A description for the series. Will be null if there is none.
      type: string
      nullable: true
      example: The Sword of Truth is a series of twenty one epic fantasy novels written by Terry Goodkind.
    series:
      type: object
      description: A series object which includes the name and description of the series.
      properties:
        id:
          $ref: '#/components/schemas/seriesId'
        name:
          $ref: '#/components/schemas/seriesName'
        description:
          $ref: '#/components/schemas/seriesDescription'
        addedAt:
          $ref: '#/components/schemas/addedAt'
        updatedAt:
          $ref: '#/components/schemas/updatedAt'
    seriesProgress:
      type: object
      description: The user's progress of a series.
      properties:
        libraryItemIds:
          description: The IDs of the library items in the series.
          type: array
          items:
            $ref: '#/components/schemas/libraryItemId'
        libraryItemIdsFinished:
          description: The IDs of the library items in the series that are finished.
          type: array
          items:
            $ref: '#/components/schemas/libraryItemId'
        isFinished:
          description: Whether the series is finished.
          type: boolean
    seriesWithProgressAndRSS:
      type: object
      description: A series object which includes the name and progress of the series.
      oneOf:
        - $ref: '#/components/schemas/series'
        - type: object
          properties:
            progress:
              $ref: '#/components/schemas/seriesProgress'
            rssFeed:
              description: The RSS feed for the series.
              type: string
              example: TBD
    NotificationEvent:
      type: object
      properties:
        name:
          type: string
          description: The name of the notification event. The names and allowable values are defined at https://github.com/advplyr/audiobookshelf/blob/master/server/utils/notifications.js
        requiresLibrary:
          type: boolean
          description: Whether the notification event depends on a library existing.
        libraryMediaType:
          type: string
          description: The type of media of the library the notification depends on existing. Will not exist if requiresLibrary is false.
          nullable: true
        description:
          type: string
          description: The description of the notification event.
        variables:
          type: array
          items:
            type: string
          description: The variables of the notification event that can be used in the notification templates.
        defaults:
          type: object
          properties:
            title:
              type: string
              description: The default title template for notifications using the notification event.
            body:
              type: string
              description: The default body template for notifications using the notification event.
        testData:
          type: object
          description: The keys of the testData object will match the list of variables. The values will be the data used when sending a test notification.
          additionalProperties:
            type: string
    notificationId:
      type: string
      description: The ID of the notification.
      example: notification-settings
    appriseApiUrl:
      type: string
      nullable: true
      description: The full URL where the Apprise API to use is located.
    libraryIdNullable:
      type: string
      description: The ID of the library. Applies to all libraries if `null`.
      format: uuid
      nullable: true
      example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b
    notificationEventName:
      type: string
      description: The name of the event the notification will fire on.
      enum:
        - onPodcastEpisodeDownloaded
        - onTest
    urls:
      type: array
      items:
        type: string
      description: The Apprise URLs to use for the notification.
      example: http://192.168.0.3:8000/notify/my-cool-notification
    titleTemplate:
      type: string
      description: The template for the notification title.
      example: New {{podcastTitle}} Episode!
    bodyTemplate:
      type: string
      description: The template for the notification body.
      example: '{{episodeTitle}} has been added to {{libraryName}} library.'
    enabled:
      type: boolean
      default: false
      description: Whether the notification is enabled.
    notificationType:
      type: string
      enum:
        - info
        - success
        - warning
        - failure
      nullable: true
      default: info
      description: The notification's type.
    Notification:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/notificationId'
        libraryId:
          $ref: '#/components/schemas/libraryIdNullable'
        eventName:
          $ref: '#/components/schemas/notificationEventName'
        urls:
          $ref: '#/components/schemas/urls'
        titleTemplate:
          $ref: '#/components/schemas/titleTemplate'
        bodyTemplate:
          $ref: '#/components/schemas/bodyTemplate'
        enabled:
          $ref: '#/components/schemas/enabled'
        type:
          $ref: '#/components/schemas/notificationType'
        lastFiredAt:
          type: integer
          nullable: true
          description: The time (in ms since POSIX epoch) when the notification was last fired. Will be null if the notification has not fired.
        lastAttemptFailed:
          type: boolean
          description: Whether the last notification attempt failed.
        numConsecutiveFailedAttempts:
          type: integer
          description: The number of consecutive times the notification has failed.
          default: 0
        numTimesFired:
          type: integer
          description: The number of times the notification has fired.
          default: 0
        createdAt:
          $ref: '#/components/schemas/createdAt'
    maxFailedAttempts:
      type: integer
      minimum: 0
      default: 5
      description: The maximum number of times a notification fails before being disabled.
    maxNotificationQueue:
      type: integer
      description: The maximum number of notifications in the notification queue before events are ignored.
    NotificationSettings:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/notificationId'
        appriseType:
          type: string
          description: The type of Apprise that will be used. At the moment, only api is available.
        appriseApiUrl:
          $ref: '#/components/schemas/appriseApiUrl'
        notifications:
          type: array
          items:
            $ref: '#/components/schemas/Notification'
          description: The set notifications.
        maxFailedAttempts:
          $ref: '#/components/schemas/maxFailedAttempts'
        maxNotificationQueue:
          $ref: '#/components/schemas/maxNotificationQueue'
        notificationDelay:
          type: integer
          description: The time (in ms) between notification pushes.
    podcastId:
      type: string
      description: The ID of podcasts and podcast episodes after 2.3.0.
      format: uuid
      example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b
    PodcastMetadata:
      type: object
      description: Metadata for a podcast.
      properties:
        title:
          type: string
          description: The title of the podcast.
          nullable: true
        author:
          type: string
          description: The author of the podcast.
          nullable: true
        description:
          type: string
          description: The description of the podcast.
          nullable: true
        releaseDate:
          type: string
          format: date-time
          description: The release date of the podcast.
          nullable: true
        genres:
          type: array
          description: The genres of the podcast.
          items:
            type: string
        feedUrl:
          type: string
          description: The URL of the podcast feed.
          nullable: true
        imageUrl:
          type: string
          description: The URL of the podcast's image.
          nullable: true
        itunesPageUrl:
          type: string
          description: The URL of the podcast's iTunes page.
          nullable: true
        itunesId:
          type: string
          description: The iTunes ID of the podcast.
          nullable: true
        itunesArtistId:
          type: string
          description: The iTunes artist ID of the podcast.
          nullable: true
        explicit:
          type: boolean
          description: Whether the podcast contains explicit content.
        language:
          type: string
          description: The language of the podcast.
          nullable: true
        type:
          type: string
          description: The type of podcast (e.g., episodic, serial).
          nullable: true
    oldPodcastId:
      description: The ID of podcasts on server version 2.2.23 and before.
      type: string
      nullable: true
      format: pod_[a-z0-9]{18}
      example: pod_o78uaoeuh78h6aoeif
    AudioTrack:
      type: object
      description: Represents an audio track with various properties.
      properties:
        index:
          type: integer
          nullable: true
          description: The index of the audio track.
          example: null
        startOffset:
          type: number
          format: float
          nullable: true
          description: The start offset of the audio track in seconds.
          example: null
        duration:
          type: number
          format: float
          nullable: true
          description: The duration of the audio track in seconds.
          example: null
        title:
          type: string
          nullable: true
          description: The title of the audio track.
          example: null
        contentUrl:
          type: string
          nullable: true
          description: The URL where the audio track content is located.
          example: '`/api/items/${itemId}/file/${audioFile.ino}`'
        mimeType:
          type: string
          nullable: true
          description: The MIME type of the audio track.
          example: null
        codec:
          type: string
          nullable: true
          description: The codec used for the audio track.
          example: aac
        metadata:
          $ref: '#/components/schemas/fileMetadata'
    PodcastEpisode:
      type: object
      description: A single episode of a podcast.
      properties:
        libraryItemId:
          $ref: '#/components/schemas/libraryItemId'
        podcastId:
          $ref: '#/components/schemas/podcastId'
        id:
          $ref: '#/components/schemas/podcastId'
        oldEpisodeId:
          $ref: '#/components/schemas/oldPodcastId'
        index:
          type: integer
          description: The index of the episode within the podcast.
          nullable: true
        season:
          type: string
          description: The season number of the episode.
          nullable: true
        episode:
          type: string
          description: The episode number within the season.
          nullable: true
        episodeType:
          type: string
          description: The type of episode (e.g., full, trailer).
          nullable: true
        title:
          type: string
          description: The title of the episode.
          nullable: true
        subtitle:
          type: string
          description: The subtitle of the episode.
          nullable: true
        description:
          type: string
          description: The description of the episode.
          nullable: true
        enclosure:
          type: object
          description: The enclosure object containing additional episode data.
          nullable: true
          additionalProperties: true
        guid:
          type: string
          description: The globally unique identifier for the episode.
          nullable: true
        pubDate:
          type: string
          description: The publication date of the episode.
          nullable: true
        chapters:
          type: array
          description: The chapters within the episode.
          items:
            type: object
        audioFile:
          $ref: '#/components/schemas/audioFile'
        publishedAt:
          $ref: '#/components/schemas/createdAt'
        addedAt:
          $ref: '#/components/schemas/addedAt'
        updatedAt:
          $ref: '#/components/schemas/updatedAt'
        audioTrack:
          $ref: '#/components/schemas/AudioTrack'
        duration:
          $ref: '#/components/schemas/durationSec'
        size:
          $ref: '#/components/schemas/size'
    autoDownloadEpisodes:
      type: boolean
      description: Whether episodes are automatically downloaded.
    Podcast:
      type: object
      description: A podcast containing multiple episodes.
      properties:
        id:
          $ref: '#/components/schemas/podcastId'
        libraryItemId:
          $ref: '#/components/schemas/libraryItemId'
        metadata:
          $ref: '#/components/schemas/PodcastMetadata'
        coverPath:
          type: string
          description: The file path to the podcast's cover image.
          nullable: true
        tags:
          type: array
          description: The tags associated with the podcast.
          items:
            type: string
        episodes:
          type: array
          description: The episodes of the podcast.
          items:
            $ref: '#/components/schemas/PodcastEpisode'
        autoDownloadEpisodes:
          $ref: '#/components/schemas/autoDownloadEpisodes'
        autoDownloadSchedule:
          type: string
          description: The schedule for automatic episode downloads, in cron format.
          nullable: true
        lastEpisodeCheck:
          type: integer
          description: The timestamp of the last episode check.
        maxEpisodesToKeep:
          type: integer
          description: The maximum number of episodes to keep.
        maxNewEpisodesToDownload:
          type: integer
          description: The maximum number of new episodes to download when automatically downloading epsiodes.
        lastCoverSearch:
          type: integer
          description: The timestamp of the last cover search.
          nullable: true
        lastCoverSearchQuery:
          type: string
          description: The query used for the last cover search.
          nullable: true
        size:
          type: integer
          description: The total size of all episodes in bytes.
        duration:
          type: integer
          description: The total duration of all episodes in seconds.
        numTracks:
          type: integer
          description: The number of tracks (episodes) in the podcast.
        latestEpisodePublished:
          type: integer
          description: The timestamp of the most recently published episode.
    username:
      type: string
      description: The username to log in with.
      example: testuser
    password:
      type: string
      description: The password of the user.
      example: password
    userId:
      type: string
      description: The ID of the user.
      example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b
      format: uuid
    userType:
      type: string
      description: The type of the user.
      example: root
    token:
      type: string
      description: The token of the user.
      example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6InRlc3R1c2VyIiwiaWF0IjoxNTE2MjM5MDIyfQ.4k1jJ9
    mediaProgressId:
      type: string
      description: The ID of the media progress.
      example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b
      format: uuid
    progress:
      type: number
      description: The user's progress in the media item.
      example: 0.5
    currentTime:
      type: number
      description: The user's current time in the media item.
      example: 0.5
    isFinished:
      type: boolean
      description: Whether the user has finished the media item.
      example: false
    hideFromContinueListening:
      type: boolean
      description: Whether the media item should be hidden from the continue listening section.
      example: false
    finishedAt:
      type: integer
      nullable: true
      description: The time (in ms since POSIX epoch) when the media was finished. Will be null if the media has is not finished.
      example: 1616239000
    mediaProgress:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/mediaProgressId'
        libraryItemId:
          $ref: '#/components/schemas/libraryItemId'
        duration:
          $ref: '#/components/schemas/durationSec'
        progress:
          $ref: '#/components/schemas/progress'
        currentTime:
          $ref: '#/components/schemas/currentTime'
        isFinished:
          $ref: '#/components/schemas/isFinished'
        hideFromContinueListening:
          $ref: '#/components/schemas/hideFromContinueListening'
        lastUpdate:
          $ref: '#/components/schemas/updatedAt'
        startedAt:
          $ref: '#/components/schemas/createdAt'
        finishedAt:
          $ref: '#/components/schemas/finishedAt'
    time:
      type: integer
      description: The time (in ms since POSIX epoch) when the bookmark was created.
      example: 1616239000
    bookmark:
      properties:
        libraryItemId:
          $ref: '#/components/schemas/libraryItemId'
        title:
          type: string
          description: The title of the bookmark.
          example: Chapter 1
        time:
          $ref: '#/components/schemas/time'
        createdAt:
          $ref: '#/components/schemas/createdAt'
    lastSeen:
      type: integer
      description: The time (in ms since POSIX epoch) when the user was last seen.
      example: 1616239000
    isActive:
      type: boolean
      description: Whether the user is active.
      example: true
    isLocked:
      type: boolean
      description: Whether the user is locked.
      example: false
    download:
      type: boolean
      description: Whether the user has permission to download media.
      example: true
    update:
      type: boolean
      description: Whether the user has permission to update media.
      example: true
    delete:
      type: boolean
      description: Whether the user has permission to delete media.
      example: true
    upload:
      type: boolean
      description: Whether the user has permission to upload media.
      example: true
    accessAllLibraries:
      type: boolean
      description: Whether the user has permission to access all libraries.
      example: true
    accessAllTags:
      type: boolean
      description: Whether the user has permission to access all tags.
      example: true
    accessExplicitContent:
      type: boolean
      description: Whether the user has permission to access explicit content.
      example: true
    permissions:
      type: object
      properties:
        download:
          $ref: '#/components/schemas/download'
        update:
          $ref: '#/components/schemas/update'
        delete:
          $ref: '#/components/schemas/delete'
        upload:
          $ref: '#/components/schemas/upload'
        accessAllLibraries:
          $ref: '#/components/schemas/accessAllLibraries'
        accessAllTags:
          $ref: '#/components/schemas/accessAllTags'
        accessExplicitContent:
          $ref: '#/components/schemas/accessExplicitContent'
      required:
        - download
        - update
        - delete
        - upload
        - accessAllLibraries
        - accessAllTags
        - accessExplicitContent
    user:
      type: object
      description: A user object which includes the user's ID, username, type, token, and media progress.
      properties:
        id:
          $ref: '#/components/schemas/userId'
        username:
          $ref: '#/components/schemas/username'
        type:
          $ref: '#/components/schemas/userType'
        token:
          $ref: '#/components/schemas/token'
        mediaProgress:
          description: The user's progress of media.
          type: array
          items:
            $ref: '#/components/schemas/mediaProgress'
        seriesHideFromContinueListening:
          description: The IDs of series to hide from the user's "Continue Series" shelf.
          type: array
          items:
            $ref: '#/components/schemas/libraryItemId'
        bookmarks:
          description: The user's bookmarks.
          type: array
          items:
            $ref: '#/components/schemas/bookmark'
        lastSeen:
          $ref: '#/components/schemas/lastSeen'
        isActive:
          $ref: '#/components/schemas/isActive'
        isLocked:
          $ref: '#/components/schemas/isLocked'
        createdAt:
          $ref: '#/components/schemas/createdAt'
        permissions:
          $ref: '#/components/schemas/permissions'
        librariesAccessible:
          description: The IDs of libraries the user has access to.
          type: array
          items:
            $ref: '#/components/schemas/libraryId'
        itemTagsSelected:
          $ref: '#/components/schemas/tags'
    socketId:
      type: string
      description: The socket ID of the user.
      example: AFcTcb7xBLsSPnIzAAAV
    libraryFile:
      type: object
      description: A library file. Includes the path and metadata of the file.
      properties:
        ino:
          $ref: '#/components/schemas/inode'
        addedAt:
          $ref: '#/components/schemas/addedAt'
        updatedAt:
          $ref: '#/components/schemas/updatedAt'
        fileType:
          description: The type of file.
          type: string
          example: audio
        metadata:
          $ref: '#/components/schemas/fileMetadata'
    libraryItem:
      type: object
      description: A single item on the server, like a book or podcast.
      allOf:
        - $ref: '#/components/schemas/libraryItemBase'
        - type: object
          properties:
            libraryFiles:
              type: array
              items:
                $ref: '#/components/schemas/libraryFile'
    deviceId:
      description: The client device identifier.
      type: string
      example: 1
    clientVersion:
      description: The client version.
      type: string
      example: 1.0.0
    clientName:
      description: The client name.
      type: string
      example: Audible
    manufacturer:
      description: The manufacturer of the device.
      type: string
      example: Apple
    model:
      description: The model of the device.
      type: string
      example: iPhone 12
    sdkVersion:
      description: For an Android client, the Android SDK version of the client.
      type: string
      example: 49
    deviceInfo:
      description: The device information to send to the server.
      type: object
      properties:
        deviceId:
          $ref: '#/components/schemas/deviceId'
        clientVersion:
          $ref: '#/components/schemas/clientVersion'
        clientName:
          $ref: '#/components/schemas/clientName'
        manufacturer:
          $ref: '#/components/schemas/manufacturer'
        model:
          $ref: '#/components/schemas/model'
        sdkVersion:
          $ref: '#/components/schemas/sdkVersion'
    forceDirectPlay:
      description: Whether to force direct play of the library item.
      type: boolean
      example: false
    forceTranscode:
      description: Whether to force transcoding of the library item.
      type: boolean
      example: false
    supportedMimeTypes:
      description: The supported mime types for the device.
      type: array
      items:
        type: string
    mediaPlayer:
      description: The media player to use.
      type: string
    playbackSessionId:
      description: The playback session identifier.
      type: string
      format: uuid
    serverVersion:
      type: string
      description: The server version
    playbackSessionBase:
      type: object
      description: Base playback session object.
      properties:
        id:
          $ref: '#/components/schemas/playbackSessionId'
        userId:
          $ref: '#/components/schemas/userId'
        libraryId:
          $ref: '#/components/schemas/libraryId'
        libraryItemId:
          $ref: '#/components/schemas/libraryItemId'
        mediaType:
          $ref: '#/components/schemas/mediaType'
        displayTitle:
          description: The display title of the media.
          type: string
        displayAuthor:
          description: The display author of the media.
          type: string
        coverPath:
          $ref: '#/components/schemas/bookCoverPath'
        duration:
          $ref: '#/components/schemas/durationSec'
        playMethod:
          type: integer
          description: The method used to play the media. 0 = Direct play, 1 = Direct Stream, 2 = Transcode, 3 = Local
        mediaPlayer:
          type: string
          description: The media player used to play the media.
        deviceInfo:
          $ref: '#/components/schemas/deviceInfo'
        serverVersion:
          $ref: '#/components/schemas/serverVersion'
        date:
          description: TODO
          type: string
        dayOfWeek:
          description: TODO
          type: string
        timeListening:
          $ref: '#/components/schemas/durationSec'
        startTime:
          $ref: '#/components/schemas/durationSec'
        currentTime:
          $ref: '#/components/schemas/durationSec'
        createdAt:
          $ref: '#/components/schemas/createdAt'
        updatedAt:
          $ref: '#/components/schemas/updatedAt'
    playbackSessionBook:
      description: Book playback session schema.
      allOf:
        - $ref: '#/components/schemas/playbackSessionBase'
        - properties:
            mediaMetadata:
              $ref: '#/components/schemas/bookMetadata'
            chapters:
              description: The chapters of the media.
              type: array
              items:
                $ref: '#/components/schemas/bookChapter'
    playbackSessionBookExpanded:
      description: Expanded book playback session schema.
      allOf:
        - $ref: '#/components/schemas/playbackSessionBook'
        - properties:
            audioTracks:
              description: The audio tracks of the media.
              type: array
              items:
                $ref: '#/components/schemas/AudioTrack'
            videoTrack:
              description: The video track of the media. TODO
              type: object
              nullable: true
            libraryItem:
              $ref: '#/components/schemas/libraryItem'
    playbackSessionPodcast:
      description: Podcast playback session schema.
      allOf:
        - $ref: '#/components/schemas/playbackSessionBase'
        - properties:
            mediaMetadata:
              $ref: '#/components/schemas/PodcastMetadata'
            episodeId:
              $ref: '#/components/schemas/podcastId'
    playbackSessionPodcastExpanded:
      description: Expanded podcast playback session schema.
      allOf:
        - $ref: '#/components/schemas/playbackSessionPodcast'
        - properties:
            audioTracks:
              description: The audio tracks of the media.
              type: array
              items:
                $ref: '#/components/schemas/AudioTrack'
            videoTrack:
              description: The video track of the media. TODO
              type: object
              nullable: true
            libraryItem:
              $ref: '#/components/schemas/libraryItem'
    playbackSessionExpanded:
      type: object
      description: A playback session object.
      oneOf:
        - $ref: '#/components/schemas/playbackSessionBookExpanded'
        - $ref: '#/components/schemas/playbackSessionPodcastExpanded'
      discriminator:
        propertyName: mediaType
        mapping:
          book: '#/components/schemas/playbackSessionBookExpanded'
          podcast: '#/components/schemas/playbackSessionPodcastExpanded'
    mediaProgressPodcastEpisode:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/mediaProgressId'
        libraryItemId:
          $ref: '#/components/schemas/libraryItemId'
        episodeId:
          $ref: '#/components/schemas/podcastId'
        duration:
          $ref: '#/components/schemas/durationSec'
        progress:
          $ref: '#/components/schemas/progress'
        currentTime:
          $ref: '#/components/schemas/currentTime'
        isFinished:
          $ref: '#/components/schemas/isFinished'
        hideFromContinueListening:
          $ref: '#/components/schemas/hideFromContinueListening'
        lastUpdate:
          $ref: '#/components/schemas/updatedAt'
        startedAt:
          $ref: '#/components/schemas/createdAt'
        finishedAt:
          $ref: '#/components/schemas/finishedAt'
    playbackSession:
      type: object
      description: A playback session object.
      oneOf:
        - $ref: '#/components/schemas/playbackSessionBook'
        - $ref: '#/components/schemas/playbackSessionPodcast'
      discriminator:
        propertyName: mediaType
        mapping:
          book: '#/components/schemas/playbackSessionBook'
          podcast: '#/components/schemas/playbackSessionPodcast'
    totalTime:
      description: The total time listened in seconds.
      type: number
      example: 123456
  responses:
    author404:
      description: Author not found.
      content:
        text/html:
          schema:
            type: string
            example: Author not found.
    email200:
      description: Successful response - Email
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/EmailSettings'
    ereader200:
      description: Successful response - Ereader
      content:
        application/json:
          schema:
            type: object
            properties:
              ereaderDevices:
                type: array
                items:
                  $ref: '#/components/schemas/EreaderDeviceObject'
    library200:
      description: Library found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/library'
    library404:
      description: Library not found.
      content:
        text/html:
          schema:
            type: string
            example: Library not found.
    notification404:
      description: An admin user is required or notification with the given ID not found.
      content:
        text/html:
          schema:
            type: string
            example: Series not found.
    notification200:
      description: Notification endpoint success.
      content:
        text/html:
          schema:
            type: string
            example: OK
    series404:
      description: Series not found.
      content:
        text/html:
          schema:
            type: string
            example: Series not found.
    libraryItem404:
      description: Not Found
      content:
        text/html:
          schema:
            type: string
            description: The library item does not exist.
            example: Not Found
    me404:
      description: Not Found
      content:
        html/text:
          schema:
            type: string
            example: Not Found
  parameters:
    minified:
      in: query
      name: minified
      description: Return minified items if true
      schema:
        type: integer
        minimum: 0
        example: 1
    limit:
      in: query
      name: limit
      description: The number of items to return. This the size of a single page for the optional `page` query.
      example: 10
      schema:
        type: integer
        default: 0
    page:
      in: query
      name: page
      description: The page number (zero indexed) to return. If no limit is specified, then page will have no effect.
      example: 0
      schema:
        type: integer
        default: 0
    desc:
      in: query
      name: desc
      description: Return items in reversed order if true.
      example: 0
      schema:
        type: integer
        default: 0
    include:
      in: query
      name: include
      description: A comma separated list of what to include with the library item. The options are progress, rssfeed, authors (for books), and downloads (for podcasts). expanded must be 1 for include to have an effect.
      allowReserved: true
      schema:
        type: string
    expanded:
      in: query
      name: expanded
      description: Whether to return Library Item Expanded instead. 0 for false, 1 for true.
      schema:
        type: integer
        example: 1
    episode:
      in: query
      name: episode
      description: If requesting progress for a podcast, the episode ID to get progress for.
      schema:
        $ref: '#/components/schemas/podcastId'