Skip to main content

​
Overview

Update an entire workflow by replacing all nodes and connections. This operation requires sending the complete workflow structure.
For incremental updates (adding/removing nodes, updating parameters), use Update Partial Workflow instead. It’s more efficient and reduces token usage by 80-90%.

​
Endpoint

PUT /workflows/:id

​
Request Parameters

​
id
string
required
Workflow ID to update
​
name
string
New workflow name (optional)
​
nodes
array
Complete array of workflow nodes (required if modifying structure)
Must include ALL nodes, not just changed ones. See Create Workflow for node structure.
​
connections
object
Complete connections object (required if modifying structure)
Must include ALL connections, not just new ones.
​
settings
object
Workflow settings to update
​
createBackup
boolean
default:true
Create version backup before updating
Backups allow rollback via n8n_workflow_versions tool. Automatic pruning keeps last 10 versions.
​
intent
string
Human-readable description of the updateExample: "Add error handling to API calls"

​
Response

​
success
boolean
Operation success status
​
data
object
Updated workflow information
​
message
string
Success message with verification guidance

​
Error Codes

​
VALIDATION_ERROR
string
Causes:
  • Invalid workflow structure
  • Missing required fields
  • Duplicate node names
  • Broken connections
  • Invalid node type format
Resolution: Use validate_workflow before updating
​
NOT_FOUND
string
Cause: Workflow ID does not existResolution: Verify ID with n8n_list_workflows
​
CONCURRENT_MODIFICATION
string
Cause: Workflow was modified by another user/processResolution: Fetch latest version and retry

​
Examples

{
  "id": "wf_abc123",
  "name": "Customer Onboarding v2",
  "intent": "Update workflow name for versioning"
}

​
Response Example

{
  "success": true,
  "data": {
    "id": "wf_abc123",
    "name": "Updated Workflow",
    "active": true,
    "nodeCount": 3
  },
  "message": "Workflow 'Updated Workflow' updated successfully. Use n8n_get_workflow with mode 'structure' to verify current state."
}

​
When to Use Full Update vs Partial Update

Use Full Update

  • Renaming workflow
  • Updating settings only
  • Replacing entire workflow structure
  • Importing from template

Use Partial Update

  • Adding/removing nodes
  • Updating node parameters
  • Modifying connections
  • Moving nodes
  • Enabling/disabling nodes
  • 90% of update operations

​
Versioning and Rollback

Full updates create automatic backups (unless createBackup: false). Access version history:
# List versions
n8n_workflow_versions({mode: "list", workflowId: "wf_abc123"})

# Rollback to version
n8n_workflow_versions({mode: "rollback", workflowId: "wf_abc123", versionId: 42})

​
Best Practices

Before Full Updates:
  1. Fetch current workflow with n8n_get_workflow({id, mode: "full"})
  2. Make your changes to the workflow object
  3. Validate with validate_workflow tool
  4. Apply update with descriptive intent parameter
  5. Verify with n8n_get_workflow({id, mode: "structure"})
Common Pitfalls:
  • Forgetting to include all nodes (only sends changed nodes)
  • Missing connections for new nodes
  • Not validating before updating
  • Concurrent modifications without version checks
Conceived by Romuald Członkowski - www.aiadvisors.pl/en

Build docs developers (and LLMs) love

Get started for freeTalk to us