Batch Workflow Operations

Overview

The n8n_update_partial_workflow tool enables efficient workflow modifications using diff operations. This approach reduces token usage by 80-90% compared to sending complete workflow JSON.

Why Use Diff Operations?

Token Efficiency

80-90% reduction in token usage vs full workflow updates

Precise Edits

Target specific nodes and connections without affecting others

Clear Intent

Each operation describes exactly what changes

Reduced Risk

Less chance of accidentally modifying unrelated parts

Basic Structure

All batch operations follow this structure:

{
  "id": "workflow-id",
  "operations": [
    {
      "type": "operation-type",
      "...operation-specific-fields..."
    }
  ]
}

Operation Types

Node Operations
Connection Operations
Workflow Metadata

Add Node

{
  "type": "addNode",
  "description": "Add HTTP Request node to fetch data",
  "node": {
    "name": "Fetch User Data",
    "type": "n8n-nodes-base.httpRequest",
    "position": [600, 300],
    "parameters": {
      "url": "https://api.example.com/users",
      "method": "GET",
      "authentication": "none"
    }
  }
}

Remove Node

{
  "type": "removeNode",
  "nodeName": "Old Node Name",
  "description": "Remove deprecated node"
}

Update Node

{
  "type": "updateNode",
  "nodeName": "HTTP Request",
  "changes": {
    "parameters.url": "https://new-api.example.com/v2/users",
    "parameters.headers.parameters": [
      {
        "name": "Authorization",
        "value": "Bearer {{$credentials.apiKey}}"
      }
    ]
  },
  "description": "Update API endpoint to v2"
}

Move Node

{
  "type": "moveNode",
  "nodeName": "Set Variable",
  "position": [800, 400],
  "description": "Reposition for better layout"
}

Enable/Disable Node

{
  "type": "disableNode",
  "nodeName": "Debug Node",
  "description": "Disable debug output for production"
}

Add Connection

CRITICAL: Use four separate string parameters for connections.

Correct Format

{
  "type": "addConnection",
  "source": "source-node-name",
  "target": "target-node-name",
  "sourcePort": "main",
  "targetPort": "main",
  "description": "Connect nodes"
}

Wrong Formats

// ❌ Object format (fails)
{
  "type": "addConnection",
  "connection": {
    "source": { "nodeId": "node-1" }
  }
}

// ❌ Combined string (fails)
{
  "type": "addConnection",
  "source": "node-1:main:0"
}

IF Node Connections

IF nodes have two outputs (TRUE and FALSE). Use the branch parameter:

True Branch

{
  "type": "addConnection",
  "source": "If Node",
  "target": "Success Handler",
  "sourcePort": "main",
  "targetPort": "main",
  "branch": "true"
}

False Branch

{
  "type": "addConnection",
  "source": "If Node",
  "target": "Error Handler",
  "sourcePort": "main",
  "targetPort": "main",
  "branch": "false"
}

Switch Node Connections

Switch nodes have multiple outputs. Use the case parameter:

{
  "type": "addConnection",
  "source": "Switch",
  "target": "Handler A",
  "sourcePort": "main",
  "targetPort": "main",
  "case": 0,
  "description": "Route case 0 to Handler A"
}

Remove Connection

{
  "type": "removeConnection",
  "source": "Old Source",
  "target": "Old Target",
  "sourcePort": "main",
  "targetPort": "main",
  "description": "Remove unused connection"
}

Rewire Connection

{
  "type": "rewireConnection",
  "source": "Webhook",
  "from": "Old Handler",
  "to": "New Handler",
  "description": "Rewire to new handler"
}

Update Name

{
  "type": "updateName",
  "name": "Production User Sync v2",
  "description": "Update workflow name for versioning"
}

Update Settings

{
  "type": "updateSettings",
  "settings": {
    "executionTimeout": 300,
    "saveDataErrorExecution": "all",
    "timezone": "America/New_York"
  },
  "description": "Configure production settings"
}

Manage Tags

Add Tag

{
  "type": "addTag",
  "tag": "production",
  "description": "Mark as production workflow"
}

Remove Tag

{
  "type": "removeTag",
  "tag": "development"
}

Transactional Updates

Batch operations use two-pass processing for atomic updates:

Pass 1: Node Operations

All node operations execute first:

addNode
removeNode
updateNode
moveNode
enableNode / disableNode

Pass 2: Other Operations

After nodes are ready:

Connection operations
Settings updates
Metadata changes

Benefits

Order Independence: Operations can be in any order
Atomic Updates: All operations succeed or all fail
Intuitive Usage: Add nodes and connect them in one call
No Hard Limits: Process unlimited operations efficiently

Example

{
  "id": "workflow-id",
  "operations": [
    // Connections (processed in Pass 2)
    {
      "type": "addConnection",
      "source": "Webhook",
      "target": "Process Data",
      "sourcePort": "main",
      "targetPort": "main"
    },
    // Nodes (processed in Pass 1, before connections)
    {
      "type": "addNode",
      "node": {
        "name": "Process Data",
        "type": "n8n-nodes-base.set",
        "position": [400, 300]
      }
    }
  ]
}

The node is added first (Pass 1), then connected (Pass 2), regardless of order in the operations array.

Complete Examples

Add Slack Notification

{
  "id": "workflow-123",
  "operations": [
    {
      "type": "addNode",
      "node": {
        "name": "Send Slack Alert",
        "type": "n8n-nodes-base.slack",
        "position": [1000, 300],
        "parameters": {
          "resource": "message",
          "operation": "post",
          "channel": "#alerts",
          "text": "Workflow completed successfully!"
        }
      }
    },
    {
      "type": "addConnection",
      "source": "Process Data",
      "target": "Send Slack Alert",
      "sourcePort": "main",
      "targetPort": "main"
    }
  ]
}

Update Multiple Webhooks

{
  "id": "workflow-456",
  "operations": [
    {
      "type": "updateNode",
      "nodeName": "Webhook 1",
      "changes": {
        "parameters.path": "v2/webhook1"
      }
    },
    {
      "type": "updateNode",
      "nodeName": "Webhook 2",
      "changes": {
        "parameters.path": "v2/webhook2"
      }
    },
    {
      "type": "updateName",
      "name": "API v2 Webhooks"
    }
  ]
}

Add Error Handling

{
  "id": "workflow-789",
  "operations": [
    {
      "type": "addNode",
      "node": {
        "name": "Error Handler",
        "type": "n8n-nodes-base.errorTrigger",
        "position": [200, 500]
      }
    },
    {
      "type": "addNode",
      "node": {
        "name": "Send Error Email",
        "type": "n8n-nodes-base.emailSend",
        "position": [400, 500],
        "parameters": {
          "toEmail": "[email protected]",
          "subject": "Workflow Error",
          "text": "={{$json.error.message}}"
        }
      }
    },
    {
      "type": "addConnection",
      "source": "Error Handler",
      "target": "Send Error Email",
      "sourcePort": "main",
      "targetPort": "main"
    }
  ]
}

Large Batch Refactoring

This example shows 26 operations in a single request:

{
  "id": "workflow-batch",
  "operations": [
    // Add 10 processing nodes
    { "type": "addNode", "node": { "name": "Filter Active Users", "type": "n8n-nodes-base.filter" } },
    { "type": "addNode", "node": { "name": "Transform Data", "type": "n8n-nodes-base.set" } },
    { "type": "addNode", "node": { "name": "Validate Email", "type": "n8n-nodes-base.if" } },
    // ... 7 more nodes

    // Connect all nodes
    { "type": "addConnection", "source": "Filter Active Users", "target": "Transform Data" },
    { "type": "addConnection", "source": "Transform Data", "target": "Validate Email" },
    // ... more connections

    // Update metadata
    { "type": "updateName", "name": "User Processing Pipeline v2" },
    { "type": "updateSettings", "settings": { "timezone": "UTC" } },
    { "type": "addTag", "tag": "production" }
  ]
}

No operation limits - process as many changes as needed!

Common Patterns

Insert Processing Step

{
  "operations": [
    {
      "type": "removeConnection",
      "source": "Source Node",
      "target": "Target Node",
      "sourcePort": "main",
      "targetPort": "main"
    },
    {
      "type": "addNode",
      "node": {
        "name": "Process Step",
        "type": "n8n-nodes-base.set",
        "position": [600, 300]
      }
    },
    {
      "type": "addConnection",
      "source": "Source Node",
      "target": "Process Step",
      "sourcePort": "main",
      "targetPort": "main"
    },
    {
      "type": "addConnection",
      "source": "Process Step",
      "target": "Target Node",
      "sourcePort": "main",
      "targetPort": "main"
    }
  ]
}

Replace Node

{
  "operations": [
    {
      "type": "addNode",
      "node": {
        "name": "New Implementation",
        "type": "n8n-nodes-base.httpRequest",
        "position": [600, 300]
      }
    },
    {
      "type": "rewireConnection",
      "source": "Previous Node",
      "from": "Old Implementation",
      "to": "New Implementation"
    },
    {
      "type": "removeNode",
      "nodeName": "Old Implementation"
    }
  ]
}

Batch Node Updates

{
  "operations": [
    {
      "type": "updateNode",
      "nodeName": "Node 1",
      "changes": { "position": [100, 200] }
    },
    {
      "type": "updateNode",
      "nodeName": "Node 2",
      "changes": { "position": [300, 200] }
    },
    {
      "type": "updateNode",
      "nodeName": "Node 3",
      "changes": { "position": [500, 200] }
    },
    {
      "type": "cleanStaleConnections"
    }
  ]
}

Error Handling

The tool validates all operations before applying changes:

Common validation errors:

Duplicate node names: Each node must have a unique name
Invalid node types: Use full package prefixes (e.g., n8n-nodes-base.webhook)
Missing connections: Referenced nodes must exist
Circular dependencies: Connections cannot create loops

Handling Errors

{
  "valid": false,
  "errors": [
    {
      "operation": 2,
      "type": "invalid_reference",
      "message": "Source node 'Nonexistent' not found"
    }
  ]
}

Fix the error and retry:

{
  "operations": [
    // First add the node
    { "type": "addNode", "node": { "name": "Nonexistent" } },
    // Then reference it
    { "type": "addConnection", "source": "Nonexistent", "target": "Other" }
  ]
}

Best Practices

Descriptive Names

Use clear node names and operation descriptions

Batch Related Changes

Group related operations in a single request

Validate First

Use validateOnly: true to test operations

Reference by Name

Prefer node names over IDs for readability

Small Focused Changes

Make targeted edits rather than large rewrites

Use Descriptions

Add descriptions to document intent

Performance Tips

Batch operations: Combine multiple changes in one request
No limits: Process unlimited operations efficiently
Atomic updates: All succeed or all fail (unless continueOnError enabled)
Order independence: Don’t worry about operation order (two-pass processing)

Next Steps

Building Workflows

Learn the complete workflow building process

Validation Strategies

Validate changes before applying

AI Agent Workflows

Building AI Agent workflows

Troubleshooting

Common batch operation issues

Get Started

Deployment

Configuration

IDE Integration

Core Concepts

Guides

​Overview

​Why Use Diff Operations?

Token Efficiency

Precise Edits

Clear Intent

Reduced Risk

​Basic Structure

​Operation Types

​Add Node

​Remove Node

​Update Node

​Move Node

​Enable/Disable Node

​Add Connection

​IF Node Connections

​Switch Node Connections

​Remove Connection

​Rewire Connection

​Update Name

​Update Settings

​Manage Tags

​Transactional Updates

​Benefits

​Example

​Complete Examples

​Common Patterns

​Insert Processing Step

​Replace Node

​Batch Node Updates

​Error Handling

​Handling Errors

​Best Practices

Descriptive Names

Batch Related Changes

Validate First

Reference by Name

Small Focused Changes

Use Descriptions

​Performance Tips

​Next Steps

Building Workflows

Validation Strategies

AI Agent Workflows

Troubleshooting

Build docs developers (and LLMs) love

Overview

Why Use Diff Operations?

Basic Structure

Operation Types

Add Node

Remove Node

Update Node

Move Node

Enable/Disable Node

Add Connection

IF Node Connections

Switch Node Connections

Remove Connection

Rewire Connection

Update Name

Update Settings

Manage Tags

Transactional Updates

Benefits

Example

Complete Examples

Common Patterns

Insert Processing Step

Replace Node

Batch Node Updates

Error Handling

Handling Errors

Best Practices

Performance Tips

Next Steps