audiobookshelf/docs/controllers/LibraryController.yaml

components:
  requestBody:
    libraryName:
      name: name
      in: requestBody
      description: The name of the library.
      content:
        application/json:
          schema:
            type: string
            example: My Audiobooks
    libraryFolders:
      name: folders
      in: requestBody
      summary: The folders of the library.
      description: The folders of the library. Only specify the fullPath.
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '../objects/Folder.yaml#/components/schemas/folder'
    libraryDisplayOrder:
      name: displayOrder
      in: requestBody
      description: The display order of the library. Must be >= 1.
      schema:
        type: integer
        minimum: 1
        example: 1
    libraryIcon:
      name: icon
      in: requestBody
      summary: The icon of library.
      description: The icon of the library. See Library Icons for a list of possible icons.
      schema:
        type: string
        example: 'audiobookshelf'
    libraryMediaType:
      name: mediaType
      in: requestBody
      summary: The type of media the library contains.
      description: The type of media that the library contains. Must be `book` or `podcast`.
      schema:
        type: string
        example: 'book'
    libraryProvider:
      name: provider
      in: requestBody
      summary: Preferred metadata provider for the library.
      description: Preferred metadata provider for the library. See Metadata Providers for a list of possible providers.
      schema:
        type: string
        example: 'audible'
    librarySettings:
      name: settings
      in: requestBody
      summary: The settings for the library.
      description: The settings for the library.
      schema:
        $ref: '../objects/Library.yaml#/components/schemas/librarySettings'
  responses:
    library200:
      description: Library found.
      content:
        application/json:
          schema:
            $ref: '../objects/Library.yaml#/components/schemas/library'
    library404:
      description: Library not found.
      content:
        text/html:
          schema:
            type: string
            example: Library not found.
paths:
  /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: array
                items:
                  $ref: '../objects/Library.yaml#/components/schemas/library'
    post:
      operationId: createLibrary
      summary: Create a new library on server
      description: Create a new library on server.
      required: [name, folders]
      tags:
        - Libraries
      requestBody:
        required: true
        description: The library object to create.
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  $ref: '#/components/requestBody/libraryName'
                folders:
                  $ref: '#/components/requestBody/libraryFolders'
                displayOrder:
                  $ref: '#/components/requestBody/libraryDisplayOrder'
                icon:
                  $ref: '#/components/requestBody/libraryIcon'
                mediaType:
                  $ref: '#/components/requestBody/libraryMediaType'
                provider:
                  $ref: '#/components/requestBody/libraryProvider'
                settings:
                  $ref: '#/components/requestBody/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: '../objects/Library.yaml#/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
      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/requestBody/libraryName'
                folders:
                  $ref: '#/components/requestBody/libraryFolders'
                displayOrder:
                  $ref: '#/components/requestBody/libraryDisplayOrder'
                icon:
                  $ref: '#/components/requestBody/libraryIcon'
                mediaType:
                  $ref: '#/components/requestBody/libraryMediaType'
                provider:
                  $ref: '#/components/requestBody/libraryProvider'
                settings:
                  $ref: '#/components/requestBody/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'