Add Labels to File Node

Add metadata labels to a file in a Needle collection.

The Add Labels to File node attaches key-value label pairs to a specific file in a collection. Labels can be used to categorize, tag, and filter files — for example, adding a "status" label, a "department" label, or classification results from an AI node.

Parameters

Parameter	Type	Required	Default	Description
collectionId	string	✅		The Needle collection containing the file
fileId	string	✅	""	The ID of the file to add labels to (supports expressions)
labels	string	✅	"[]"	JSON array of labels 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 containing the file.

fileId

Type: string | Required: ✅

The ID of the file to add labels to. Must start with the fle_ prefix.

Examples:

• Static: fle_01ABC123
• Dynamic (expression): input.fileId

labels

Type: string | Required: ✅ | Default: "[]"

A JSON array of label objects to add. Each label has three properties:

Field	Type	Description
key	string	The label key (e.g. category, status)
type	string	The label type (e.g. string)
value	string	The label value (e.g. report, reviewed)

Example:

[
  { "key": "category", "type": "string", "value": "invoice" },
  { "key": "status", "type": "string", "value": "processed" }
]

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.
• input — Runs once for the entire input.

Configuring This Node

When you select an Add Labels to File node on the workflow canvas, the right-hand configuration panel displays the following sections from top to bottom:

Run Mode & Error Handling

At the top of the panel you will find:

• Run Mode dropdown — Choose between Item (the node executes once per array element) and Input (the node executes once for the entire input object). This corresponds to the runMode parameter.
• Continue on Error toggle — When enabled, the workflow continues to the next node even if this node encounters an error. When disabled (the default), a node error will stop the workflow run.

Variables

A multi-select dropdown that lets you bind workflow variables to this node. Bound variables become accessible in expressions via the variables object (e.g. variables.myVar). You can also click the Create variable button to define a new workflow variable inline without leaving the node panel.

Collection

A dropdown listing all Needle collections you have access to. Select the collection that contains the file you want to label. This sets the collectionId parameter.

Instructions

A template text area where you can provide natural language guidance. Use ${...} syntax to interpolate dynamic values from the workflow context. For example:

Add a "${variables.labelKey}" label with value "${variables.labelValue}" to the file.

Property Fields

Below the Instructions area, property fields are organized into Required and Optional sections:

• fileId (Required) — The ID of the file to add labels to.
• labels (Required) — A JSON array of label objects, each with key, type, and value fields.

Each property field has a parameter mode selector (accessible via a small icon on the field) with three options:

Mode	Description
Fixed	Enter a static value directly (e.g. paste a file ID or a JSON array of labels).
Expression	Write a JavaScript expression with access to input, item, and variables from the workflow.
AI Decide	Let the AI agent determine the value at runtime based on the node's instructions and context.

Examples

1. Add Static Labels

Tag a file with fixed labels:

Parameters:

{
  "runMode": "input",
  "collectionId": "<your-collection-id>",
  "fileId": "fle_01ABC123",
  "labels": "[{\"key\": \"status\", \"type\": \"string\", \"value\": \"reviewed\"}]"
}

2. Add Dynamic Labels from AI Classification

Apply labels from a previous AI node's structured output:

Parameters:

{
  "runMode": "input",
  "collectionId": "<your-collection-id>",
  "fileId": "input.fileId",
  "labels": "input.labels",
  "parameterMode": {
    "fileId": "expression",
    "labels": "expression"
  },
  "continueOnError": true
}

3. Label Files in a Loop

Process an array of files and label each one:

Parameters:

{
  "runMode": "item",
  "collectionId": "<your-collection-id>",
  "fileId": "item.id",
  "labels": "[{\"key\": \"processed\", \"type\": \"string\", \"value\": \"true\"}]",
  "parameterMode": {
    "fileId": "expression"
  }
}

Output Structure

The node returns confirmation of the labels added:

{
  "fileId": "fle_01ABC123",
  "labels": [{ "key": "status", "type": "string", "value": "reviewed" }]
}

Important Notes

• Label format: Labels must follow the { key, type, value } format. The labels parameter can be a JSON string or an expression that evaluates to an array.
• Collection access: The user must have at least viewer access to the collection.
• Additive: Adding labels does not remove existing labels. To remove labels, use the Remove Labels from File node.
• Common pattern: AI Node (classify) → Add Labels to File is a common pipeline for auto-categorizing documents.
• Continue on Error: Enable the Continue on Error toggle in the node panel to allow the workflow to proceed even if labeling fails (e.g. invalid file ID or permission error). This is especially useful when labeling files in a loop where individual failures should not stop the entire batch.
• Workflow Variables: Bind workflow variables to this node to use them in expressions. For example, use variables.defaultCategory in a labels expression to apply a configurable default label across runs.
• Parameter modes: Each property field supports three modes — Fixed (static value), Expression (JavaScript with access to input, item, variables), and AI Decide (the AI agent determines the value at runtime). Choose the mode that fits your use case via the mode selector on each field.