{ "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": [ { "name": "id", "in": "path", "description": "Author ID", "required": true, "schema": { "type": "string", "description": "The ID of the author.", "format": "uuid", "example": "e4bb1afb-4a4f-4dd6-8be0-e615d233185b" } }, { "name": "include", "in": "query", "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.", "required": false, "schema": { "type": "string", "example": "items" }, "examples": { "empty": { "summary": "Do not return library items", "value": "" }, "itemOnly": { "summary": "Only return library items", "value": "items" }, "itemsAndSeries": { "summary": "Return library items and series", "value": "items,series" } } }, { "name": "library", "in": "query", "description": "The ID of the library to to include filter included items from.", "required": false, "schema": { "type": "string", "description": "The ID of the library.", "format": "uuid", "example": "e4bb1afb-4a4f-4dd6-8be0-e615d233185b" } } ], "responses": { "200": { "description": "getAuthorById OK", "content": { "application/json": { "schema": { "oneOf": [ { "description": "An author object which includes a description and image path.", "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the author.", "format": "uuid", "example": "e4bb1afb-4a4f-4dd6-8be0-e615d233185b" }, "asin": { "type": "string", "description": "The Audible identifier (ASIN) of the author. Will be null if unknown. Not the Amazon identifier.", "nullable": true, "example": "B000APZOQA" }, "name": { "description": "The name of the author.", "type": "string", "example": "Terry Goodkind" }, "description": { "description": "A description of the author. Will be null if there is none.", "type": "string", "nullable": true, "example": "Terry Goodkind is a #1 New York Times Bestselling Author and creator of the critically acclaimed masterwork,\nΓÇÿThe Sword of TruthΓÇÖ. He has written 30+ major, bestselling novels, has been published in more than 20\nlanguages world-wide, and has sold more than 26 Million books. ΓÇÿThe Sword of TruthΓÇÖ is a revered literary\ntour de force, comprised of 17 volumes, borne from over 25 years of dedicated writing. Terry Goodkind's\nbrilliant books are character-driven stories, with a focus on the complexity of the human psyche. Goodkind\nhas an uncanny grasp for crafting compelling stories about people like you and me, trapped in terrifying\nsituations.\n" }, "imagePath": { "description": "The absolute path for the author image located in the `metadata/` directory. Will be null if there is no image.", "type": "string", "nullable": true, "example": "/metadata/authors/aut_bxxbyjiptmgb56yzoz.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 } } }, { "type": "object", "description": "The author schema with an array of items they are associated with.", "allOf": [ { "description": "An author object which includes a description and image path.", "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the author.", "format": "uuid", "example": "e4bb1afb-4a4f-4dd6-8be0-e615d233185b" }, "asin": { "type": "string", "description": "The Audible identifier (ASIN) of the author. Will be null if unknown. Not the Amazon identifier.", "nullable": true, "example": "B000APZOQA" }, "name": { "description": "The name of the author.", "type": "string", "example": "Terry Goodkind" }, "description": { "description": "A description of the author. Will be null if there is none.", "type": "string", "nullable": true, "example": "Terry Goodkind is a #1 New York Times Bestselling Author and creator of the critically acclaimed masterwork,\nΓÇÿThe Sword of TruthΓÇÖ. He has written 30+ major, bestselling novels, has been published in more than 20\nlanguages world-wide, and has sold more than 26 Million books. ΓÇÿThe Sword of TruthΓÇÖ is a revered literary\ntour de force, comprised of 17 volumes, borne from over 25 years of dedicated writing. Terry Goodkind's\nbrilliant books are character-driven stories, with a focus on the complexity of the human psyche. Goodkind\nhas an uncanny grasp for crafting compelling stories about people like you and me, trapped in terrifying\nsituations.\n" }, "imagePath": { "description": "The absolute path for the author image located in the `metadata/` directory. Will be null if there is no image.", "type": "string", "nullable": true, "example": "/metadata/authors/aut_bxxbyjiptmgb56yzoz.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 } } }, { "type": "object", "properties": { "libraryItems": { "description": "The items associated with the author", "type": "string" } } } ] }, { "type": "object", "description": "The author schema with an array of items and series they are associated with.", "allOf": [ { "type": "object", "description": "The author schema with an array of items they are associated with.", "allOf": [ { "description": "An author object which includes a description and image path.", "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the author.", "format": "uuid", "example": "e4bb1afb-4a4f-4dd6-8be0-e615d233185b" }, "asin": { "type": "string", "description": "The Audible identifier (ASIN) of the author. Will be null if unknown. Not the Amazon identifier.", "nullable": true, "example": "B000APZOQA" }, "name": { "description": "The name of the author.", "type": "string", "example": "Terry Goodkind" }, "description": { "description": "A description of the author. Will be null if there is none.", "type": "string", "nullable": true, "example": "Terry Goodkind is a #1 New York Times Bestselling Author and creator of the critically acclaimed masterwork,\nΓÇÿThe Sword of TruthΓÇÖ. He has written 30+ major, bestselling novels, has been published in more than 20\nlanguages world-wide, and has sold more than 26 Million books. ΓÇÿThe Sword of TruthΓÇÖ is a revered literary\ntour de force, comprised of 17 volumes, borne from over 25 years of dedicated writing. Terry Goodkind's\nbrilliant books are character-driven stories, with a focus on the complexity of the human psyche. Goodkind\nhas an uncanny grasp for crafting compelling stories about people like you and me, trapped in terrifying\nsituations.\n" }, "imagePath": { "description": "The absolute path for the author image located in the `metadata/` directory. Will be null if there is no image.", "type": "string", "nullable": true, "example": "/metadata/authors/aut_bxxbyjiptmgb56yzoz.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 } } }, { "type": "object", "properties": { "libraryItems": { "description": "The items associated with the author", "type": "string" } } } ] }, { "type": "object", "properties": { "series": { "description": "The series associated with the author", "type": "array", "items": { "type": "object", "description": "Series and the included library items that an author has written.", "properties": { "id": { "type": "string", "description": "The ID of the series.", "format": "uuid", "example": "e4bb1afb-4a4f-4dd6-8be0-e615d233185b" }, "name": { "description": "The name of the series.", "type": "string", "example": "Sword of Truth" }, "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": {} } } } } } } ] } ] } } } }, "404": { "description": "Author not found.", "content": { "text/html": { "schema": { "type": "string", "example": "Not found" } } } } } }, "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": [ { "name": "id", "in": "path", "description": "Author ID", "required": true, "schema": { "type": "string", "description": "The ID of the author.", "format": "uuid", "example": "e4bb1afb-4a4f-4dd6-8be0-e615d233185b" } }, { "name": "asin", "in": "query", "description": "The Audible Identifier (ASIN).", "required": false, "schema": { "type": "string", "description": "The Audible identifier (ASIN) of the author. Will be null if unknown. Not the Amazon identifier.", "nullable": true, "example": "B000APZOQA" } }, { "name": "name", "in": "query", "description": "The new name of the author.", "required": false, "schema": { "description": "The name of the author.", "type": "string", "example": "Terry Goodkind" } }, { "name": "description", "in": "query", "description": "The new description of the author.", "required": false, "schema": { "type": "string", "nullable": true, "example": "Terry Goodkind is a" } }, { "name": "imagePath", "in": "query", "description": "The new absolute path for the author image.", "required": false, "schema": { "type": "string", "nullable": true, "example": "/metadata/authors/aut_z3leimgybl7uf3y4ab.jpg" } } ], "responses": { "200": { "description": "updateAuthorById OK", "content": { "application/json": { "schema": { "allOf": [ { "description": "An author object which includes a description and image path.", "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the author.", "format": "uuid", "example": "e4bb1afb-4a4f-4dd6-8be0-e615d233185b" }, "asin": { "type": "string", "description": "The Audible identifier (ASIN) of the author. Will be null if unknown. Not the Amazon identifier.", "nullable": true, "example": "B000APZOQA" }, "name": { "description": "The name of the author.", "type": "string", "example": "Terry Goodkind" }, "description": { "description": "A description of the author. Will be null if there is none.", "type": "string", "nullable": true, "example": "Terry Goodkind is a #1 New York Times Bestselling Author and creator of the critically acclaimed masterwork,\nΓÇÿThe Sword of TruthΓÇÖ. He has written 30+ major, bestselling novels, has been published in more than 20\nlanguages world-wide, and has sold more than 26 Million books. ΓÇÿThe Sword of TruthΓÇÖ is a revered literary\ntour de force, comprised of 17 volumes, borne from over 25 years of dedicated writing. Terry Goodkind's\nbrilliant books are character-driven stories, with a focus on the complexity of the human psyche. Goodkind\nhas an uncanny grasp for crafting compelling stories about people like you and me, trapped in terrifying\nsituations.\n" }, "imagePath": { "description": "The absolute path for the author image located in the `metadata/` directory. Will be null if there is no image.", "type": "string", "nullable": true, "example": "/metadata/authors/aut_bxxbyjiptmgb56yzoz.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 } } }, { "description": "Whether the author was updated without errors. Will not exist if author was merged.", "type": "boolean", "nullable": true }, { "type": "object", "properties": { "merged": { "description": "Will only exist and be `true` if the author was merged with another author", "type": "boolean", "nullable": true } } } ] } } } }, "404": { "description": "Author not found.", "content": { "text/html": { "schema": { "type": "string", "example": "Not found" } } } } } }, "delete": { "operationId": "deleteAuthorById", "summary": "Delete a single author by ID on server and remove author from all books.", "tags": [ "Authors" ], "parameters": [ { "name": "id", "in": "path", "description": "Author ID", "required": true, "schema": { "type": "string", "description": "The ID of the author.", "format": "uuid", "example": "e4bb1afb-4a4f-4dd6-8be0-e615d233185b" } } ], "responses": { "200": { "$ref": "#/components/responses/ok200" }, "404": { "description": "Author not found.", "content": { "text/html": { "schema": { "type": "string", "example": "Not found" } } } } } } }, "/api/authors/{id}/image": { "post": { "operationId": "setAuthorImageById", "summary": "Set an author image using a provided URL.", "tags": [ "Authors" ], "parameters": [ { "name": "id", "in": "path", "description": "Author ID", "required": true, "schema": { "type": "string", "description": "The ID of the author.", "format": "uuid", "example": "e4bb1afb-4a4f-4dd6-8be0-e615d233185b" } }, { "name": "url", "in": "query", "description": "The URL of the image to add to the server", "required": true, "schema": { "type": "string", "format": "uri", "example": "https://images-na.ssl-images-amazon.com/images/I/51NoQTm33OL.__01_SX120_CR0,0,120,120__.jpg" } } ], "responses": { "200": { "description": "setAuthorImageById OK", "content": { "application/json": { "schema": { "oneOf": [ { "description": "An author object which includes a description and image path.", "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the author.", "format": "uuid", "example": "e4bb1afb-4a4f-4dd6-8be0-e615d233185b" }, "asin": { "type": "string", "description": "The Audible identifier (ASIN) of the author. Will be null if unknown. Not the Amazon identifier.", "nullable": true, "example": "B000APZOQA" }, "name": { "description": "The name of the author.", "type": "string", "example": "Terry Goodkind" }, "description": { "description": "A description of the author. Will be null if there is none.", "type": "string", "nullable": true, "example": "Terry Goodkind is a #1 New York Times Bestselling Author and creator of the critically acclaimed masterwork,\nΓÇÿThe Sword of TruthΓÇÖ. He has written 30+ major, bestselling novels, has been published in more than 20\nlanguages world-wide, and has sold more than 26 Million books. ΓÇÿThe Sword of TruthΓÇÖ is a revered literary\ntour de force, comprised of 17 volumes, borne from over 25 years of dedicated writing. Terry Goodkind's\nbrilliant books are character-driven stories, with a focus on the complexity of the human psyche. Goodkind\nhas an uncanny grasp for crafting compelling stories about people like you and me, trapped in terrifying\nsituations.\n" }, "imagePath": { "description": "The absolute path for the author image located in the `metadata/` directory. Will be null if there is no image.", "type": "string", "nullable": true, "example": "/metadata/authors/aut_bxxbyjiptmgb56yzoz.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 } } } ] } } } }, "404": { "description": "Author not found.", "content": { "text/html": { "schema": { "type": "string", "example": "Not found" } } } } } }, "delete": { "operationId": "deleteAuthorImageById", "summary": "Delete an author image from the server and remove the image from the database.", "tags": [ "Authors" ], "parameters": [ { "name": "id", "in": "path", "description": "Author ID", "required": true, "schema": { "type": "string", "description": "The ID of the author.", "format": "uuid", "example": "e4bb1afb-4a4f-4dd6-8be0-e615d233185b" } } ], "responses": { "200": { "$ref": "#/components/responses/ok200" }, "404": { "description": "Author not found.", "content": { "text/html": { "schema": { "type": "string", "example": "Not found" } } } } } }, "patch": { "operationId": "getAuthorImageById", "summary": "Return the author image by author ID.", "tags": [ "Authors" ], "parameters": [ { "name": "id", "in": "path", "description": "Author ID", "required": true, "schema": { "type": "string", "description": "The ID of the author.", "format": "uuid", "example": "e4bb1afb-4a4f-4dd6-8be0-e615d233185b" } }, { "name": "width", "in": "query", "description": "The requested width of image in pixels.", "schema": { "type": "integer", "default": 400, "example": 400 }, "example": 400 }, { "name": "height", "in": "query", "description": "The requested height of image in pixels. If `null`, the height is scaled to maintain aspect ratio based on the requested width.", "schema": { "type": "integer", "nullable": true, "default": null, "example": 600 }, "examples": { "scaleHeight": { "summary": "Scale height with width", "value": null }, "fixedHeight": { "summary": "Force height of image", "value": 600 } } }, { "name": "format", "in": "query", "description": "The requested output format.", "schema": { "type": "string", "default": "jpeg", "example": "webp" } }, { "name": "raw", "in": "query", "description": "Return the raw image without scaling if true.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "getAuthorImageById OK", "content": { "image/*": { "schema": { "type": "string", "format": "binary" } } } }, "404": { "description": "Author not found.", "content": { "text/html": { "schema": { "type": "string", "example": "Not found" } } } } } } }, "/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": [ { "name": "id", "in": "path", "description": "Author ID", "required": true, "schema": { "type": "string", "description": "The ID of the author.", "format": "uuid", "example": "e4bb1afb-4a4f-4dd6-8be0-e615d233185b" } }, { "name": "asin", "in": "query", "description": "The Audible Identifier (ASIN).", "required": false, "schema": { "type": "string", "description": "The Audible identifier (ASIN) of the author. Will be null if unknown. Not the Amazon identifier.", "nullable": true, "example": "B000APZOQA" } }, { "name": "q", "in": "query", "description": "The name of the author to use for searching.", "required": false, "schema": { "type": "string", "example": "Terry Goodkind" } } ], "responses": { "200": { "description": "matchAuthorById OK", "content": { "application/json": { "schema": { "allOf": [ { "description": "An author object which includes a description and image path.", "type": "object", "properties": { "id": { "type": "string", "description": "The ID of the author.", "format": "uuid", "example": "e4bb1afb-4a4f-4dd6-8be0-e615d233185b" }, "asin": { "type": "string", "description": "The Audible identifier (ASIN) of the author. Will be null if unknown. Not the Amazon identifier.", "nullable": true, "example": "B000APZOQA" }, "name": { "description": "The name of the author.", "type": "string", "example": "Terry Goodkind" }, "description": { "description": "A description of the author. Will be null if there is none.", "type": "string", "nullable": true, "example": "Terry Goodkind is a #1 New York Times Bestselling Author and creator of the critically acclaimed masterwork,\nΓÇÿThe Sword of TruthΓÇÖ. He has written 30+ major, bestselling novels, has been published in more than 20\nlanguages world-wide, and has sold more than 26 Million books. ΓÇÿThe Sword of TruthΓÇÖ is a revered literary\ntour de force, comprised of 17 volumes, borne from over 25 years of dedicated writing. Terry Goodkind's\nbrilliant books are character-driven stories, with a focus on the complexity of the human psyche. Goodkind\nhas an uncanny grasp for crafting compelling stories about people like you and me, trapped in terrifying\nsituations.\n" }, "imagePath": { "description": "The absolute path for the author image located in the `metadata/` directory. Will be null if there is no image.", "type": "string", "nullable": true, "example": "/metadata/authors/aut_bxxbyjiptmgb56yzoz.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 } } }, { "description": "Whether the author was updated without errors. Will not exist if author was merged.", "type": "boolean", "nullable": true } ] } } } }, "404": { "description": "Author not found.", "content": { "text/html": { "schema": { "type": "string", "example": "Not found" } } } } } } } }, "tags": [ { "name": "Authors", "description": "Author endpoints" } ] }