N8n Workflow Sdk

n8n Workflow SDK

Build, test, validate, and manage n8n workflows programmatically using the @n8n/workflow-sdk. This skill enables code-based workflow construction with full validation, JSON round-tripping, and testing support.

When You Need More Detail

This skill uses progressive disclosure. The SKILL.md covers the full workflow, decision-making, and quick-reference API. For complete patterns and examples, read these reference files:

• references/workflow-building.md — Workflow creation, settings, JSON import/export, and complete building patterns
• references/nodes-and-connections.md — All node factories, subnodes (AI/LangChain), connection patterns, and credentials
• references/control-flow.md — IF/Else, Switch/Case, Split in Batches, Merge, error handling, and branching
• references/expressions-and-code.md — Expression system, Code node helpers, fromAi, and expression context
• references/validation-and-testing.md — Workflow validation, pin data, test data generation, and testing strategies
• references/code-generation.md — JSON-to-code, code-to-JSON, parseWorkflowCode, and the generation pipeline
• references/plugins-and-advanced.md — Plugin system, type generation, Zod schemas, and extensibility
• references/node-registry-official.json — Cached registry of all 556 official n8n nodes (name, version, description)
• references/node-registry-community.json — Cached registry of community nodes (name, version, packageName)
• references/node-registry-properties.jsonl — Node properties/parameters (one JSON line per node, grep for a specific node)

Read the appropriate reference file before writing any code.

Project Setup

Before writing SDK code, the project needs @n8n/workflow-sdk and TypeScript tooling installed. If the project already has these, skip this section.

For a new project:

mkdir my-workflow-project && cd my-workflow-project
npm init -y
npm install @n8n/workflow-sdk
npm install --save-dev typescript tsx @types/node

For an existing project:

npm install @n8n/workflow-sdk
npm install --save-dev typescript tsx @types/node

Running workflow scripts:

npx tsx src/my-workflow.ts

The SDK is a pure TypeScript/JavaScript library — no build step is required. tsx runs .ts files directly. If the project already uses ts-node or another TypeScript runner, that works too.

CRITICAL: Node Type Lookup — Never Guess Node Types

DO NOT invent or guess node type identifiers. n8n has hundreds of nodes, each with a specific type string (e.g., n8n-nodes-base.slack). Using a wrong or made-up type produces a workflow that fails in n8n.

Always look up the real node type from the cached node registry before using it.

Local Registry Cache (Primary Source)

This skill ships with cached copies of the n8n node registries. Read these files to look up node types — no network requests needed:

• references/node-registry-official.json — Index of all 556 built-in n8n nodes (name, version, description)
• references/node-registry-community.json — Index of community-contributed nodes (name, version, packageName)
• references/node-registry-properties.jsonl — Full node properties/parameters (one JSON line per node)

Index files (for finding the right node)

Each official node entry has:

• name — The node type identifier to use in node() / trigger() (e.g., "n8n-nodes-base.slack")
• displayName — Human-readable name (e.g., "Slack")
• version — Current version number
• description — What the node does
• group — "[\"trigger\"]" or other classification
• alias — Alternative names for search (e.g., ["message", "chat"])
• categories — Node categories (e.g., ["Communication"])

Each community node entry has:

• name — The node type identifier
• displayName — Human-readable name
• packageName — The npm package the user must install (e.g., "@mendable/n8n-nodes-firecrawl")
• version — Version number
• isOfficialNode — Whether verified by n8n

How to find a node: Read the appropriate registry JSON index and search for the node by displayName, name, alias, or description.

Properties file (for configuring a node)

Once you've found a node's name in the index, grep the properties file to get its available parameters:

grep 'n8n-nodes-base.slack' references/node-registry-properties.jsonl

Each line is a JSON object: {"node": "n8n-nodes-base.slack", "properties": [...]} where properties contains the node's parameter definitions — field names, types, defaults, options, required flags, and conditional display rules. Use this to correctly configure the parameters object in node() / trigger().

CRITICAL: Use option value, not display name. For options-type parameters, the properties JSONL lists both a display name (what the UI shows) and the actual value (what goes in the workflow JSON). These are often different — you must use the value. Common traps:

CRITICAL: Set node v3.3+/3.4 uses assignments, NOT fields. The parameter schema changed at v3.3. If you're using Set node v3.4, you MUST use assignments.assignments (with type: 'string'/'number'/'boolean' and a single value field). The old fields.values / stringValue / numberValue format is for v3.0–3.2 only. See nodes-and-connections.md for full examples.

Deriving version hints from properties data

When the registry cache version field appears to be a rounded major version (e.g., 4 instead of 4.4), you can derive the actual latest version from @version hints in the properties JSONL. About 96 of 554 nodes include these hints.

Node properties use displayOptions.show["@version"] and displayOptions.hide["@version"] to control which fields appear for which versions. These arrays contain the version numbers the node supports, letting you infer the latest version.

How to extract version hints:

1. Grep the properties file for the node: grep 'n8n-nodes-base.set' references/node-registry-properties.jsonl
2. Search the JSON for all "@version" values in displayOptions
3. Collect all version numbers — they appear in two forms:
   • Explicit lists: "@version": [3, 3.1, 3.2] — the node supports versions 3, 3.1, and 3.2
   • Conditions: "@version": [{"_cnd": {"gte": 3.1}}] — applies to version ≥ 3.1
4. The maximum value across all explicit numbers and condition thresholds approximates the latest minor version

Examples from real nodes:

• Set node — "@version": [3, 3.1, 3.2] → latest is at least 3.2 (actual defaultVersion: 3.4)
• Agent node — "@version": [{"_cnd": {"gte": 3.1}}] → latest is at least 3.1 (actual: 3.1)
• Switch node — "@version": [{"_cnd": {"gte": 3.3}}] → latest is at least 3.3 (actual: 3.4)

Limitations: This technique only provides a lower bound (the actual defaultVersion may be higher). ~458 of 554 nodes have no @version hints at all. The registry cache version field (updated via refresh-node-registry.sh which extracts real defaultVersion from npm packages) is always the most accurate source.

Refreshing the Cache

If a node can't be found in the cached registries (they may be outdated), run the refresh script to pull the latest data from the live APIs:

bash scripts/refresh-node-registry.sh

This fetches from https://api.n8n.io/api/nodes and https://api.n8n.io/api/community-nodes, installs the n8n-nodes-base and @n8n/n8n-nodes-langchain npm packages to extract accurate defaultVersion values (the API only returns major versions), strips heavy fields, and updates all three cache files. Run this when you suspect the cache is stale or when a user asks for a node that should exist but isn't in the cache.

Community Node Warning

When using a community node, the user must install the npm package in their n8n instance first. Always add a sticky() note to the workflow warning about the required community node package:

const installNote = sticky(
  '⚠️ Required Community Node: Install the "@mendable/n8n-nodes-firecrawl" package in your n8n instance (Settings → Community Nodes → Install) before using this workflow.',
  [firecrawlNode],
  { color: 5 }
)

Lookup Workflow

1. User asks for a specific integration (e.g., "add a Slack node")
2. Read references/node-registry-official.json and search for the matching node
3. If not found in official nodes, read references/node-registry-community.json and search there
4. If still not found, run bash scripts/refresh-node-registry.sh to update the cache, then search again
5. Use the exact name and version from the registry in your node() / trigger() call
6. Grep references/node-registry-properties.jsonl for the node name to get its available parameters and configure it correctly
7. If using a community node, add a sticky() note listing the required npm package
8. If no matching node exists anywhere, tell the user — do not invent a type

Quick Reference: Core Utility Nodes

These fundamental utility node type names are always safe to use without a registry lookup. However, always look up the correct version from references/node-registry-official.json — do NOT copy version numbers from code examples, as they may be outdated.

⚠️ IMPORTANT: Version numbers in code examples throughout this skill are illustrative and may be outdated. The only reliable source for the current version of any node is references/node-registry-official.json (or references/node-registry-community.json for community nodes). Always read the registry cache to get the correct version before using any node, even core utility nodes listed above.

For ANY integration node not in this list (Slack, Gmail, Notion, Airtable, Google Sheets, Postgres, etc.), you MUST look up the correct type and version from the registry cache before using it.

Core Concepts

The SDK provides a fluent, chainable API for building n8n workflows in TypeScript/JavaScript. Instead of hand-crafting JSON, you construct workflows programmatically with full type safety, validation, and testing capabilities.

Key capabilities:

1. Create workflows — Fluent builder API with workflow(), node(), trigger()
2. Import existing workflows — workflow.fromJSON(json) loads any n8n workflow JSON
3. Export to JSON — .toJSON() produces n8n-compatible workflow JSON
4. Convert JSON to code — generateWorkflowCode(json) produces readable SDK code
5. Convert code to JSON — parseWorkflowCode(code) parses SDK code back to JSON
6. Validate — validateWorkflow() checks structure, connections, expressions, and best practices
7. Test with pin data — .generatePinData() creates mock data from output declarations
8. Build AI workflows — Full support for LangChain subnodes (models, tools, memory, etc.)

Common Workflows

Pattern 1: Create a New Workflow from Scratch

import { workflow, node, trigger, validateWorkflow } from '@n8n/workflow-sdk'

const myTrigger = trigger({ type: 'n8n-nodes-base.manualTrigger', version: 1, config: {} })
const httpNode = node({
  type: 'n8n-nodes-base.httpRequest', version: 4.4,
  config: {
    parameters: { url: 'https://api.example.com/data', method: 'GET' },
    output: [{ json: { id: 1, name: 'Example' } }]
  }
})

const wf = workflow('my-workflow', 'My Workflow')
  .add(myTrigger)
  .to(httpNode)
  .generatePinData()

const validation = validateWorkflow(wf)
if (validation.valid) {
  const json = wf.toJSON()  // Ready for n8n
}

Pattern 2: Load Existing JSON, Modify, Test, Export

import { workflow, node, generateWorkflowCode, validateWorkflow } from '@n8n/workflow-sdk'

// 1. Load from JSON (user provides their workflow JSON)
const wf = workflow.fromJSON(existingWorkflowJSON)

// 2. Convert to code to understand it
const code = generateWorkflowCode(existingWorkflowJSON)

// 3. Modify — add a new node
const newNode = node({
  type: 'n8n-nodes-base.set', version: 3.4,
  config: {
    name: 'Transform',
    parameters: {
      mode: 'manual',
      assignments: {
        assignments: [
          { name: 'processed', value: true, type: 'boolean' },
          { name: 'label', value: '={{ $json.name }}', type: 'string' }
        ]
      },
      includeOtherFields: true,
      options: {}
    }
  }
})
// Rebuild with modifications using the SDK

// 4. Validate
const result = validateWorkflow(wf)
console.log(result.errors, result.warnings)

// 5. Export back to JSON
const updatedJSON = wf.toJSON()

Pattern 3: Convert JSON to Code, Modify, Convert Back

import { generateWorkflowCode, parseWorkflowCode, validateWorkflow } from '@n8n/workflow-sdk'

// JSON → Code (for reading/understanding)
const code = generateWorkflowCode(workflowJSON)

// Modify the code as needed...

// Code → JSON (for importing back to n8n)
const newJSON = parseWorkflowCode(modifiedCode)

// Validate before deploying
const result = validateWorkflow(newJSON)

Pattern 4: Build an AI Agent Workflow

import { workflow, node, trigger, languageModel, tool, memory, fromAi } from '@n8n/workflow-sdk'

const model = languageModel({
  type: '@n8n/n8n-nodes-langchain.lmChatOpenAi', version: 1.3,
  config: {
    parameters: {
      model: { __rl: true, mode: 'list', value: 'gpt-4o-mini', cachedResultName: 'gpt-4o-mini' },
      options: {}
    },
    credentials: { openAiApi: { name: 'OpenAI', id: 'cred-123' } }
  }
})

const emailTool = tool({
  type: '@n8n/n8n-nodes-langchain.toolGmail', version: 1,
  config: {
    parameters: {
      recipient: fromAi('recipient', 'Email recipient address'),
      subject: fromAi('subject', 'Email subject line')
    }
  }
})

const agent = node({
  type: '@n8n/n8n-nodes-langchain.agent', version: 3.1,
  config: {
    name: 'AI Agent',
    parameters: {
      promptType: 'define',
      text: '={{ $json.chatInput }}',
      options: { systemMessage: 'You are a helpful AI assistant.' }
    },
    subnodes: { model, tools: [emailTool], memory: memoryNode }
  }
})

const wf = workflow('ai-workflow', 'AI Agent Workflow')
  .add(trigger({ type: 'n8n-nodes-base.manualTrigger', version: 1, config: {} }))
  .to(agent)

⚠️ Model IDs in examples are illustrative and will become outdated. Always choose the most appropriate current model for the user's use case — do NOT copy model IDs like gpt-4o-mini from these examples. Check the provider's latest model offerings.

SDK API Quick Reference

Factory Functions

Subnode Factories (AI/LangChain)

Expression Utilities

Code Helpers

Validation & Testing

Code Generation

WorkflowBuilder Methods

NodeInstance Methods

Decision Guide

When to Use Each Pattern

Creating a brand-new workflow:

1. Look up node types — Read references/node-registry-official.json (and references/node-registry-community.json if needed) to get the correct type and version for every integration node
2. Design the flow (trigger → processing → output)
3. Create nodes with node() and trigger() using the real types from the registry
4. If using community nodes, add sticky() notes listing required npm packages
5. Chain with .add() and .to()
6. Add output declarations for testing
7. Validate with validateWorkflow()
8. Export with .toJSON()

Modifying an existing n8n workflow (JSON):

1. Load with workflow.fromJSON(json)
2. Optionally convert to code with generateWorkflowCode(json) to understand it
3. Build the modified version using the SDK
4. Validate the new version
5. Export with .toJSON()

Understanding a complex workflow:

1. Convert with generateWorkflowCode(json) — produces readable TypeScript
2. Read the generated code to understand the flow

Testing/verifying a workflow:

1. Build or load the workflow
2. Add output declarations to nodes (expected output shapes)
3. Call .generatePinData() to create test data
4. Call validateWorkflow() to check for errors
5. Review validation errors and warnings

Round-tripping (code ↔ JSON):

• JSON → Code: generateWorkflowCode(json)
• Code → JSON: parseWorkflowCode(code)
• Code → Builder: parseWorkflowCodeToBuilder(code) (allows validation before JSON export)

Connection Patterns Summary

// Sequential: A → B → C
workflow('id', 'name').add(a).to(b).to(c)

// Fan-out: A → [B, C, D] (parallel branches, output indices 0, 1, 2)
workflow('id', 'name').add(a).to([b, c, d])

// Multi-input (Merge): A → merge.input(0), B → merge.input(1)
workflow('id', 'name')
  .add(a).to(merge.input(0))
  .add(b).to(merge.input(1))

// Explicit indexed: source output 0 → target input 1
workflow('id', 'name').connect(source, 0, target, 1)

// Output selection: use specific output of a multi-output node
nodeA.output(0).to(nodeB)
nodeA.output(1).to(nodeC)

// IF branching
ifNode.onTrue(trueNode).onFalse(falseNode)

// Switch branching
switchNode.onCase(0, caseA).onCase(1, caseB).onCase(2, caseC)

// Error handling
sourceNode.onError(errorHandler)

// Split in Batches loop
sib.onEachBatch(process.to(nextBatch(sib))).onDone(finalNode)

Validation Error Codes

The SDK validates for 23+ error conditions. Key ones to watch for:

See references/validation-and-testing.md for the complete list and resolution strategies.

Node Type Constants

import { NODE_TYPES } from '@n8n/workflow-sdk'

NODE_TYPES.IF                  // 'n8n-nodes-base.if'
NODE_TYPES.SWITCH              // 'n8n-nodes-base.switch'
NODE_TYPES.MERGE               // 'n8n-nodes-base.merge'
NODE_TYPES.STICKY_NOTE         // 'n8n-nodes-base.stickyNote'
NODE_TYPES.SPLIT_IN_BATCHES    // 'n8n-nodes-base.splitInBatches'
NODE_TYPES.HTTP_REQUEST        // 'n8n-nodes-base.httpRequest'
NODE_TYPES.WEBHOOK             // 'n8n-nodes-base.webhook'
NODE_TYPES.DATA_TABLE          // 'n8n-nodes-base.dataTable'

Type Guards

import {
  isIfNodeType, isSwitchNodeType, isMergeNodeType,
  isStickyNoteType, isSplitInBatchesType, isHttpRequestType,
  isWebhookType, isDataTableType, isNodeChain, isNodeInstance
} from '@n8n/workflow-sdk'

Scope

This skill is for building and manipulating n8n workflows programmatically using the @n8n/workflow-sdk. It covers workflow creation, JSON import/export, validation, code generation, pin data, and the full SDK API.

This skill is NOT for:

• Deploying workflows to n8n instances or managing n8n server configuration
• Building custom n8n community nodes (use the n8n-node-builder skill instead)
• Using the n8n UI or REST API directly
• Managing n8n credentials in a running instance

Best Practices

1. NEVER guess node types or versions — always look them up — Read references/node-registry-official.json (official) or references/node-registry-community.json (community) to get the real type and version. Do NOT copy version numbers from code examples in this skill — they are illustrative and may be outdated. The registry cache is the single source of truth for versions. A wrong node type or version produces a broken workflow.
2. Flag community nodes with sticky notes — If the workflow uses community nodes, add a sticky() note listing the npm packages the user must install in their n8n instance.
3. Always validate before exporting — Call validateWorkflow() before .toJSON(). The SDK catches 23+ error conditions that would silently produce broken workflows in n8n, so skipping validation means shipping bugs.
4. Use output declarations for testing — Add output to node configs, then call generatePinData(). Without output declarations, there's no way to generate test fixtures automatically, and downstream nodes can't be tested with realistic data shapes.
5. Use generateWorkflowCode() to understand existing workflows — Raw n8n JSON is verbose and hard to follow. The generated TypeScript code reveals the logical flow, branching, and node relationships at a glance.
6. Use parseWorkflowCode() for round-tripping — Code → JSON → Code round-trips cleanly, making it safe to convert, edit in code, and convert back without data loss.
7. Use parseWorkflowCodeToBuilder() when you need validation — Unlike parseWorkflowCode() which returns raw JSON, this returns a WorkflowBuilder so you can .validate() before .toJSON(), catching errors before they reach n8n.
8. Use credentials objects, not hardcoded values — Hardcoded API keys in parameters are a security risk and won't work across environments. The validator catches HARDCODED_CREDENTIALS to prevent this.
9. Use fromAi() only in tool nodes — fromAi() generates $fromAI expressions that only the AI Agent node can resolve. Using them in regular nodes produces expressions that will fail at runtime. The validator catches FROM_AI_IN_NON_TOOL.
10. Use expr() for dynamic values — Raw strings with ={{ }} are error-prone (missing = prefix, unbalanced braces). expr() handles the prefix automatically and makes intent clear in code.
11. Set output on nodes to enable pin data generation — This is how you create test fixtures. Without declared outputs, generatePinData() has nothing to convert.
12. Use sticky() for workflow documentation — Auto-positions around given nodes, making it easy to annotate sections of complex workflows for other developers.
13. NEVER generate empty Set nodes — A Set node with parameters: { options: {} } is broken and does nothing. Every Set node v3.4 MUST have mode: 'manual' with assignments.assignments containing at least one entry, OR mode: 'raw' with a jsonOutput string. Use type: 'string'/'number'/'boolean' and a single value field — NOT the old stringValue/numberValue format. If you don't know what fields to set, ask the user.
14. Use current AI models, not example model IDs — Model IDs in code examples (e.g., gpt-4o-mini, claude-sonnet-4-20250514) are illustrative and become outdated. Always select the most appropriate current model for the user's task. Check the provider's latest offerings rather than copying from examples.