+ 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:
+
To access the API a user has to have the "Access System API" permission enabled on one of their assigned roles. @@ -16,8 +41,70 @@
The API is primarily design to be interfaced using JSON so the majority of API endpoints, that accept data, will read JSON request data although application/x-www-form-urlencoded request data is also accepted. Endpoints that receive file data will need data sent in a multipart/form-data format although this will be highlighted in the documentation for such endpoints.
For endpoints in this documentation that accept data, a "Body Parameters" table will be available showing the parameters that will 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.
+ ++ 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:
+
+
+ * 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.
+
+
+
+ * Form requests can accept boolean (true/false) values via a 1 or 0.
+
+
+ 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",
+ "locked": true,
+ "books": [105, 263],
+ "tags": [{"name": "Tag Name", "value": "Tag Value"}],
+}x-www-form-urlencoded
+ +name=My%20new%20item&locked=1&books%5B0%5D=105&books%5B1%5D=263&tags%5B0%5D%5Bname%5D=Tag%20Name&tags%5B0%5D%5Bvalue%5D=Tag%20Valuex-www-form-urlencoded (Decoded for readability)
+ +name=My new item
+locked=1
+books[0]=105
+books[1]=263
+tags[0][name]=Tag Name
+tags[0][value]=Tag Value| Parameter | +Parameter | Details | Examples |
|---|