n8n Workflow Craft

Overview

Work with n8n workflows through direct REST API calls and helper utilities. Handles comprehensive n8n operations: listing workflows, retrieving workflow details, updating existing workflows, duplicating workflows, activation/deactivation, credential discovery, execution monitoring, tag management, workflow validation, and designing new workflows based on proven patterns.

Configuration

Set these environment variables for API access:

export N8N_API_KEY="your-api-key"
export N8N_BASE_URL="http://localhost:5678"  # Default if not set

In Python code:

import os
api_key = os.environ.get("N8N_API_KEY")
base_url = os.environ.get("N8N_BASE_URL", "http://localhost:5678")

Core Operations

1. List Workflows

Get all workflows with basic metadata:

import requests

response = requests.get(
    f"{base_url}/api/v1/workflows",
    headers={"X-N8N-API-KEY": api_key}
)
workflows = response.json()["data"]

# Each workflow includes: id, name, active, createdAt, updatedAt, tags

Helper script:

python3 ${CLAUDE_PLUGIN_ROOT}/lib/n8n_client.py list

2. Get Workflow Details

Retrieve complete workflow definition including all nodes and connections:

workflow_id = "123"
response = requests.get(
    f"{base_url}/api/v1/workflows/{workflow_id}",
    headers={"X-N8N-API-KEY": api_key}
)
workflow = response.json()

# Includes: id, name, nodes, connections, settings, staticData, active

Helper script:

python3 ${CLAUDE_PLUGIN_ROOT}/lib/n8n_client.py get <workflow-id>

3. Update Workflow

Update an existing workflow (must include complete nodes and connections):

# First, get the current workflow
current = requests.get(
    f"{base_url}/api/v1/workflows/{workflow_id}",
    headers={"X-N8N-API-KEY": api_key}
).json()

# Modify as needed
current["name"] = "Updated Name"
current["nodes"].append(new_node)
# Update connections accordingly

# Send update
response = requests.patch(
    f"{base_url}/api/v1/workflows/{workflow_id}",
    headers={
        "X-N8N-API-KEY": api_key,
        "Content-Type": "application/json"
    },
    json=current
)
updated = response.json()

Critical: Always send the complete nodes and connections arrays, not just changes.

4. Duplicate Workflow

Clone an existing workflow with optional new name:

# Using helper script (recommended)
from lib.n8n_client import N8nClient

client = N8nClient(base_url, api_key)
duplicate = client.duplicate_workflow(
    workflow_id="123",
    new_name="My New Workflow"  # Optional
)

Helper script:

python3 ${CLAUDE_PLUGIN_ROOT}/lib/n8n_client.py duplicate <workflow-id> "New Workflow Name"

The duplicate will be created as inactive by default.

5. Activate/Deactivate Workflow

Toggle workflow activation status:

# Activate
requests.patch(
    f"{base_url}/api/v1/workflows/{workflow_id}",
    headers={
        "X-N8N-API-KEY": api_key,
        "Content-Type": "application/json"
    },
    json={"active": True}
)

# Deactivate
requests.patch(
    f"{base_url}/api/v1/workflows/{workflow_id}",
    headers={
        "X-N8N-API-KEY": api_key,
        "Content-Type": "application/json"
    },
    json={"active": False}
)

Helper scripts:

python3 ${CLAUDE_PLUGIN_ROOT}/lib/n8n_client.py activate <workflow-id>
python3 ${CLAUDE_PLUGIN_ROOT}/lib/n8n_client.py deactivate <workflow-id>

6. Search Workflows

Find workflows by name pattern:

from lib.n8n_client import N8nClient

client = N8nClient(base_url, api_key)
results = client.search_workflows("email")  # Case-insensitive

# Returns list of matching workflows

Helper script:

python3 ${CLAUDE_PLUGIN_ROOT}/lib/n8n_client.py search "email"

7. Search for Specific Nodes

Find nodes within workflows or across all workflows:

Search nodes in a specific workflow:

from lib.n8n_client import N8nClient

client = N8nClient(base_url, api_key)

# Find all HTTP Request nodes
http_nodes = client.search_nodes_in_workflow(
    workflow_id="123",
    node_type="n8n-nodes-base.httpRequest"
)

# Find nodes by name
email_nodes = client.search_nodes_in_workflow(
    workflow_id="123",
    node_name="email"  # Case-insensitive partial match
)

# Combine filters
specific_nodes = client.search_nodes_in_workflow(
    workflow_id="123",
    node_type="n8n-nodes-base.httpRequest",
    node_name="API"
)

Helper script:

# Find all webhook nodes in workflow 123
python3 ${CLAUDE_PLUGIN_ROOT}/lib/n8n_client.py search-nodes 123 --type n8n-nodes-base.webhook

# Find nodes with "email" in name
python3 ${CLAUDE_PLUGIN_ROOT}/lib/n8n_client.py search-nodes 123 --name "email"

# Combine filters
python3 ${CLAUDE_PLUGIN_ROOT}/lib/n8n_client.py search-nodes 123 --type n8n-nodes-base.code --name "transform"

Search nodes across ALL workflows:

# Find all workflows using a specific node type
results = client.search_nodes_across_workflows(
    node_type="n8n-nodes-base.webhook"
)

# Results: {workflow_id: {workflow_name: "...", nodes: [...]}}

Helper script:

# Find all workflows with webhook nodes
python3 ${CLAUDE_PLUGIN_ROOT}/lib/n8n_client.py search-nodes-all --type n8n-nodes-base.webhook

# Find all code nodes across workflows
python3 ${CLAUDE_PLUGIN_ROOT}/lib/n8n_client.py search-nodes-all --type n8n-nodes-base.code

Common node types to search for:

• n8n-nodes-base.httpRequest - HTTP API calls
• n8n-nodes-base.webhook - Webhook triggers
• n8n-nodes-base.code - JavaScript/Python code
• n8n-nodes-base.postgres - Database queries
• n8n-nodes-base.schedule or n8n-nodes-base.scheduleTrigger - Cron jobs
• n8n-nodes-base.if - Conditional logic

Advanced Operations

Credential Discovery

List available credentials before building workflows to ensure proper authentication configuration:

# List all available credentials
python3 ${CLAUDE_PLUGIN_ROOT}/lib/n8n_client.py credentials

# Find credentials by type (partial match)
python3 ${CLAUDE_PLUGIN_ROOT}/lib/n8n_client.py find-credential postgres
python3 ${CLAUDE_PLUGIN_ROOT}/lib/n8n_client.py find-credential slack

Use this before:

• Creating workflows that need external service authentication
• Validating credential availability for a planned integration
• Discovering what credential types are already configured

Response includes:

• Credential ID
• Name
• Type (e.g., "postgresDb", "slackApi", "httpHeaderAuth")
• Whether it's shared across workflows

Execution Monitoring

Execute workflows programmatically and monitor their execution status:

# Execute a workflow and wait for result
python3 ${CLAUDE_PLUGIN_ROOT}/lib/n8n_client.py execute <workflow-id>

# List recent executions
python3 ${CLAUDE_PLUGIN_ROOT}/lib/n8n_client.py executions --limit 50

# List executions for specific workflow
python3 ${CLAUDE_PLUGIN_ROOT}/lib/n8n_client.py executions --workflow-id 123

# Filter by status (success, error, waiting)
python3 ${CLAUDE_PLUGIN_ROOT}/lib/n8n_client.py executions --workflow-id 123 --status error

# Get detailed execution data
python3 ${CLAUDE_PLUGIN_ROOT}/lib/n8n_client.py execution <execution-id>

Use cases:

• Test workflows programmatically before activation
• Debug failed executions by inspecting node outputs
• Monitor production workflows for errors
• Validate data transformation logic

Tag Management

Organize workflows with tags for better categorization:

# List all tags
python3 ${CLAUDE_PLUGIN_ROOT}/lib/n8n_client.py tags

# Create a new tag
python3 ${CLAUDE_PLUGIN_ROOT}/lib/n8n_client.py create-tag "content-pipeline"

# Tag a workflow
python3 ${CLAUDE_PLUGIN_ROOT}/lib/n8n_client.py tag-workflow 123 "content-pipeline"

# Remove tag from workflow
python3 ${CLAUDE_PLUGIN_ROOT}/lib/n8n_client.py untag-workflow 123 "old-tag"

Best practices:

• Use tags like production, staging, experimental
• Tag by domain: content-pipeline, user-management, notifications
• Tag by integration: stripe, salesforce, mailchimp

Workflow Validation

Validate workflow JSON structure before deploying to catch errors early:

# Validate workflow JSON before deploying
python3 ${CLAUDE_PLUGIN_ROOT}/lib/workflow_validator.py workflow.json

16 validation checks performed:

1. Required fields present: Validates name, nodes, connections exist
2. Node structure: Each node has id, name, type, parameters, position
3. Unique node IDs: No duplicate node IDs
4. Connection references: All connections reference existing nodes
5. Connection format: Proper connection structure with node/type/index
6. Trigger node exists: At least one trigger node (start, webhook, schedule, etc.)
7. Node type format: Valid node type naming (e.g., n8n-nodes-base.xxx)
8. Position format: Node positions are [x, y] arrays with numbers
9. Orphaned nodes: All non-trigger nodes are reachable from a trigger
10. Parameter types: Common parameter types match expected formats
11. Expression syntax: Basic n8n expression validation (={{ }})
12. Credential references: Credential IDs are valid format if present
13. Webhook paths: Webhook paths don't contain invalid characters
14. Loop detection: Basic circular dependency detection
15. Empty parameters: Warns about likely incomplete configuration
16. Deprecated nodes: Checks for known deprecated node types

When to validate:

• Before creating a new workflow via API
• After programmatically generating workflow JSON
• When migrating workflows between instances
• Before bulk updates to existing workflows

Idempotent Upsert Pattern

Create or update workflows by name to avoid duplicates:

# Create or update workflow by name (won't create duplicates)
python3 ${CLAUDE_PLUGIN_ROOT}/lib/n8n_client.py upsert workflow.json

How it works:

1. Searches for existing workflow with matching name
2. If found: Updates the existing workflow (preserves ID, staticData)
3. If not found: Creates new workflow
4. Returns workflow ID and whether it was created or updated

Use cases:

• Deploying workflows from source control
• Syncing workflows across environments
• Automation scripts that shouldn't create duplicates
• GitOps-style workflow management

Example workflow.json:

{
  "name": "Daily Report Generator",
  "nodes": [...],
  "connections": {...},
  "active": false
}

Webhook Path Collision Detection

Check if a webhook path is already in use before creating new webhook workflows:

# Check if a webhook path is already in use
python3 ${CLAUDE_PLUGIN_ROOT}/lib/n8n_client.py check-webhook "stripe-events"
python3 ${CLAUDE_PLUGIN_ROOT}/lib/n8n_client.py check-webhook "api/v1/user/signup"

Response:

• If available: "Webhook path 'stripe-events' is available"
• If in use: "Webhook path 'stripe-events' is already used by workflow 'Payment Processor' (ID: 45)"

Use before:

• Creating new webhook endpoints
• Planning API endpoint structure
• Troubleshooting webhook conflicts

Best practices:

• Use descriptive paths: github-webhooks, stripe-events, form-submissions
• Namespace by service: api/stripe/..., webhooks/github/...
• Avoid generic paths like webhook or api

Workflow Design & Ideation

When designing new workflows or modifying existing ones, use proven patterns from references/workflow_patterns.md or start from templates in references/workflow_templates.md:

Creating Workflows from Scratch

Load template reference when:

• User asks to create a new workflow
• User wants a quick-start template
• User mentions specific triggers (webhook, schedule, manual)

# Read available templates
with open(f"{CLAUDE_PLUGIN_ROOT}/skills/n8n-workflow-craft/references/workflow_templates.md") as f:
    templates = f.read()

# Select appropriate template (Manual, Webhook, Scheduled, API, Database, Email, Error Handling)
# Customize for user's needs

Available starter templates:

1. Basic Manual Trigger - For manual testing/one-off operations
2. Webhook API Endpoint - Create API endpoints
3. Scheduled Task - Periodic/cron-based automation
4. HTTP API Integration - Fetch and process external API data
5. Database CRUD - Read/write database operations
6. Email Processing - Send or process emails
7. Error Handling - Robust workflows with error management

Pattern Selection for Modifications

Load patterns reference when:

• User wants to add functionality to existing workflow
• User asks for workflow design advice
• User mentions specific integration types (API, webhook, scheduled tasks, etc.)

# Read pattern examples
with open(f"{CLAUDE_PLUGIN_ROOT}/skills/n8n-workflow-craft/references/workflow_patterns.md") as f:
    patterns = f.read()

# Select appropriate pattern based on requirements
# Adapt pattern to user's specific needs

Common Workflow Types

1. HTTP API Integration - Call external APIs, process responses
2. Webhook Receiver - Receive and process incoming webhooks
3. Scheduled Tasks - Periodic data fetching and processing
4. Conditional Branching - Route data based on conditions
5. Error Handling - Catch and handle errors gracefully
6. Data Transformation - Reshape data between formats
7. Batch Processing - Process items in loops or batches

Node Structure

Every node requires:

{
  "parameters": {},        // Node-specific config
  "id": "unique-id",      // Unique identifier
  "name": "Display Name",  // Human-readable name
  "type": "n8n-nodes-base.nodetype",
  "typeVersion": 1,
  "position": [x, y]      // Canvas position
}

Connection Structure

Connect nodes through the connections object:

{
  "SourceNode": {
    "main": [
      [
        {
          "node": "TargetNode",
          "type": "main",
          "index": 0
        }
      ]
    ]
  }
}

Workflow Composition

Build complex workflows by composing smaller sub-workflows using the executeWorkflow node:

Pattern: Reusable Sub-Workflow

{
  "parameters": {
    "workflowId": "={{ $json.workflowToRun }}",
    "mode": "integrated",
    "waitForCompletion": true
  },
  "name": "Execute User Validation",
  "type": "n8n-nodes-base.executeWorkflow",
  "typeVersion": 1,
  "position": [650, 300]
}

Benefits:

• Modularity: Break complex workflows into testable units
• Reusability: Share common logic (validation, transformation, notification)
• Maintainability: Update one sub-workflow used by many parent workflows
• Error isolation: Wrap sub-workflow calls in error handlers

Common sub-workflow patterns:

• Data validation and sanitization
• Authentication/authorization checks
• Notification dispatching (email, Slack, SMS)
• Data transformation pipelines
• Third-party API wrappers with retry logic

Error wrapper pattern:

{
  "nodes": [
    {
      "name": "Try Execute Sub-Workflow",
      "type": "n8n-nodes-base.executeWorkflow",
      "parameters": {"workflowId": "123"},
      "onError": "continueErrorOutput"
    },
    {
      "name": "Handle Error",
      "type": "n8n-nodes-base.code",
      "parameters": {
        "jsCode": "return [{json: {error: $input.item.json.error, workflow: 'user-validation'}}];"
      }
    }
  ],
  "connections": {
    "Try Execute Sub-Workflow": {
      "error": [[{"node": "Handle Error"}]]
    }
  }
}

Sticky Note Documentation

Add inline documentation to workflows using sticky notes for better readability and maintenance:

{
  "parameters": {
    "content": "## Data Validation\nThis section validates incoming webhook data:\n- Checks required fields\n- Validates email format\n- Ensures user_id is numeric",
    "height": 250,
    "width": 400
  },
  "name": "Note: Validation Logic",
  "type": "n8n-nodes-base.stickyNote",
  "typeVersion": 1,
  "position": [450, 100]
}

Best practices:

• Use markdown formatting (##, -, **bold**)
• Place notes above or beside relevant node groups
• Document non-obvious business logic
• Include links to external docs or tickets
• Use color coding (via background parameter) for different note types

Common note types:

// Section header
{"content": "## Authentication Flow", "height": 80, "width": 300}

// Warning
{"content": "⚠️ **WARNING**: This modifies production database", "height": 100, "width": 350}

// Configuration reference
{"content": "**Config:**\nAPI Key: Use 'stripe-prod' credential\nWebhook: /webhooks/stripe", "height": 150, "width": 300}

// TODO marker
{"content": "🚧 **TODO:**\n- Add retry logic\n- Implement rate limiting", "height": 120, "width": 280}

Progressive Disclosure References

Load reference files progressively based on task complexity:

When Building New Workflows

Load workflow_templates.md first:

# Contains 7 starter templates for common patterns
# Quick-start for: manual trigger, webhook, scheduled, API, database, email, error handling

Use when:

• User says "create a new workflow"
• User mentions starting from scratch
• User asks "how do I build a workflow that..."

When Adding Patterns to Existing Workflows

Load workflow_patterns.md:

# Contains reusable patterns with complete JSON examples
# Patterns for: HTTP calls, webhooks, conditionals, loops, error handling, data transformation

Use when:

• User wants to add functionality to existing workflow
• User asks "how do I add error handling"
• User needs conditional logic, loops, or advanced patterns

When Working with Advanced API Operations

Load api_reference.md:

# Complete REST API documentation
# Includes: workflows, executions, credentials, tags endpoints
# Response formats, error codes, authentication details

Use when:

• Troubleshooting API errors
• Building custom integrations
• Need details on request/response formats
• Working with executions, credentials, or tags APIs

When Checking Node Types

Load node_registry.md:

# Human-readable reference of common node types
# Organized by category: triggers, actions, flow control, data transformation
# Includes required parameters and typeVersion guidance

Use when:

• User asks "what nodes are available"
• Need to know required parameters for a node
• Choosing between node type versions
• Discovering nodes for specific use cases (database, HTTP, code, etc.)

Complete Workflow Example

Creating a simple HTTP to database workflow:

import requests
import json

new_workflow = {
    "name": "API to Database",
    "nodes": [
        {
            "parameters": {},
            "id": "start",
            "name": "Start",
            "type": "n8n-nodes-base.start",
            "position": [250, 300],
            "typeVersion": 1
        },
        {
            "parameters": {
                "url": "https://api.example.com/data",
                "method": "GET"
            },
            "id": "http",
            "name": "Fetch Data",
            "type": "n8n-nodes-base.httpRequest",
            "position": [450, 300],
            "typeVersion": 1
        },
        {
            "parameters": {
                "values": {
                    "string": [
                        {
                            "name": "processed",
                            "value": "={{ $json.data }}"
                        }
                    ]
                }
            },
            "id": "set",
            "name": "Transform",
            "type": "n8n-nodes-base.set",
            "position": [650, 300],
            "typeVersion": 1
        }
    ],
    "connections": {
        "Start": {
            "main": [[{"node": "Fetch Data", "type": "main", "index": 0}]]
        },
        "Fetch Data": {
            "main": [[{"node": "Transform", "type": "main", "index": 0}]]
        }
    },
    "active": False,
    "settings": {}
}

# Create the workflow
response = requests.post(
    f"{base_url}/api/v1/workflows",
    headers={
        "X-N8N-API-KEY": api_key,
        "Content-Type": "application/json"
    },
    json=new_workflow
)
created_workflow = response.json()
print(f"Created workflow: {created_workflow['id']}")

Best Practices

1. Always get before update: Fetch current workflow state before modifying
2. Test inactive first: Create/update workflows as inactive, test, then activate
3. Validate structure: Ensure all referenced nodes exist in connections
4. Use helper script: Leverage lib/n8n_client.py for common operations
5. Handle errors: Wrap API calls in try/except blocks
6. Keep nodes organized: Use consistent positioning (250px horizontal spacing)
7. Name clearly: Use descriptive names for nodes and workflows
8. Validate before deploy: Use workflow_validator.py to catch structural issues
9. Check credentials: Use credentials command to verify auth is available
10. Monitor executions: Use executions command to debug failed workflows
11. Use upsert for CI/CD: Avoid duplicate workflows in deployment pipelines
12. Check webhook paths: Prevent collision errors with check-webhook
13. Document workflows: Add sticky notes for complex logic
14. Compose workflows: Break complex automation into reusable sub-workflows
15. Tag workflows: Organize with tags for easier discovery and management

Resources

lib/n8n_client.py

Python client with N8nClient class for all operations. Can be imported or run as CLI tool. Includes node search, credential discovery, execution monitoring, tag management, upsert, and webhook collision detection.

lib/workflow_validator.py

Standalone workflow validation utility. Performs 16 structural checks before deployment to catch errors early.

references/api_reference.md

Complete n8n REST API documentation including workflows, executions, credentials, and tags endpoints. Load when working with advanced API features or troubleshooting.

references/workflow_patterns.md

Reusable workflow patterns with complete JSON examples for common use cases. Load when designing new workflows or adding functionality to existing ones.

references/workflow_templates.md

Quick-start templates for creating workflows from scratch. Includes 7 pre-built templates: Manual, Webhook, Scheduled, API Integration, Database, Email, and Error Handling. Load when user wants to create a new workflow.

references/node_registry.md

Human-readable reference of common node types organized by category (triggers, actions, flow control, data transformation, database, communication, annotations). Includes required parameters and typeVersion guidance. Load when user asks about available nodes or needs parameter details.

Troubleshooting

Authentication errors: Verify N8N_API_KEY is set and valid Connection errors: Check N8N_BASE_URL is correct and server is running Update failures: Ensure you're sending complete nodes/connections arrays Missing nodes: Verify all node types are installed in your n8n instance Invalid workflow: Use inactive mode first to test before activating Webhook collisions: Use check-webhook before creating webhook workflows Execution failures: Use executions --status error to debug Missing credentials: Use credentials to verify auth is configured Duplicate workflows: Use upsert instead of create for idempotent deploys Validation errors: Run workflow_validator.py to identify structural issues