Create Workflow

Overview

Create a new workflow in your n8n instance. Workflows are created in an inactive state by default. You must activate them separately using the update-partial endpoint.

Workflows require at least one trigger node to be executable. Common triggers include Webhook, Schedule, Manual Trigger, or integration-specific triggers.

Endpoint

POST /workflows

Request Body

name

string

required

Human-readable workflow name. Must be unique within your instance.Example: "Customer Onboarding Flow"

nodes

array

required

Array of workflow nodes. Each node represents a step in your automation.

Show Node Object Properties

string

required

Unique identifier for the node (UUIDs recommended)

name

string

required

Display name for the node. Must be unique within the workflow.

type

string

required

Full node type identifier (e.g., "n8n-nodes-base.httpRequest")

Use FULL form: n8n-nodes-base.* not nodes-base.*

typeVersion

number

required

Node type version. Use get_node to find the latest version.

position

array

required

Canvas position as [x, y] coordinatesExample: [400, 300]

parameters

object

required

Node-specific configuration parameters

credentials

object

Credential configuration for authenticated nodes

disabled

boolean

default:false

Whether the node is disabled

notes

string

Documentation notes for the node

continueOnFail

boolean

default:false

Continue workflow execution if this node fails

retryOnFail

boolean

default:false

Retry failed node execution

maxTries

number

default:3

Maximum retry attempts (requires retryOnFail: true)

waitBetweenTries

number

default:1000

Milliseconds to wait between retries

connections

object

required

Workflow connections object. Keys are source node names (not IDs), values define output connections.Structure:

{
  "Source Node Name": {
    "main": [
      [
        {
          "node": "Target Node Name",
          "type": "main",
          "index": 0
        }
      ]
    ]
  }
}

settings

object

Workflow execution settings

Show Settings Properties

executionOrder

string

default:"v1"

Execution order version: "v0" or "v1"

timezone

string

Timezone for scheduled workflows (e.g., "America/New_York")

saveDataErrorExecution

string

default:"all"

Save execution data on error: "all" or "none"

saveDataSuccessExecution

string

default:"all"

Save execution data on success: "all" or "none"

saveManualExecutions

boolean

default:true

Save manual test execution data

saveExecutionProgress

boolean

default:false

Save intermediate execution progress

executionTimeout

number

Maximum execution time in seconds

errorWorkflow

string

Workflow ID to trigger on error

Response

success

boolean

Operation success status

data

object

Created workflow information

Show Response Data

string

Generated workflow ID

name

string

Workflow name

active

boolean

Workflow active status (always false for new workflows)

nodeCount

number

Number of nodes in the workflow

message

string

Success message with workflow ID

Error Codes

VALIDATION_ERROR

string

Causes:

Missing required fields (name, nodes, connections)
Invalid node type format (use FULL form: n8n-nodes-base.*)
Duplicate node names
Invalid connection references
Missing workflow metadata

Resolution: Use validate_workflow tool before creating

API_ERROR

string

Causes:

n8n API not configured (missing N8N_API_URL or N8N_API_KEY)
Network connectivity issues
n8n instance unavailable

Resolution: Verify API credentials with n8n_health_check

DUPLICATE_NAME

string

Cause: Workflow name already existsResolution: Use a unique name or delete the existing workflow

Examples

{
  "name": "Simple Webhook Handler",
  "nodes": [
    {
      "id": "webhook-1",
      "name": "Webhook",
      "type": "n8n-nodes-base.webhook",
      "typeVersion": 1,
      "position": [250, 300],
      "parameters": {
        "path": "test-webhook",
        "httpMethod": "POST",
        "responseMode": "onReceived"
      }
    },
    {
      "id": "set-1",
      "name": "Process Data",
      "type": "n8n-nodes-base.set",
      "typeVersion": 1,
      "position": [450, 300],
      "parameters": {
        "values": {
          "string": [
            {
              "name": "message",
              "value": "Data received successfully"
            }
          ]
        }
      }
    }
  ],
  "connections": {
    "Webhook": {
      "main": [
        [
          {
            "node": "Process Data",
            "type": "main",
            "index": 0
          }
        ]
      ]
    }
  }
}

Best Practices

Before Creating Workflows:

Use search_nodes to find the right nodes for your use case
Use get_node to get parameter schemas and examples
Use validate_node to verify node configurations
Use validate_workflow to check the complete workflow

Common Pitfalls:

Using SHORT form node types (nodes-base.*) instead of FULL form (n8n-nodes-base.*)
Referencing node IDs instead of names in connections
Missing typeVersion on nodes
Duplicate node names within a workflow
Invalid connection structure

Get Workflow - Retrieve workflow details
Update Workflow - Modify existing workflow
Validate Workflow - Validate before creation
List Workflows - Browse existing workflows

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

MCP Tools

Workflow Management

Execution Management

Library API

Create Workflow

Overview

Endpoint

Request Body

Response

Error Codes

Examples

Best Practices

Build docs developers (and LLMs) love

MCP Tools

Workflow Management

Execution Management

Library API

​Overview

​Endpoint

​Request Body

​Response

​Error Codes

​Examples

​Best Practices

​Related Endpoints

Build docs developers (and LLMs) love

Overview

Endpoint

Request Body

Response

Error Codes

Examples

Best Practices

Related Endpoints