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:
            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
      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. 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 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.
      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.
      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.
      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. 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'
tags:
  - name: Authors
    description: Author endpoints