BookStack icon

BookStack

Consume BookStack API
Join our community

Actions56

Overview

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

Common scenarios where this node is beneficial include:

  • Fetching all shelves in a BookStack instance to display or process their metadata.
  • Automating documentation workflows by listing collections (shelves) before performing further actions like updating or exporting content.
  • Integrating BookStack shelf data into other systems or dashboards.

Practical example:

  • A user wants to retrieve all shelves to generate a report on how documentation is organized across different collections.
  • An automation that syncs shelf information with an external catalog or search index.

Properties

Name Meaning
Tool Description Choose how to determine the resource and operation:
- Set Automatically
- Set Manually
Request Description When "Set Automatically" is selected, describe your request in natural language (e.g., "List all shelves") and the system will infer the appropriate resource and operation.

Note: For this specific Resource-Operation (Shelf - Get Many), typically "Tool Description" would be set to "manual" and "Resource" set to "Shelf", "Operation" set to "Get Many". However, if "automatic" is chosen, the node attempts to parse the description text to detect the intent.

Output

The output is an array of JSON objects representing the shelves retrieved from the BookStack API. Each item corresponds to one shelf resource and contains its properties as returned by the API under the json field.

Example structure of each output item’s json field (based on typical BookStack shelf data):

{
  "id": 1,
  "name": "Shelf Name",
  "description": "Description of the shelf",
  "created_at": "2023-01-01T12:00:00Z",
  "updated_at": "2023-01-02T12:00:00Z",
  // ... other shelf-specific fields
}

The node does not output binary data for this operation.

Dependencies

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

Troubleshooting

  • Common issues:

    • Incorrect or missing API credentials will cause authentication failures.
    • Providing an invalid base URL or network connectivity issues will prevent API calls.
    • If using automatic tool description mode, ambiguous or unclear descriptions may lead to incorrect resource or operation detection.

  • Error messages:

    • Authentication errors typically indicate invalid or expired tokens; verify and update credentials.
    • HTTP 404 errors may occur if the endpoint URL is malformed or the resource does not exist.
    • Parsing errors in automatic mode suggest refining the request description for clearer intent.

  • Resolution tips:

    • Double-check API credentials and ensure they have sufficient permissions.
    • Use manual mode to explicitly select resource and operation if automatic detection fails.
    • Review logs/debug output for detailed error context.

Links and References

Discussion