audiobookshelf/docs/spec.yaml

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

components:
  schemas:
    mediaType:
      type: string
      description: The type of media, will be book or podcast.
      enum: [book, podcast]
    mediaMinified:
      description: The minified media of the library item.
      oneOf:
        - $ref: '#/components/schemas/bookMinified'
    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
    bookBase:
      type: object
      description: Base book schema
      properties:
        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
          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'
    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
    narrators:
      description: The narrators of the audiobook.
      type: array
      items:
        type: string
        example: Sam Tsoutsouvas
    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
    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
    bookChapter:
      type: object
      description: A book chapter. Includes the title and timestamps.
      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: integer
          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
    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
      description: An ebook file for a library item.
      nullable: true
      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'
    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
    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
    addedAt:
      type: integer
      description: The time (in ms since POSIX epoch) when added to the server.
      example: 1633522963509
    createdAt:
      type: integer
      description: The time (in ms since POSIX epoch) when was created.
      example: 1633522963509
    updatedAt:
      type: integer
      description: The time (in ms since POSIX epoch) when last updated.
      example: 1633522963509
    size:
      description: The total size (in bytes) of the item or file.
      type: integer
      example: 268824228
    durationSec:
      description: The total length (in seconds) of the item or file.
      type: number
      example: 33854.905
    tags:
      description: Tags applied to items.
      type: array
      items:
        type: string
      example: ["To Be Read", "Genre: Nonfiction"]
    inode:
      description: The inode of the item in the file system.
      type: string
      format: "[0-9]*"
      example: '649644248522215260'
    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
    folderId:
      type: string
      description: The ID of the folder.
      format: uuid
      example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b
    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'
    authorUpdated:
      description: Whether the author was updated without errors. Will not exist if author was merged.
      type: boolean
      nullable: true
    authorId:
      type: string
      description: The ID of the author.
      format: uuid
      example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b
    authorASIN:
      type: string
      description: The Audible identifier (ASIN) of the author. Will be null if unknown. Not the Amazon identifier.
      nullable: true
      example: B000APZOQA
    authorName:
      description: The name of the author.
      type: string
      example: Terry Goodkind
    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.
      type: object
      properties:
        id:
          $ref: '#/components/schemas/authorId'
        asin:
          $ref: '#/components/schemas/authorASIN'
        name:
          $ref: '#/components/schemas/authorName'
        description:
          description: A description of the author. Will be null if there is none.
          type: string
          nullable: true
          example: |
            Terry Goodkind is a #1 New York Times Bestselling Author and creator of the critically acclaimed masterwork,
            ‘The Sword of Truth’. He has written 30+ major, bestselling novels, has been published in more than 20
            languages world-wide, and has sold more than 26 Million books. ‘The Sword of Truth’ is a revered literary
            tour de force, comprised of 17 volumes, borne from over 25 years of dedicated writing. Terry Goodkind's
            brilliant books are character-driven stories, with a focus on the complexity of the human psyche. Goodkind
            has an uncanny grasp for crafting compelling stories about people like you and me, trapped in terrifying
            situations.            
        imagePath:
          description: The absolute path for the author image located in the `metadata/` directory. Will be null if there is no image.
          type: string
          nullable: true
          example: /metadata/authors/aut_bxxbyjiptmgb56yzoz.jpg
        addedAt:
          $ref: '#/components/schemas/addedAt'
        updatedAt:
          $ref: '#/components/schemas/updatedAt'
    authorWithItems:
      type: object
      description: The author schema with an array of items they are associated with.
      allOf:
        - $ref: '#/components/schemas/author'
        - type: object
          properties:
            libraryItems:
              description: The items associated with the author
              type: array
              items:
                $ref: '#/components/schemas/libraryItemMinified'
    authorWithSeries:
      type: object
      description: The author schema with an array of items and series they are associated with.
      allOf:
        - $ref: '#/components/schemas/authorWithItems'
        - type: object
          properties:
            series:
              description: The series associated with the author
              type: array
              items:
                $ref: '#/components/schemas/authorSeries'
    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'
    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
    oldLibraryId:
      type: string
      description: The ID of the libraries created on server version 2.2.23 and before.
      format: "lib_[a-z0-9]{18}"
      example: lib_o78uaoeuh78h6aoeif
    libraryId:
      type: string
      description: The ID of the library.
      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
    libraryItemId:
      type: string
      description: The ID of library items after 2.3.0.
      format: uuid
      example: e4bb1afb-4a4f-4dd6-8be0-e615d233185b
    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'
    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'
  parameters:
    authorID:
      name: id
      in: path
      description: Author ID
      required: true
      schema:
        $ref: '#/components/schemas/authorId'
    authorInclude:
      name: include
      in: query
      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.
      required: false
      schema:
        type: string
        example: "items"
      examples:
        empty:
          summary: Do not return library items
          value: ""
        itemOnly:
          summary: Only return library items
          value: "items"
        itemsAndSeries:
          summary: Return library items and series
          value: "items,series"
    authorLibraryId:
      name: library
      in: query
      description: The ID of the library to to include filter included items from.
      required: false
      schema:
        $ref: '#/components/schemas/libraryId'
    asin:
      name: asin
      in: query
      description: The Audible Identifier (ASIN).
      required: false
      schema:
        $ref: '#/components/schemas/authorASIN'
    authorSearchName:
      name: q
      in: query
      description: The name of the author to use for searching.
      required: false
      schema:
        type: string
        example: Terry Goodkind
    authorName:
      name: name
      in: query
      description: The new name of the author.
      required: false
      schema:
        $ref: '#/components/schemas/authorName'
    authorDescription:
      name: description
      in: query
      description: The new description of the author.
      required: false
      schema:
        type: string
        nullable: true
        example: Terry Goodkind is a #1 New York Times Bestselling Author and creator of the critically acclaimed masterwork, ‘The Sword of Truth’. He has written 30+ major, bestselling novels, has been published in more than 20 languages world-wide, and has sold more than 26 Million books. ‘The Sword of Truth’ is a revered literary tour de force, comprised of 17 volumes, borne from over 25 years of dedicated writing.
    authorImagePath:
      name: imagePath
      in: query
      description: The new absolute path for the author image.
      required: false
      schema:
        type: string
        nullable: true
        example: /metadata/authors/aut_z3leimgybl7uf3y4ab.jpg
    imageURL:
      name: url
      in: query
      description: The URL of the image to add to the server
      required: true
      schema:
        type: string
        format: uri
        example: https://images-na.ssl-images-amazon.com/images/I/51NoQTm33OL.__01_SX120_CR0,0,120,120__.jpg
    imageWidth:
      name: width
      in: query
      description: The requested width of image in pixels.
      schema:
        type: integer
        default: 400
        example: 400
      example: 400
    imageHeight:
      name: height
      in: query
      description: The requested height of image in pixels. If `null`, the height is scaled to maintain aspect ratio based on the requested width.
      schema:
        type: integer
        nullable: true
        default: null
        example: 600
      examples:
        scaleHeight:
          summary: Scale height with width
          value: null
        fixedHeight:
          summary: Force height of image
          value: 600
    imageFormat:
      name: format
      in: query
      description: The requested output format.
      schema:
        type: string
        default: jpeg
        example: webp
    imageRaw:
      name: raw
      in: query
      description: Return the raw image without scaling if true.
      schema:
        type: boolean
        default: false
  responses: 
    ok200:
      description: OK
    author404:
      description: Author not found.
      content:
        text/html:
          schema:
            type: string
            example: Not found
  paths:
    /api/authors/{id}:
      get:
        operationId: getAuthorByID
        summary: Get a single author by ID on server
        tags:
          - Authors
        parameters:
          - $ref: '#/components/parameters/authorID'
          - $ref: '#/components/parameters/authorInclude'
          - $ref: '#/components/parameters/authorLibraryId'
        responses:
          200:
            description: getAuthorByID OK
            content:
              application/json:
                schema:
                  oneOf:
                    - $ref: '#/components/schemas/author'
                    - $ref: '#/components/schemas/authorWithItems'
                    - $ref: '#/components/schemas/authorWithSeries'
          404:
            $ref: '#/components/responses/author404'
    /api/authors/{id}:
      patch:
        operationId: updateAuthorByID
        summary: Update a single author by ID on server. This endpoint will merge two authors if the new author name matches another author in the database.
        tags:
          - Authors
        parameters:
          - $ref: '#/components/parameters/authorID'
          - $ref: '#/components/parameters/asin'
          - $ref: '#/components/parameters/authorName'
          - $ref: '#/components/parameters/authorDescription'
          - $ref: '#/components/parameters/authorImagePath'
        responses:
          200:
            description: updateAuthorByID OK
            content:
              application/json:
                schema:
                  allOf:
                    - $ref: '#/components/schemas/author'
                    - $ref: '#/components/schemas/authorUpdated'
                    - type: object
                      properties:
                        merged:
                          description: Will only exist and be `true` if the author was merged with another author
                          type: boolean
                          nullable: true
          404:
            $ref: '#/components/responses/author404'
    /api/authors/{id}:
      delete:
        operationId: deleteAuthorByID
        summary: Delete a single author by ID on server and remove author from all books.
        tags:
          - Authors
        parameters:
          - $ref: '#/components/parameters/authorID'
        responses:
          200:
            $ref: '#/components/responses/ok200'
          404:
            $ref: '#/components/responses/author404'
    /api/authors/{id}/image:
      post:
        operationId: setAuthorImageByID
        summary: Set an author image using a provided URL.
        tags:
          - Authors
        parameters:
          - $ref: '#/components/parameters/authorID'
          - $ref: '#/components/parameters/imageURL'
        responses:
          200:
            description: setAuthorImageByID OK
            content:
              application/json:
                schema:
                  oneOf:
                    - $ref: '#/components/schemas/author'
          404:
            $ref: '#/components/responses/author404'
    /api/authors/{id}/image:
      delete:
        operationId: deleteAuthorImageByID
        summary: Delete an author image from the server and remove the image from the database.
        tags:
          - Authors
        parameters:
          - $ref: '#/components/parameters/authorID'
        responses:
          200:
            $ref: '#/components/responses/ok200'
          404:
            $ref: '#/components/responses/author404'
    /api/authors/{id}/match:
      post:
        operationId: matchAuthorByID
        summary: 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
        parameters:
          - $ref: '#/components/parameters/authorID'
          - $ref: '#/components/parameters/asin'
          - $ref: '#/components/parameters/authorSearchName'
        responses:
          200:
            description: matchAuthorByID OK
            content:
              application/json:
                schema:
                  allOf:
                    - $ref: '#/components/schemas/author'
                    - $ref: '#/components/schemas/authorUpdated'
          404:
            $ref: '#/components/responses/author404'
    /api/authors/{id}/image:
      patch:
        operationId: getAuthorImageByID
        summary: Return the author image by author ID.
        tags:
          - Authors
        parameters:
          - $ref: '#/components/parameters/authorID'
          - $ref: '#/components/parameters/imageWidth'
          - $ref: '#/components/parameters/imageHeight'
          - $ref: '#/components/parameters/imageFormat'
          - $ref: '#/components/parameters/imageRaw'
        responses:
          200:
            description: getAuthorImageByID OK
            content:
              image/*:
                schema:
                  type: string
                  format: binary
          404:
            $ref: '#/components/responses/author404'
tags:
  - name: Authors
    description: Author endpoints