Workflows API

Overview

The Workflows API allows you to programmatically manage your automation workflows. You can create, read, update, delete, activate, and execute workflows through REST endpoints.

List Workflows

Retrieve a paginated list of workflows.

GET /api/v1/workflows

Query Parameters

cursor

string

Pagination cursor from previous response’s nextCursor

limit

number

default:"100"

Number of workflows to return (max: 250)

name

string

Filter workflows by name (partial match)

active

boolean

Filter by active status: true for active, false for inactive

Example Request

curl -H "X-N8N-API-KEY: your-api-key" \
  "https://your-n8n-instance.com/api/v1/workflows?active=true&limit=50"

Response

data

array

Array of workflow objects

string

Unique workflow identifier

name

string

Workflow name

active

boolean

Whether the workflow is currently active

nodes

array

Array of node configurations in the workflow

connections

object

Node connection mappings

settings

object

Workflow settings and configurations

createdAt

string

ISO 8601 timestamp of creation

updatedAt

string

ISO 8601 timestamp of last update

nextCursor

string | null

Cursor for next page of results, or null if no more results

Example Response

{
  "data": [
    {
      "id": "workflow_abc123",
      "name": "Customer Onboarding",
      "active": true,
      "nodes": [
        {
          "id": "node_1",
          "type": "n8n-nodes-base.webhook",
          "name": "Webhook",
          "position": [250, 300],
          "parameters": {
            "path": "customer-signup"
          }
        }
      ],
      "connections": {
        "Webhook": {
          "main": [[{ "node": "SendEmail", "type": "main", "index": 0 }]]
        }
      },
      "settings": {
        "executionOrder": "v1"
      },
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-02-10T14:20:00.000Z"
    }
  ],
  "nextCursor": "eyJsYXN0SWQiOiJ3b3JrZmxvd19hYmMxMjMiLCJsaW1pdCI6NTB9"
}

Get Workflow

Retrieve a specific workflow by ID.

GET /api/v1/workflows/:id

Path Parameters

string

required

The workflow ID

Query Parameters

excludePinnedData

boolean

default:"false"

Exclude pinned test data from response

Example Request

curl -H "X-N8N-API-KEY: your-api-key" \
  https://your-n8n-instance.com/api/v1/workflows/workflow_abc123

Response

Returns a single workflow object with full details including nodes, connections, and settings.

Create Workflow

Create a new workflow.

POST /api/v1/workflows

Request Body

name

string

required

Workflow name (max 128 characters)

nodes

array

required

Array of node configurations

connections

object

required

Object mapping node connections

settings

object

Workflow settings and configuration

staticData

object

Static data stored with the workflow

Example Request

curl -X POST \
  -H "X-N8N-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Customer Workflow",
    "nodes": [
      {
        "id": "webhook_1",
        "type": "n8n-nodes-base.webhook",
        "name": "Webhook",
        "position": [250, 300],
        "parameters": {
          "path": "new-customer",
          "httpMethod": "POST"
        }
      }
    ],
    "connections": {},
    "settings": {
      "executionOrder": "v1"
    }
  }' \
  https://your-n8n-instance.com/api/v1/workflows

Response

Returns the created workflow object with generated ID and additional metadata.

New workflows are always created in inactive state. Use the activate endpoint to enable them.

Update Workflow

Update an existing workflow.

PATCH /api/v1/workflows/:id

Path Parameters

string

required

The workflow ID to update

Request Body

All fields are optional. Only include fields you want to update.

name

string

Updated workflow name

nodes

array

Updated node configurations

connections

object

Updated connection mappings

settings

object

Updated workflow settings

staticData

object

Updated static data

Example Request

curl -X PATCH \
  -H "X-N8N-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Workflow Name",
    "settings": {
      "executionOrder": "v1",
      "timezone": "America/New_York"
    }
  }' \
  https://your-n8n-instance.com/api/v1/workflows/workflow_abc123

Response

Returns the updated workflow object.

Delete Workflow

Permanently delete a workflow.

DELETE /api/v1/workflows/:id

Path Parameters

string

required

The workflow ID to delete

Example Request

curl -X DELETE \
  -H "X-N8N-API-KEY: your-api-key" \
  https://your-n8n-instance.com/api/v1/workflows/workflow_abc123

Response

{
  "id": "workflow_abc123",
  "name": "Deleted Workflow"
}

Deleting a workflow also deletes all associated execution history. This action cannot be undone.

Activate Workflow

Activate a workflow to run automatically based on triggers.

POST /api/v1/workflows/:id/activate

Path Parameters

string

required

The workflow ID to activate

Request Body

versionId

string

Specific version ID to activate

name

string

Optional name for the active version

description

string

Optional description for the active version

Example Request

curl -X POST \
  -H "X-N8N-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "versionId": "version_xyz",
    "name": "Production Release"
  }' \
  https://your-n8n-instance.com/api/v1/workflows/workflow_abc123/activate

Response

Returns the activated workflow with active: true.

Deactivate Workflow

Deactivate an active workflow.

POST /api/v1/workflows/:id/deactivate

Path Parameters

string

required

The workflow ID to deactivate

Example Request

curl -X POST \
  -H "X-N8N-API-KEY: your-api-key" \
  https://your-n8n-instance.com/api/v1/workflows/workflow_abc123/deactivate

Response

Returns the deactivated workflow with active: false.

Execute Workflow

Manually trigger a workflow execution.

POST /api/v1/workflows/:id/run

Path Parameters

string

required

The workflow ID to execute

Request Body

workflowData

object

required

The complete workflow configuration to execute

startNodes

string[]

Array of node names to start execution from

destinationNode

string

Target node name to execute up to

runData

object

Input data for the execution

Example Request

curl -X POST \
  -H "X-N8N-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "workflowData": {
      "id": "workflow_abc123",
      "name": "Customer Onboarding",
      "nodes": [...],
      "connections": {...}
    }
  }' \
  https://your-n8n-instance.com/api/v1/workflows/workflow_abc123/run

Response

{
  "executionId": "execution_def456",
  "finished": true,
  "data": {
    "resultData": {
      "runData": {...}
    }
  }
}

Transfer Workflow

Transfer a workflow to a different project.

PUT /api/v1/workflows/:id/transfer

Path Parameters

string

required

The workflow ID to transfer

Request Body

destinationProjectId

string

required

The target project ID

Whether to share associated credentials with the destination project

Example Request

curl -X PUT \
  -H "X-N8N-API-KEY: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "destinationProjectId": "project_xyz789",
    "shareCredentials": true
  }' \
  https://your-n8n-instance.com/api/v1/workflows/workflow_abc123/transfer

Response

Returns 204 No Content on success.

Common Patterns

Cloning a Workflow

// 1. Get the source workflow
const source = await fetch(
  'https://your-n8n-instance.com/api/v1/workflows/source_id',
  { headers: { 'X-N8N-API-KEY': 'your-api-key' } }
).then(r => r.json());

// 2. Create a copy with a new name
const { id, createdAt, updatedAt, ...workflowData } = source;
workflowData.name = `${workflowData.name} (Copy)`;

const cloned = await fetch(
  'https://your-n8n-instance.com/api/v1/workflows',
  {
    method: 'POST',
    headers: {
      'X-N8N-API-KEY': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(workflowData)
  }
).then(r => r.json());

Bulk Operations

const workflowIds = ['id1', 'id2', 'id3'];

const results = await Promise.all(
  workflowIds.map(id =>
    fetch(
      `https://your-n8n-instance.com/api/v1/workflows/${id}/activate`,
      {
        method: 'POST',
        headers: { 'X-N8N-API-KEY': 'your-api-key' }
      }
    ).then(r => r.json())
  )
);

console.log(`Activated ${results.length} workflows`);

Error Responses

400 Bad Request

{
  "message": "Workflow with id \"workflow_abc123\" exists already."
}

403 Forbidden

{
  "message": "You don't have the permissions to save the workflow in this project."
}

404 Not Found

{
  "message": "Workflow with ID \"workflow_abc123\" does not exist"
}

Next Steps

Executions API

Monitor workflow executions

Credentials API

Manage workflow credentials

Authentication

Learn about API authentication

Webhooks

Trigger workflows via webhooks

Core API

Node API

​Overview

​List Workflows

​Query Parameters

​Example Request

​Response

​Get Workflow

​Path Parameters

​Query Parameters

​Example Request

​Response

​Create Workflow

​Request Body

​Example Request

​Response

​Update Workflow

​Path Parameters

​Request Body

​Example Request

​Response

​Delete Workflow

​Path Parameters

​Example Request

​Response

​Activate Workflow

​Path Parameters

​Request Body

​Example Request

​Response

​Deactivate Workflow

​Path Parameters

​Example Request

​Response

​Execute Workflow

​Path Parameters

​Request Body

​Example Request

​Response

​Transfer Workflow

​Path Parameters

​Request Body

​Example Request

​Response

​Common Patterns

​Cloning a Workflow

​Bulk Operations

​Error Responses

​400 Bad Request

​403 Forbidden

​404 Not Found

​Next Steps

Executions API

Credentials API

Authentication

Webhooks

Overview

List Workflows

Query Parameters

Example Request

Response

Get Workflow

Path Parameters

Query Parameters

Example Request

Response

Create Workflow

Request Body

Example Request

Response

Update Workflow

Path Parameters

Request Body

Example Request

Response

Delete Workflow

Path Parameters

Example Request

Response

Activate Workflow

Path Parameters

Request Body

Example Request

Response

Deactivate Workflow

Path Parameters

Example Request

Response

Execute Workflow

Path Parameters

Request Body

Example Request

Response

Transfer Workflow

Path Parameters

Request Body

Example Request

Response

Common Patterns

Cloning a Workflow

Bulk Operations

Error Responses

400 Bad Request

403 Forbidden

404 Not Found

Next Steps