audiobookshelf/docs/openapi.json

{
  "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"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Authors",
      "description": "Author endpoints"
    },
    {
      "name": "Libraries",
      "description": "Library endpoints"
    },
    {
      "name": "Series",
      "description": "Series endpoints"
    }
  ],
  "paths": {
    "/api/authors/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "description": "Author ID",
          "required": true,
          "schema": {
            "$ref": "#/components/schemas/authorId"
          }
        }
      ],
      "get": {
        "operationId": "getAuthorById",
        "summary": "Get an author by ID",
        "description": "Get an author by ID. The author's books and series can be included in the response.",
        "tags": ["Authors"],
        "requestBody": {
          "required": false,
          "description": "The author object to create.",
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "include": {
                    "$ref": "#/components/schemas/authorInclude"
                  },
                  "library": {
                    "$ref": "#/components/schemas/libraryId"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "getAuthorById OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/author"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/author404"
          }
        }
      },
      "patch": {
        "operationId": "updateAuthorById",
        "summary": "Update an author by ID",
        "description": "Update an author by ID. The author's name and description can be updated. This endpoint will merge two authors if the new author name matches another author name in the database.",
        "tags": ["Authors"],
        "requestBody": {
          "description": "The author object to update.",
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "name": {
                    "$ref": "#/components/schemas/authorName"
                  },
                  "description": {
                    "$ref": "#/components/schemas/authorDescription"
                  },
                  "imagePath": {
                    "$ref": "#/components/schemas/authorImagePath"
                  },
                  "asin": {
                    "$ref": "#/components/schemas/authorAsin"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "updateAuthorById OK",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/author"
                    },
                    {
                      "$ref": "#/components/schemas/authorUpdated"
                    },
                    {
                      "$ref": "#/components/schemas/authorMerged"
                    }
                  ]
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/author404"
          }
        }
      },
      "delete": {
        "operationId": "deleteAuthorById",
        "summary": "Delete an author by ID",
        "description": "Delete an author by ID. This will remove the author from all books.",
        "tags": ["Authors"],
        "responses": {
          "200": {
            "description": "deleteAuthorById OK",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string",
                  "example": "Author deleted."
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/author404"
          }
        }
      }
    },
    "/api/authors/{id}/image": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "description": "Author ID",
          "required": true,
          "schema": {
            "$ref": "#/components/schemas/authorId"
          }
        }
      ],
      "get": {
        "operationId": "getAuthorImageById",
        "summary": "Get an author image by author ID",
        "description": "Get an author image by author ID. The image will be returned in the requested format and size.",
        "tags": ["Authors"],
        "requestBody": {
          "required": false,
          "description": "The author image to get.",
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "width": {
                    "$ref": "#/components/schemas/imageWidth"
                  },
                  "height": {
                    "$ref": "#/components/schemas/imageHeight"
                  },
                  "format": {
                    "$ref": "#/components/schemas/imageFormat"
                  },
                  "raw": {
                    "$ref": "#/components/schemas/imageRaw"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "getAuthorImageById OK",
            "content": {
              "image/webp": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/jpeg": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              },
              "image/*": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/author404"
          }
        }
      },
      "post": {
        "operationId": "addAuthorImageById",
        "summary": "Add an author image to the server",
        "description": "Add an author image to the server. The image will be downloaded from the provided URL and stored on the server.",
        "tags": ["Authors"],
        "requestBody": {
          "required": true,
          "description": "The author image to add by URL.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/imageUrl"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "addAuthorImageById OK",
            "content": {
              "image/*": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/author404"
          }
        }
      },
      "patch": {
        "operationId": "updateAuthorImageById",
        "summary": "Update an author image by author ID",
        "description": "Update an author image by author ID. The image will be resized if the width, height, or format is provided.",
        "tags": ["Authors"],
        "requestBody": {
          "description": "The author image to update.",
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "width": {
                    "$ref": "#/components/schemas/imageWidth"
                  },
                  "height": {
                    "$ref": "#/components/schemas/imageHeight"
                  },
                  "format": {
                    "$ref": "#/components/schemas/imageFormat"
                  },
                  "raw": {
                    "$ref": "#/components/schemas/imageRaw"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "updateAuthorImageById OK",
            "content": {
              "image/*": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/author404"
          }
        }
      },
      "delete": {
        "operationId": "deleteAuthorImageById",
        "summary": "Delete an author image by author ID",
        "description": "Delete an author image by author ID. This will remove the image from the server and the database.",
        "tags": ["Authors"],
        "responses": {
          "200": {
            "description": "deleteAuthorImageById OK"
          },
          "404": {
            "$ref": "#/components/responses/author404"
          }
        }
      }
    },
    "/api/authors/{id}/match": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "description": "Author ID",
          "required": true,
          "schema": {
            "$ref": "#/components/schemas/authorId"
          }
        }
      ],
      "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"],
        "requestBody": {
          "required": true,
          "description": "The author object to match against an online provider.",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "q": {
                    "$ref": "#/components/schemas/authorSearchName"
                  },
                  "asin": {
                    "$ref": "#/components/schemas/authorAsin"
                  },
                  "region": {
                    "$ref": "#/components/schemas/region"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "matchAuthorById OK",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/author"
                    },
                    {
                      "$ref": "#/components/schemas/authorUpdated"
                    }
                  ]
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/author404"
          }
        }
      }
    },
    "/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": "#/components/schemas/library"
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createLibrary",
        "summary": "Create a new library on server",
        "description": "Create a new library on server.",
        "tags": ["Libraries"],
        "requestBody": {
          "description": "The library object to create.",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name", "folders"],
                "properties": {
                  "name": {
                    "$ref": "#/components/schemas/libraryName"
                  },
                  "folders": {
                    "$ref": "#/components/schemas/libraryFolders"
                  },
                  "displayOrder": {
                    "$ref": "#/components/schemas/libraryDisplayOrder"
                  },
                  "icon": {
                    "$ref": "#/components/schemas/libraryIcon"
                  },
                  "mediaType": {
                    "$ref": "#/components/schemas/libraryMediaType"
                  },
                  "provider": {
                    "$ref": "#/components/schemas/libraryProvider"
                  },
                  "settings": {
                    "$ref": "#/components/schemas/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": "#/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/schemas/libraryName"
                  },
                  "folders": {
                    "$ref": "#/components/schemas/libraryFolders"
                  },
                  "displayOrder": {
                    "$ref": "#/components/schemas/libraryDisplayOrder"
                  },
                  "icon": {
                    "$ref": "#/components/schemas/libraryIcon"
                  },
                  "mediaType": {
                    "$ref": "#/components/schemas/libraryMediaType"
                  },
                  "provider": {
                    "$ref": "#/components/schemas/libraryProvider"
                  },
                  "settings": {
                    "$ref": "#/components/schemas/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"
          }
        }
      }
    },
    "/api/libraries/{id}/authors": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "description": "The ID of the library.",
          "required": true,
          "schema": {
            "$ref": "#/components/schemas/libraryId"
          }
        }
      ],
      "get": {
        "operationId": "getLibraryAuthors",
        "summary": "Get all authors in a library",
        "description": "Get all authors in a library by ID on server.",
        "tags": ["Libraries"],
        "responses": {
          "200": {
            "description": "getLibraryAuthors OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "authors": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/authorExpanded"
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/library404"
          }
        }
      }
    },
    "/api/libraries/{id}/items": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "description": "The ID of the library.",
          "required": true,
          "schema": {
            "$ref": "#/components/schemas/libraryId"
          }
        }
      ],
      "get": {
        "operationId": "getLibraryItems",
        "summary": "Get items in a library",
        "description": "Get items in a library by ID on server.",
        "tags": ["Libraries"],
        "requestBody": {
          "required": false,
          "description": "The filters to apply to the requested library items.",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "limit": {
                    "$ref": "#/components/schemas/limit"
                  },
                  "page": {
                    "$ref": "#/components/schemas/page"
                  },
                  "sort": {
                    "$ref": "#/components/schemas/librarySort"
                  },
                  "desc": {
                    "$ref": "#/components/schemas/sortDesc"
                  },
                  "filter": {
                    "$ref": "#/components/schemas/libraryFilter"
                  },
                  "minified": {
                    "$ref": "#/components/schemas/minified"
                  },
                  "collapseSeries": {
                    "$ref": "#/components/schemas/libraryCollapseSeries"
                  },
                  "include": {
                    "$ref": "#/components/schemas/libraryInclude"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "getLibraryItems OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/libraryItemBase"
                      }
                    },
                    "total": {
                      "$ref": "#/components/schemas/total"
                    },
                    "limit": {
                      "$ref": "#/components/schemas/limit"
                    },
                    "page": {
                      "$ref": "#/components/schemas/page"
                    },
                    "sortBy": {
                      "$ref": "#/components/schemas/sortBy"
                    },
                    "sortDesc": {
                      "$ref": "#/components/schemas/sortDesc"
                    },
                    "filterBy": {
                      "$ref": "#/components/schemas/filterBy"
                    },
                    "mediaType": {
                      "$ref": "#/components/schemas/mediaType"
                    },
                    "minified": {
                      "$ref": "#/components/schemas/minified"
                    },
                    "collapseSeries": {
                      "$ref": "#/components/schemas/collapseSeries"
                    },
                    "include": {
                      "$ref": "#/components/schemas/libraryInclude"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/library404"
          }
        }
      }
    },
    "/api/libraries/{id}/issues": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "description": "The ID of the library.",
          "required": true,
          "schema": {
            "$ref": "#/components/schemas/libraryId"
          }
        }
      ],
      "delete": {
        "operationId": "deleteLibraryIssues",
        "summary": "Delete items with issues in a library.",
        "description": "Delete all items with issues in a library by library ID on the server. This only removes the items from the ABS database and does not delete media files.",
        "tags": ["Libraries"],
        "responses": {
          "200": {
            "description": "deleteLibraryIssues OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "string",
                  "example": "Issues deleted."
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/library404"
          }
        }
      }
    },
    "/api/libraries/{id}/series": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "description": "The ID of the library.",
          "required": true,
          "schema": {
            "$ref": "#/components/schemas/libraryId"
          }
        }
      ],
      "get": {
        "operationId": "getLibrarySeries",
        "summary": "Get library series",
        "description": "Get series in a library. Filtering and sorting can be applied.",
        "tags": ["Libraries"],
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "description": "The number of series to return. If 0, all series are returned.",
            "example": 10,
            "schema": {
              "type": "integer",
              "default": 0
            }
          },
          {
            "in": "query",
            "name": "page",
            "description": "The page number (zero indexed) to return. If no limit is specified, then page will have no effect.",
            "example": 0,
            "schema": {
              "type": "integer",
              "default": 0
            }
          },
          {
            "in": "query",
            "name": "sort",
            "description": "The field to sort by from the request.",
            "example": "numBooks",
            "schema": {
              "type": "string",
              "enum": ["name", "numBooks", "totalDuration", "addedAt", "lastBookAdded", "lastBookUpdated"],
              "default": "name"
            }
          },
          {
            "in": "query",
            "name": "desc",
            "description": "Return items in reversed order if true.",
            "example": true,
            "schema": {
              "type": "boolean",
              "default": false
            }
          },
          {
            "in": "query",
            "name": "filter",
            "description": "The filter for the library.",
            "example": "media.metadata.title",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "include",
            "description": "The fields to include in the response. The only current option is `rssfeed`.",
            "example": "rssfeed",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "getLibrarySeries OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "results": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/seriesBooks"
                      }
                    },
                    "total": {
                      "$ref": "#/components/schemas/total"
                    },
                    "limit": {
                      "$ref": "#/components/schemas/limit"
                    },
                    "page": {
                      "$ref": "#/components/schemas/page"
                    },
                    "sortBy": {
                      "$ref": "#/components/schemas/sortBy"
                    },
                    "sortDesc": {
                      "$ref": "#/components/schemas/sortDesc"
                    },
                    "filterBy": {
                      "$ref": "#/components/schemas/filterBy"
                    },
                    "minified": {
                      "$ref": "#/components/schemas/minified"
                    },
                    "include": {
                      "$ref": "#/components/schemas/libraryInclude"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/library404"
          }
        }
      }
    },
    "/api/libraries/{id}/series/{seriesId}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "description": "The ID of the library.",
          "required": true,
          "schema": {
            "$ref": "#/components/schemas/libraryId"
          }
        },
        {
          "name": "seriesId",
          "in": "path",
          "description": "The ID of the series.",
          "required": true,
          "schema": {
            "$ref": "#/components/schemas/seriesId"
          }
        }
      ],
      "get": {
        "operationId": "getLibrarySeriesById",
        "summary": "Get single series in library",
        "description": "Get a single series in a library by ID on server. This endpoint is deprecated and `/api/series/{id}` should be used instead.",
        "deprecated": true,
        "tags": ["Libraries"],
        "requestBody": {
          "required": false,
          "description": "The filters to apply to the requested library series.",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "limit": {
                    "$ref": "#/components/schemas/limit"
                  },
                  "page": {
                    "$ref": "#/components/schemas/page"
                  },
                  "sort": {
                    "description": "The field to sort by from the request.",
                    "type": "string",
                    "enum": ["name", "numBooks", "totalDuration", "addedAt", "lastBookAdded", "lastBookUpdated"],
                    "example": "numBooks",
                    "default": "name"
                  },
                  "desc": {
                    "$ref": "#/components/schemas/sortDesc"
                  },
                  "filter": {
                    "$ref": "#/components/schemas/libraryFilter"
                  },
                  "minified": {
                    "$ref": "#/components/schemas/minified"
                  },
                  "include": {
                    "$ref": "#/components/schemas/libraryInclude"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "getLibrarySeriesById OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/seriesWithProgressAndRSS"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/library404"
          }
        }
      }
    },
    "/api/series/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "description": "The ID of the series.",
          "required": true,
          "schema": {
            "$ref": "#/components/schemas/seriesId"
          }
        }
      ],
      "get": {
        "operationId": "getSeries",
        "tags": ["Series"],
        "summary": "Get series",
        "description": "Get a series by ID.",
        "requestBody": {
          "required": false,
          "description": "A comma separated list of what to include with the series.",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "include": {
                    "type": "string",
                    "description": "A comma separated list of what to include with the series.",
                    "example": "progress,rssfeed",
                    "enum": ["progress", "rssfeed", "progress,rssfeed", "rssfeed,progress"]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/seriesWithProgressAndRSS"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/series404"
          }
        }
      },
      "patch": {
        "operationId": "updateSeries",
        "tags": ["Series"],
        "summary": "Update series",
        "description": "Update a series by ID.",
        "requestBody": {
          "required": true,
          "description": "The series to update.",
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "name": {
                    "$ref": "#/components/schemas/seriesName"
                  },
                  "description": {
                    "$ref": "#/components/schemas/seriesDescription"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/series"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/series404"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "description": "Bearer authentication",
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "authorId": {
        "type": "string",
        "description": "The ID of the author.",
        "format": "uuid",
        "example": "e4bb1afb-4a4f-4dd6-8be0-e615d233185b"
      },
      "authorInclude": {
        "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. For example, the value `items,series` will include both library items and series.",
        "type": "string",
        "example": "items"
      },
      "libraryId": {
        "type": "string",
        "description": "The ID of the library.",
        "format": "uuid",
        "example": "e4bb1afb-4a4f-4dd6-8be0-e615d233185b"
      },
      "authorAsin": {
        "description": "The Audible identifier (ASIN) of the author. Will be null if unknown. Not the Amazon identifier.",
        "type": "string",
        "nullable": true,
        "example": "B000APZOQA"
      },
      "authorName": {
        "description": "The name of the author.",
        "type": "string",
        "example": "Terry Goodkind"
      },
      "authorDescription": {
        "description": "The new description of the author.",
        "type": "string",
        "nullable": true,
        "example": "Terry Goodkind is a"
      },
      "authorImagePath": {
        "description": "The absolute path for the author image. This will be in the `metadata/` directory. Will be null if there is no image.",
        "type": "string",
        "nullable": true,
        "example": "/metadata/authors/aut_z3leimgybl7uf3y4ab.jpg"
      },
      "addedAt": {
        "type": "integer",
        "description": "The time (in ms since POSIX epoch) when added to the server.",
        "example": 1633522963509
      },
      "updatedAt": {
        "type": "integer",
        "description": "The time (in ms since POSIX epoch) when last updated.",
        "example": 1633522963509
      },
      "libraryItemId": {
        "type": "string",
        "description": "The ID of library items after 2.3.0.",
        "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"
      },
      "inode": {
        "description": "The inode of the item in the file system.",
        "type": "string",
        "format": "[0-9]*",
        "example": "649644248522215260"
      },
      "folderId": {
        "type": "string",
        "description": "The ID of the folder.",
        "format": "uuid",
        "example": "e4bb1afb-4a4f-4dd6-8be0-e615d233185b"
      },
      "mediaType": {
        "type": "string",
        "description": "The type of media, will be book or podcast.",
        "enum": ["book", "podcast"]
      },
      "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"
          }
        }
      },
      "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"
              }
            }
          }
        ]
      },
      "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"
      },
      "tags": {
        "description": "Tags applied to items.",
        "type": "array",
        "items": {
          "type": "string"
        },
        "example": ["To Be Read", "Genre: Nonfiction"]
      },
      "durationSec": {
        "description": "The total length (in seconds) of the item or file.",
        "type": "number",
        "example": 33854.905
      },
      "size": {
        "description": "The total size (in bytes) of the item or file.",
        "type": "integer",
        "example": 268824228
      },
      "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
          }
        }
      },
      "mediaMinified": {
        "description": "The minified media of the library item.",
        "oneOf": [
          {
            "$ref": "#/components/schemas/bookMinified"
          }
        ]
      },
      "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"
              }
            }
          }
        ]
      },
      "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"
      },
      "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. The library items and series associated with the author are optionally included.",
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/authorId"
          },
          "asin": {
            "$ref": "#/components/schemas/authorAsin"
          },
          "name": {
            "$ref": "#/components/schemas/authorName"
          },
          "description": {
            "$ref": "#/components/schemas/authorDescription"
          },
          "imagePath": {
            "$ref": "#/components/schemas/authorImagePath"
          },
          "addedAt": {
            "$ref": "#/components/schemas/addedAt"
          },
          "updatedAt": {
            "$ref": "#/components/schemas/updatedAt"
          },
          "libraryItems": {
            "description": "The items associated with the author",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/libraryItemMinified"
            }
          },
          "series": {
            "description": "The series associated with the author",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/authorSeries"
            }
          }
        }
      },
      "authorUpdated": {
        "description": "Whether the author was updated without errors. Will not exist if author was merged.",
        "type": "boolean",
        "nullable": true
      },
      "authorMerged": {
        "description": "Whether the author was merged with another author. Will not exist if author was updated.",
        "type": "boolean",
        "nullable": true
      },
      "imageWidth": {
        "description": "The requested width of image in pixels.",
        "type": "integer",
        "default": 400,
        "example": 400
      },
      "imageHeight": {
        "description": "The requested height of image in pixels. If `null`, the height is scaled to maintain aspect ratio based on the requested width.",
        "type": "integer",
        "nullable": true,
        "default": null,
        "example": 600
      },
      "imageFormat": {
        "description": "The requested output format.",
        "type": "string",
        "default": "jpeg",
        "example": "webp"
      },
      "imageRaw": {
        "description": "Return the raw image without scaling if true.",
        "type": "boolean",
        "default": false
      },
      "imageUrl": {
        "description": "The URL of the image to add to the server",
        "type": "string",
        "format": "uri",
        "example": "https://images-na.ssl-images-amazon.com/images/I/51NoQTm33OL.__01_SX120_CR0,0,120,120__.jpg"
      },
      "authorSearchName": {
        "description": "The name of the author to use for searching.",
        "type": "string",
        "example": "Terry Goodkind"
      },
      "region": {
        "description": "The region used to search.",
        "type": "string",
        "example": "us",
        "default": "us"
      },
      "libraryName": {
        "description": "The name of the library.",
        "type": "string",
        "example": "My Audiobooks"
      },
      "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"
          }
        }
      },
      "librarySettings": {
        "description": "The settings for the library.",
        "type": "object",
        "properties": {
          "coverAspectRatio": {
            "description": "Whether the library should use square book covers. Must be 0 (for false) or 1 (for true).",
            "type": "integer",
            "example": 1
          },
          "disableWatcher": {
            "description": "Whether to disable the folder watcher for the library.",
            "type": "boolean",
            "example": false
          },
          "skipMatchingMediaWithAsin": {
            "description": "Whether to skip matching books that already have an ASIN.",
            "type": "boolean",
            "example": false
          },
          "skipMatchingMediaWithIsbn": {
            "description": "Whether to skip matching books that already have an ISBN.",
            "type": "boolean",
            "example": false
          },
          "autoScanCronExpression": {
            "description": "The cron expression for when to automatically scan the library folders. If null, automatic scanning will be disabled.",
            "type": "string",
            "nullable": true,
            "example": "0 0 0 * * *"
          },
          "audiobooksOnly": {
            "description": "Whether the library should ignore ebook files and only allow ebook files to be supplementary.",
            "type": "boolean",
            "example": false
          },
          "hideSingleBookSeries": {
            "description": "Whether to hide series with only one book.",
            "type": "boolean",
            "example": false
          },
          "onlyShowLaterBooksInContinueSeries": {
            "description": "Whether to only show books in a series after the highest series sequence.",
            "type": "boolean",
            "example": false
          },
          "metadataPrecedence": {
            "description": "The precedence of metadata sources. See Metadata Providers for a list of possible providers.",
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": ["folderStructure", "audioMetatags", "nfoFile", "txtFiles", "opfFile", "absMetadata"]
          },
          "podcastSearchRegion": {
            "description": "The region to use when searching for podcasts.",
            "type": "string",
            "example": "us"
          }
        }
      },
      "createdAt": {
        "type": "integer",
        "description": "The time (in ms since POSIX epoch) when was created.",
        "example": 1633522963509
      },
      "library": {
        "description": "A library object which includes either books or podcasts.",
        "type": "object",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/libraryId"
          },
          "name": {
            "$ref": "#/components/schemas/libraryName"
          },
          "folders": {
            "description": "The folders that belong to the library.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/folder"
            }
          },
          "displayOrder": {
            "description": "Display position of the library in the list of libraries. Must be >= 1.",
            "type": "integer",
            "example": 1
          },
          "icon": {
            "description": "The selected icon for the library. See Library Icons for a list of possible icons.",
            "type": "string",
            "example": "audiobookshelf"
          },
          "mediaType": {
            "description": "The type of media that the library contains. Will be `book` or `podcast`. (Read Only)",
            "type": "string",
            "example": "book"
          },
          "provider": {
            "description": "Preferred metadata provider for the library. See Metadata Providers for a list of possible providers.",
            "type": "string",
            "example": "audible"
          },
          "settings": {
            "$ref": "#/components/schemas/librarySettings"
          },
          "createdAt": {
            "$ref": "#/components/schemas/createdAt"
          },
          "lastUpdate": {
            "$ref": "#/components/schemas/updatedAt"
          }
        }
      },
      "libraryFolders": {
        "description": "The folders of the library. Only specify the fullPath.",
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/folder"
        }
      },
      "libraryDisplayOrder": {
        "description": "The display order of the library. Must be >= 1.",
        "type": "integer",
        "minimum": 1,
        "example": 1
      },
      "libraryIcon": {
        "description": "The icon of the library. See Library Icons for a list of possible icons.",
        "type": "string",
        "example": "audiobookshelf"
      },
      "libraryMediaType": {
        "description": "The type of media that the library contains. Must be `book` or `podcast`.",
        "type": "string",
        "example": "book"
      },
      "libraryProvider": {
        "description": "Preferred metadata provider for the library. See Metadata Providers for a list of possible providers.",
        "type": "string",
        "example": "audible"
      },
      "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
              }
            }
          }
        ]
      },
      "limit": {
        "description": "The number of items to return. If 0, no items are returned.",
        "type": "integer",
        "example": 10,
        "default": 0
      },
      "page": {
        "description": "The page number (zero indexed) to return. If no limit is specified, then page will have no effect.",
        "type": "integer",
        "example": 1,
        "default": 0
      },
      "librarySort": {
        "description": "The sort order of the library. For example, to sort by title use 'sort=media.metadata.title'.",
        "type": "string",
        "example": "media.metadata.title"
      },
      "sortDesc": {
        "description": "Return items in reversed order if true.",
        "type": "boolean",
        "example": true,
        "default": false
      },
      "libraryFilter": {
        "description": "The filter for the library.",
        "type": "string",
        "example": "media.metadata.title"
      },
      "minified": {
        "description": "Return minified items if true.",
        "type": "boolean",
        "example": true,
        "default": false
      },
      "libraryCollapseSeries": {
        "description": "Whether to collapse series.",
        "type": "boolean",
        "example": true,
        "default": false
      },
      "libraryInclude": {
        "description": "The fields to include in the response. The only current option is `rssfeed`.",
        "type": "string",
        "example": "rssfeed"
      },
      "total": {
        "description": "The total number of items in the response.",
        "type": "integer",
        "example": 100
      },
      "sortBy": {
        "type": "string",
        "description": "The field to sort by from the request.",
        "example": "media.metadata.title"
      },
      "filterBy": {
        "type": "string",
        "description": "The field to filter by from the request. TODO",
        "example": "media.metadata.title"
      },
      "collapseSeries": {
        "type": "boolean",
        "description": "Whether collapse series was set in the request.",
        "example": true
      },
      "sequence": {
        "description": "The position in the series the book is.",
        "type": "string",
        "nullable": true
      },
      "libraryItemSequence": {
        "type": "object",
        "description": "A single item on the server, like a book or podcast. Includes series sequence information.",
        "allOf": [
          {
            "$ref": "#/components/schemas/libraryItemBase"
          },
          {
            "$ref": "#/components/schemas/sequence"
          }
        ]
      },
      "seriesBooks": {
        "type": "object",
        "description": "A series object which includes the name and books in the series.",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/seriesId"
          },
          "name": {
            "$ref": "#/components/schemas/seriesName"
          },
          "addedAt": {
            "$ref": "#/components/schemas/addedAt"
          },
          "nameIgnorePrefix": {
            "description": "The name of the series with any prefix moved to the end.",
            "type": "string"
          },
          "nameIgnorePrefixSort": {
            "description": "The name of the series with any prefix removed.",
            "type": "string"
          },
          "type": {
            "description": "Will always be `series`.",
            "type": "string"
          },
          "books": {
            "description": "The library items that contain the books in the series. A sequence attribute that denotes the position in the series the book is in, is tacked on.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/libraryItemSequence"
            }
          },
          "totalDuration": {
            "description": "The combined duration (in seconds) of all books in the series.",
            "type": "number"
          }
        }
      },
      "seriesDescription": {
        "description": "A description for the series. Will be null if there is none.",
        "type": "string",
        "nullable": true,
        "example": "The Sword of Truth is a series of twenty one epic fantasy novels written by Terry Goodkind."
      },
      "series": {
        "type": "object",
        "description": "A series object which includes the name and description of the series.",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/seriesId"
          },
          "name": {
            "$ref": "#/components/schemas/seriesName"
          },
          "description": {
            "$ref": "#/components/schemas/seriesDescription"
          },
          "addedAt": {
            "$ref": "#/components/schemas/addedAt"
          },
          "updatedAt": {
            "$ref": "#/components/schemas/updatedAt"
          }
        }
      },
      "seriesProgress": {
        "type": "object",
        "description": "The user's progress of a series.",
        "properties": {
          "libraryItemIds": {
            "description": "The IDs of the library items in the series.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/libraryItemId"
            }
          },
          "libraryItemIdsFinished": {
            "description": "The IDs of the library items in the series that are finished.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/libraryItemId"
            }
          },
          "isFinished": {
            "description": "Whether the series is finished.",
            "type": "boolean"
          }
        }
      },
      "seriesWithProgressAndRSS": {
        "type": "object",
        "description": "A series object which includes the name and progress of the series.",
        "oneOf": [
          {
            "$ref": "#/components/schemas/series"
          },
          {
            "type": "object",
            "properties": {
              "progress": {
                "$ref": "#/components/schemas/seriesProgress"
              },
              "rssFeed": {
                "description": "The RSS feed for the series.",
                "type": "string",
                "example": "TBD"
              }
            }
          }
        ]
      }
    },
    "responses": {
      "author404": {
        "description": "Author not found.",
        "content": {
          "text/html": {
            "schema": {
              "type": "string",
              "example": "Author not found."
            }
          }
        }
      },
      "library200": {
        "description": "Library found.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/library"
            }
          }
        }
      },
      "library404": {
        "description": "Library not found.",
        "content": {
          "text/html": {
            "schema": {
              "type": "string",
              "example": "Library not found."
            }
          }
        }
      },
      "series404": {
        "description": "Series not found.",
        "content": {
          "text/html": {
            "schema": {
              "type": "string",
              "example": "Series not found."
            }
          }
        }
      }
    }
  }
}