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:
  responses: 
    ok200:
      description: OK
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