Remove Labels from File Node

Remove metadata labels from a file in a Needle collection.

The Remove Labels from File node removes specific labels from a file by their label keys. This is useful for cleaning up labels, resetting classification results, or updating file metadata as part of a processing pipeline.

Parameters

Parameter	Type	Required	Default	Description
collectionId	string	✅		The Needle collection containing the file
fileId	string	✅	""	The ID of the file to remove labels from (supports expressions)
labelKeys	string	✅	"[]"	JSON array of label keys to remove (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 remove labels from. Must start with the fle_ prefix.

Examples:

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

labelKeys

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

A JSON array of label key strings to remove. Only the keys are needed — you do not need to specify the type or value.

Example:

["status", "category"]

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 a Remove Labels from 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 whose labels you want to remove. 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:

Remove the "${variables.labelToRemove}" label from 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 remove labels from.
• labelKeys (Required) — A JSON array of label key strings to remove.

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 keys).
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. Remove Specific Labels

Remove the "status" and "category" labels from a file:

Parameters:

{
  "runMode": "input",
  "collectionId": "<your-collection-id>",
  "fileId": "fle_01ABC123",
  "labelKeys": "[\"status\", \"category\"]"
}

2. Remove Labels Dynamically

Use label keys from a previous node's output:

Parameters:

{
  "runMode": "input",
  "collectionId": "<your-collection-id>",
  "fileId": "input.fileId",
  "labelKeys": "input.keysToRemove",
  "parameterMode": {
    "fileId": "expression",
    "labelKeys": "expression"
  }
}

3. Clear Labels from Multiple Files

Process an array of files and remove a label from each:

Parameters:

{
  "runMode": "item",
  "collectionId": "<your-collection-id>",
  "fileId": "item.id",
  "labelKeys": "[\"processed\"]",
  "parameterMode": {
    "fileId": "expression"
  }
}

Output Structure

The node returns confirmation of the labels removed:

{
  "fileId": "fle_01ABC123",
  "removedLabelKeys": ["status", "category"]
}

Important Notes

• Key-based removal: Labels are removed by their key. You do not need to know the value or type — just the key.
• Non-existent keys: Attempting to remove a label key that doesn't exist on the file is a no-op (no error).
• Collection access: The user must have at least viewer access to the collection.
• Complementary to Add Labels: Use Add Labels to File to attach labels, and Remove Labels from File to clean them up.
• Continue on Error: Enable the Continue on Error toggle in the node panel to allow the workflow to proceed even if label removal fails (e.g. invalid file ID or permission error). This is especially useful when removing labels from multiple files in a loop.
• Workflow Variables: Bind workflow variables to this node to use them in expressions. For example, set labelKeys to an expression like variables.keysToClean to make the set of labels to remove configurable 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.