BookStack

Consume BookStack API

Actions40

Overview

This node integrates with the BookStack API to manage various resources such as books, pages, chapters, shelves, users, roles, attachments, and tags. Specifically for the Role resource with the Get Many operation, it retrieves a list of role resources from the BookStack system.

Common scenarios where this node is beneficial include:

Fetching all user roles defined in a BookStack instance to audit permissions.
Integrating role data into workflows that require role-based access control information.
Automating reports or synchronizations involving user roles.

Practical example:

You want to retrieve all roles available in your BookStack documentation platform to display them in an external dashboard or to assign roles programmatically based on certain criteria.

Properties

Name	Meaning
Tool Description	Choose how to determine the resource and operation: either "Set Automatically" or "Set Manually".
Request Description	When "Set Automatically" is selected, describe what you want to do (e.g., "List all roles") and the system will automatically select the appropriate resource and operation.

Note: For this specific Resource-Operation ("Role" - "Get Many"), typically the "Tool Description" would be set to "manual" or "automatic" with a description that leads to fetching multiple roles.

Output

The output is an array of JSON objects representing the retrieved roles from the BookStack API. Each item corresponds to one role resource with its properties as returned by the API.

Example structure of each role object (based on typical BookStack API responses, not explicitly shown in code):

{
  "id": 1,
  "name": "Editor",
  "description": "Can edit content",
  "system_role": false,
  "external_auth_id": null,
  ...
}

No binary data output is produced by this node.

Dependencies

Requires connection to a BookStack instance via its API.
Needs an API token credential configured in n8n with:
- Base URL of the BookStack API.
- Authentication token and secret.
The node uses HTTP requests authenticated with these credentials to interact with the BookStack API.

Troubleshooting

Common issues:
- Incorrect or missing API credentials leading to authentication errors.
- Network connectivity problems preventing access to the BookStack API.
- Using "automatic" tool description with vague or unsupported request descriptions may lead to incorrect resource/operation detection.
Error messages:
- Authentication failures: Check that the API token and base URL are correct.
- 404 Not Found: Verify that the BookStack API endpoint is reachable and the resource path is correct.
- Validation errors: Ensure required parameters are provided when using manual mode.
Resolutions:
- Double-check API credentials and permissions.
- Use clear and precise request descriptions if using automatic mode.
- Switch to manual mode and explicitly select "Role" and "Get Many" if automatic detection fails.