Directus icon

Directus

Consume Directus API

Actions100

Overview

The Directus node for n8n, when configured with the Resource: Roles and Operation: List, retrieves a list of roles from a Directus instance. This operation is useful for automating user management workflows, auditing permissions, or integrating role data into other systems. For example, you might use this node to:

  • Fetch all available roles to display in a dashboard.
  • Export role definitions for compliance or backup purposes.
  • Filter or aggregate roles based on custom criteria.

Properties

Name Type Meaning
Return All boolean If enabled, returns all results; if disabled, limits the number of returned roles according to the "Limit" property.
Limit number The maximum number of roles to return (only shown if "Return All" is false). Must be between 1 and 100.
Split Into Items boolean If enabled, outputs each role as a separate item in the workflow; otherwise, returns all roles in a single item.
JSON/RAW Parameters boolean If enabled, allows setting query parameters as raw JSON instead of using the UI fields.
Query Parameters json Custom query parameters as a flat JSON object (only used if "JSON/RAW Parameters" is true).
Additional Fields collection A set of optional fields to further customize the request, including:
- Aggregate collection Aggregation functions to perform calculations on role data (e.g., count, sum, average, min, max, etc.).
- Binary Property for Export Data string Name of the binary property to which exported data will be attached.
- Deep (JSON) json Allows setting nested query parameters for relational datasets.
- Export options Format to export the API response as a file (json, csv, xml).
- Fields string Specifies which fields to include in the response.
- File Name for Export Data string File name (without extension) for exported data.
- Filter (JSON) json Conditions to filter the roles returned.
- Group By string Field(s) to group results by, enabling grouped aggregations.
- Meta string Specifies what metadata to include in the response.
- Offset number Number of items to skip (for pagination).
- Search string Search term to filter roles containing the given query in any field.
- Sort string Sorting order for the returned roles. Accepts CSV of fields, minus sign for descending, or ? for random order.

Output

  • Standard Output:
    The node outputs an array of role objects under the json field. Each object represents a role with its properties as defined in your Directus instance (e.g., id, name, description, permissions, etc.).
  • Split Into Items:
    If "Split Into Items" is enabled, each output item contains a single role object.
  • Binary Output:
    If the "Export" option is used, the response is also provided as a binary file (in the specified format: JSON, CSV, or XML) attached to the output item under the property name defined in "Binary Property for Export Data".

Example Output Structure

[
  {
    "json": {
      "id": "1234",
      "name": "Administrator",
      "description": "Full access to all resources.",
      // ...other role fields
    }
  },
  {
    "json": {
      "id": "5678",
      "name": "Editor",
      "description": "Can edit content.",
      // ...other role fields
    }
  }
]

If exporting:

{
  "json": { /* role data or summary */ },
  "binary": {
    "data": { /* binary file buffer and metadata */ }
  }
}

Dependencies

  • Directus API:
    Requires access to a running Directus instance with API credentials configured in n8n.
  • n8n Credentials:
    You must set up a credential of type directusApi in n8n, providing the necessary API URL and authentication details.

Troubleshooting

  • Common Issues:

    • Invalid Credentials:
      If the API credentials are incorrect or missing, the node will fail with an authentication error. Ensure your Directus API credentials are correctly configured in n8n.
    • API Connection Errors:
      Network issues or incorrect API URLs can cause connection failures. Double-check the Directus instance URL and network accessibility.
    • Malformed JSON:
      If using "JSON/RAW Parameters" or any JSON input, ensure the JSON is valid. Malformed JSON will result in parsing errors.
    • Limit Exceeded:
      If "Limit" is set outside the allowed range (1–100), the node may throw a validation error.

  • Error Messages:

    • "Cannot read property 'data' of undefined": Usually indicates that the API response did not contain the expected structure. Check your query parameters and Directus API version.
    • "Unexpected token ... in JSON": Indicates invalid JSON input. Validate your JSON syntax.
    • "Request failed with status code 401": Authentication failure. Recheck your credentials.

Links and References

Summary:
This node operation provides a flexible way to fetch, filter, aggregate, and export role data from Directus, supporting both simple and advanced use cases through its rich set of input properties.

Discussion