audiobookshelf/docs/openapi.json
Nicholas Wallace 74dd24febf Bundled spec
2024-04-01 00:26:55 +00:00

857 lines
36 KiB
JSON
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

{
"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": [
{
"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,\nThe 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,\nThe 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,\nThe 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,\nThe 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,\nThe 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,\nThe 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"
}
]
}