BookStack icon

BookStack

Consume BookStack API

Actions40

Overview

This node integrates with the BookStack API to manage various BookStack resources such as books, pages, chapters, shelves, users, roles, attachments, and tags. Specifically for the Shelf - Create operation, it allows users to create a new shelf resource in their BookStack instance.

The node supports two modes of operation:

  • Automatic mode: Users provide a natural language description of what they want to do (e.g., "Create a new shelf about project documentation"), and the node attempts to parse this description to determine the appropriate resource and operation, then constructs the request accordingly.
  • Manual mode: Users explicitly select the resource ("Shelf") and operation ("Create") and provide the required properties directly.

Typical use cases include automating the creation of organizational structures within BookStack, such as adding new shelves to categorize collections of books, which is useful for documentation teams or knowledge bases that need to programmatically manage content organization.

Example: Automatically creating a shelf named "Engineering Docs" with a description "Collection of engineering related books" by either describing the request or manually entering the name and description.

Properties

Name Meaning
Tool Description Choose how to determine the resource and operation:
- Set Automatically
- Set Manually
Request Description (Shown if Tool Description is Automatic) A text input where you describe your request in natural language, e.g., "Create a new page about API documentation". The system uses this to infer resource and operation.
Name (Required for create/update on shelf) The name of the shelf to create.
Description (Optional for create/update on shelf) A textual description of the shelf.

Output

The node outputs an array of JSON objects corresponding to each input item processed. For the Shelf Create operation, the output JSON contains the response from the BookStack API representing the newly created shelf resource. This typically includes fields like the shelf's ID, name, description, creation timestamps, and other metadata as returned by the API.

No binary data output is produced by this node.

Dependencies

  • Requires connection to a BookStack instance via its API.
  • Requires an API authentication token credential configured in n8n to authorize requests.
  • The base URL of the BookStack API and authentication tokens must be set up in the node credentials.
  • HTTP requests are made using the BookStack API endpoints under /api/shelfs (pluralized resource path).

Troubleshooting

  • Common issues:

    • Incorrect or missing API credentials will cause authentication failures.
    • Providing invalid or empty "Name" property when creating a shelf will result in API errors.
    • If using automatic mode, ambiguous or unclear request descriptions may lead to incorrect resource/operation detection.
    • Network connectivity issues to the BookStack server can cause request failures.

  • Error messages:

    • Authentication errors: Check that the API token and base URL are correctly configured.
    • Validation errors from the API (e.g., missing required fields): Ensure all required properties like "Name" are provided.
    • Parsing errors in automatic mode: Try simplifying or clarifying the request description.

Links and References

Discussion