Getting Started

This documentation covers use of the REST API.
Examples of API usage, in a variety of programming languages, can be found in the BookStack api-scripts repo on GitHub.

Some alternative options for extension and customization can be found below:

Webhooks - HTTP POST calls upon events occurring in BookStack.
Visual Theme System - Methods to override views, translations and icons within BookStack.
Logical Theme System - Methods to extend back-end functionality within BookStack.

Authentication

To access the API a user has to have the "Access System API" permission enabled on one of their assigned roles. Permissions to content accessed via the API is limited by the roles & permissions assigned to the user that's used to access the API.

Authentication to use the API is primarily done using API Tokens. Once the "Access System API" permission has been assigned to a user, a "API Tokens" section should be visible when editing their user profile. Choose "Create Token" and enter an appropriate name and expiry date, relevant for your API usage then press "Save". A "Token ID" and "Token Secret" will be immediately displayed. These values should be used as a header in API HTTP requests in the following format:

Authorization: Token <token_id>:<token_secret>

Here's an example of an authorized cURL request to list books in the system:

curl --request GET \
  --url https://example.com/api/books \
  --header 'Authorization: Token C6mdvEQTGnebsmVn3sFNeeuelGEBjyQp:NOvD3VlzuSVuBPNaf1xWHmy7nIRlaj22'

If already logged into the system within the browser, via a user account with permission to access the API, the system will also accept an existing session meaning you can browse API endpoints directly in the browser or use the browser devtools to play with the API.

Request Format

For endpoints in this documentation that accept data a "Body Parameters" table will be available to show the parameters that are accepted in the request. Any rules for the values of such parameters, such as the data-type or if they're required, will be shown alongside the parameter name.

The API can accept request data in the following Content-Type formats:

application/json
application/x-www-form-urlencoded*
multipart/form-data*

* Form requests currently only work for POST requests due to how PHP handles request data. If you need to use these formats for PUT or DELETE requests you can work around this limitation by using a POST request and providing a "_method" parameter with the value equal to PUT or DELETE.

Regardless of format chosen, ensure you set a Content-Type header on requests so that the system can correctly parse your request data. The API is primarily designed to be interfaced using JSON, since responses are always in JSON format, hence examples in this documentation will be shown as JSON. Some endpoints, such as those that receive file data, may require the use of multipart/form-data. This will be mentioned within the description for such endpoints.

Some data may be expected in a more complex nested structure such as a nested object or array. These can be sent in non-JSON request formats using square brackets to denote index keys or property names. Below is an example of a JSON request body data and it's equivalent x-www-form-urlencoded representation.

JSON

{
  "name": "My new item",
  "books": [105, 263],
  "tags": [{"name": "Tag Name", "value": "Tag Value"}],
}

x-www-form-urlencoded

name=My%20new%20item&books%5B0%5D=105&books%5B1%5D=263&tags%5B0%5D%5Bname%5D=Tag%20Name&tags%5B0%5D%5Bvalue%5D=Tag%20Value

x-www-form-urlencoded (Decoded for readability)

name=My new item
books[0]=105
books[1]=263
tags[0][name]=Tag Name
tags[0][value]=Tag Value

Listing Endpoints

Some endpoints will return a list of data models. These endpoints will return an array of the model data under a data property along with a numeric total property to indicate the total number of records found for the query within the system. Here's an example of a listing response:

{
  "data": [
    {
      "id": 1,
      "name": "BookStack User Guide",
      "slug": "bookstack-user-guide",
      "description": "This is a general guide on using BookStack on a day-to-day basis.",
      "created_at": "2019-05-05 21:48:46",
      "updated_at": "2019-12-11 20:57:31",
      "created_by": 1,
      "updated_by": 1,
      "image_id": 3
    }
  ],
  "total": 16
}

There are a number of standard URL parameters that can be supplied to manipulate and page through the results returned from a listing endpoint:

Parameter Details Examples

count Specify how many records will be returned in the response.
(Default: 100, Max: 500) Limit the count to 50
?count=50

offset Specify how many records to skip over in the response.
(Default: 0) Skip over the first 100 records
?offset=100

sort Specify what field is used to sort the data and the direction of the sort (Ascending or Descending).
Value is the name of a field, A + or - prefix dictates ordering.
Direction defaults to ascending.
Can use most fields shown in the response. Sort by name ascending
?sort=+name

Sort by "Created At" date descending
?sort=-created_at

filter[<field>]

Specify a filter to be applied to the query. Can use most fields shown in the response.
By default a filter will apply a "where equals" query but the below operations are available using the format filter[<field>:<operation>]

eq	Where `<field>` equals the filter value.
ne	Where `<field>` does not equal the filter value.
gt	Where `<field>` is greater than the filter value.
lt	Where `<field>` is less than the filter value.
gte	Where `<field>` is greater than or equal to the filter value.
lte	Where `<field>` is less than or equal to the filter value.
like	Where `<field>` is "like" the filter value. `%` symbols can be used as wildcards.

Filter where id is 5:
?filter[id]=5

Filter where id is not 5:
?filter[id:ne]=5

Filter where name contains "cat":
?filter[name:like]=%cat%

Filter where created after 2020-01-01:
?filter[created_at:gt]=2020-01-01

Error Handling

Successful responses will return a 200 or 204 HTTP response code. Errors will return a 4xx or a 5xx HTTP response code depending on the type of error. Errors follow a standard format as shown below. The message provided may be translated depending on the configured language of the system in addition to the API users' language preference. The code provided in the JSON response will match the HTTP response code.

{
	"error": {
		"code": 401,
		"message": "No authorization token found on the request"
	}
}

Rate Limits

The API has built-in per-user rate-limiting to prevent potential abuse using the API. By default, this is set to 180 requests per minute but this can be changed by an administrator by setting an "API_REQUESTS_PER_MIN" .env option like so:

# The number of API requests that can be made per minute by a single user.
API_REQUESTS_PER_MIN=180

When the limit is reached you will receive a 429 "Too Many Attempts." error response. It's generally good practice to limit requests made from your API client, where possible, to avoid affecting normal use of the system caused by over-consuming system resources. Keep in mind there may be other rate-limiting factors such as web-server & firewall controls.

Content Security

Many of the available endpoints will return content that has been provided by user input. Some of this content may be provided in a certain data-format (Such as HTML or Markdown for page content). Such content is not guaranteed to be safe so keep security in mind when dealing with such user-input. In some cases, the system will apply some filtering to content in an attempt to prevent certain vulnerabilities, but this is not assured to be a bullet-proof defence.

Within its own interfaces, unless disabled, the system makes use of Content Security Policy (CSP) rules to heavily negate cross-site scripting vulnerabilities from user content. If displaying user content externally, it's advised you also use defences such as CSP or the disabling of JavaScript completely.

docs

display

GET https://chatbase.h82.se/api/docs

Load the docs page for the API.

json

GET https://chatbase.h82.se/api/docs.json

Show a JSON view of the API docs data.

attachments

list

GET https://chatbase.h82.se/api/attachments

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.

Example Response

{
  "data": [
    {
      "id": 3,
      "name": "datasheet.pdf",
      "extension": "pdf",
      "uploaded_to": 8,
      "external": false,
      "order": 1,
      "created_at": "2021-10-11T06:18:49.000000Z",
      "updated_at": "2021-10-20T06:31:10.000000Z",
      "created_by": 1,
      "updated_by": 1
    },
    {
      "id": 4,
      "name": "Cat reference",
      "extension": "",
      "uploaded_to": 9,
      "external": true,
      "order": 1,
      "created_at": "2021-10-20T06:30:11.000000Z",
      "updated_at": "2021-10-20T06:30:11.000000Z",
      "created_by": 1,
      "updated_by": 1
    }
  ],
  "total": 2
}

create

POST https://chatbase.h82.se/api/attachments

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. If you're uploading a file the POST data should be provided via a multipart/form-data type request instead of JSON.

Body Parameters

Param Name	Value Rules
name	`required` `min:1` `max:255` `string`
uploaded_to	`required` `integer` `exists:pages,id`
file	`required_without:link` `file` `max:50000`
link	`required_without:file` `min:1` `max:255` `safe_url`

Example Request

{
  "name": "My uploaded attachment",
  "uploaded_to": 8,
  "link": "https://link.example.com"
}

Example Response

{
  "id": 5,
  "name": "My uploaded attachment",
  "extension": "",
  "uploaded_to": 8,
  "external": true,
  "order": 2,
  "created_by": 1,
  "updated_by": 1,
  "created_at": "2021-10-20T06:35:46.000000Z",
  "updated_at": "2021-10-20T06:35:46.000000Z"
}

read

GET https://chatbase.h82.se/api/attachments/{id}

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.

Example Response

{
  "id": 5,
  "name": "My link attachment",
  "extension": "",
  "uploaded_to": 4,
  "external": true,
  "order": 2,
  "created_by": {
    "id": 1,
    "name": "Admin",
    "slug": "admin"
  },
  "updated_by": {
    "id": 1,
    "name": "Admin",
    "slug": "admin"
  },
  "created_at": "2021-10-20T06:35:46.000000Z",
  "updated_at": "2021-10-20T06:37:11.000000Z",
  "links": {
    "html": "<a target=\"_blank\" href=\"https://bookstack.local/attachments/5\">My updated attachment</a>",
    "markdown": "[My updated attachment](https://bookstack.local/attachments/5)"
  },
  "content": "https://link.example.com/updated"
}

update

PUT https://chatbase.h82.se/api/attachments/{id}

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 Parameters

Param Name	Value Rules
name	`min:1` `max:255` `string`
uploaded_to	`integer` `exists:pages,id`
file	`file` `max:50000`
link	`min:1` `max:255` `safe_url`

Example Request

{
  "name": "My updated attachment",
  "uploaded_to": 4,
  "link": "https://link.example.com/updated"
}

Example Response

{
  "id": 5,
  "name": "My updated attachment",
  "extension": "",
  "uploaded_to": 4,
  "external": true,
  "order": 2,
  "created_by": 1,
  "updated_by": 1,
  "created_at": "2021-10-20T06:35:46.000000Z",
  "updated_at": "2021-10-20T06:37:11.000000Z"
}

delete

DELETE https://chatbase.h82.se/api/attachments/{id}

Delete an attachment of the given ID.

books

list

GET https://chatbase.h82.se/api/books

Get a listing of books visible to the user.

Example Response

{
  "data": [
    {
      "id": 1,
      "name": "BookStack User Guide",
      "slug": "bookstack-user-guide",
      "description": "This is a general guide on using BookStack on a day-to-day basis.",
      "created_at": "2019-05-05T21:48:46.000000Z",
      "updated_at": "2019-12-11T20:57:31.000000Z",
      "created_by": 1,
      "updated_by": 1,
      "owned_by": 1
    },
    {
      "id": 2,
      "name": "Inventore inventore quia voluptatem.",
      "slug": "inventore-inventore-quia-voluptatem",
      "description": "Veniam nihil voluptas enim laborum corporis quos sint. Ab rerum voluptas ut iste voluptas magni quibusdam ut. Amet omnis enim voluptate neque facilis.",
      "created_at": "2019-05-05T22:10:14.000000Z",
      "updated_at": "2019-12-11T20:57:23.000000Z",
      "created_by": 4,
      "updated_by": 3,
      "owned_by": 3
    }
  ],
  "total": 14
}

create

POST https://chatbase.h82.se/api/books

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 Parameters

Param Name	Value Rules
name	`required` `string` `max:255`
description	`string` `max:1000`
tags	`array`
image	`nullable` `image_extension` `mimes:jpeg,png,gif,webp` `max:50000`

Example Request

{
  "name": "My own book",
  "description": "This is my own little book"
}

Example Response

{
  "name": "My new book",
  "description": "This is a book created via the API",
  "created_by": 1,
  "updated_by": 1,
  "owned_by": 1,
  "slug": "my-new-book",
  "updated_at": "2020-01-12T14:05:11.000000Z",
  "created_at": "2020-01-12T14:05:11.000000Z",
  "id": 15
}

read

GET https://chatbase.h82.se/api/books/{id}

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.

Example Response

{
  "id": 16,
  "name": "My own book",
  "slug": "my-own-book",
  "description": "This is my own little book",
  "created_at": "2020-01-12T14:09:59.000000Z",
  "updated_at": "2020-01-12T14:11:51.000000Z",
  "created_by": {
    "id": 1,
    "name": "Admin"
  },
  "updated_by": {
    "id": 1,
    "name": "Admin"
  },
  "owned_by": {
    "id": 1,
    "name": "Admin"
  },
  "contents": [
    {
      "id": 50,
      "name": "Bridge Structures",
      "slug": "bridge-structures",
      "book_id": 16,
      "created_at": "2021-12-19T15:22:11.000000Z",
      "updated_at": "2021-12-21T19:42:29.000000Z",
      "url": "https://example.com/books/my-own-book/chapter/bridge-structures",
      "type": "chapter",
      "pages": [
        {
          "id": 42,
          "name": "Building Bridges",
          "slug": "building-bridges",
          "book_id": 16,
          "chapter_id": 50,
          "draft": false,
          "template": false,
          "created_at": "2021-12-19T15:22:11.000000Z",
          "updated_at": "2022-09-29T13:44:15.000000Z",
          "url": "https://example.com/books/my-own-book/page/building-bridges"
        }
      ]
    },
    {
      "id": 43,
      "name": "Cool Animals",
      "slug": "cool-animals",
      "book_id": 16,
      "chapter_id": 0,
      "draft": false,
      "template": false,
      "created_at": "2021-12-19T18:22:11.000000Z",
      "updated_at": "2022-07-29T13:44:15.000000Z",
      "url": "https://example.com/books/my-own-book/page/cool-animals"
    }
  ],
  "tags": [
    {
      "id": 13,
      "name": "Category",
      "value": "Guide",
      "order": 0
    }
  ],
  "cover": {
    "id": 452,
    "name": "sjovall_m117hUWMu40.jpg",
    "url": "https://example.com/uploads/images/cover_book/2020-01/sjovall_m117hUWMu40.jpg",
    "created_at": "2020-01-12T14:11:51.000000Z",
    "updated_at": "2020-01-12T14:11:51.000000Z",
    "created_by": 1,
    "updated_by": 1,
    "path": "/uploads/images/cover_book/2020-01/sjovall_m117hUWMu40.jpg",
    "type": "cover_book",
    "uploaded_to": 16
  }
}

update

PUT https://chatbase.h82.se/api/books/{id}

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 Parameters

Param Name	Value Rules
name	`string` `min:1` `max:255`
description	`string` `max:1000`
tags	`array`
image	`nullable` `image_extension` `mimes:jpeg,png,gif,webp` `max:50000`

Example Request

{
  "name": "My updated book",
  "description": "This is my book with updated details"
}

Example Response

{
  "id": 16,
  "name": "My own book",
  "slug": "my-own-book",
  "description": "This is my own little book - updated",
  "created_at": "2020-01-12T14:09:59.000000Z",
  "updated_at": "2020-01-12T14:16:10.000000Z",
  "created_by": 1,
  "updated_by": 1,
  "owned_by": 1
}

delete

DELETE https://chatbase.h82.se/api/books/{id}

Delete a single book. This will typically send the book to the recycle bin.

export-html

GET https://chatbase.h82.se/api/books/{id}/export/html

Export a book as a contained HTML file.

export-pdf

GET https://chatbase.h82.se/api/books/{id}/export/pdf

Export a book as a PDF file.

export-plain-text

GET https://chatbase.h82.se/api/books/{id}/export/plaintext

Export a book as a plain text file.

export-markdown

GET https://chatbase.h82.se/api/books/{id}/export/markdown

Export a book as a markdown file.

chapters

list

GET https://chatbase.h82.se/api/chapters

Get a listing of chapters visible to the user.

Example Response

{
  "data": [
    {
      "id": 1,
      "book_id": 1,
      "name": "Content Creation",
      "slug": "content-creation",
      "description": "How to create documentation on whatever subject you need to write about.",
      "priority": 3,
      "created_at": "2019-05-05:",
      "updated_at": "2019-09-28T11:24:23.000000Z",
      "created_by": 1,
      "updated_by": 1,
      "owned_by": 1
    },
    {
      "id": 2,
      "book_id": 1,
      "name": "Managing Content",
      "slug": "managing-content",
      "description": "How to keep things organised and orderly in the system for easier navigation and better user experience.",
      "priority": 5,
      "created_at": "2019-05-05T21:58:07.000000Z",
      "updated_at": "2019-10-17T15:05:34.000000Z",
      "created_by": 3,
      "updated_by": 3,
      "owned_by": 3
    }
  ],
  "total": 40
}

create

POST https://chatbase.h82.se/api/chapters

Create a new chapter in the system.

Body Parameters

Param Name	Value Rules
book_id	`required` `integer`
name	`required` `string` `max:255`
description	`string` `max:1000`
tags	`array`

Example Request

{
  "book_id": 1,
  "name": "My fantastic new chapter",
  "description": "This is a great new chapter that I've created via the API",
  "tags": [
    {"name": "Category", "value": "Top Content"},
    {"name": "Rating", "value": "Highest"}
  ]
}

Example Response

{
  "book_id": 1,
  "priority": 6,
  "name": "My fantastic new chapter",
  "description": "This is a great new chapter that I've created via the API",
  "created_by": 1,
  "updated_by": 1,
  "owned_by": 1,
  "slug": "my-fantastic-new-chapter",
  "updated_at": "2020-05-22T22:59:55.000000Z",
  "created_at": "2020-05-22T22:59:55.000000Z",
  "id": 74,
  "book": {
    "id": 1,
    "name": "BookStack User Guide",
    "slug": "bookstack-user-guide",
    "description": "This is a general guide on using BookStack on a day-to-day basis.",
    "created_at": "2019-05-05T21:48:46.000000Z",
    "updated_at": "2019-12-11T20:57:31.000000Z",
    "created_by": 1,
    "updated_by": 1
  },
  "tags": [
    {
      "name": "Category",
      "value": "Top Content",
      "order": 0,
      "created_at": "2020-05-22T22:59:55.000000Z",
      "updated_at": "2020-05-22T22:59:55.000000Z"
    },
    {
      "name": "Rating",
      "value": "Highest",
      "order": 0,
      "created_at": "2020-05-22T22:59:55.000000Z",
      "updated_at": "2020-05-22T22:59:55.000000Z"
    }
  ]
}

read

GET https://chatbase.h82.se/api/chapters/{id}

View the details of a single chapter.

Example Response

{
  "id": 1,
  "book_id": 1,
  "slug": "content-creation",
  "name": "Content Creation",
  "description": "How to create documentation on whatever subject you need to write about.",
  "priority": 3,
  "created_at": "2019-05-05T21:49:56.000000Z",
  "updated_at": "2019-09-28T11:24:23.000000Z",
  "created_by": {
    "id": 1,
    "name": "Admin"
  },
  "updated_by": {
    "id": 1,
    "name": "Admin"
  },
  "owned_by": {
    "id": 1,
    "name": "Admin"
  },
  "tags": [
    {
      "name": "Category",
      "value": "Guide",
      "order": 0
    }
  ],
  "pages": [
    {
      "id": 1,
      "book_id": 1,
      "chapter_id": 1,
      "name": "How to create page content",
      "slug": "how-to-create-page-content",
      "priority": 0,
      "created_at": "2019-05-05T21:49:58.000000Z",
      "updated_at": "2019-08-26T14:32:59.000000Z",
      "created_by": 1,
      "updated_by": 1,
      "draft": false,
      "revision_count": 2,
      "template": false
    },
    {
      "id": 7,
      "book_id": 1,
      "chapter_id": 1,
      "name": "Good book structure",
      "slug": "good-book-structure",
      "priority": 1,
      "created_at": "2019-05-05T22:01:55.000000Z",
      "updated_at": "2019-06-06T12:03:04.000000Z",
      "created_by": 3,
      "updated_by": 3,
      "draft": false,
      "revision_count": 1,
      "template": false
    }
  ]
}

update

PUT https://chatbase.h82.se/api/chapters/{id}

Update the details of a single chapter.

Body Parameters

Param Name	Value Rules
book_id	`integer`
name	`string` `min:1` `max:255`
description	`string` `max:1000`
tags	`array`

Example Request

{
  "book_id": 1,
  "name": "My fantastic updated chapter",
  "description": "This is an updated chapter that I've altered via the API",
  "tags": [
    {"name": "Category", "value": "Kinda Good Content"},
    {"name": "Rating", "value": "Medium"}
  ]
}

Example Response

{
  "id": 75,
  "book_id": 1,
  "slug": "my-fantastic-updated-chapter",
  "name": "My fantastic updated chapter",
  "description": "This is an updated chapter that I've altered via the API",
  "priority": 7,
  "created_at": "2020-05-22T23:03:35.000000Z",
  "updated_at": "2020-05-22T23:07:20.000000Z",
  "created_by": 1,
  "updated_by": 1,
  "owned_by": 1,
  "book": {
    "id": 1,
    "name": "BookStack User Guide",
    "slug": "bookstack-user-guide",
    "description": "This is a general guide on using BookStack on a day-to-day basis.",
    "created_at": "2019-05-05T21:48:46.000000Z",
    "updated_at": "2019-12-11T20:57:31.000000Z",
    "created_by": 1,
    "updated_by": 1
  },
  "tags": [
    {
      "name": "Category",
      "value": "Kinda Good Content",
      "order": 0,
      "created_at": "2020-05-22T23:07:20.000000Z",
      "updated_at": "2020-05-22T23:07:20.000000Z"
    },
    {
      "name": "Rating",
      "value": "Medium",
      "order": 0,
      "created_at": "2020-05-22T23:07:20.000000Z",
      "updated_at": "2020-05-22T23:07:20.000000Z"
    }
  ]
}

delete

DELETE https://chatbase.h82.se/api/chapters/{id}

Delete a chapter. This will typically send the chapter to the recycle bin.

export-html

GET https://chatbase.h82.se/api/chapters/{id}/export/html

Export a chapter as a contained HTML file.

export-pdf

GET https://chatbase.h82.se/api/chapters/{id}/export/pdf

Export a chapter as a PDF file.

export-plain-text

GET https://chatbase.h82.se/api/chapters/{id}/export/plaintext

Export a chapter as a plain text file.

export-markdown

GET https://chatbase.h82.se/api/chapters/{id}/export/markdown

Export a chapter as a markdown file.

pages

list

GET https://chatbase.h82.se/api/pages

Get a listing of pages visible to the user.

Example Response

{
	"data": [
		{
			"id": 1,
			"book_id": 1,
			"chapter_id": 1,
			"name": "How to create page content",
			"slug": "how-to-create-page-content",
			"priority": 0,
			"draft": false,
			"template": false,
			"created_at": "2019-05-05T21:49:58.000000Z",
			"updated_at": "2020-07-04T15:50:58.000000Z",
			"created_by": 1,
			"updated_by": 1,
			"owned_by": 1
		},
		{
			"id": 2,
			"book_id": 1,
			"chapter_id": 1,
			"name": "How to use images",
			"slug": "how-to-use-images",
			"priority": 2,
			"draft": false,
			"template": false,
			"created_at": "2019-05-05T21:53:30.000000Z",
			"updated_at": "2019-06-06T12:03:04.000000Z",
			"created_by": 1,
			"updated_by": 1,
			"owned_by": 1
		},
		{
			"id": 3,
			"book_id": 1,
			"chapter_id": 1,
			"name": "Drawings via draw.io",
			"slug": "drawings-via-drawio",
			"priority": 3,
			"draft": false,
			"template": false,
			"created_at": "2019-05-05T21:53:49.000000Z",
			"updated_at": "2019-12-18T21:56:52.000000Z",
			"created_by": 1,
			"updated_by": 1,
			"owned_by": 1
		}
	],
	"total": 322
}

create

POST https://chatbase.h82.se/api/pages

Create a new page in the system. The ID of a parent book or chapter is required to indicate where this page should be located. Any 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 Parameters

Param Name	Value Rules
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`

Example Request

{
	"book_id": 1,
	"name": "My API Page",
	"html": "<p>my new API page</p>",
	"tags": [
		{"name": "Category", "value": "Not Bad Content"},
		{"name": "Rating", "value": "Average"}
	]
}

Example Response

{
	"id": 358,
	"book_id": 1,
	"chapter_id": 0,
	"name": "My API Page",
	"slug": "my-api-page",
	"html": "<p id=\"bkmrk-my-new-api-page\">my new API page</p>",
	"priority": 14,
	"created_at": "2020-11-28T15:01:39.000000Z",
	"updated_at": "2020-11-28T15:01:39.000000Z",
	"created_by": {
		"id": 1,
		"name": "Admin"
	},
	"updated_by": {
		"id": 1,
		"name": "Admin"
	},
	"owned_by": {
		"id": 1,
		"name": "Admin"
	},
	"draft": false,
	"markdown": "",
	"revision_count": 1,
	"template": false,
	"tags": [
		{
			"name": "Category",
			"value": "Not Bad Content",
			"order": 0
		},
		{
			"name": "Rating",
			"value": "Average",
			"order": 1
		}
	]
}

read

GET https://chatbase.h82.se/api/pages/{id}

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. See the "Content Security" section of these docs for security considerations when using the page content returned from this endpoint.

Example Response

{
	"id": 306,
	"book_id": 1,
	"chapter_id": 0,
	"name": "A page written in markdown",
	"slug": "a-page-written-in-markdown",
	"html": "<h1 id=\"bkmrk-how-this-is-built\">How this is built</h1>\r\n<p id=\"bkmrk-this-page-is-written\">This page is written in markdown. BookStack stores the page data in HTML.</p>\r\n<p id=\"bkmrk-here%27s-a-cute-pictur\">Here's a cute picture of my cat:</p>\r\n<p id=\"bkmrk-\"><a href=\"http://example.com/uploads/images/gallery/2020-04/yXSrubes.jpg\"><img src=\"http://example.com/uploads/images/gallery/2020-04/scaled-1680-/yXSrubes.jpg\" alt=\"yXSrubes.jpg\"></a></p>",
	"priority": 13,
	"created_at": "2020-02-02T21:40:38.000000Z",
	"updated_at": "2020-11-28T14:43:20.000000Z",
	"created_by": {
		"id": 1,
		"name": "Admin"
	},
	"updated_by": {
		"id": 1,
		"name": "Admin"
	},
	"owned_by": {
		"id": 1,
		"name": "Admin"
	},
	"draft": false,
	"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[![yXSrubes.jpg](http://example.com/uploads/images/gallery/2020-04/scaled-1680-/yXSrubes.jpg)](http://example.com/uploads/images/gallery/2020-04/yXSrubes.jpg)",
	"revision_count": 5,
	"template": false,
	"tags": [
		{
			"name": "Category",
			"value": "Top Content",
			"order": 0
		},
		{
			"name": "Animal",
			"value": "Cat",
			"order": 1
		}
	]
}

update

PUT https://chatbase.h82.se/api/pages/{id}

Update the details of a single page. See 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 Parameters

Param Name	Value Rules
book_id	`integer`
chapter_id	`integer`
name	`string` `min:1` `max:255`
html	`string`
markdown	`string`
tags	`array`

Example Request

{
	"chapter_id": 1,
	"name": "My updated API Page",
	"html": "<p>my new API page - Updated</p>",
	"tags": [
		{"name": "Category", "value": "API Examples"},
		{"name": "Rating", "value": "Alright"}
	]
}

Example Response

{
	"id": 361,
	"book_id": 1,
	"chapter_id": 1,
	"name": "My updated API Page",
	"slug": "my-updated-api-page",
	"html": "<p id=\"bkmrk-my-new-api-page---up\">my new API page - Updated</p>",
	"priority": 16,
	"created_at": "2020-11-28T15:10:54.000000Z",
	"updated_at": "2020-11-28T15:13:03.000000Z",
	"created_by": {
		"id": 1,
		"name": "Admin"
	},
	"updated_by": {
		"id": 1,
		"name": "Admin"
	},
	"owned_by": {
		"id": 1,
		"name": "Admin"
	},
	"draft": false,
	"markdown": "",
	"revision_count": 5,
	"template": false,
	"tags": [
		{
			"name": "Category",
			"value": "API Examples",
			"order": 0
		},
		{
			"name": "Rating",
			"value": "Alright",
			"order": 0
		}
	]
}

delete

DELETE https://chatbase.h82.se/api/pages/{id}

Delete a page. This will typically send the page to the recycle bin.

export-html

GET https://chatbase.h82.se/api/pages/{id}/export/html

Export a page as a contained HTML file.

export-pdf

GET https://chatbase.h82.se/api/pages/{id}/export/pdf

Export a page as a PDF file.

export-plain-text

GET https://chatbase.h82.se/api/pages/{id}/export/plaintext

Export a page as a plain text file.

export-mark-down

GET https://chatbase.h82.se/api/pages/{id}/export/markdown

Export a page as a markdown file.

search

all

GET https://chatbase.h82.se/api/search

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. The 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.

Query Parameters

Param Name	Value Rules
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

Example Response

{
  "data": [
    {
      "id": 84,
      "book_id": 1,
      "slug": "a-chapter-for-cats",
      "name": "A chapter for cats",
      "created_at": "2021-11-14T15:57:35.000000Z",
      "updated_at": "2021-11-14T15:57:35.000000Z",
      "type": "chapter",
      "url": "https://example.com/books/my-book/chapter/a-chapter-for-cats",
      "preview_html": {
        "name": "A chapter for <strong>cats</strong>",
        "content": "...once a bunch of <strong>cats</strong> named tony...behaviour of <strong>cats</strong> is unsuitable"
      },
      "tags": []
    },
    {
      "name": "The hows and whys of cats",
      "id": 396,
      "slug": "the-hows-and-whys-of-cats",
      "book_id": 1,
      "chapter_id": 75,
      "draft": false,
      "template": false,
      "created_at": "2021-05-15T16:28:10.000000Z",
      "updated_at": "2021-11-14T15:56:49.000000Z",
      "type": "page",
      "url": "https://example.com/books/my-book/page/the-hows-and-whys-of-cats",
      "preview_html": {
        "name": "The hows and whys of <strong>cats</strong>",
        "content": "...people ask why <strong>cats</strong>? but there are...the reason that <strong>cats</strong> are fast are due to..."
      },
      "tags": [
        {
          "name": "Animal",
          "value": "Cat",
          "order": 0
        },
        {
          "name": "Category",
          "value": "Top Content",
          "order": 0
        }
      ]
    },
    {
      "name": "How advanced are cats?",
      "id": 362,
      "slug": "how-advanced-are-cats",
      "book_id": 13,
      "chapter_id": 73,
      "draft": false,
      "template": false,
      "created_at": "2020-11-29T21:55:07.000000Z",
      "updated_at": "2021-11-14T16:02:39.000000Z",
      "type": "page",
      "url": "https://example.com/books/my-book/page/how-advanced-are-cats",
      "preview_html": {
        "name": "How advanced are <strong>cats</strong>?",
        "content": "<strong>cats</strong> are some of the most advanced animals in the world."
      },
      "tags": []
    }
  ],
  "total": 3
}

shelves

list

GET https://chatbase.h82.se/api/shelves

Get a listing of shelves visible to the user.

Example Response

{
  "data": [
    {
      "id": 8,
      "name": "Qui qui aspernatur autem molestiae libero necessitatibus molestias.",
      "slug": "qui-qui-aspernatur-autem-molestiae-libero-necessitatibus-molestias",
      "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.",
      "created_at": "2019-05-05T22:10:16.000000Z",
      "updated_at": "2020-04-10T13:00:45.000000Z",
      "created_by": 4,
      "updated_by": 1,
      "owned_by": 1
    },
    {
      "id": 9,
      "name": "Ipsum aut inventore fuga libero non facilis.",
      "slug": "ipsum-aut-inventore-fuga-libero-non-facilis",
      "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.",
      "created_at": "2019-05-05T22:10:16.000000Z",
      "updated_at": "2020-04-10T13:00:58.000000Z",
      "created_by": 4,
      "updated_by": 1,
      "owned_by": 1
    },
    {
      "id": 10,
      "name": "Omnis reiciendis aut molestias sint accusantium.",
      "slug": "omnis-reiciendis-aut-molestias-sint-accusantium",
      "description": "Qui ea occaecati alias est dolores voluptatem doloribus. Ad reiciendis corporis vero nostrum omnis et. Non doloribus ut eaque ut quos dolores.",
      "created_at": "2019-05-05T22:10:16.000000Z",
      "updated_at": "2020-04-10T13:00:53.000000Z",
      "created_by": 4,
      "updated_by": 1,
      "owned_by": 4
    }
  ],
  "total": 3
}

create

POST https://chatbase.h82.se/api/shelves

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 Parameters

Param Name	Value Rules
name	`required` `string` `max:255`
description	`string` `max:1000`
books	`array`
tags	`array`
image	`nullable` `image_extension` `mimes:jpeg,png,gif,webp` `max:50000`

Example Request

{
  "name": "My shelf",
  "description": "This is my shelf with some books",
  "books": [5,1,3]
}

Example Response

{
  "name": "My shelf",
  "description": "This is my shelf with some books",
  "created_by": 1,
  "updated_by": 1,
  "owned_by": 1,
  "slug": "my-shelf",
  "updated_at": "2020-04-10T13:24:09.000000Z",
  "created_at": "2020-04-10T13:24:09.000000Z",
  "id": 14
}

read

GET https://chatbase.h82.se/api/shelves/{id}

View the details of a single shelf.

Example Response

{
  "id": 14,
  "name": "My shelf",
  "slug": "my-shelf",
  "description": "This is my shelf with some books",
  "created_by": {
    "id": 1,
    "name": "Admin"
  },
  "updated_by": {
    "id": 1,
    "name": "Admin"
  },
  "owned_by": {
    "id": 1,
    "name": "Admin"
  },
  "created_at": "2020-04-10T13:24:09.000000Z",
  "updated_at": "2020-04-10T13:31:04.000000Z",
  "tags": [
    {
      "id": 16,
      "name": "Category",
      "value": "Guide",
      "order": 0
    }
  ],
  "cover": {
    "id": 501,
    "name": "anafrancisconi_Sp04AfFCPNM.jpg",
    "url": "http://bookstack.local/uploads/images/cover_book/2020-04/anafrancisconi_Sp04AfFCPNM.jpg",
    "created_at": "2020-04-10T13:31:04.000000Z",
    "updated_at": "2020-04-10T13:31:04.000000Z",
    "created_by": 1,
    "updated_by": 1,
    "path": "/uploads/images/cover_book/2020-04/anafrancisconi_Sp04AfFCPNM.jpg",
    "type": "cover_book",
    "uploaded_to": 14
  },
  "books": [
    {
      "id": 5,
      "name": "Sint explicabo alias sunt.",
      "slug": "jbsQrzuaXe"
    },
    {
      "id": 1,
      "name": "BookStack User Guide",
      "slug": "bookstack-user-guide"
    },
    {
      "id": 3,
      "name": "Molestiae doloribus sint velit suscipit dolorem.",
      "slug": "H99QxALaoG"
    }
  ]
}

update

PUT https://chatbase.h82.se/api/shelves/{id}

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 Parameters

Param Name	Value Rules
name	`string` `min:1` `max:255`
description	`string` `max:1000`
books	`array`
tags	`array`
image	`nullable` `image_extension` `mimes:jpeg,png,gif,webp` `max:50000`

Example Request

{
  "name": "My updated shelf",
  "description": "This is my update shelf with some books",
  "books": [5,1,3]
}

Example Response

{
  "id": 14,
  "name": "My updated shelf",
  "slug": "my-updated-shelf",
  "description": "This is my update shelf with some books",
  "created_by": 1,
  "updated_by": 1,
  "owned_by": 1,
  "created_at": "2020-04-10T13:24:09.000000Z",
  "updated_at": "2020-04-10T13:48:22.000000Z"
}

delete

DELETE https://chatbase.h82.se/api/shelves/{id}

Delete a single shelf. This will typically send the shelf to the recycle bin.

users

list

GET https://chatbase.h82.se/api/users

Get a listing of users in the system. Requires permission to manage users.

Example Response

{
  "data": [
    {
      "id": 1,
      "name": "Dan Brown",
      "email": "dannyb@example.com",
      "created_at": "2022-02-03T16:27:55.000000Z",
      "updated_at": "2022-02-03T16:27:55.000000Z",
      "external_auth_id": "abc123456",
      "slug": "dan-brown",
      "user_id": 1,
      "last_activity_at": "2022-02-03T16:27:55.000000Z",
      "profile_url": "https://docs.example.com/user/dan-brown",
      "edit_url": "https://docs.example.com/settings/users/1",
      "avatar_url": "https://docs.example.com/uploads/images/user/2021-10/thumbs-50-50/profile-2021.jpg"
    },
    {
      "id": 2,
      "name": "Benny",
      "email": "benny@example.com",
      "created_at": "2022-01-31T20:39:24.000000Z",
      "updated_at": "2021-11-18T17:10:58.000000Z",
      "external_auth_id": "",
      "slug": "benny",
      "user_id": 2,
      "last_activity_at": "2022-01-31T20:39:24.000000Z",
      "profile_url": "https://docs.example.com/user/benny",
      "edit_url": "https://docs.example.com/settings/users/2",
      "avatar_url": "https://docs.example.com/uploads/images/user/2021-11/thumbs-50-50/guest.jpg"
    }
  ],
  "total": 28
}

create

POST https://chatbase.h82.se/api/users

Create a new user in the system. Requires permission to manage users.

Body Parameters

Param Name	Value Rules
name	`required` `min:2` `max:100`
email	`required` `min:2` `email` `unique:users,email,NULL,id`
external_auth_id	`string`
language	`string` `max:15` `alpha_dash`
password	`min:8`
roles	`array`
roles.*	`integer`
send_invite	`boolean`

Example Request

{
  "name": "Dan Brown",
  "email": "dannyb@example.com",
  "roles": [1],
  "language": "fr",
  "send_invite": true
}

Example Response

{
  "id": 1,
  "name": "Dan Brown",
  "email": "dannyb@example.com",
  "created_at": "2022-02-03T16:27:55.000000Z",
  "updated_at": "2022-02-03T16:27:55.000000Z",
  "external_auth_id": "abc123456",
  "slug": "dan-brown",
  "last_activity_at": "2022-02-03T16:27:55.000000Z",
  "profile_url": "https://docs.example.com/user/dan-brown",
  "edit_url": "https://docs.example.com/settings/users/1",
  "avatar_url": "https://docs.example.com/uploads/images/user/2021-10/thumbs-50-50/profile-2021.jpg",
  "roles": [
    {
      "id": 1,
      "display_name": "Admin"
    }
  ]
}

read

GET https://chatbase.h82.se/api/users/{id}

View the details of a single user. Requires permission to manage users.

Example Response

{
  "id": 1,
  "name": "Dan Brown",
  "email": "dannyb@example.com",
  "created_at": "2022-02-03T16:27:55.000000Z",
  "updated_at": "2022-02-03T16:27:55.000000Z",
  "external_auth_id": "abc123456",
  "slug": "dan-brown",
  "last_activity_at": "2022-02-03T16:27:55.000000Z",
  "profile_url": "https://docs.example.com/user/dan-brown",
  "edit_url": "https://docs.example.com/settings/users/1",
  "avatar_url": "https://docs.example.com/uploads/images/user/2021-10/thumbs-50-50/profile-2021.jpg",
  "roles": [
    {
      "id": 1,
      "display_name": "Admin"
    }
  ]
}

update

PUT https://chatbase.h82.se/api/users/{id}

Update an existing user in the system. Requires permission to manage users.

Body Parameters

Param Name	Value Rules
name	`min:2` `max:100`
email	`min:2` `email` `unique:users,email,NULL,id`
external_auth_id	`string`
language	`string` `max:15` `alpha_dash`
password	`min:8`
roles	`array`
roles.*	`integer`

Example Request

{
  "name": "Dan Spaggleforth",
  "email": "dspaggles@example.com",
  "roles": [2],
  "language": "de",
  "password": "hunter2000"
}

Example Response

{
  "id": 1,
  "name": "Dan Spaggleforth",
  "email": "dspaggles@example.com",
  "created_at": "2022-02-03T16:27:55.000000Z",
  "updated_at": "2022-02-03T16:27:55.000000Z",
  "external_auth_id": "abc123456",
  "slug": "dan-spaggleforth",
  "last_activity_at": "2022-02-03T16:27:55.000000Z",
  "profile_url": "https://docs.example.com/user/dan-spaggleforth",
  "edit_url": "https://docs.example.com/settings/users/1",
  "avatar_url": "https://docs.example.com/uploads/images/user/2021-10/thumbs-50-50/profile-2021.jpg",
  "roles": [
    {
      "id": 2,
      "display_name": "Editors"
    }
  ]
}

delete

DELETE https://chatbase.h82.se/api/users/{id}

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 Parameters

Param Name	Value Rules
migrate_ownership_id	`integer` `exists:users,id`

Example Request

{
  "migrate_ownership_id": 5
}

recycle-bin

list

GET https://chatbase.h82.se/api/recycle-bin

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.

Example Response

{
  "data": [
    {
      "id": 18,
      "deleted_by": 1,
      "created_at": "2022-04-20T12:57:46.000000Z",
      "updated_at": "2022-04-20T12:57:46.000000Z",
      "deletable_type": "page",
      "deletable_id": 2582,
      "deletable": {
        "id": 2582,
        "book_id": 25,
        "chapter_id": 0,
        "name": "A Wonderful Page",
        "slug": "a-wonderful-page",
        "priority": 9,
        "created_at": "2022-02-08T00:44:45.000000Z",
        "updated_at": "2022-04-20T12:57:46.000000Z",
        "created_by": 1,
        "updated_by": 1,
        "draft": false,
        "revision_count": 1,
        "template": false,
        "owned_by": 1,
        "editor": "wysiwyg",
        "book_slug": "a-great-book",
        "parent": {
          "id": 25,
          "name": "A Great Book",
          "slug": "a-great-book",
          "description": "",
          "created_at": "2022-01-24T16:14:28.000000Z",
          "updated_at": "2022-03-06T15:14:50.000000Z",
          "created_by": 1,
          "updated_by": 1,
          "owned_by": 1,
          "type": "book"
        }
      }
    },
    {
      "id": 19,
      "deleted_by": 1,
      "created_at": "2022-04-25T16:07:46.000000Z",
      "updated_at": "2022-04-25T16:07:46.000000Z",
      "deletable_type": "book",
      "deletable_id": 13,
      "deletable": {
        "id": 13,
        "name": "A Big Book!",
        "slug": "a-big-book",
        "description": "This is a very large book with loads of cool stuff in it!",
        "created_at": "2021-11-08T11:26:43.000000Z",
        "updated_at": "2022-04-25T16:07:47.000000Z",
        "created_by": 27,
        "updated_by": 1,
        "owned_by": 1,
        "pages_count": 208,
        "chapters_count": 50
      }
    }
  ],
  "total": 2
}

restore

PUT https://chatbase.h82.se/api/recycle-bin/{deletionId}

Restore a single deletion from the recycle bin. Requires permission to manage both system settings and permissions.

Example Response

{
  "restore_count": 2
}

destroy

DELETE https://chatbase.h82.se/api/recycle-bin/{deletionId}

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.

Example Response

{
  "delete_count": 2
}