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

string

Pagination cursor from previous response’s nextCursor

number

default:"100"

Number of workflows to return (max: 250)

string

Filter workflows by name (partial match)

boolean

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

string

Comma-separated tag names to filter by

string

Filter workflows by project ID

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?active=true&limit=50"

const response = await fetch(
  'https://your-n8n-instance.com/api/v1/workflows?active=true&limit=50',
  {
    headers: { 'X-N8N-API-KEY': 'your-api-key' }
  }
);

const { data, nextCursor } = await response.json();

import requests

response = requests.get(
    'https://your-n8n-instance.com/api/v1/workflows',
    headers={'X-N8N-API-KEY': 'your-api-key'},
    params={'active': True, 'limit': 50}
)

data = response.json()

Response

array

Array of workflow objects

string

Unique workflow identifier

string

Workflow name

boolean

Whether the workflow is currently active

array

Array of node configurations in the workflow

object

Node connection mappings

object

Workflow settings and configurations

string

ISO 8601 timestamp of creation

string

ISO 8601 timestamp of last update

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

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

const response = await fetch(
  'https://your-n8n-instance.com/api/v1/workflows/workflow_abc123',
  {
    headers: { 'X-N8N-API-KEY': 'your-api-key' }
  }
);

const workflow = await response.json();

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

string

required

Workflow name (max 128 characters)

array

required

Array of node configurations

object

required

Object mapping node connections

object

Workflow settings and configuration

object

Static data stored with the workflow

string[]

Array of tag IDs to assign

string

Project ID to create workflow in (defaults to personal project)

object

Metadata about 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

const response = 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({
      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'
      }
    })
  }
);

const workflow = await response.json();

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.

string

Updated workflow name

array

Updated node configurations

object

Updated connection mappings

object

Updated workflow settings

object

Updated static data

string[]

Updated array of tag IDs

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

const response = await fetch(
  'https://your-n8n-instance.com/api/v1/workflows/workflow_abc123',
  {
    method: 'PATCH',
    headers: {
      'X-N8N-API-KEY': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Updated Workflow Name',
      settings: {
        executionOrder: 'v1',
        timezone: 'America/New_York'
      }
    })
  }
);

const updatedWorkflow = await response.json();

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

const response = await fetch(
  'https://your-n8n-instance.com/api/v1/workflows/workflow_abc123',
  {
    method: 'DELETE',
    headers: { 'X-N8N-API-KEY': 'your-api-key' }
  }
);

const result = await response.json();

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

string

Specific version ID to activate

string

Optional name for the active version

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

const response = await fetch(
  'https://your-n8n-instance.com/api/v1/workflows/workflow_abc123/activate',
  {
    method: 'POST',
    headers: {
      'X-N8N-API-KEY': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      versionId: 'version_xyz',
      name: 'Production Release'
    })
  }
);

const activeWorkflow = await response.json();

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

const response = await fetch(
  'https://your-n8n-instance.com/api/v1/workflows/workflow_abc123/deactivate',
  {
    method: 'POST',
    headers: { 'X-N8N-API-KEY': 'your-api-key' }
  }
);

const inactiveWorkflow = await response.json();

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

object

required

The complete workflow configuration to execute

string[]

Array of node names to start execution from

string

Target node name to execute up to

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

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

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

const execution = await response.json();

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

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

​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