Update Partial Workflow

Overview

Update workflows incrementally using targeted diff operations instead of sending the entire workflow. This approach:

Reduces token usage by 80-90% compared to full workflow updates
More precise edits with clearer intent
Supports batching - apply unlimited operations in a single request
Atomic or best-effort - choose transaction behavior

This is the recommended way to update workflows. Use full update only when renaming or changing settings.

Endpoint

PATCH /workflows/:id

Request Parameters

string

required

Workflow ID to update

operations

array

required

Array of diff operations to apply. Each operation must have a type field.Supported Types:

addNode, removeNode, updateNode, moveNode
enableNode, disableNode
addConnection, removeConnection, rewireConnection
activateWorkflow, deactivateWorkflow
updateSettings, updateName
addTag, removeTag
cleanStaleConnections

validateOnly

boolean

default:false

If true, only validate operations without applying them

continueOnError

boolean

default:false

If true, apply valid operations even if some fail (best-effort mode)Default (false) is atomic - all operations succeed or all fail.

createBackup

boolean

default:true

Create version backup before applying operations

intent

string

Human-readable description of changesExample: "Add Slack notification for errors"

Operation Types

Node Operations

addNode

Add a new node to the workflow.

type

string

required

"addNode"

node

object

required

Complete node object (see Create Workflow for structure)

description

string

Human-readable description

Example:

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

removeNode

Remove a node from the workflow.

type

string

required

"removeNode"

nodeName

string

required

Name of the node to remove

Example:

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

updateNode

Update node parameters using dot notation paths.

type

string

required

"updateNode"

nodeName

string

required

Name of the node to update

changes

object

required

Object with dot-notation paths as keys and new values

Example:

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

moveNode

Move a node to a new position on the canvas.

type

string

required

"moveNode"

nodeName

string

required

Name of the node to move

position

array

required

New [x, y] position

Example:

{
  "type": "moveNode",
  "nodeName": "Set Variable",
  "position": [800, 400]
}

enableNode / disableNode

Enable or disable a node.

type

string

required

"enableNode" or "disableNode"

nodeName

string

required

Name of the node

Example:

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

Connection Operations

addConnection

Connect two nodes.

type

string

required

"addConnection"

source

string

required

Source node name

target

string

required

Target node name

sourceOutput

string

default:"main"

Source output type

targetInput

string

default:"main"

Target input type

sourceIndex

number

default:0

Source output index

targetIndex

number

default:0

Target input index

branch

string

Smart parameter for IF nodes: "true" or "false"Automatically sets sourceIndex based on branch.

case

number

Smart parameter for Switch nodes: Case number (0-based)Automatically sets sourceIndex for the specified case.

Examples:

// Basic connection
{
  "type": "addConnection",
  "source": "Webhook",
  "target": "Process Data"
}

// IF node with branch parameter
{
  "type": "addConnection",
  "source": "IF",
  "target": "Success Handler",
  "branch": "true",
  "description": "Route true branch to success handler"
}

// Switch node with case parameter
{
  "type": "addConnection",
  "source": "Switch",
  "target": "Handler A",
  "case": 0
}

removeConnection

Remove a connection between nodes.

type

string

required

"removeConnection"

source

string

required

Source node name

target

string

required

Target node name

sourceOutput

string

default:"main"

Source output type

sourceIndex

number

default:0

Source output index

Example:

{
  "type": "removeConnection",
  "source": "Old Source",
  "target": "Old Target"
}

rewireConnection

Change the target of an existing connection.

type

string

required

"rewireConnection"

source

string

required

Source node name

from

string

required

Current target node name

string

required

New target node name

Example:

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

cleanStaleConnections

Remove connections to non-existent nodes.

type

string

required

"cleanStaleConnections"

dryRun

boolean

default:false

If true, only report stale connections without removing them

Example:

{
  "type": "cleanStaleConnections",
  "dryRun": true,
  "description": "Preview stale connections"
}

Workflow Operations

activateWorkflow / deactivateWorkflow

Activate or deactivate the workflow.

type

string

required

"activateWorkflow" or "deactivateWorkflow"

Example:

{
  "type": "activateWorkflow",
  "description": "Enable workflow for production"
}

updateSettings

Update workflow settings.

type

string

required

"updateSettings"

settings

object

required

Settings object (see Create Workflow for properties)

Example:

{
  "type": "updateSettings",
  "settings": {
    "executionTimeout": 300,
    "saveDataErrorExecution": "all"
  }
}

updateName

Update workflow name.

type

string

required

"updateName"

name

string

required

New workflow name

Example:

{
  "type": "updateName",
  "name": "Production User Sync v2"
}

addTag / removeTag

Add or remove workflow tags.

type

string

required

"addTag" or "removeTag"

tag

string

required

Tag name

Example:

{
  "type": "addTag",
  "tag": "production"
}

Response

success

boolean

Operation success status

data

object

Update result

Show Response Fields

string

Workflow ID

name

string

Workflow name

active

boolean

Active status

nodeCount

number

Total nodes after update

operationsApplied

number

Number of operations successfully applied

message

string

Success message with operation count

details

object

Detailed operation results

Show Details Fields

applied

array

Indices of successfully applied operations

failed

array

Indices of failed operations (only in continueOnError mode)

errors

array

Error messages for failed operations

warnings

array

Non-critical warnings

Complete Examples

See the comprehensive Workflow Diff Examples guide for:

All operation types with examples
Common patterns (add processing step, replace node, error handling)
Large batch operations (26+ operations in one request)
Best practices and troubleshooting

Basic Examples

Simple operations for common tasks

Advanced Patterns

Multi-step refactoring and complex changes

Batch Processing

Build entire pipelines in one request

Error Handling

Validation and error recovery

Error Codes

VALIDATION_ERROR

string

Causes:

Invalid operation structure
Referenced node doesn’t exist
Duplicate node names
Invalid connection references
Workflow structure violations after applying operations

Resolution:

Use validateOnly: true to test operations
Check operation syntax in diff examples
Ensure referenced nodes exist before connecting

OPERATION_FAILED

string

Causes:

Node type doesn’t exist
Invalid parameter values
Connection loop detected
Missing required fields

Resolution:

Use validate_node to verify node configs
Check details.errors for specific operation failures
In continueOnError mode, check applied vs failed arrays

STRUCTURAL_INTEGRITY

string

Causes:

Binary operator with singleValue: true
Unary operator missing singleValue: true
Missing metadata on filter nodes (IF v2.2+, Switch v3.2+)
Branch count mismatch on Switch nodes
Stale connections after node removal

Resolution:

Use cleanStaleConnections operation to remove orphaned connections
Check error details for specific structural issues
Auto-sanitization runs automatically but can’t fix all issues

Transaction Behavior

Atomic Mode (default)

{
  "id": "wf_abc123",
  "operations": [ /* ... */ ]
}

All operations succeed or all fail
Workflow remains unchanged if any operation fails
Best for critical changes

Best-Effort Mode

{
  "id": "wf_abc123",
  "operations": [ /* ... */ ],
  "continueOnError": true
}

Applies valid operations even if some fail
Response includes applied and failed operation indices
Useful for large batch operations where partial success is acceptable

Two-Pass Processing

The diff engine uses two-pass processing for optimal operation ordering: Pass 1: Node operations (addNode, removeNode, updateNode, moveNode, enable/disableNode) Pass 2: All other operations (connections, settings, metadata) This allows you to add nodes and connect them in the same request without worrying about operation order.

You can send operations in any order. The engine automatically processes them in the correct sequence.

Best Practices

Optimal Workflow:

Use descriptive description fields for each operation
Batch related changes in a single request
Use validateOnly: true to preview changes
Provide meaningful intent parameter
Verify changes with n8n_get_workflow({id, mode: "structure"})

Common Pitfalls:

Referencing nodes before they’re added (use two-pass automatically handles this)
Using node IDs instead of names in connections
Forgetting to remove stale connections when deleting nodes
Not using branch parameter for IF nodes (manually calculating sourceIndex)

Performance

Token Savings

80-90% reduction vs full update

Batch Limit

Unlimited operations per request

Processing

Two-pass automatic ordering

Update Full Workflow - Replace entire workflow
Get Workflow - Fetch current workflow
Validate Workflow - Validate before updating
Workflow Versions - Version history and rollback

Conceived by Romuald Członkowski - www.aiadvisors.pl/en

MCP Tools

Workflow Management

Execution Management

Library API

​Overview

​Endpoint

​Request Parameters

​Operation Types

​Node Operations

​addNode

​removeNode

​updateNode

​moveNode

​enableNode / disableNode

​Connection Operations

​addConnection

​removeConnection

​rewireConnection

​cleanStaleConnections

​Workflow Operations

​activateWorkflow / deactivateWorkflow

​updateSettings

​updateName

​addTag / removeTag

​Response

​Complete Examples

Basic Examples

Advanced Patterns

Batch Processing

Error Handling

​Error Codes

​Transaction Behavior

​Atomic Mode (default)

​Best-Effort Mode

​Two-Pass Processing

​Best Practices

​Performance

Token Savings

Batch Limit

Processing

​Related Endpoints

Build docs developers (and LLMs) love

Overview

Endpoint

Request Parameters

Operation Types

Node Operations

addNode

removeNode

updateNode

moveNode

enableNode / disableNode

Connection Operations

addConnection

removeConnection

rewireConnection

cleanStaleConnections

Workflow Operations

activateWorkflow / deactivateWorkflow

updateSettings

updateName

addTag / removeTag

Response

Complete Examples

Error Codes

Transaction Behavior

Atomic Mode (default)

Best-Effort Mode

Two-Pass Processing

Best Practices

Performance

Related Endpoints