bookstack_api_spec.json•89 kB
{
"docs": [
{
"name": "docs-display",
"uri": "api/docs",
"method": "GET",
"controller": "BookStack\\Api\\ApiDocsController",
"controller_method": "display",
"controller_method_kebab": "display",
"base_model": "docs",
"description": "Load the docs page for the API.",
"body_params": null,
"example_request": null,
"example_response": null
},
{
"name": "docs-json",
"uri": "api/docs.json",
"method": "GET",
"controller": "BookStack\\Api\\ApiDocsController",
"controller_method": "json",
"controller_method_kebab": "json",
"base_model": "docs",
"description": "Show a JSON view of the API docs data.",
"body_params": null,
"example_request": null,
"example_response": null
}
],
"attachments": [
{
"name": "attachments-list",
"uri": "api/attachments",
"method": "GET",
"controller": "BookStack\\Uploads\\Controllers\\AttachmentApiController",
"controller_method": "list",
"controller_method_kebab": "list",
"base_model": "attachments",
"description": "Get a listing of attachments visible to the user. The external property indicates whether the attachment is simple a link. A false value for the external property would indicate a file upload.",
"body_params": null,
"example_request": null,
"example_response": "{\n \"data\": [\n {\n \"id\": 3,\n \"name\": \"datasheet.pdf\",\n \"extension\": \"pdf\",\n \"uploaded_to\": 8,\n \"external\": false,\n \"order\": 1,\n \"created_at\": \"2021-10-11T06:18:49.000000Z\",\n \"updated_at\": \"2021-10-20T06:31:10.000000Z\",\n \"created_by\": 1,\n \"updated_by\": 1\n },\n {\n \"id\": 4,\n \"name\": \"Cat reference\",\n \"extension\": \"\",\n \"uploaded_to\": 9,\n \"external\": true,\n \"order\": 1,\n \"created_at\": \"2021-10-20T06:30:11.000000Z\",\n \"updated_at\": \"2021-10-20T06:30:11.000000Z\",\n \"created_by\": 1,\n \"updated_by\": 1\n }\n ],\n \"total\": 2\n}"
},
{
"name": "attachments-create",
"uri": "api/attachments",
"method": "POST",
"controller": "BookStack\\Uploads\\Controllers\\AttachmentApiController",
"controller_method": "create",
"controller_method_kebab": "create",
"base_model": "attachments",
"description": "Create a new attachment in the system. An uploaded_to value must be provided containing an ID of the page that this upload will be related to.\nIf you're uploading a file the POST data should be provided via a multipart/form-data type request instead of JSON. ",
"body_params": {
"name": ["required", "string", "min:1", "max:255"],
"uploaded_to": ["required", "integer", "exists:pages,id"],
"file": ["required_without:link", "file", "max:50000"],
"link": [
"required_without:file",
"string",
"min:1",
"max:2000",
"safe_url"
]
},
"example_request": "{\n \"name\": \"My uploaded attachment\",\n \"uploaded_to\": 8,\n \"link\": \"https://link.example.com\"\n}",
"example_response": "{\n \"id\": 5,\n \"name\": \"My uploaded attachment\",\n \"extension\": \"\",\n \"uploaded_to\": 8,\n \"external\": true,\n \"order\": 2,\n \"created_by\": 1,\n \"updated_by\": 1,\n \"created_at\": \"2021-10-20T06:35:46.000000Z\",\n \"updated_at\": \"2021-10-20T06:35:46.000000Z\"\n}"
},
{
"name": "attachments-read",
"uri": "api/attachments/{id}",
"method": "GET",
"controller": "BookStack\\Uploads\\Controllers\\AttachmentApiController",
"controller_method": "read",
"controller_method_kebab": "read",
"base_model": "attachments",
"description": "Get the details & content of a single attachment of the given ID. The attachment link or file content is provided via a 'content' property. For files the content will be base64 encoded. ",
"body_params": null,
"example_request": null,
"example_response": "{\n \"id\": 5,\n \"name\": \"My link attachment\",\n \"extension\": \"\",\n \"uploaded_to\": 4,\n \"external\": true,\n \"order\": 2,\n \"created_by\": {\n \"id\": 1,\n \"name\": \"Admin\",\n \"slug\": \"admin\"\n },\n \"updated_by\": {\n \"id\": 1,\n \"name\": \"Admin\",\n \"slug\": \"admin\"\n },\n \"created_at\": \"2021-10-20T06:35:46.000000Z\",\n \"updated_at\": \"2021-10-20T06:37:11.000000Z\",\n \"links\": {\n \"html\": \"\u003Ca target=\\\"_blank\\\" href=\\\"https://bookstack.local/attachments/5\\\"\u003EMy updated attachment\u003C/a\u003E\",\n \"markdown\": \"[My updated attachment](https://bookstack.local/attachments/5)\"\n },\n \"content\": \"https://link.example.com/updated\"\n}"
},
{
"name": "attachments-update",
"uri": "api/attachments/{id}",
"method": "PUT",
"controller": "BookStack\\Uploads\\Controllers\\AttachmentApiController",
"controller_method": "update",
"controller_method_kebab": "update",
"base_model": "attachments",
"description": "Update the details of a single attachment. As per the create endpoint, if a file is being provided as the attachment content the request should be formatted as a multipart/form-data request instead of JSON. ",
"body_params": {
"name": ["string", "min:1", "max:255"],
"uploaded_to": ["integer", "exists:pages,id"],
"file": ["file", "max:50000"],
"link": ["string", "min:1", "max:2000", "safe_url"]
},
"example_request": "{\n \"name\": \"My updated attachment\",\n \"uploaded_to\": 4,\n \"link\": \"https://link.example.com/updated\"\n}",
"example_response": "{\n \"id\": 5,\n \"name\": \"My updated attachment\",\n \"extension\": \"\",\n \"uploaded_to\": 4,\n \"external\": true,\n \"order\": 2,\n \"created_by\": 1,\n \"updated_by\": 1,\n \"created_at\": \"2021-10-20T06:35:46.000000Z\",\n \"updated_at\": \"2021-10-20T06:37:11.000000Z\"\n}"
},
{
"name": "attachments-delete",
"uri": "api/attachments/{id}",
"method": "DELETE",
"controller": "BookStack\\Uploads\\Controllers\\AttachmentApiController",
"controller_method": "delete",
"controller_method_kebab": "delete",
"base_model": "attachments",
"description": "Delete an attachment of the given ID. ",
"body_params": null,
"example_request": null,
"example_response": null
}
],
"books": [
{
"name": "books-list",
"uri": "api/books",
"method": "GET",
"controller": "BookStack\\Entities\\Controllers\\BookApiController",
"controller_method": "list",
"controller_method_kebab": "list",
"base_model": "books",
"description": "Get a listing of books visible to the user.",
"body_params": null,
"example_request": null,
"example_response": "{\n \"data\": [\n {\n \"id\": 1,\n \"name\": \"BookStack User Guide\",\n \"slug\": \"bookstack-user-guide\",\n \"description\": \"This is a general guide on using BookStack on a day-to-day basis.\",\n \"created_at\": \"2019-05-05T21:48:46.000000Z\",\n \"updated_at\": \"2019-12-11T20:57:31.000000Z\",\n \"created_by\": 1,\n \"updated_by\": 1,\n \"owned_by\": 1,\n \"cover\": null\n },\n {\n \"id\": 2,\n \"name\": \"Inventore inventore quia voluptatem.\",\n \"slug\": \"inventore-inventore-quia-voluptatem\",\n \"description\": \"Veniam nihil voluptas enim laborum corporis quos sint. Ab rerum voluptas ut iste voluptas magni quibusdam ut. Amet omnis enim voluptate neque facilis.\",\n \"created_at\": \"2019-05-05T22:10:14.000000Z\",\n \"updated_at\": \"2019-12-11T20:57:23.000000Z\",\n \"created_by\": 4,\n \"updated_by\": 3,\n \"owned_by\": 3,\n \"cover\": {\n \"id\": 11,\n \"name\": \"cat_banner.jpg\",\n \"url\": \"https://example.com/uploads/images/cover_book/2021-10/cat-banner.jpg\"\n }\n }\n ],\n \"total\": 14\n}"
},
{
"name": "books-create",
"uri": "api/books",
"method": "POST",
"controller": "BookStack\\Entities\\Controllers\\BookApiController",
"controller_method": "create",
"controller_method_kebab": "create",
"base_model": "books",
"description": "Create a new book in the system. The cover image of a book can be set by sending a file via an 'image' property within a 'multipart/form-data' request. If the 'image' property is null then the book cover image will be removed. ",
"body_params": {
"name": ["required", "string", "max:255"],
"description": ["string", "max:1900"],
"description_html": ["string", "max:2000"],
"tags": ["array"],
"image": [
"nullable",
"image_extension",
"mimes:jpeg,png,gif,webp",
"max:50000"
],
"default_template_id": ["nullable", "integer"]
},
"example_request": "{\n \"name\": \"My own book\",\n \"description_html\": \"\u003Cp\u003EThis is \u003Cstrong\u003Emy\u003C/strong\u003E own little book created via the API\u003C/p\u003E\",\n \"default_template_id\": 2427,\n \"tags\": [\n {\"name\": \"Category\", \"value\": \"Top Content\"},\n {\"name\": \"Rating\", \"value\": \"Highest\"}\n ]\n}",
"example_response": "{\n \"id\": 226,\n \"name\": \"My own book\",\n \"slug\": \"my-own-book\",\n \"description\": \"This is my own little book created via the API\",\n \"created_at\": \"2023-12-22T14:22:28.000000Z\",\n \"updated_at\": \"2023-12-22T14:22:28.000000Z\",\n \"created_by\": 1,\n \"updated_by\": 1,\n \"owned_by\": 1,\n \"default_template_id\": 2427,\n \"description_html\": \"\u003Cp\u003EThis is \u003Cstrong\u003Emy\u003C\\/strong\u003E own little book created via the API\u003C\\/p\u003E\",\n \"tags\": [\n {\n \"name\": \"Category\",\n \"value\": \"Top Content\",\n \"order\": 0\n },\n {\n \"name\": \"Rating\",\n \"value\": \"Highest\",\n \"order\": 0\n }\n ],\n \"cover\": null\n}"
},
{
"name": "books-read",
"uri": "api/books/{id}",
"method": "GET",
"controller": "BookStack\\Entities\\Controllers\\BookApiController",
"controller_method": "read",
"controller_method_kebab": "read",
"base_model": "books",
"description": "View the details of a single book. The response data will contain 'content' property listing the chapter and pages directly within, in the same structure as you'd see within the BookStack interface when viewing a book. Top-level contents will have a 'type' property to distinguish between pages & chapters.",
"body_params": null,
"example_request": null,
"example_response": "{\n \"id\": 16,\n \"name\": \"My own book\",\n \"slug\": \"my-own-book\",\n \"description\": \"This is my own little book\",\n \"description_html\": \"\u003Cp\u003EThis is my own \u003Cem\u003Elittle\u003C/em\u003E book\u003C/p\u003E\",\n \"created_at\": \"2020-01-12T14:09:59.000000Z\",\n \"updated_at\": \"2020-01-12T14:11:51.000000Z\",\n \"created_by\": {\n \"id\": 1,\n \"name\": \"Admin\",\n \"slug\": \"admin\"\n },\n \"updated_by\": {\n \"id\": 1,\n \"name\": \"Admin\",\n \"slug\": \"admin\"\n },\n \"owned_by\": {\n \"id\": 1,\n \"name\": \"Admin\",\n \"slug\": \"admin\"\n },\n \"default_template_id\": null,\n \"contents\": [\n {\n \"id\": 50,\n \"name\": \"Bridge Structures\",\n \"slug\": \"bridge-structures\",\n \"book_id\": 16,\n \"created_at\": \"2021-12-19T15:22:11.000000Z\",\n \"updated_at\": \"2021-12-21T19:42:29.000000Z\",\n \"url\": \"https://example.com/books/my-own-book/chapter/bridge-structures\",\n \"type\": \"chapter\",\n \"pages\": [\n {\n \"id\": 42,\n \"name\": \"Building Bridges\",\n \"slug\": \"building-bridges\",\n \"book_id\": 16,\n \"chapter_id\": 50,\n \"draft\": false,\n \"template\": false,\n \"created_at\": \"2021-12-19T15:22:11.000000Z\",\n \"updated_at\": \"2022-09-29T13:44:15.000000Z\",\n \"url\": \"https://example.com/books/my-own-book/page/building-bridges\"\n }\n ]\n },\n {\n \"id\": 43,\n \"name\": \"Cool Animals\",\n \"slug\": \"cool-animals\",\n \"book_id\": 16,\n \"chapter_id\": 0,\n \"draft\": false,\n \"template\": false,\n \"created_at\": \"2021-12-19T18:22:11.000000Z\",\n \"updated_at\": \"2022-07-29T13:44:15.000000Z\",\n \"url\": \"https://example.com/books/my-own-book/page/cool-animals\",\n \"type\": \"page\"\n }\n ],\n \"tags\": [\n {\n \"name\": \"Category\",\n \"value\": \"Guide\",\n \"order\": 0\n }\n ],\n \"cover\": {\n \"id\": 452,\n \"name\": \"sjovall_m117hUWMu40.jpg\",\n \"url\": \"https://example.com/uploads/images/cover_book/2020-01/sjovall_m117hUWMu40.jpg\",\n \"created_at\": \"2020-01-12T14:11:51.000000Z\",\n \"updated_at\": \"2020-01-12T14:11:51.000000Z\",\n \"created_by\": 1,\n \"updated_by\": 1,\n \"path\": \"/uploads/images/cover_book/2020-01/sjovall_m117hUWMu40.jpg\",\n \"type\": \"cover_book\",\n \"uploaded_to\": 16\n }\n}"
},
{
"name": "books-update",
"uri": "api/books/{id}",
"method": "PUT",
"controller": "BookStack\\Entities\\Controllers\\BookApiController",
"controller_method": "update",
"controller_method_kebab": "update",
"base_model": "books",
"description": "Update the details of a single book. The cover image of a book can be set by sending a file via an 'image' property within a 'multipart/form-data' request. If the 'image' property is null then the book cover image will be removed. ",
"body_params": {
"name": ["string", "min:1", "max:255"],
"description": ["string", "max:1900"],
"description_html": ["string", "max:2000"],
"tags": ["array"],
"image": [
"nullable",
"image_extension",
"mimes:jpeg,png,gif,webp",
"max:50000"
],
"default_template_id": ["nullable", "integer"]
},
"example_request": "{\n \"name\": \"My updated book\",\n \"description_html\": \"\u003Cp\u003EThis is my book with \u003Cem\u003Eupdated\u003C/em\u003E details\u003C/p\u003E\",\n \"default_template_id\": 2427,\n \"tags\": [\n {\"name\": \"Subject\", \"value\": \"Updates\"}\n ]\n}",
"example_response": "{\n \"id\": 226,\n \"name\": \"My updated book\",\n \"slug\": \"my-updated-book\",\n \"description\": \"This is my book with updated details\",\n \"created_at\": \"2023-12-22T14:22:28.000000Z\",\n \"updated_at\": \"2023-12-22T14:24:07.000000Z\",\n \"created_by\": 1,\n \"updated_by\": 1,\n \"owned_by\": 1,\n \"default_template_id\": 2427,\n \"description_html\": \"\u003Cp\u003EThis is my book with \u003Cem\u003Eupdated\u003C\\/em\u003E details\u003C\\/p\u003E\",\n \"tags\": [\n {\n \"name\": \"Subject\",\n \"value\": \"Updates\",\n \"order\": 0\n }\n ],\n \"cover\": null\n}"
},
{
"name": "books-delete",
"uri": "api/books/{id}",
"method": "DELETE",
"controller": "BookStack\\Entities\\Controllers\\BookApiController",
"controller_method": "delete",
"controller_method_kebab": "delete",
"base_model": "books",
"description": "Delete a single book. This will typically send the book to the recycle bin. ",
"body_params": null,
"example_request": null,
"example_response": null
},
{
"name": "books-exportHtml",
"uri": "api/books/{id}/export/html",
"method": "GET",
"controller": "BookStack\\Exports\\Controllers\\BookExportApiController",
"controller_method": "exportHtml",
"controller_method_kebab": "export-html",
"base_model": "books",
"description": "Export a book as a contained HTML file. ",
"body_params": null,
"example_request": null,
"example_response": null
},
{
"name": "books-exportPdf",
"uri": "api/books/{id}/export/pdf",
"method": "GET",
"controller": "BookStack\\Exports\\Controllers\\BookExportApiController",
"controller_method": "exportPdf",
"controller_method_kebab": "export-pdf",
"base_model": "books",
"description": "Export a book as a PDF file. ",
"body_params": null,
"example_request": null,
"example_response": null
},
{
"name": "books-exportPlainText",
"uri": "api/books/{id}/export/plaintext",
"method": "GET",
"controller": "BookStack\\Exports\\Controllers\\BookExportApiController",
"controller_method": "exportPlainText",
"controller_method_kebab": "export-plain-text",
"base_model": "books",
"description": "Export a book as a plain text file.",
"body_params": null,
"example_request": null,
"example_response": null
},
{
"name": "books-exportMarkdown",
"uri": "api/books/{id}/export/markdown",
"method": "GET",
"controller": "BookStack\\Exports\\Controllers\\BookExportApiController",
"controller_method": "exportMarkdown",
"controller_method_kebab": "export-markdown",
"base_model": "books",
"description": "Export a book as a markdown file.",
"body_params": null,
"example_request": null,
"example_response": null
}
],
"chapters": [
{
"name": "chapters-list",
"uri": "api/chapters",
"method": "GET",
"controller": "BookStack\\Entities\\Controllers\\ChapterApiController",
"controller_method": "list",
"controller_method_kebab": "list",
"base_model": "chapters",
"description": "Get a listing of chapters visible to the user.",
"body_params": null,
"example_request": null,
"example_response": "{\n \"data\": [\n {\n \"id\": 1,\n \"book_id\": 1,\n \"name\": \"Content Creation\",\n \"slug\": \"content-creation\",\n \"description\": \"How to create documentation on whatever subject you need to write about.\",\n \"priority\": 3,\n \"created_at\": \"2019-05-05T21:49:56.000000Z\",\n \"updated_at\": \"2019-09-28T11:24:23.000000Z\",\n \"created_by\": 1,\n \"updated_by\": 1,\n \"owned_by\": 1,\n \"book_slug\": \"example-book\"\n },\n {\n \"id\": 2,\n \"book_id\": 1,\n \"name\": \"Managing Content\",\n \"slug\": \"managing-content\",\n \"description\": \"How to keep things organised and orderly in the system for easier navigation and better user experience.\",\n \"priority\": 5,\n \"created_at\": \"2019-05-05T21:58:07.000000Z\",\n \"updated_at\": \"2019-10-17T15:05:34.000000Z\",\n \"created_by\": 3,\n \"updated_by\": 3,\n \"owned_by\": 3,\n \"book_slug\": \"example-book\"\n }\n ],\n \"total\": 40\n}"
},
{
"name": "chapters-create",
"uri": "api/chapters",
"method": "POST",
"controller": "BookStack\\Entities\\Controllers\\ChapterApiController",
"controller_method": "create",
"controller_method_kebab": "create",
"base_model": "chapters",
"description": "Create a new chapter in the system.",
"body_params": {
"book_id": ["required", "integer"],
"name": ["required", "string", "max:255"],
"description": ["string", "max:1900"],
"description_html": ["string", "max:2000"],
"tags": ["array"],
"priority": ["integer"],
"default_template_id": ["nullable", "integer"]
},
"example_request": "{\n \"book_id\": 1,\n \"name\": \"My fantastic new chapter\",\n \"description_html\": \"\u003Cp\u003EThis is a \u003Cstrong\u003Egreat new chapter\u003C/strong\u003E that I've created via the API\u003C/p\u003E\",\n \"priority\": 15,\n \"default_template_id\": 25,\n \"tags\": [\n {\"name\": \"Category\", \"value\": \"Top Content\"},\n {\"name\": \"Rating\", \"value\": \"Highest\"}\n ]\n}\n",
"example_response": "{\n \"id\": 668,\n \"book_id\": 1,\n \"slug\": \"my-fantastic-new-chapter\",\n \"name\": \"My fantastic new chapter\",\n \"description\": \"This is a great new chapter that I've created via the API\",\n \"priority\": 15,\n \"created_at\": \"2023-12-22T14:26:28.000000Z\",\n \"updated_at\": \"2023-12-22T14:26:28.000000Z\",\n \"created_by\": 1,\n \"updated_by\": 1,\n \"owned_by\": 1,\n \"description_html\": \"\u003Cp\u003EThis is a \u003Cstrong\u003Egreat new chapter\u003C\\/strong\u003E that I've created via the API\u003C\\/p\u003E\",\n \"default_template_id\": 25,\n \"book_slug\": \"example-book\",\n \"tags\": [\n {\n \"name\": \"Category\",\n \"value\": \"Top Content\",\n \"order\": 0\n },\n {\n \"name\": \"Rating\",\n \"value\": \"Highest\",\n \"order\": 0\n }\n ]\n}\n"
},
{
"name": "chapters-read",
"uri": "api/chapters/{id}",
"method": "GET",
"controller": "BookStack\\Entities\\Controllers\\ChapterApiController",
"controller_method": "read",
"controller_method_kebab": "read",
"base_model": "chapters",
"description": "View the details of a single chapter.",
"body_params": null,
"example_request": null,
"example_response": "{\n \"id\": 1,\n \"book_id\": 1,\n \"slug\": \"content-creation\",\n \"name\": \"Content Creation\",\n \"description\": \"How to create documentation on whatever subject you need to write about.\",\n \"description_html\": \"\u003Cp\u003EHow to create \u003Cstrong\u003Edocumentation\u003C/strong\u003E on whatever subject you need to write about.\u003C/p\u003E\",\n \"default_template_id\": 25,\n \"priority\": 3,\n \"created_at\": \"2019-05-05T21:49:56.000000Z\",\n \"updated_at\": \"2019-09-28T11:24:23.000000Z\",\n \"created_by\": {\n \"id\": 1,\n \"name\": \"Admin\",\n \"slug\": \"admin\"\n },\n \"updated_by\": {\n \"id\": 1,\n \"name\": \"Admin\",\n \"slug\": \"admin\"\n },\n \"owned_by\": {\n \"id\": 1,\n \"name\": \"Admin\",\n \"slug\": \"admin\"\n },\n \"book_slug\": \"example-book\",\n \"tags\": [\n {\n \"name\": \"Category\",\n \"value\": \"Guide\",\n \"order\": 0\n }\n ],\n \"pages\": [\n {\n \"id\": 1,\n \"book_id\": 1,\n \"chapter_id\": 1,\n \"name\": \"How to create page content\",\n \"slug\": \"how-to-create-page-content\",\n \"priority\": 0,\n \"created_at\": \"2019-05-05T21:49:58.000000Z\",\n \"updated_at\": \"2019-08-26T14:32:59.000000Z\",\n \"created_by\": 1,\n \"updated_by\": 1,\n \"owned_by\": 1,\n \"draft\": false,\n \"revision_count\": 2,\n \"template\": false,\n \"editor\": \"wysiwyg\",\n \"book_slug\": \"example-book\"\n },\n {\n \"id\": 7,\n \"book_id\": 1,\n \"chapter_id\": 1,\n \"name\": \"Good book structure\",\n \"slug\": \"good-book-structure\",\n \"priority\": 1,\n \"created_at\": \"2019-05-05T22:01:55.000000Z\",\n \"updated_at\": \"2019-06-06T12:03:04.000000Z\",\n \"created_by\": 3,\n \"updated_by\": 3,\n \"owned_by\": 1,\n \"draft\": false,\n \"revision_count\": 1,\n \"template\": false,\n \"editor\": \"wysiwyg\",\n \"book_slug\": \"example-book\"\n }\n ]\n}"
},
{
"name": "chapters-update",
"uri": "api/chapters/{id}",
"method": "PUT",
"controller": "BookStack\\Entities\\Controllers\\ChapterApiController",
"controller_method": "update",
"controller_method_kebab": "update",
"base_model": "chapters",
"description": "Update the details of a single chapter. Providing a 'book_id' property will essentially move the chapter into that parent element if you have permissions to do so.",
"body_params": {
"book_id": ["integer"],
"name": ["string", "min:1", "max:255"],
"description": ["string", "max:1900"],
"description_html": ["string", "max:2000"],
"tags": ["array"],
"priority": ["integer"],
"default_template_id": ["nullable", "integer"]
},
"example_request": "{\n \"book_id\": 1,\n \"name\": \"My fantastic updated chapter\",\n \"description_html\": \"\u003Cp\u003EThis is an \u003Cstrong\u003Eupdated chapter\u003C/strong\u003E that I've altered via the API\u003C/p\u003E\",\n \"priority\": 16,\n \"default_template_id\": 2428,\n \"tags\": [\n {\"name\": \"Category\", \"value\": \"Kinda Good Content\"},\n {\"name\": \"Rating\", \"value\": \"Medium\"}\n ]\n}\n",
"example_response": "{\n \"id\": 668,\n \"book_id\": 1,\n \"slug\": \"my-fantastic-updated-chapter\",\n \"name\": \"My fantastic updated chapter\",\n \"description\": \"This is an updated chapter that I've altered via the API\",\n \"priority\": 16,\n \"created_at\": \"2023-12-22T14:26:28.000000Z\",\n \"updated_at\": \"2023-12-22T14:27:59.000000Z\",\n \"created_by\": 1,\n \"updated_by\": 1,\n \"owned_by\": 1,\n \"description_html\": \"\u003Cp\u003EThis is an \u003Cstrong\u003Eupdated chapter\u003C\\/strong\u003E that I've altered via the API\u003C\\/p\u003E\",\n \"default_template_id\": 2428,\n \"book_slug\": \"example-book\",\n \"tags\": [\n {\n \"name\": \"Category\",\n \"value\": \"Kinda Good Content\",\n \"order\": 0\n },\n {\n \"name\": \"Rating\",\n \"value\": \"Medium\",\n \"order\": 0\n }\n ]\n}\n"
},
{
"name": "chapters-delete",
"uri": "api/chapters/{id}",
"method": "DELETE",
"controller": "BookStack\\Entities\\Controllers\\ChapterApiController",
"controller_method": "delete",
"controller_method_kebab": "delete",
"base_model": "chapters",
"description": "Delete a chapter. This will typically send the chapter to the recycle bin.",
"body_params": null,
"example_request": null,
"example_response": null
},
{
"name": "chapters-exportHtml",
"uri": "api/chapters/{id}/export/html",
"method": "GET",
"controller": "BookStack\\Exports\\Controllers\\ChapterExportApiController",
"controller_method": "exportHtml",
"controller_method_kebab": "export-html",
"base_model": "chapters",
"description": "Export a chapter as a contained HTML file. ",
"body_params": null,
"example_request": null,
"example_response": null
},
{
"name": "chapters-exportPdf",
"uri": "api/chapters/{id}/export/pdf",
"method": "GET",
"controller": "BookStack\\Exports\\Controllers\\ChapterExportApiController",
"controller_method": "exportPdf",
"controller_method_kebab": "export-pdf",
"base_model": "chapters",
"description": "Export a chapter as a PDF file. ",
"body_params": null,
"example_request": null,
"example_response": null
},
{
"name": "chapters-exportPlainText",
"uri": "api/chapters/{id}/export/plaintext",
"method": "GET",
"controller": "BookStack\\Exports\\Controllers\\ChapterExportApiController",
"controller_method": "exportPlainText",
"controller_method_kebab": "export-plain-text",
"base_model": "chapters",
"description": "Export a chapter as a plain text file.",
"body_params": null,
"example_request": null,
"example_response": null
},
{
"name": "chapters-exportMarkdown",
"uri": "api/chapters/{id}/export/markdown",
"method": "GET",
"controller": "BookStack\\Exports\\Controllers\\ChapterExportApiController",
"controller_method": "exportMarkdown",
"controller_method_kebab": "export-markdown",
"base_model": "chapters",
"description": "Export a chapter as a markdown file.",
"body_params": null,
"example_request": null,
"example_response": null
}
],
"pages": [
{
"name": "pages-list",
"uri": "api/pages",
"method": "GET",
"controller": "BookStack\\Entities\\Controllers\\PageApiController",
"controller_method": "list",
"controller_method_kebab": "list",
"base_model": "pages",
"description": "Get a listing of pages visible to the user.",
"body_params": null,
"example_request": null,
"example_response": "{\n\t\"data\": [\n\t\t{\n\t\t\t\"id\": 1,\n\t\t\t\"book_id\": 1,\n\t\t\t\"chapter_id\": 1,\n\t\t\t\"name\": \"How to create page content\",\n\t\t\t\"slug\": \"how-to-create-page-content\",\n\t\t\t\"priority\": 0,\n\t\t\t\"draft\": false,\n\t\t\t\"revision_count\": 3,\n\t\t\t\"template\": false,\n\t\t\t\"created_at\": \"2019-05-05T21:49:58.000000Z\",\n\t\t\t\"updated_at\": \"2020-07-04T15:50:58.000000Z\",\n\t\t\t\"created_by\": 1,\n\t\t\t\"updated_by\": 1,\n\t\t\t\"owned_by\": 1,\n\t\t\t\"editor\": \"wysiwyg\",\n\t\t\t\"book_slug\": \"example-book\"\n\t\t},\n\t\t{\n\t\t\t\"id\": 2,\n\t\t\t\"book_id\": 1,\n\t\t\t\"chapter_id\": 1,\n\t\t\t\"name\": \"How to use images\",\n\t\t\t\"slug\": \"how-to-use-images\",\n\t\t\t\"priority\": 2,\n\t\t\t\"draft\": false,\n\t\t\t\"revision_count\": 3,\n\t\t\t\"template\": false,\n\t\t\t\"created_at\": \"2019-05-05T21:53:30.000000Z\",\n\t\t\t\"updated_at\": \"2019-06-06T12:03:04.000000Z\",\n\t\t\t\"created_by\": 1,\n\t\t\t\"updated_by\": 1,\n\t\t\t\"owned_by\": 1,\n\t\t\t\"editor\": \"wysiwyg\",\n\t\t\t\"book_slug\": \"example-book\"\n\t\t},\n\t\t{\n\t\t\t\"id\": 3,\n\t\t\t\"book_id\": 1,\n\t\t\t\"chapter_id\": 1,\n\t\t\t\"name\": \"Drawings via draw.io\",\n\t\t\t\"slug\": \"drawings-via-drawio\",\n\t\t\t\"priority\": 3,\n\t\t\t\"draft\": false,\n\t\t\t\"revision_count\": 3,\n\t\t\t\"template\": false,\n\t\t\t\"created_at\": \"2019-05-05T21:53:49.000000Z\",\n\t\t\t\"updated_at\": \"2019-12-18T21:56:52.000000Z\",\n\t\t\t\"created_by\": 1,\n\t\t\t\"updated_by\": 1,\n\t\t\t\"owned_by\": 1,\n\t\t\t\"editor\": \"wysiwyg\",\n\t\t\t\"book_slug\": \"example-book\"\n\t\t}\n\t],\n\t\"total\": 322\n}"
},
{
"name": "pages-create",
"uri": "api/pages",
"method": "POST",
"controller": "BookStack\\Entities\\Controllers\\PageApiController",
"controller_method": "create",
"controller_method_kebab": "create",
"base_model": "pages",
"description": "Create a new page in the system.\nThe ID of a parent book or chapter is required to indicate where this page should be located.\nAny HTML content provided should be kept to a single-block depth of plain HTML elements to remain compatible with the BookStack front-end and editors. Any images included via base64 data URIs will be extracted and saved as gallery images against the page during upload.",
"body_params": {
"book_id": ["required_without:chapter_id", "integer"],
"chapter_id": ["required_without:book_id", "integer"],
"name": ["required", "string", "max:255"],
"html": ["required_without:markdown", "string"],
"markdown": ["required_without:html", "string"],
"tags": ["array"],
"priority": ["integer"]
},
"example_request": "{\n\t\"book_id\": 1,\n\t\"name\": \"My API Page\",\n\t\"html\": \"\u003Cp\u003Emy new API page\u003C/p\u003E\",\n\t\"priority\": 15,\n\t\"tags\": [\n\t\t{\"name\": \"Category\", \"value\": \"Not Bad Content\"},\n\t\t{\"name\": \"Rating\", \"value\": \"Average\"}\n\t]\n}\n",
"example_response": "{\n\t\"id\": 358,\n\t\"book_id\": 1,\n\t\"chapter_id\": 0,\n\t\"name\": \"My API Page\",\n\t\"slug\": \"my-api-page\",\n\t\"html\": \"\u003Cp id=\\\"bkmrk-my-new-api-page\\\"\u003Emy new API page\u003C/p\u003E\",\n\t\"raw_html\": \"\u003Cp id=\\\"bkmrk-my-new-api-page\\\"\u003Emy new API page\u003C/p\u003E\",\n\t\"priority\": 15,\n\t\"created_at\": \"2020-11-28T15:01:39.000000Z\",\n\t\"updated_at\": \"2020-11-28T15:01:39.000000Z\",\n\t\"created_by\": {\n\t\t\"id\": 1,\n\t\t\"name\": \"Admin\",\n\t\t\"slug\": \"admin\"\n\t},\n\t\"updated_by\": {\n\t\t\"id\": 1,\n\t\t\"name\": \"Admin\",\n\t\t\"slug\": \"admin\"\n\t},\n\t\"owned_by\": {\n\t\t\"id\": 1,\n\t\t\"name\": \"Admin\",\n\t\t\"slug\": \"admin\"\n\t},\n\t\"draft\": false,\n\t\"markdown\": \"\",\n\t\"revision_count\": 1,\n\t\"template\": false,\n\t\"editor\": \"wysiwyg\",\n\t\"tags\": [\n\t\t{\n\t\t\t\"name\": \"Category\",\n\t\t\t\"value\": \"Not Bad Content\",\n\t\t\t\"order\": 0\n\t\t},\n\t\t{\n\t\t\t\"name\": \"Rating\",\n\t\t\t\"value\": \"Average\",\n\t\t\t\"order\": 1\n\t\t}\n\t]\n}"
},
{
"name": "pages-read",
"uri": "api/pages/{id}",
"method": "GET",
"controller": "BookStack\\Entities\\Controllers\\PageApiController",
"controller_method": "read",
"controller_method_kebab": "read",
"base_model": "pages",
"description": "View the details of a single page. Pages will always have HTML content. They may have markdown content if the markdown editor was used to last update the page.\nThe 'html' property is the fully rendered & escaped HTML content that BookStack would show on page view, with page includes handled. The 'raw_html' property is the direct database stored HTML content, which would be what BookStack shows on page edit.\nSee the \"Content Security\" section of these docs for security considerations when using the page content returned from this endpoint.",
"body_params": null,
"example_request": null,
"example_response": "{\n\t\"id\": 306,\n\t\"book_id\": 1,\n\t\"chapter_id\": 0,\n\t\"name\": \"A page written in markdown\",\n\t\"slug\": \"a-page-written-in-markdown\",\n\t\"html\": \"\u003Ch1 id=\\\"bkmrk-this-is-my-cool-page\\\"\u003EThis is my cool page! With some included text\u003C/h1\u003E\",\n\t\"raw_html\": \"\u003Ch1 id=\\\"bkmrk-this-is-my-cool-page\\\"\u003EThis is my cool page! {{@1#bkmrk-a}}\u003C/h1\u003E\",\n\t\"priority\": 13,\n\t\"created_at\": \"2020-02-02T21:40:38.000000Z\",\n\t\"updated_at\": \"2020-11-28T14:43:20.000000Z\",\n\t\"created_by\": {\n\t\t\"id\": 1,\n\t\t\"name\": \"Admin\",\n\t\t\"slug\": \"admin\"\n\t},\n\t\"updated_by\": {\n\t\t\"id\": 1,\n\t\t\"name\": \"Admin\",\n\t\t\"slug\": \"admin\"\n\t},\n\t\"owned_by\": {\n\t\t\"id\": 1,\n\t\t\"name\": \"Admin\",\n\t\t\"slug\": \"admin\"\n\t},\n\t\"draft\": false,\n\t\"markdown\": \"# How this is built\\r\\n\\r\\nThis page is written in markdown. BookStack stores the page data in HTML.\\r\\n\\r\\nHere's a cute picture of my cat:\\r\\n\\r\\n[](http://example.com/uploads/images/gallery/2020-04/yXSrubes.jpg)\",\n\t\"revision_count\": 5,\n\t\"template\": false,\n\t\"editor\": \"wysiwyg\",\n\t\"tags\": [\n\t\t{\n\t\t\t\"name\": \"Category\",\n\t\t\t\"value\": \"Top Content\",\n\t\t\t\"order\": 0\n\t\t},\n\t\t{\n\t\t\t\"name\": \"Animal\",\n\t\t\t\"value\": \"Cat\",\n\t\t\t\"order\": 1\n\t\t}\n\t]\n}"
},
{
"name": "pages-update",
"uri": "api/pages/{id}",
"method": "PUT",
"controller": "BookStack\\Entities\\Controllers\\PageApiController",
"controller_method": "update",
"controller_method_kebab": "update",
"base_model": "pages",
"description": "Update the details of a single page.\nSee the 'create' action for details on the provided HTML/Markdown. Providing a 'book_id' or 'chapter_id' property will essentially move the page into that parent element if you have permissions to do so.",
"body_params": {
"book_id": ["integer"],
"chapter_id": ["integer"],
"name": ["string", "min:1", "max:255"],
"html": ["string"],
"markdown": ["string"],
"tags": ["array"],
"priority": ["integer"]
},
"example_request": "{\n\t\"chapter_id\": 1,\n\t\"name\": \"My updated API Page\",\n\t\"html\": \"\u003Cp\u003Emy new API page - Updated\u003C/p\u003E\",\n\t\"priority\": 16,\n\t\"tags\": [\n\t\t{\"name\": \"Category\", \"value\": \"API Examples\"},\n\t\t{\"name\": \"Rating\", \"value\": \"Alright\"}\n\t]\n}\n",
"example_response": "{\n\t\"id\": 361,\n\t\"book_id\": 1,\n\t\"chapter_id\": 1,\n\t\"name\": \"My updated API Page\",\n\t\"slug\": \"my-updated-api-page\",\n\t\"html\": \"\u003Cp id=\\\"bkmrk-my-new-api-page---up\\\"\u003Emy new API page - Updated\u003C/p\u003E\",\n\t\"raw_html\": \"\u003Cp id=\\\"bkmrk-my-new-api-page---up\\\"\u003Emy new API page - Updated\u003C/p\u003E\",\n\t\"priority\": 16,\n\t\"created_at\": \"2020-11-28T15:10:54.000000Z\",\n\t\"updated_at\": \"2020-11-28T15:13:03.000000Z\",\n\t\"created_by\": {\n\t\t\"id\": 1,\n\t\t\"name\": \"Admin\",\n\t\t\"slug\": \"admin\"\n\t},\n\t\"updated_by\": {\n\t\t\"id\": 1,\n\t\t\"name\": \"Admin\",\n\t\t\"slug\": \"admin\"\n\t},\n\t\"owned_by\": {\n\t\t\"id\": 1,\n\t\t\"name\": \"Admin\",\n\t\t\"slug\": \"admin\"\n\t},\n\t\"draft\": false,\n\t\"markdown\": \"\",\n\t\"revision_count\": 5,\n\t\"template\": false,\n\t\"editor\": \"wysiwyg\",\n\t\"tags\": [\n\t\t{\n\t\t\t\"name\": \"Category\",\n\t\t\t\"value\": \"API Examples\",\n\t\t\t\"order\": 0\n\t\t},\n\t\t{\n\t\t\t\"name\": \"Rating\",\n\t\t\t\"value\": \"Alright\",\n\t\t\t\"order\": 0\n\t\t}\n\t]\n}"
},
{
"name": "pages-delete",
"uri": "api/pages/{id}",
"method": "DELETE",
"controller": "BookStack\\Entities\\Controllers\\PageApiController",
"controller_method": "delete",
"controller_method_kebab": "delete",
"base_model": "pages",
"description": "Delete a page. This will typically send the page to the recycle bin.",
"body_params": null,
"example_request": null,
"example_response": null
},
{
"name": "pages-exportHtml",
"uri": "api/pages/{id}/export/html",
"method": "GET",
"controller": "BookStack\\Exports\\Controllers\\PageExportApiController",
"controller_method": "exportHtml",
"controller_method_kebab": "export-html",
"base_model": "pages",
"description": "Export a page as a contained HTML file. ",
"body_params": null,
"example_request": null,
"example_response": null
},
{
"name": "pages-exportPdf",
"uri": "api/pages/{id}/export/pdf",
"method": "GET",
"controller": "BookStack\\Exports\\Controllers\\PageExportApiController",
"controller_method": "exportPdf",
"controller_method_kebab": "export-pdf",
"base_model": "pages",
"description": "Export a page as a PDF file. ",
"body_params": null,
"example_request": null,
"example_response": null
},
{
"name": "pages-exportPlainText",
"uri": "api/pages/{id}/export/plaintext",
"method": "GET",
"controller": "BookStack\\Exports\\Controllers\\PageExportApiController",
"controller_method": "exportPlainText",
"controller_method_kebab": "export-plain-text",
"base_model": "pages",
"description": "Export a page as a plain text file.",
"body_params": null,
"example_request": null,
"example_response": null
},
{
"name": "pages-exportMarkdown",
"uri": "api/pages/{id}/export/markdown",
"method": "GET",
"controller": "BookStack\\Exports\\Controllers\\PageExportApiController",
"controller_method": "exportMarkdown",
"controller_method_kebab": "export-markdown",
"base_model": "pages",
"description": "Export a page as a markdown file.",
"body_params": null,
"example_request": null,
"example_response": null
}
],
"image-gallery": [
{
"name": "image-gallery-list",
"uri": "api/image-gallery",
"method": "GET",
"controller": "BookStack\\Uploads\\Controllers\\ImageGalleryApiController",
"controller_method": "list",
"controller_method_kebab": "list",
"base_model": "image-gallery",
"description": "Get a listing of images in the system. Includes gallery (page content) images and drawings. Requires visibility of the page they're originally uploaded to.",
"body_params": null,
"example_request": null,
"example_response": "{\n \"data\": [\n {\n \"id\": 1,\n \"name\": \"My cat scribbles\",\n \"url\": \"https:\\/\\/bookstack.example.com\\/uploads\\/images\\/gallery\\/2023-02\\/scribbles.jpg\",\n \"path\": \"\\/uploads\\/images\\/gallery\\/2023-02\\/scribbles.jpg\",\n \"type\": \"gallery\",\n \"uploaded_to\": 1,\n \"created_by\": 1,\n \"updated_by\": 1,\n \"created_at\": \"2023-02-12T16:34:57.000000Z\",\n \"updated_at\": \"2023-02-12T16:34:57.000000Z\"\n },\n {\n \"id\": 2,\n \"name\": \"Drawing-1.png\",\n \"url\": \"https:\\/\\/bookstack.example.com\\/uploads\\/images\\/drawio\\/2023-02\\/drawing-1.png\",\n \"path\": \"\\/uploads\\/images\\/drawio\\/2023-02\\/drawing-1.png\",\n \"type\": \"drawio\",\n \"uploaded_to\": 2,\n \"created_by\": 2,\n \"updated_by\": 2,\n \"created_at\": \"2023-02-12T16:39:19.000000Z\",\n \"updated_at\": \"2023-02-12T16:39:19.000000Z\"\n },\n {\n \"id\": 8,\n \"name\": \"beans.jpg\",\n \"url\": \"https:\\/\\/bookstack.example.com\\/uploads\\/images\\/gallery\\/2023-02\\/beans.jpg\",\n \"path\": \"\\/uploads\\/images\\/gallery\\/2023-02\\/beans.jpg\",\n \"type\": \"gallery\",\n \"uploaded_to\": 6,\n \"created_by\": 1,\n \"updated_by\": 1,\n \"created_at\": \"2023-02-15T19:37:44.000000Z\",\n \"updated_at\": \"2023-02-15T19:37:44.000000Z\"\n }\n ],\n \"total\": 3\n}"
},
{
"name": "image-gallery-create",
"uri": "api/image-gallery",
"method": "POST",
"controller": "BookStack\\Uploads\\Controllers\\ImageGalleryApiController",
"controller_method": "create",
"controller_method_kebab": "create",
"base_model": "image-gallery",
"description": "Create a new image in the system.\nSince \"image\" is expected to be a file, this needs to be a 'multipart/form-data' type request. The provided \"uploaded_to\" should be an existing page ID in the system.\nIf the \"name\" parameter is omitted, the filename of the provided image file will be used instead. The \"type\" parameter should be 'gallery' for page content images, and 'drawio' should only be used when the file is a PNG file with diagrams.net image data embedded within.",
"body_params": {
"type": ["required", "string", "in:gallery,drawio"],
"uploaded_to": ["required", "integer"],
"image": [
"required",
"file",
"image_extension",
"mimes:jpeg,png,gif,webp",
"max:50000"
],
"name": ["string", "max:180"]
},
"example_request": null,
"example_response": "{\n \"name\": \"cute-cat-image.png\",\n \"path\": \"\\/uploads\\/images\\/gallery\\/2023-03\\/cute-cat-image.png\",\n \"url\": \"https:\\/\\/bookstack.example.com\\/uploads\\/images\\/gallery\\/2023-03\\/cute-cat-image.png\",\n \"type\": \"gallery\",\n \"uploaded_to\": 1,\n \"created_by\": {\n \"id\": 1,\n \"name\": \"Admin\",\n \"slug\": \"admin\"\n },\n \"updated_by\": {\n \"id\": 1,\n \"name\": \"Admin\",\n \"slug\": \"admin\"\n },\n \"updated_at\": \"2023-03-15T16:32:09.000000Z\",\n \"created_at\": \"2023-03-15T16:32:09.000000Z\",\n \"id\": 618,\n \"thumbs\": {\n \"gallery\": \"https:\\/\\/bookstack.example.com\\/uploads\\/images\\/gallery\\/2023-03\\/thumbs-150-150\\/cute-cat-image.png\",\n \"display\": \"https:\\/\\/bookstack.example.com\\/uploads\\/images\\/gallery\\/2023-03\\/scaled-1680-\\/cute-cat-image.png\"\n },\n \"content\": {\n \"html\": \"\u003Ca href=\\\"https:\\/\\/bookstack.example.com\\/uploads\\/images\\/gallery\\/2023-03\\/cute-cat-image.png\\\" target=\\\"_blank\\\"\u003E\u003Cimg src=\\\"https:\\/\\/bookstack.example.com\\/uploads\\/images\\/gallery\\/2023-03\\/scaled-1680-\\/cute-cat-image.png\\\" alt=\\\"cute-cat-image.png\\\"\u003E\u003C\\/a\u003E\",\n \"markdown\": \"\"\n }\n}"
},
{
"name": "image-gallery-read",
"uri": "api/image-gallery/{id}",
"method": "GET",
"controller": "BookStack\\Uploads\\Controllers\\ImageGalleryApiController",
"controller_method": "read",
"controller_method_kebab": "read",
"base_model": "image-gallery",
"description": "View the details of a single image. The \"thumbs\" response property contains links to scaled variants that BookStack may use in its UI. The \"content\" response property provides HTML and Markdown content, in the format that BookStack would typically use by default to add the image in page content, as a convenience. Actual image file data is not provided but can be fetched via the \"url\" response property.",
"body_params": null,
"example_request": null,
"example_response": "{\n \"id\": 618,\n \"name\": \"cute-cat-image.png\",\n \"url\": \"https:\\/\\/bookstack.example.com\\/uploads\\/images\\/gallery\\/2023-03\\/cute-cat-image.png\",\n \"created_at\": \"2023-03-15T16:32:09.000000Z\",\n \"updated_at\": \"2023-03-15T16:32:09.000000Z\",\n \"created_by\": {\n \"id\": 1,\n \"name\": \"Admin\",\n \"slug\": \"admin\"\n },\n \"updated_by\": {\n \"id\": 1,\n \"name\": \"Admin\",\n \"slug\": \"admin\"\n },\n \"path\": \"\\/uploads\\/images\\/gallery\\/2023-03\\/cute-cat-image.png\",\n \"type\": \"gallery\",\n \"uploaded_to\": 1,\n \"thumbs\": {\n \"gallery\": \"https:\\/\\/bookstack.example.com\\/uploads\\/images\\/gallery\\/2023-03\\/thumbs-150-150\\/cute-cat-image.png\",\n \"display\": \"https:\\/\\/bookstack.example.com\\/uploads\\/images\\/gallery\\/2023-03\\/scaled-1680-\\/cute-cat-image.png\"\n },\n \"content\": {\n \"html\": \"\u003Ca href=\\\"https:\\/\\/bookstack.example.com\\/uploads\\/images\\/gallery\\/2023-03\\/cute-cat-image.png\\\" target=\\\"_blank\\\"\u003E\u003Cimg src=\\\"https:\\/\\/bookstack.example.com\\/uploads\\/images\\/gallery\\/2023-03\\/scaled-1680-\\/cute-cat-image.png\\\" alt=\\\"cute-cat-image.png\\\"\u003E\u003C\\/a\u003E\",\n \"markdown\": \"\"\n }\n}"
},
{
"name": "image-gallery-update",
"uri": "api/image-gallery/{id}",
"method": "PUT",
"controller": "BookStack\\Uploads\\Controllers\\ImageGalleryApiController",
"controller_method": "update",
"controller_method_kebab": "update",
"base_model": "image-gallery",
"description": "Update the details of an existing image in the system. Since \"image\" is expected to be a file, this needs to be a 'multipart/form-data' type request if providing a new image file. Updated image files should be of the same file type as the original image.",
"body_params": {
"name": ["string", "max:180"],
"image": [
"file",
"image_extension",
"mimes:jpeg,png,gif,webp",
"max:50000"
]
},
"example_request": "{\n \"name\": \"My updated image name\"\n}",
"example_response": "{\n \"id\": 618,\n \"name\": \"My updated image name\",\n \"url\": \"https:\\/\\/bookstack.example.com\\/uploads\\/images\\/gallery\\/2023-03\\/cute-cat-image.png\",\n \"created_at\": \"2023-03-15T16:32:09.000000Z\",\n \"updated_at\": \"2023-03-15T18:31:14.000000Z\",\n \"created_by\": {\n \"id\": 1,\n \"name\": \"Admin\",\n \"slug\": \"admin\"\n },\n \"updated_by\": {\n \"id\": 1,\n \"name\": \"Admin\",\n \"slug\": \"admin\"\n },\n \"path\": \"\\/uploads\\/images\\/gallery\\/2023-03\\/cute-cat-image.png\",\n \"type\": \"gallery\",\n \"uploaded_to\": 1,\n \"thumbs\": {\n \"gallery\": \"https:\\/\\/bookstack.example.com\\/uploads\\/images\\/gallery\\/2023-03\\/thumbs-150-150\\/cute-cat-image.png\",\n \"display\": \"https:\\/\\/bookstack.example.com\\/uploads\\/images\\/gallery\\/2023-03\\/scaled-1680-\\/cute-cat-image.png\"\n },\n \"content\": {\n \"html\": \"\u003Ca href=\\\"https:\\/\\/bookstack.example.com\\/uploads\\/images\\/gallery\\/2023-03\\/cute-cat-image.png\\\" target=\\\"_blank\\\"\u003E\u003Cimg src=\\\"https:\\/\\/bookstack.example.com\\/uploads\\/images\\/gallery\\/2023-03\\/scaled-1680-\\/cute-cat-image.png\\\" alt=\\\"My updated image name\\\"\u003E\u003C\\/a\u003E\",\n \"markdown\": \"\"\n }\n}"
},
{
"name": "image-gallery-delete",
"uri": "api/image-gallery/{id}",
"method": "DELETE",
"controller": "BookStack\\Uploads\\Controllers\\ImageGalleryApiController",
"controller_method": "delete",
"controller_method_kebab": "delete",
"base_model": "image-gallery",
"description": "Delete an image from the system. Will also delete thumbnails for the image. Does not check or handle image usage so this could leave pages with broken image references.",
"body_params": null,
"example_request": null,
"example_response": null
}
],
"search": [
{
"name": "search-all",
"uri": "api/search",
"method": "GET",
"controller": "BookStack\\Search\\SearchApiController",
"controller_method": "all",
"controller_method_kebab": "all",
"base_model": "search",
"description": "Run a search query against all main content types (shelves, books, chapters & pages) in the system. Takes the same input as the main search bar within the BookStack interface as a 'query' parameter. See https://www.bookstackapp.com/docs/user/searching/ for a full list of search term options. Results contain a 'type' property to distinguish between: bookshelf, book, chapter & page.\nThe paging parameters and response format emulates a standard listing endpoint but standard sorting and filtering cannot be done on this endpoint. If a count value is provided this will only be taken as a suggestion. The results in the response may currently be up to 4x this value.",
"body_params": {
"query": ["required"],
"page": ["integer", "min:1"],
"count": ["integer", "min:1", "max:100"]
},
"example_request": "GET /api/search?query=cats+{created_by:me}&page=1&count=2\n",
"example_response": "{\n \"data\": [\n {\n \"id\": 84,\n \"book_id\": 1,\n \"slug\": \"a-chapter-for-cats\",\n \"name\": \"A chapter for cats\",\n \"created_at\": \"2021-11-14T15:57:35.000000Z\",\n \"updated_at\": \"2021-11-14T15:57:35.000000Z\",\n \"type\": \"chapter\",\n \"url\": \"https://example.com/books/cats/chapter/a-chapter-for-cats\",\n \"book\": {\n \"id\": 1,\n \"name\": \"Cats\",\n \"slug\": \"cats\"\n },\n \"preview_html\": {\n \"name\": \"A chapter for \u003Cstrong\u003Ecats\u003C/strong\u003E\",\n \"content\": \"...once a bunch of \u003Cstrong\u003Ecats\u003C/strong\u003E named tony...behaviour of \u003Cstrong\u003Ecats\u003C/strong\u003E is unsuitable\"\n },\n \"tags\": []\n },\n {\n \"name\": \"The hows and whys of cats\",\n \"id\": 396,\n \"slug\": \"the-hows-and-whys-of-cats\",\n \"book_id\": 1,\n \"chapter_id\": 75,\n \"draft\": false,\n \"template\": false,\n \"created_at\": \"2021-05-15T16:28:10.000000Z\",\n \"updated_at\": \"2021-11-14T15:56:49.000000Z\",\n \"type\": \"page\",\n \"url\": \"https://example.com/books/cats/page/the-hows-and-whys-of-cats\",\n \"book\": {\n \"id\": 1,\n \"name\": \"Cats\",\n \"slug\": \"cats\"\n },\n \"chapter\": {\n \"id\": 75,\n \"name\": \"A chapter for cats\",\n \"slug\": \"a-chapter-for-cats\"\n },\n \"preview_html\": {\n \"name\": \"The hows and whys of \u003Cstrong\u003Ecats\u003C/strong\u003E\",\n \"content\": \"...people ask why \u003Cstrong\u003Ecats\u003C/strong\u003E? but there are...the reason that \u003Cstrong\u003Ecats\u003C/strong\u003E are fast are due to...\"\n },\n \"tags\": [\n {\n \"name\": \"Animal\",\n \"value\": \"Cat\",\n \"order\": 0\n },\n {\n \"name\": \"Category\",\n \"value\": \"Top Content\",\n \"order\": 0\n }\n ]\n },\n {\n \"name\": \"How advanced are cats?\",\n \"id\": 362,\n \"slug\": \"how-advanced-are-cats\",\n \"book_id\": 13,\n \"chapter_id\": 73,\n \"draft\": false,\n \"template\": false,\n \"created_at\": \"2020-11-29T21:55:07.000000Z\",\n \"updated_at\": \"2021-11-14T16:02:39.000000Z\",\n \"type\": \"page\",\n \"url\": \"https://example.com/books/big-cats/page/how-advanced-are-cats\",\n \"book\": {\n \"id\": 13,\n \"name\": \"Big Cats\",\n \"slug\": \"big-cats\"\n },\n \"chapter\": {\n \"id\": 73,\n \"name\": \"A chapter for bigger cats\",\n \"slug\": \"a-chapter-for-bigger-cats\"\n },\n \"preview_html\": {\n \"name\": \"How advanced are \u003Cstrong\u003Ecats\u003C/strong\u003E?\",\n \"content\": \"\u003Cstrong\u003Ecats\u003C/strong\u003E are some of the most advanced animals in the world.\"\n },\n \"tags\": []\n }\n ],\n \"total\": 3\n}\n"
}
],
"shelves": [
{
"name": "shelves-list",
"uri": "api/shelves",
"method": "GET",
"controller": "BookStack\\Entities\\Controllers\\BookshelfApiController",
"controller_method": "list",
"controller_method_kebab": "list",
"base_model": "shelves",
"description": "Get a listing of shelves visible to the user.",
"body_params": null,
"example_request": null,
"example_response": "{\n \"data\": [\n {\n \"id\": 8,\n \"name\": \"Qui qui aspernatur autem molestiae libero necessitatibus molestias.\",\n \"slug\": \"qui-qui-aspernatur-autem-molestiae-libero-necessitatibus-molestias\",\n \"description\": \"Enim dolor ut quia error dolores est. Aut distinctio consequuntur non nisi nostrum. Labore cupiditate error labore aliquid provident impedit voluptatibus. Quaerat impedit excepturi eius qui eius voluptatem reiciendis.\",\n \"created_at\": \"2019-05-05T22:10:16.000000Z\",\n \"updated_at\": \"2020-04-10T13:00:45.000000Z\",\n \"created_by\": 4,\n \"updated_by\": 1,\n \"owned_by\": 1,\n \"cover\": {\n \"id\": 4,\n \"name\": \"shelf.jpg\",\n \"url\": \"https://example.com/uploads/images/cover_bookshelf/2024-12/shelf.jpg\"\n }\n },\n {\n \"id\": 9,\n \"name\": \"Ipsum aut inventore fuga libero non facilis.\",\n \"slug\": \"ipsum-aut-inventore-fuga-libero-non-facilis\",\n \"description\": \"Labore culpa modi perspiciatis harum sit. Maxime non et nam est. Quae ut laboriosam repellendus sunt quisquam. Velit at est perspiciatis nesciunt adipisci nobis illo. Sed possimus odit optio officiis nisi voluptates officiis dolor.\",\n \"created_at\": \"2019-05-05T22:10:16.000000Z\",\n \"updated_at\": \"2020-04-10T13:00:58.000000Z\",\n \"created_by\": 4,\n \"updated_by\": 1,\n \"owned_by\": 1,\n \"cover\": null\n },\n {\n \"id\": 10,\n \"name\": \"Omnis reiciendis aut molestias sint accusantium.\",\n \"slug\": \"omnis-reiciendis-aut-molestias-sint-accusantium\",\n \"description\": \"Qui ea occaecati alias est dolores voluptatem doloribus. Ad reiciendis corporis vero nostrum omnis et. Non doloribus ut eaque ut quos dolores.\",\n \"created_at\": \"2019-05-05T22:10:16.000000Z\",\n \"updated_at\": \"2020-04-10T13:00:53.000000Z\",\n \"created_by\": 4,\n \"updated_by\": 1,\n \"owned_by\": 4,\n \"cover\": null\n }\n ],\n \"total\": 3\n}"
},
{
"name": "shelves-create",
"uri": "api/shelves",
"method": "POST",
"controller": "BookStack\\Entities\\Controllers\\BookshelfApiController",
"controller_method": "create",
"controller_method_kebab": "create",
"base_model": "shelves",
"description": "Create a new shelf in the system. An array of books IDs can be provided in the request. These will be added to the shelf in the same order as provided. The cover image of a shelf can be set by sending a file via an 'image' property within a 'multipart/form-data' request. If the 'image' property is null then the shelf cover image will be removed. ",
"body_params": {
"name": ["required", "string", "max:255"],
"description": ["string", "max:1900"],
"description_html": ["string", "max:2000"],
"books": ["array"],
"tags": ["array"],
"image": [
"nullable",
"image_extension",
"mimes:jpeg,png,gif,webp",
"max:50000"
]
},
"example_request": "{\n \"name\": \"My shelf\",\n \"description_html\": \"\u003Cp\u003EThis is \u003Cstrong\u003Emy shelf\u003C/strong\u003E with some books\u003C/p\u003E\",\n \"books\": [5,1,3],\n \"tags\": [\n {\"name\": \"Category\", \"value\": \"Learning\"}\n ]\n}",
"example_response": "{\n \"id\": 20,\n \"name\": \"My shelf\",\n \"slug\": \"my-shelf\",\n \"description\": \"This is my shelf with some books\",\n \"created_by\": 1,\n \"updated_by\": 1,\n \"created_at\": \"2023-12-22T14:33:52.000000Z\",\n \"updated_at\": \"2023-12-22T14:33:52.000000Z\",\n \"owned_by\": 1,\n \"description_html\": \"\u003Cp\u003EThis is \u003Cstrong\u003Emy shelf\u003C\\/strong\u003E with some books\u003C\\/p\u003E\",\n \"tags\": [\n {\n \"name\": \"Category\",\n \"value\": \"Learning\",\n \"order\": 0\n }\n ],\n \"cover\": null\n}"
},
{
"name": "shelves-read",
"uri": "api/shelves/{id}",
"method": "GET",
"controller": "BookStack\\Entities\\Controllers\\BookshelfApiController",
"controller_method": "read",
"controller_method_kebab": "read",
"base_model": "shelves",
"description": "View the details of a single shelf.",
"body_params": null,
"example_request": null,
"example_response": "{\n \"id\": 14,\n \"name\": \"My shelf\",\n \"slug\": \"my-shelf\",\n \"description\": \"This is my shelf with some books\",\n \"description_html\": \"\u003Cp\u003EThis is my shelf with some books\u003C/p\u003E\",\n \"created_by\": {\n \"id\": 1,\n \"name\": \"Admin\",\n \"slug\": \"admin\"\n },\n \"updated_by\": {\n \"id\": 1,\n \"name\": \"Admin\",\n \"slug\": \"admin\"\n },\n \"owned_by\": {\n \"id\": 1,\n \"name\": \"Admin\",\n \"slug\": \"admin\"\n },\n \"created_at\": \"2020-04-10T13:24:09.000000Z\",\n \"updated_at\": \"2020-04-10T13:31:04.000000Z\",\n \"tags\": [\n {\n \"name\": \"Category\",\n \"value\": \"Guide\",\n \"order\": 0\n }\n ],\n \"cover\": {\n \"id\": 501,\n \"name\": \"anafrancisconi_Sp04AfFCPNM.jpg\",\n \"url\": \"http://bookstack.local/uploads/images/cover_book/2020-04/anafrancisconi_Sp04AfFCPNM.jpg\",\n \"created_at\": \"2020-04-10T13:31:04.000000Z\",\n \"updated_at\": \"2020-04-10T13:31:04.000000Z\",\n \"created_by\": 1,\n \"updated_by\": 1,\n \"path\": \"/uploads/images/cover_book/2020-04/anafrancisconi_Sp04AfFCPNM.jpg\",\n \"type\": \"cover_book\",\n \"uploaded_to\": 14\n },\n \"books\": [\n {\n \"id\": 5,\n \"name\": \"Sint explicabo alias sunt.\",\n \"slug\": \"jbsQrzuaXe\",\n \"description\": \"Hic forum est.\",\n \"created_at\": \"2020-04-10T13:31:04.000000Z\",\n \"updated_at\": \"2020-04-10T13:31:04.000000Z\",\n \"created_by\": 1,\n \"updated_by\": 1,\n \"owned_by\": 1\n },\n {\n \"id\": 1,\n \"name\": \"BookStack User Guide\",\n \"slug\": \"bookstack-user-guide\",\n \"description\": \"The Bookstack User Guide Book.\",\n \"created_at\": \"2020-04-10T15:30:32.000000Z\",\n \"updated_at\": \"2020-04-13T09:01:04.000000Z\",\n \"created_by\": 1,\n \"updated_by\": 2,\n \"owned_by\": 1\n },\n {\n \"id\": 3,\n \"name\": \"Molestiae doloribus sint velit suscipit dolorem.\",\n \"slug\": \"H99QxALaoG\",\n \"description\": \"Lorem ipsum dolor sit amet, consectetur adipiscing elit.\",\n \"created_at\": \"2020-04-10T13:31:04.000000Z\",\n \"updated_at\": \"2020-04-10T13:31:04.000000Z\",\n \"created_by\": 1,\n \"updated_by\": 1,\n \"owned_by\": 1\n }\n ]\n}"
},
{
"name": "shelves-update",
"uri": "api/shelves/{id}",
"method": "PUT",
"controller": "BookStack\\Entities\\Controllers\\BookshelfApiController",
"controller_method": "update",
"controller_method_kebab": "update",
"base_model": "shelves",
"description": "Update the details of a single shelf. An array of books IDs can be provided in the request. These will be added to the shelf in the same order as provided and overwrite any existing book assignments. The cover image of a shelf can be set by sending a file via an 'image' property within a 'multipart/form-data' request. If the 'image' property is null then the shelf cover image will be removed. ",
"body_params": {
"name": ["string", "min:1", "max:255"],
"description": ["string", "max:1900"],
"description_html": ["string", "max:2000"],
"books": ["array"],
"tags": ["array"],
"image": [
"nullable",
"image_extension",
"mimes:jpeg,png,gif,webp",
"max:50000"
]
},
"example_request": "{\n \"name\": \"My updated shelf\",\n \"description_html\": \"\u003Cp\u003EThis is my \u003Cem\u003Eupdated shelf\u003C/em\u003E with some books\u003C/p\u003E\",\n \"books\": [5,1,3]\n}",
"example_response": "{\n \"id\": 20,\n \"name\": \"My updated shelf\",\n \"slug\": \"my-updated-shelf\",\n \"description\": \"This is my updated shelf with some books\",\n \"created_by\": 1,\n \"updated_by\": 1,\n \"created_at\": \"2023-12-22T14:33:52.000000Z\",\n \"updated_at\": \"2023-12-22T14:35:00.000000Z\",\n \"owned_by\": 1,\n \"description_html\": \"\u003Cp\u003EThis is my \u003Cem\u003Eupdated shelf\u003C\\/em\u003E with some books\u003C\\/p\u003E\",\n \"tags\": [\n {\n \"name\": \"Category\",\n \"value\": \"Learning\",\n \"order\": 0\n }\n ],\n \"cover\": null\n}"
},
{
"name": "shelves-delete",
"uri": "api/shelves/{id}",
"method": "DELETE",
"controller": "BookStack\\Entities\\Controllers\\BookshelfApiController",
"controller_method": "delete",
"controller_method_kebab": "delete",
"base_model": "shelves",
"description": "Delete a single shelf. This will typically send the shelf to the recycle bin. ",
"body_params": null,
"example_request": null,
"example_response": null
}
],
"users": [
{
"name": "users-list",
"uri": "api/users",
"method": "GET",
"controller": "BookStack\\Users\\Controllers\\UserApiController",
"controller_method": "list",
"controller_method_kebab": "list",
"base_model": "users",
"description": "Get a listing of users in the system. Requires permission to manage users.",
"body_params": null,
"example_request": null,
"example_response": "{\n \"data\": [\n {\n \"id\": 1,\n \"name\": \"Dan Brown\",\n \"email\": \"dannyb@example.com\",\n \"created_at\": \"2022-02-03T16:27:55.000000Z\",\n \"updated_at\": \"2022-02-03T16:27:55.000000Z\",\n \"external_auth_id\": \"abc123456\",\n \"slug\": \"dan-brown\",\n \"last_activity_at\": \"2022-02-03T16:27:55.000000Z\",\n \"profile_url\": \"https://docs.example.com/user/dan-brown\",\n \"edit_url\": \"https://docs.example.com/settings/users/1\",\n \"avatar_url\": \"https://docs.example.com/uploads/images/user/2021-10/thumbs-50-50/profile-2021.jpg\"\n },\n {\n \"id\": 2,\n \"name\": \"Benny\",\n \"email\": \"benny@example.com\",\n \"created_at\": \"2020-01-15T04:43:11.000000Z\",\n \"updated_at\": \"2021-11-18T17:10:58.000000Z\",\n \"external_auth_id\": \"\",\n \"slug\": \"benny\",\n \"last_activity_at\": \"2022-01-31T20:39:24.000000Z\",\n \"profile_url\": \"https://docs.example.com/user/benny\",\n \"edit_url\": \"https://docs.example.com/settings/users/2\",\n \"avatar_url\": \"https://docs.example.com/uploads/images/user/2021-11/thumbs-50-50/guest.jpg\"\n }\n ],\n \"total\": 28\n}"
},
{
"name": "users-create",
"uri": "api/users",
"method": "POST",
"controller": "BookStack\\Users\\Controllers\\UserApiController",
"controller_method": "create",
"controller_method_kebab": "create",
"base_model": "users",
"description": "Create a new user in the system. Requires permission to manage users.",
"body_params": {
"name": ["required", "string", "min:1", "max:100"],
"email": [
"required",
"string",
"email",
"min:2",
"unique:users,email,NULL,id"
],
"external_auth_id": ["string"],
"language": ["string", "max:15", "alpha_dash"],
"password": ["string", "min:8"],
"roles": ["array"],
"roles.*": ["integer"],
"send_invite": ["boolean"]
},
"example_request": "{\n \"name\": \"Dan Brown\",\n \"email\": \"dannyb@example.com\",\n \"roles\": [1],\n \"language\": \"fr\",\n \"send_invite\": true\n}",
"example_response": "{\n \"id\": 1,\n \"name\": \"Dan Brown\",\n \"email\": \"dannyb@example.com\",\n \"created_at\": \"2022-02-03T16:27:55.000000Z\",\n \"updated_at\": \"2022-02-03T16:27:55.000000Z\",\n \"external_auth_id\": \"abc123456\",\n \"slug\": \"dan-brown\",\n \"last_activity_at\": \"2022-02-03T16:27:55.000000Z\",\n \"profile_url\": \"https://docs.example.com/user/dan-brown\",\n \"edit_url\": \"https://docs.example.com/settings/users/1\",\n \"avatar_url\": \"https://docs.example.com/uploads/images/user/2021-10/thumbs-50-50/profile-2021.jpg\",\n \"roles\": [\n {\n \"id\": 1,\n \"display_name\": \"Admin\"\n }\n ]\n}"
},
{
"name": "users-read",
"uri": "api/users/{id}",
"method": "GET",
"controller": "BookStack\\Users\\Controllers\\UserApiController",
"controller_method": "read",
"controller_method_kebab": "read",
"base_model": "users",
"description": "View the details of a single user. Requires permission to manage users.",
"body_params": null,
"example_request": null,
"example_response": "{\n \"id\": 1,\n \"name\": \"Dan Brown\",\n \"email\": \"dannyb@example.com\",\n \"created_at\": \"2022-02-03T16:27:55.000000Z\",\n \"updated_at\": \"2022-02-03T16:27:55.000000Z\",\n \"external_auth_id\": \"abc123456\",\n \"slug\": \"dan-brown\",\n \"last_activity_at\": \"2022-02-03T16:27:55.000000Z\",\n \"profile_url\": \"https://docs.example.com/user/dan-brown\",\n \"edit_url\": \"https://docs.example.com/settings/users/1\",\n \"avatar_url\": \"https://docs.example.com/uploads/images/user/2021-10/thumbs-50-50/profile-2021.jpg\",\n \"roles\": [\n {\n \"id\": 1,\n \"display_name\": \"Admin\"\n }\n ]\n}"
},
{
"name": "users-update",
"uri": "api/users/{id}",
"method": "PUT",
"controller": "BookStack\\Users\\Controllers\\UserApiController",
"controller_method": "update",
"controller_method_kebab": "update",
"base_model": "users",
"description": "Update an existing user in the system. Requires permission to manage users. ",
"body_params": {
"name": ["string", "min:1", "max:100"],
"email": ["string", "email", "min:2", "unique:users,email,NULL,id"],
"external_auth_id": ["string"],
"language": ["string", "max:15", "alpha_dash"],
"password": ["string", "min:8"],
"roles": ["array"],
"roles.*": ["integer"]
},
"example_request": "{\n \"name\": \"Dan Spaggleforth\",\n \"email\": \"dspaggles@example.com\",\n \"roles\": [2],\n \"language\": \"de\",\n \"password\": \"hunter2000\"\n}",
"example_response": "{\n \"id\": 1,\n \"name\": \"Dan Spaggleforth\",\n \"email\": \"dspaggles@example.com\",\n \"created_at\": \"2022-02-03T16:27:55.000000Z\",\n \"updated_at\": \"2022-02-03T16:27:55.000000Z\",\n \"external_auth_id\": \"abc123456\",\n \"slug\": \"dan-spaggleforth\",\n \"last_activity_at\": \"2022-02-03T16:27:55.000000Z\",\n \"profile_url\": \"https://docs.example.com/user/dan-spaggleforth\",\n \"edit_url\": \"https://docs.example.com/settings/users/1\",\n \"avatar_url\": \"https://docs.example.com/uploads/images/user/2021-10/thumbs-50-50/profile-2021.jpg\",\n \"roles\": [\n {\n \"id\": 2,\n \"display_name\": \"Editors\"\n }\n ]\n}"
},
{
"name": "users-delete",
"uri": "api/users/{id}",
"method": "DELETE",
"controller": "BookStack\\Users\\Controllers\\UserApiController",
"controller_method": "delete",
"controller_method_kebab": "delete",
"base_model": "users",
"description": "Delete a user from the system. Can optionally accept a user id via `migrate_ownership_id` to indicate who should be the new owner of their related content. Requires permission to manage users.",
"body_params": {
"migrate_ownership_id": ["integer", "exists:users,id"]
},
"example_request": "{\n \"migrate_ownership_id\": 5\n}",
"example_response": null
}
],
"roles": [
{
"name": "roles-list",
"uri": "api/roles",
"method": "GET",
"controller": "BookStack\\Users\\Controllers\\RoleApiController",
"controller_method": "list",
"controller_method_kebab": "list",
"base_model": "roles",
"description": "Get a listing of roles in the system. Requires permission to manage roles.",
"body_params": null,
"example_request": null,
"example_response": "{\n \"data\": [\n {\n \"id\": 1,\n \"display_name\": \"Admin\",\n \"description\": \"Administrator of the whole application\",\n \"created_at\": \"2021-09-29T16:29:19.000000Z\",\n \"updated_at\": \"2022-11-03T13:26:18.000000Z\",\n \"system_name\": \"admin\",\n \"external_auth_id\": \"wizards\",\n \"mfa_enforced\": true,\n \"users_count\": 11,\n \"permissions_count\": 54\n },\n {\n \"id\": 2,\n \"display_name\": \"Editor\",\n \"description\": \"User can edit Books, Chapters & Pages\",\n \"created_at\": \"2021-09-29T16:29:19.000000Z\",\n \"updated_at\": \"2022-12-01T02:32:57.000000Z\",\n \"system_name\": \"\",\n \"external_auth_id\": \"\",\n \"mfa_enforced\": false,\n \"users_count\": 17,\n \"permissions_count\": 49\n },\n {\n \"id\": 3,\n \"display_name\": \"Public\",\n \"description\": \"The role given to public visitors if allowed\",\n \"created_at\": \"2021-09-29T16:29:19.000000Z\",\n \"updated_at\": \"2022-09-02T12:32:12.000000Z\",\n \"system_name\": \"public\",\n \"external_auth_id\": \"\",\n \"mfa_enforced\": false,\n \"users_count\": 1,\n \"permissions_count\": 2\n }\n ],\n \"total\": 3\n}"
},
{
"name": "roles-create",
"uri": "api/roles",
"method": "POST",
"controller": "BookStack\\Users\\Controllers\\RoleApiController",
"controller_method": "create",
"controller_method_kebab": "create",
"base_model": "roles",
"description": "Create a new role in the system. Permissions should be provided as an array of permission name strings. Requires permission to manage roles.",
"body_params": {
"display_name": ["required", "string", "min:3", "max:180"],
"description": ["string", "max:180"],
"mfa_enforced": ["boolean"],
"external_auth_id": ["string", "max:180"],
"permissions": ["array"],
"permissions.*": ["string"]
},
"example_request": "{\n \"display_name\": \"Book Maintainer\",\n \"description\": \"People who maintain books\",\n \"mfa_enforced\": true,\n \"permissions\": [\n \"book-view-all\",\n \"book-update-all\",\n \"book-delete-all\",\n \"restrictions-manage-all\"\n ]\n}",
"example_response": "{\n \"display_name\": \"Book Maintainer\",\n \"description\": \"People who maintain books\",\n \"mfa_enforced\": true,\n \"updated_at\": \"2023-02-19T15:38:40.000000Z\",\n \"created_at\": \"2023-02-19T15:38:40.000000Z\",\n \"id\": 26,\n \"permissions\": [\n \"book-delete-all\",\n \"book-update-all\",\n \"book-view-all\",\n \"restrictions-manage-all\"\n ],\n \"users\": []\n}"
},
{
"name": "roles-read",
"uri": "api/roles/{id}",
"method": "GET",
"controller": "BookStack\\Users\\Controllers\\RoleApiController",
"controller_method": "read",
"controller_method_kebab": "read",
"base_model": "roles",
"description": "View the details of a single role. Provides the permissions and a high-level list of the users assigned. Requires permission to manage roles.",
"body_params": null,
"example_request": null,
"example_response": "{\n \"id\": 26,\n \"display_name\": \"Book Maintainer\",\n \"description\": \"People who maintain books\",\n \"created_at\": \"2023-02-19T15:38:40.000000Z\",\n \"updated_at\": \"2023-02-19T15:38:40.000000Z\",\n \"system_name\": \"\",\n \"external_auth_id\": \"\",\n \"mfa_enforced\": true,\n \"permissions\": [\n \"book-delete-all\",\n \"book-update-all\",\n \"book-view-all\",\n \"restrictions-manage-all\"\n ],\n \"users\": [\n {\n \"id\": 11,\n \"name\": \"Barry Scott\",\n \"slug\": \"barry-scott\"\n }\n ]\n}"
},
{
"name": "roles-update",
"uri": "api/roles/{id}",
"method": "PUT",
"controller": "BookStack\\Users\\Controllers\\RoleApiController",
"controller_method": "update",
"controller_method_kebab": "update",
"base_model": "roles",
"description": "Update an existing role in the system. Permissions should be provided as an array of permission name strings. An empty \"permissions\" array would clear granted permissions. In many cases, where permissions are changed, you'll want to fetch the existing permissions and then modify before providing in your update request. Requires permission to manage roles.",
"body_params": {
"display_name": ["string", "min:3", "max:180"],
"description": ["string", "max:180"],
"mfa_enforced": ["boolean"],
"external_auth_id": ["string", "max:180"],
"permissions": ["array"],
"permissions.*": ["string"]
},
"example_request": "{\n \"display_name\": \"Book & Shelf Maintainers\",\n \"description\": \"All those who maintain books & shelves\",\n \"mfa_enforced\": false,\n \"permissions\": [\n \"book-view-all\",\n \"book-update-all\",\n \"book-delete-all\",\n \"bookshelf-view-all\",\n \"bookshelf-update-all\",\n \"bookshelf-delete-all\",\n \"restrictions-manage-all\"\n ]\n}",
"example_response": "{\n \"id\": 26,\n \"display_name\": \"Book & Shelf Maintainers\",\n \"description\": \"All those who maintain books & shelves\",\n \"created_at\": \"2023-02-19T15:38:40.000000Z\",\n \"updated_at\": \"2023-02-19T15:49:13.000000Z\",\n \"system_name\": \"\",\n \"external_auth_id\": \"\",\n \"mfa_enforced\": false,\n \"permissions\": [\n \"book-delete-all\",\n \"book-update-all\",\n \"book-view-all\",\n \"bookshelf-delete-all\",\n \"bookshelf-update-all\",\n \"bookshelf-view-all\",\n \"restrictions-manage-all\"\n ],\n \"users\": [\n {\n \"id\": 11,\n \"name\": \"Barry Scott\",\n \"slug\": \"barry-scott\"\n }\n ]\n}"
},
{
"name": "roles-delete",
"uri": "api/roles/{id}",
"method": "DELETE",
"controller": "BookStack\\Users\\Controllers\\RoleApiController",
"controller_method": "delete",
"controller_method_kebab": "delete",
"base_model": "roles",
"description": "Delete a role from the system. Requires permission to manage roles.",
"body_params": null,
"example_request": null,
"example_response": null
}
],
"recycle-bin": [
{
"name": "recycle-bin-list",
"uri": "api/recycle-bin",
"method": "GET",
"controller": "BookStack\\Entities\\Controllers\\RecycleBinApiController",
"controller_method": "list",
"controller_method_kebab": "list",
"base_model": "recycle-bin",
"description": "Get a top-level listing of the items in the recycle bin. The \"deletable\" property will reflect the main item deleted. For books and chapters, counts of child pages/chapters will be loaded within this \"deletable\" data. For chapters & pages, the parent item will be loaded within this \"deletable\" data. Requires permission to manage both system settings and permissions.",
"body_params": null,
"example_request": null,
"example_response": "{\n \"data\": [\n {\n \"id\": 18,\n \"deleted_by\": 1,\n \"created_at\": \"2022-04-20T12:57:46.000000Z\",\n \"updated_at\": \"2022-04-20T12:57:46.000000Z\",\n \"deletable_type\": \"page\",\n \"deletable_id\": 2582,\n \"deletable\": {\n \"id\": 2582,\n \"book_id\": 25,\n \"chapter_id\": 0,\n \"name\": \"A Wonderful Page\",\n \"slug\": \"a-wonderful-page\",\n \"priority\": 9,\n \"created_at\": \"2022-02-08T00:44:45.000000Z\",\n \"updated_at\": \"2022-04-20T12:57:46.000000Z\",\n \"created_by\": 1,\n \"updated_by\": 1,\n \"draft\": false,\n \"revision_count\": 1,\n \"template\": false,\n \"owned_by\": 1,\n \"editor\": \"wysiwyg\",\n \"book_slug\": \"a-great-book\",\n \"parent\": {\n \"id\": 25,\n \"name\": \"A Great Book\",\n \"slug\": \"a-great-book\",\n \"description\": \"\",\n \"created_at\": \"2022-01-24T16:14:28.000000Z\",\n \"updated_at\": \"2022-03-06T15:14:50.000000Z\",\n \"created_by\": 1,\n \"updated_by\": 1,\n \"owned_by\": 1,\n \"type\": \"book\"\n }\n }\n },\n {\n \"id\": 19,\n \"deleted_by\": 1,\n \"created_at\": \"2022-04-25T16:07:46.000000Z\",\n \"updated_at\": \"2022-04-25T16:07:46.000000Z\",\n \"deletable_type\": \"book\",\n \"deletable_id\": 13,\n \"deletable\": {\n \"id\": 13,\n \"name\": \"A Big Book!\",\n \"slug\": \"a-big-book\",\n \"description\": \"This is a very large book with loads of cool stuff in it!\",\n \"created_at\": \"2021-11-08T11:26:43.000000Z\",\n \"updated_at\": \"2022-04-25T16:07:47.000000Z\",\n \"created_by\": 27,\n \"updated_by\": 1,\n \"owned_by\": 1,\n \"pages_count\": 208,\n \"chapters_count\": 50\n }\n }\n ],\n \"total\": 2\n}"
},
{
"name": "recycle-bin-restore",
"uri": "api/recycle-bin/{deletionId}",
"method": "PUT",
"controller": "BookStack\\Entities\\Controllers\\RecycleBinApiController",
"controller_method": "restore",
"controller_method_kebab": "restore",
"base_model": "recycle-bin",
"description": "Restore a single deletion from the recycle bin. Requires permission to manage both system settings and permissions.",
"body_params": null,
"example_request": null,
"example_response": "{\n \"restore_count\": 2\n}"
},
{
"name": "recycle-bin-destroy",
"uri": "api/recycle-bin/{deletionId}",
"method": "DELETE",
"controller": "BookStack\\Entities\\Controllers\\RecycleBinApiController",
"controller_method": "destroy",
"controller_method_kebab": "destroy",
"base_model": "recycle-bin",
"description": "Remove a single deletion from the recycle bin. Use this endpoint carefully as it will entirely remove the underlying deleted items from the system. Requires permission to manage both system settings and permissions.",
"body_params": null,
"example_request": null,
"example_response": "{\n \"delete_count\": 2\n}"
}
],
"content-permissions": [
{
"name": "content-permissions-read",
"uri": "api/content-permissions/{contentType}/{contentId}",
"method": "GET",
"controller": "BookStack\\Permissions\\ContentPermissionApiController",
"controller_method": "read",
"controller_method_kebab": "read",
"base_model": "content-permissions",
"description": "Read the configured content-level permissions for the item of the given type and ID.\n'contentType' should be one of: page, book, chapter, bookshelf. 'contentId' should be the relevant ID of that item type you'd like to handle permissions for.\nThe permissions shown are those that override the default for just the specified item, they do not show the full evaluated permission for a role, nor do they reflect permissions inherited from other items in the hierarchy. Fallback permission values may be `null` when inheriting is active.",
"body_params": null,
"example_request": null,
"example_response": "{\n \"owner\": {\n \"id\": 1,\n \"name\": \"Admin\",\n \"slug\": \"admin\"\n },\n \"role_permissions\": [\n {\n \"role_id\": 2,\n \"view\": true,\n \"create\": false,\n \"update\": true,\n \"delete\": false,\n \"role\": {\n \"id\": 2,\n \"display_name\": \"Editor\"\n }\n },\n {\n \"role_id\": 10,\n \"view\": true,\n \"create\": true,\n \"update\": false,\n \"delete\": false,\n \"role\": {\n \"id\": 10,\n \"display_name\": \"Wizards of the west\"\n }\n }\n ],\n \"fallback_permissions\": {\n \"inheriting\": false,\n \"view\": true,\n \"create\": false,\n \"update\": false,\n \"delete\": false\n }\n}"
},
{
"name": "content-permissions-update",
"uri": "api/content-permissions/{contentType}/{contentId}",
"method": "PUT",
"controller": "BookStack\\Permissions\\ContentPermissionApiController",
"controller_method": "update",
"controller_method_kebab": "update",
"base_model": "content-permissions",
"description": "Update the configured content-level permission overrides for the item of the given type and ID. 'contentType' should be one of: page, book, chapter, bookshelf.\n'contentId' should be the relevant ID of that item type you'd like to handle permissions for. Providing an empty `role_permissions` array will remove any existing configured role permissions, so you may want to fetch existing permissions beforehand if just adding/removing a single item. You should completely omit the `owner_id`, `role_permissions` and/or the `fallback_permissions` properties from your request data if you don't wish to update details within those categories.",
"body_params": {
"owner_id": ["int"],
"role_permissions": ["array"],
"role_permissions.*.role_id": ["required", "int", "exists:roles,id"],
"role_permissions.*.view": ["required", "boolean"],
"role_permissions.*.create": ["required", "boolean"],
"role_permissions.*.update": ["required", "boolean"],
"role_permissions.*.delete": ["required", "boolean"],
"fallback_permissions": ["nullable"],
"fallback_permissions.inheriting": [
"required_with:fallback_permissions",
"boolean"
],
"fallback_permissions.view": [
"required_if:fallback_permissions.inheriting,false",
"boolean"
],
"fallback_permissions.create": [
"required_if:fallback_permissions.inheriting,false",
"boolean"
],
"fallback_permissions.update": [
"required_if:fallback_permissions.inheriting,false",
"boolean"
],
"fallback_permissions.delete": [
"required_if:fallback_permissions.inheriting,false",
"boolean"
]
},
"example_request": "{\n \"owner_id\": 1,\n \"role_permissions\": [\n {\n \"role_id\": 2,\n \"view\": true,\n \"create\": true,\n \"update\": true,\n \"delete\": false\n },\n {\n \"role_id\": 3,\n \"view\": false,\n \"create\": false,\n \"update\": false,\n \"delete\": false\n }\n ],\n \"fallback_permissions\": {\n \"inheriting\": false,\n \"view\": true,\n \"create\": true,\n \"update\": false,\n \"delete\": false\n }\n}",
"example_response": "{\n \"owner\": {\n \"id\": 1,\n \"name\": \"Admin\",\n \"slug\": \"admin\"\n },\n \"role_permissions\": [\n {\n \"role_id\": 2,\n \"view\": true,\n \"create\": true,\n \"update\": true,\n \"delete\": false,\n \"role\": {\n \"id\": 2,\n \"display_name\": \"Editor\"\n }\n },\n {\n \"role_id\": 3,\n \"view\": false,\n \"create\": false,\n \"update\": false,\n \"delete\": false,\n \"role\": {\n \"id\": 3,\n \"display_name\": \"Viewer\"\n }\n }\n ],\n \"fallback_permissions\": {\n \"inheriting\": false,\n \"view\": true,\n \"create\": true,\n \"update\": false,\n \"delete\": false\n }\n}"
}
],
"audit-log": [
{
"name": "audit-log-list",
"uri": "api/audit-log",
"method": "GET",
"controller": "BookStack\\Activity\\Controllers\\AuditLogApiController",
"controller_method": "list",
"controller_method_kebab": "list",
"base_model": "audit-log",
"description": "Get a listing of audit log events in the system. The loggable relation fields currently only relates to core content types (page, book, bookshelf, chapter) but this may be used more in the future across other types. Requires permission to manage both users and system settings.",
"body_params": null,
"example_request": null,
"example_response": "{\n \"data\": [\n {\n \"id\": 1,\n \"type\": \"bookshelf_create\",\n \"detail\": \"\",\n \"user_id\": 1,\n \"loggable_id\": 1,\n \"loggable_type\": \"bookshelf\",\n \"ip\": \"124.4.x.x\",\n \"created_at\": \"2021-09-29T12:32:02.000000Z\",\n \"user\": {\n \"id\": 1,\n \"name\": \"Admins\",\n \"slug\": \"admins\"\n }\n },\n {\n \"id\": 2,\n \"type\": \"auth_login\",\n \"detail\": \"standard; (1) Admin\",\n \"user_id\": 1,\n \"loggable_id\": null,\n \"loggable_type\": null,\n \"ip\": \"127.0.x.x\",\n \"created_at\": \"2021-09-29T12:32:04.000000Z\",\n \"user\": {\n \"id\": 1,\n \"name\": \"Admins\",\n \"slug\": \"admins\"\n }\n },\n {\n \"id\": 3,\n \"type\": \"bookshelf_update\",\n \"detail\": \"\",\n \"user_id\": 1,\n \"loggable_id\": 1,\n \"loggable_type\": \"bookshelf\",\n \"ip\": \"127.0.x.x\",\n \"created_at\": \"2021-09-29T12:32:07.000000Z\",\n \"user\": {\n \"id\": 1,\n \"name\": \"Admins\",\n \"slug\": \"admins\"\n }\n },\n {\n \"id\": 4,\n \"type\": \"page_create\",\n \"detail\": \"\",\n \"user_id\": 1,\n \"loggable_id\": 1,\n \"loggable_type\": \"page\",\n \"ip\": \"127.0.x.x\",\n \"created_at\": \"2021-09-29T12:32:13.000000Z\",\n \"user\": {\n \"id\": 1,\n \"name\": \"Admins\",\n \"slug\": \"admins\"\n }\n },\n {\n \"id\": 5,\n \"type\": \"page_update\",\n \"detail\": \"\",\n \"user_id\": 1,\n \"loggable_id\": 1,\n \"loggable_type\": \"page\",\n \"ip\": \"127.0.x.x\",\n \"created_at\": \"2021-09-29T12:37:27.000000Z\",\n \"user\": {\n \"id\": 1,\n \"name\": \"Admins\",\n \"slug\": \"admins\"\n }\n }\n ],\n \"total\": 6088\n}"
}
]
}