audiobookshelf/docs/root.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:
  securitySchemes:
    BearerAuth:
      description: Bearer authentication
      type: http
      scheme: bearer
  responses:
    ok200:
      description: OK
security:
  - BearerAuth: []
paths:
  /api/authors/{id}:
    get:
      operationId: getAuthorById
      summary: Get a single author by ID on server
      description: Get a single author by ID on server. The author's books and series can be included in the response.
      tags:
        - Authors
      parameters:
        - $ref: './controllers/AuthorController.yaml#/components/parameters/authorId'
        - $ref: './controllers/AuthorController.yaml#/components/parameters/authorInclude'
        - $ref: './controllers/AuthorController.yaml#/components/parameters/authorLibraryId'
      responses:
        '200':
          description: getAuthorById OK
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: './objects/entities/Author.yaml#/components/schemas/author'
                  - $ref: './objects/entities/Author.yaml#/components/schemas/authorWithItems'
                  - $ref: './objects/entities/Author.yaml#/components/schemas/authorWithSeries'
        '404':
          $ref: './controllers/AuthorController.yaml#/components/responses/author404'
    patch:
      operationId: updateAuthorById
      summary: Update a single author by ID on server.
      description: 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: './controllers/AuthorController.yaml#/components/parameters/authorId'
        - $ref: './controllers/AuthorController.yaml#/components/parameters/asin'
        - $ref: './controllers/AuthorController.yaml#/components/parameters/authorName'
        - $ref: './controllers/AuthorController.yaml#/components/parameters/authorDescription'
        - $ref: './controllers/AuthorController.yaml#/components/parameters/authorImagePath'
      responses:
        '200':
          description: updateAuthorById OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: './objects/entities/Author.yaml#/components/schemas/author'
                  - $ref: './controllers/AuthorController.yaml#/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: './controllers/AuthorController.yaml#/components/responses/author404'
    delete:
      operationId: deleteAuthorById
      summary: Delete a single author by ID.
      description: Delete a single author by ID on server and remove author from all books.
      tags:
        - Authors
      parameters:
        - $ref: './controllers/AuthorController.yaml#/components/parameters/authorId'
      responses:
        '200':
          $ref: '#/components/responses/ok200'
        '404':
          $ref: './controllers/AuthorController.yaml#/components/responses/author404'
  /api/authors/{id}/image:
    post:
      operationId: setAuthorImageById
      summary: Set an author image using a provided URL.
      description: Set an author image using a provided URL. The image will be downloaded and stored on the server.
      tags:
        - Authors
      parameters:
        - $ref: './controllers/AuthorController.yaml#/components/parameters/authorId'
        - $ref: './controllers/AuthorController.yaml#/components/parameters/imageUrl'
      responses:
        '200':
          description: setAuthorImageById OK
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: './objects/entities/Author.yaml#/components/schemas/author'
        '404':
          $ref: './controllers/AuthorController.yaml#/components/responses/author404'
    delete:
      operationId: deleteAuthorImageById
      summary: Delete an author image from the server and remove the image from the database.
      description: Delete an author image from the server.
      tags:
        - Authors
      parameters:
        - $ref: './controllers/AuthorController.yaml#/components/parameters/authorId'
      responses:
        '200':
          $ref: '#/components/responses/ok200'
        '404':
          $ref: './controllers/AuthorController.yaml#/components/responses/author404'
    patch:
      operationId: getAuthorImageById
      summary: Return the author image by author ID.
      description: Return the author image by author ID. The image will be resized if the width, height, or format is provided.
      tags:
        - Authors
      parameters:
        - $ref: './controllers/AuthorController.yaml#/components/parameters/authorId'
        - $ref: './controllers/AuthorController.yaml#/components/parameters/imageWidth'
        - $ref: './controllers/AuthorController.yaml#/components/parameters/imageHeight'
        - $ref: './controllers/AuthorController.yaml#/components/parameters/imageFormat'
        - $ref: './controllers/AuthorController.yaml#/components/parameters/imageRaw'
      responses:
        '200':
          description: getAuthorImageById OK
          content:
            image/*:
              schema:
                type: string
                format: binary
        '404':
          $ref: './controllers/AuthorController.yaml#/components/responses/author404'
  /api/authors/{id}/match:
    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
      parameters:
        - $ref: './controllers/AuthorController.yaml#/components/parameters/authorId'
        - $ref: './controllers/AuthorController.yaml#/components/parameters/asin'
        - $ref: './controllers/AuthorController.yaml#/components/parameters/authorSearchName'
      responses:
        '200':
          description: matchAuthorById OK
          content:
            application/json:
              schema:
                allOf:
                  - $ref: './objects/entities/Author.yaml#/components/schemas/author'
                  - $ref: './controllers/AuthorController.yaml#/components/schemas/authorUpdated'
        '404':
          $ref: './controllers/AuthorController.yaml#/components/responses/author404'
  /api/libraries:
    $ref: './controllers/LibraryController.yaml#/paths/~1api~1libraries'
  /api/libraries/{id}:
    $ref: './controllers/LibraryController.yaml#/paths/~1api~1libraries~1{id}'
tags:
  - name: Authors
    description: Author endpoints
  - name: Libraries
    description: Library endpoints