Directus icon

Directus

Consume Directus API

Actions100

Overview

The Directus - File: List operation allows you to retrieve a list of files from your Directus instance. This node is useful for automating file management tasks, such as listing all available files, filtering files based on specific criteria, exporting file metadata, or integrating file data into other workflows.

Common scenarios include:

  • Fetching all files for reporting or backup purposes.
  • Filtering files by type, name, or custom fields.
  • Exporting file lists in CSV, JSON, or XML formats for external processing.
  • Paginating through large sets of files.
  • Aggregating file data (e.g., counting files, summing sizes).

Practical examples:

  • Retrieve all image files uploaded in the last month and export their metadata as a CSV.
  • List files with a specific tag and send their details to another system.
  • Get a paginated list of files for display in a dashboard.

Properties

Name Type Meaning
Return All boolean If enabled, returns all matching files. If disabled, limits the number of results according to the "Limit" property.
Limit number Maximum number of files to return (only used if "Return All" is false). Must be between 1 and 100.
Split Into Items boolean If enabled, outputs each file as a separate item; otherwise, returns an array of files in a single item.
JSON/RAW Parameters boolean If enabled, allows you to specify query parameters as raw JSON instead of using the UI fields.
Query Parameters json (Visible if "JSON/RAW Parameters" is true) Custom query parameters as a flat JSON object.
Additional Fields collection (Visible if "JSON/RAW Parameters" is false) Extra options for filtering, sorting, aggregating, and exporting files. Includes the following sub-properties:
└ Aggregate collection Define aggregation functions (count, sum, avg, min, max, etc.) to apply to file fields.
└ Binary Property for Export Data string Name of the binary property to store exported file data (used when exporting as a file).
└ Deep (JSON) json Set nested query parameters for related datasets.
└ Export options Export the API response as a file in one of the following formats: csv, json, xml.
└ Fields string Specify which fields to return for each file.
└ File Name for Export Data string File name (without extension) for exported data.
└ Filter (JSON) json Filter conditions for selecting files.
└ Group By string Group results by specified field(s), useful for aggregations.
└ Meta string Specify what metadata to include in the response.
└ Offset number Number of items to skip (for pagination).
└ Search string Search term to filter files by content in any field.
└ Sort string Sorting order for returned files (CSV of fields, use minus sign for descending, question mark for random).

Output

  • The output is an array of file objects, each representing a file in Directus.
  • If "Split Into Items" is enabled, each output item contains a single file's data in its json property.
  • If "Export" is set (csv, json, xml), the exported file will be attached as binary data under the specified binary property name.
  • The structure of each file object depends on the selected fields and filters but typically includes properties like id, filename_download, title, type, filesize, created_on, etc.

Example output (simplified):

[
  {
    "json": {
      "id": "abc123",
      "filename_download": "report.pdf",
      "title": "Monthly Report",
      "type": "application/pdf",
      "filesize": 102400,
      "created_on": "2024-06-01T12:00:00Z"
      // ...other fields depending on selection
    }
  },
  {
    "json": {
      "id": "def456",
      "filename_download": "image.png",
      "title": "Logo",
      "type": "image/png",
      "filesize": 20480,
      "created_on": "2024-05-15T09:30:00Z"
      // ...other fields
    }
  }
]
  • If exporting, the output will also contain a binary property with the exported file.

Dependencies

  • Directus API: Requires access to a running Directus instance.
  • API Credentials: You must configure the directusApi credentials in n8n for authentication.
  • n8n Environment: No special environment variables are required beyond standard n8n setup.

Troubleshooting

Common issues:

  • Authentication errors: Ensure your Directus API credentials are correct and have permission to list files.
  • Invalid query/filter syntax: When using JSON/RAW parameters or filters, ensure your JSON is valid and matches Directus API expectations.
  • Large result sets: If "Return All" is enabled and there are many files, performance may be affected.
  • Export errors: If exporting, ensure the binary property name does not conflict with existing properties.

Error messages:

  • "error": "Request failed with status code 401": Check your API credentials.
  • "error": "Unexpected token ... in JSON": There is a syntax error in your JSON input.
  • "error": "Field 'xyz' does not exist": The specified field in filters, sort, or group by does not exist in the files collection.

Links and References

Discussion