Add Files to Collection Node

Upload files to a Needle collection for indexing and search.

The Add Files to Collection node adds one or more files to a Needle collection. Files can be provided via public URLs or base64 data URLs. Once added, the files are automatically indexed and become searchable. This node is commonly used in scraping and data ingestion workflows to store extracted content.

Parameters

Parameter	Type	Required	Default	Description
collectionId	string	✅		The Needle collection to add files to
files	string	✅	""	JSON array of files to add (supports expressions)
instructions	string	❌	""	Additional instructions (template mode)
runMode	string	✅	item	Run mode: item or input

collectionId

Type: string | Required: ✅

The ID of the Needle collection to add files to. The user must have editor or owner access to the collection.

files

Type: string | Required: ✅

A JSON array of file objects to add. Each file must have a name and url property. Optionally, you can include labels for each file.

File object format:

[
  {
    "name": "document.pdf",
    "url": "https://example.com/document.pdf",
    "labels": [{ "key": "category", "type": "string", "value": "report" }]
  }
]

Supported URL formats:

• Public URLs: https://example.com/file.pdf
• Data URLs (base64): data:application/pdf;base64,JVBERi0xLjQ...

instructions

Type: string | Required: ❌

Additional natural language instructions. Evaluated in template mode.

runMode

Type: string | Required: ✅ | Default: item

Controls how the node processes input data:

• item — Runs once per array element. Use item in expressions.
• input — Runs once for the entire input. Use input in expressions.

Configuring This Node

When you click the Add Files to Collection node in the workflow builder, a configuration panel appears with the following sections from top to bottom:

Run Mode & Continue on Error

At the top of the panel is a Run Mode dropdown with two options:

• Item — The node executes once for every element in the input array. Use item in expressions to reference the current element.
• Input — The node executes once for the entire input. Use input in expressions to reference the full input.

Next to the dropdown is a Continue on Error toggle. When enabled, the workflow continues executing downstream nodes even if this node fails. The error is captured in the node's output so downstream nodes can inspect and handle it.

Collection

A dropdown that lists all Needle collections available to you. Select the target collection where files will be added. The selected collection's ID is used as the collectionId parameter.

Instructions

A template text area for optional AI instructions. Supports ${...} template literal syntax for inserting dynamic values. These instructions guide the AI agent in how to use the tool when the node is part of an AI-driven workflow.

Property Fields

The remaining parameters (files) are displayed as property fields, organized into Required and Optional sections based on the node's schema. Each field has a mode toggle that lets you switch between three parameter modes:

• Fixed — Enter a static value directly in the field.
• Expression — Write a JavaScript expression that is evaluated at runtime. Expressions can reference input, item, and other context objects.
• AI Decide — Let the AI agent determine the value based on the surrounding context and instructions.

Examples

1. Add Files from Scraped Data

Add pages scraped by a previous node:

Parameters:

{
  "runMode": "item",
  "collectionId": "<your-collection-id>",
  "files": "[{ name: item.name, url: item.url }]",
  "instructions": "Add scraped page content to collection",
  "parameterMode": {
    "files": "expression"
  }
}

2. Conditionally Add Files

Add a file only if a previous step succeeded:

Parameters:

{
  "runMode": "input",
  "collectionId": "<your-collection-id>",
  "files": "input.success ? [{ \"name\": input.name, \"url\": input.url }] : []",
  "instructions": "Add transcript to collection",
  "parameterMode": {
    "files": "expression"
  },
  "continueOnError": true
}

3. Add Files with Labels

Add files and tag them with metadata labels:

Parameters:

{
  "runMode": "item",
  "collectionId": "<your-collection-id>",
  "files": "[{ name: item.name, url: item.url, labels: [{ key: \"source\", type: \"string\", value: \"focus-group\" }] }]",
  "instructions": "Add transcript to collection for RAG",
  "parameterMode": {
    "files": "expression"
  }
}

Output Structure

The node returns confirmation of the added files:

{
  "files": [
    {
      "id": "fle_01ABC...",
      "name": "document.pdf",
      "status": "processing"
    }
  ]
}

Important Notes

• Editor access required: The user must have editor or owner permissions on the collection.
• Indexing is asynchronous: Files are queued for indexing after being added. They will not appear in search results until indexing completes.
• File format: The files parameter must be a valid JSON array. When using expression mode, ensure the expression evaluates to a proper array.
• Labels: Labels are optional key-value pairs that can be attached to files for filtering and organization.
• Continue on Error: Use the toggle at the top of the configuration panel to allow the workflow to continue even if this node fails. The error details are captured in the node's output for downstream handling.
• Parameter modes: Each property field can be switched between Fixed (static value), Expression (runtime JavaScript expression), and AI Decide (let the AI agent choose the value) modes using the toggle on the field.