File Download

Controlled node

Overview

The File Download node downloads files from external URLs via HTTP GET or POST requests and saves them to your project's library as temporary files. It supports custom headers, request bodies (for POST), automatic file type detection, and configurable timeout and retry logic.

This node is useful for fetching files from APIs, webhooks, or external storage that aren't already in your Intellectible library. The downloaded file is returned as a standard file object that can be passed to other nodes like Read CSV, Read PDF, or Read Image.

File Size Limits

The node enforces a maximum download size of 500MB. If the target file exceeds this limit, the download will be aborted and an error returned.

Filename Resolution

The node attempts to determine the filename using the following priority:

1. Content-Disposition header filename parameter
2. Final URL path segment (after redirects)
3. Auto-generated UUID with extension based on MIME type

Inputs

Input	Type	Description	Default
Run	Event	Triggers the file download operation.	-
Method	Enum	HTTP method to use: GET or POST.	GET
File Type	Enum	Expected MIME type of the file. Select "Unknown - best guess" to auto-detect from headers or URL.	Unknown - best guess
URL	Text	The URL to download the file from. Must include protocol (http:// or https://).	-
Headers	Dictionary	Optional HTTP headers to include in the request (e.g., Authorization, Content-Type).	-
Data	Data	Request body for POST requests. Can be text, JSON, or other data types.	-
Timeout	Number	Request timeout in milliseconds (max 300,000ms / 5 minutes).	60000
Retries	Number	Number of retry attempts if the request fails (max 10).	0

File Type Options

Value	Description
Unknown - best guess	Auto-detect from Content-Type header, Content-Disposition, or URL extension
Text File	text/plain
CSV Table	text/csv
Image (jpeg)	image/jpeg
Image (png)	image/png
PDF Document	application/pdf
Zip File	application/zip

Outputs

Output	Type	Description
Done	Event	Fires when the download completes successfully or fails.
Output	Data	File object containing id, name, mimeType, size, and dir. Compatible with file inputs of other nodes. Returns error object if download fails.

Runtime Behavior

When triggered, the node performs the following operations:

1. Pre-flight Check: Sends a HEAD request to check Content-Length and validate the URL (2-second timeout)
2. Size Validation: Aborts if file exceeds 500MB
3. Download: Streams the file with size monitoring to prevent memory issues
4. Storage: Uploads to your project's library as a temporary file
5. Cleanup: Temporary files are automatically managed by the system

Error Handling

If the download fails (network error, timeout, size exceeded, or HTTP error), the Output will contain an error object with the following structure:

{
  "error": "Error message description",
  "errorCode": "ECONNRESET" // or HTTP status code
}

Redirects

The node automatically follows up to 5 redirects (3xx responses).

Example

Downloading a CSV from an API

This example shows downloading a CSV file from an external API and then reading it:

1. Add a Start node and connect its fired event to the File Download node's run input
2. Configure the File Download node:
   • URL: https://api.example.com/v1/reports/data.csv
   • Method: GET
   • Headers: Add Authorization: Bearer YOUR_TOKEN if required
   • File Type: CSV Table (or leave as Unknown)
   • Timeout: 30000 (30 seconds)
3. Connect the File Download node's done event to a Read CSV node's run input
4. Connect the File Download node's output to the Read CSV node's file input

POST Request with Body

To download a file that requires a POST request (e.g., generating a report):

1. Set Method to POST
2. Set URL to the endpoint (e.g., https://api.example.com/v1/export)
3. Set Data to the request body (e.g., {"format": "pdf", "date": "2024-01-01"})
4. Set Headers to include Content-Type: application/json
5. Set File Type to match the expected response (e.g., PDF Document)