Back to Details

n8n-api

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

n8n REST API Skill

n8n REST API Skill

Interact with an n8n automation platform instance via its public REST API v1.
通过n8n自动化平台的公开REST API v1与其实例进行交互。

Environment Variables (REQUIRED)

环境变量（必填）

Before making any API calls, ensure these environment variables are set:
VariableDescriptionExample
N8N_HOST
n8n instance hostname (with protocol, no trailing slash)
https://n8n.example.com
N8N_API_KEY
API key generated in n8n UI (Settings > API)
n8n_api_...
bash
export N8N_HOST="https://n8n.example.com"
export N8N_API_KEY="your-api-key-here"
If these are not set, ask the user to provide them before proceeding.
在发起任何API调用前，请确保已设置以下环境变量：
变量名描述示例
N8N_HOST
n8n实例的主机名（包含协议，末尾无斜杠）
https://n8n.example.com
N8N_API_KEY
在n8n界面（设置 > API）生成的API密钥
n8n_api_...
bash
export N8N_HOST="https://n8n.example.com"
export N8N_API_KEY="your-api-key-here"
如果未设置这些变量，请询问用户提供后再继续操作。

Authentication

认证

All requests require the 
X-N8N-API-KEY
header:
bash
curl -H "X-N8N-API-KEY: $N8N_API_KEY" "$N8N_HOST/api/v1/workflows"
Every request pattern below assumes:
  • Base URL: 
    $N8N_HOST/api/v1
  • Header: 
    X-N8N-API-KEY: $N8N_API_KEY
  • Content-Type: 
    application/json
    (for POST/PUT/PATCH)
所有请求都需要携带
X-N8N-API-KEY
请求头：
bash
curl -H "X-N8N-API-KEY: $N8N_API_KEY" "$N8N_HOST/api/v1/workflows"
以下所有请求模式均默认：
  • 基础URL：
    $N8N_HOST/api/v1
  • 请求头：
    X-N8N-API-KEY: $N8N_API_KEY
  • Content-Type：
    application/json
    （适用于POST/PUT/PATCH请求）

API Endpoints

API端点

Workflows

工作流

MethodPathDescription
GET
/workflows
List all workflows (supports 
?active=true/false
, 
?tags=tagId
, 
?limit=N
, 
?cursor=
)
GET
/workflows/{id}
Get a single workflow by ID
POST
/workflows
Create a new workflow
PUT
/workflows/{id}
Update an existing workflow (full replace)
DELETE
/workflows/{id}
Delete a workflow
POST
/workflows/{id}/activate
Activate a workflow
POST
/workflows/{id}/deactivate
Deactivate a workflow
POST
/workflows/{id}/transfer
Transfer workflow to another project
请求方法路径描述
GET
/workflows
列出所有工作流（支持
?active=true/false
、
?tags=tagId
、
?limit=N
、
?cursor=
参数）
GET
/workflows/{id}
根据ID获取单个工作流
POST
/workflows
创建新工作流
PUT
/workflows/{id}
更新现有工作流（全量替换）
DELETE
/workflows/{id}
删除工作流
POST
/workflows/{id}/activate
激活工作流
POST
/workflows/{id}/deactivate
停用工作流
POST
/workflows/{id}/transfer
将工作流转移至其他项目

List workflows

列出工作流

bash
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_HOST/api/v1/workflows?limit=50" | jq .
Query parameters:
  • active
    (boolean) — filter by active/inactive status
  • tags
    (string) — filter by tag ID
  • name
    (string) — filter by name (partial match)
  • limit
    (number) — results per page (default 10, max 250)
  • cursor
    (string) — pagination cursor from previous response
bash
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_HOST/api/v1/workflows?limit=50" | jq .
查询参数：
  • active
    （布尔值）——按激活/停用状态筛选
  • tags
    （字符串）——按标签ID筛选
  • name
    （字符串）——按名称筛选（部分匹配）
  • limit
    （数字）——每页结果数（默认10，最大250）
  • cursor
    （字符串）——上一次响应中的分页游标

Get a workflow

获取单个工作流

bash
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_HOST/api/v1/workflows/{id}" | jq .
bash
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_HOST/api/v1/workflows/{id}" | jq .

Create a workflow

创建工作流

bash
curl -s -X POST \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Workflow",
    "nodes": [],
    "connections": {},
    "settings": {
      "executionOrder": "v1"
    }
  }' \
  "$N8N_HOST/api/v1/workflows" | jq .
Request body fields:
  • name
    (string, required) — workflow name
  • nodes
    (array, required) — array of node objects
  • connections
    (object, required) — node connections map
  • settings
    (object) — workflow settings
  • staticData
    (object) — static data for the workflow
  • tags
    (array of objects) — tags to assign 
    [{"id": "tagId"}]
bash
curl -s -X POST \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Workflow",
    "nodes": [],
    "connections": {},
    "settings": {
      "executionOrder": "v1"
    }
  }' \
  "$N8N_HOST/api/v1/workflows" | jq .
请求体字段：
  • name
    （字符串，必填）——工作流名称
  • nodes
    （数组，必填）——节点对象数组
  • connections
    （对象，必填）——节点连接映射
  • settings
    （对象）——工作流设置
  • staticData
    （对象）——工作流的静态数据
  • tags
    （对象数组）——要分配的标签 
    [{"id": "tagId"}]

Update a workflow

更新工作流

bash
curl -s -X PUT \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Workflow",
    "nodes": [...],
    "connections": {...},
    "settings": {...}
  }' \
  "$N8N_HOST/api/v1/workflows/{id}" | jq .
Note: If the workflow is active, the updated version is automatically re-published.
bash
curl -s -X PUT \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Workflow",
    "nodes": [...],
    "connections": {...},
    "settings": {...}
  }' \
  "$N8N_HOST/api/v1/workflows/{id}" | jq .
注意： 如果工作流处于激活状态，更新后的版本会自动重新发布。

Activate / Deactivate

激活/停用

bash
undefined
bash
undefined

Activate

激活

curl -s -X POST -H "X-N8N-API-KEY: $N8N_API_KEY"
"$N8N_HOST/api/v1/workflows/{id}/activate" | jq .
curl -s -X POST -H "X-N8N-API-KEY: $N8N_API_KEY"
"$N8N_HOST/api/v1/workflows/{id}/activate" | jq .

Deactivate

停用

curl -s -X POST -H "X-N8N-API-KEY: $N8N_API_KEY"
"$N8N_HOST/api/v1/workflows/{id}/deactivate" | jq .
undefined
curl -s -X POST -H "X-N8N-API-KEY: $N8N_API_KEY"
"$N8N_HOST/api/v1/workflows/{id}/deactivate" | jq .
undefined

Delete a workflow

删除工作流

bash
curl -s -X DELETE -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_HOST/api/v1/workflows/{id}" | jq .
bash
curl -s -X DELETE -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_HOST/api/v1/workflows/{id}" | jq .

Executions

执行记录

MethodPathDescription
GET
/executions
List executions (supports filters)
GET
/executions/{id}
Get a single execution
DELETE
/executions/{id}
Delete an execution
POST
/executions/{id}/stop
Stop a running execution
请求方法路径描述
GET
/executions
列出执行记录（支持筛选）
GET
/executions/{id}
获取单个执行记录
DELETE
/executions/{id}
删除执行记录
POST
/executions/{id}/stop
停止正在运行的执行记录

List executions

列出执行记录

bash
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_HOST/api/v1/executions?limit=20&status=error" | jq .
Query parameters:
  • workflowId
    (string) — filter by workflow ID
  • status
    (string) — 
    error
    , 
    success
    , 
    waiting
    , 
    running
  • limit
    (number) — results per page (default 10, max 250)
  • cursor
    (string) — pagination cursor
  • includeData
    (boolean) — include full execution data (default false)
bash
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_HOST/api/v1/executions?limit=20&status=error" | jq .
查询参数：
  • workflowId
    （字符串）——按工作流ID筛选
  • status
    （字符串）——
    error
    , 
    success
    , 
    waiting
    , 
    running
  • limit
    （数字）——每页结果数（默认10，最大250）
  • cursor
    （字符串）——分页游标
  • includeData
    （布尔值）——包含完整执行数据（默认false）

Get execution details

获取执行记录详情

bash
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_HOST/api/v1/executions/{id}?includeData=true" | jq .
Response includes:
  • id
    — execution ID
  • finished
    — boolean
  • mode
    — trigger mode (manual, webhook, trigger, etc.)
  • startedAt
    / 
    stoppedAt
    — timestamps
  • workflowId
    — associated workflow
  • status
    — success/error/waiting/running
  • data
    — full execution data (when 
    includeData=true
    )
bash
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_HOST/api/v1/executions/{id}?includeData=true" | jq .
响应包含：
  • id
    ——执行记录ID
  • finished
    ——布尔值，表示是否完成
  • mode
    ——触发模式（手动、Webhook、触发器等）
  • startedAt
    / 
    stoppedAt
    ——时间戳
  • workflowId
    ——关联的工作流ID
  • status
    ——成功/错误/等待/运行中
  • data
    ——完整执行数据（当
    includeData=true
    时返回）

Stop a running execution

停止正在运行的执行记录

bash
curl -s -X POST -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_HOST/api/v1/executions/{id}/stop" | jq .
bash
curl -s -X POST -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_HOST/api/v1/executions/{id}/stop" | jq .

Credentials

凭证

MethodPathDescription
GET
/credentials
List all credentials
POST
/credentials
Create new credential
DELETE
/credentials/{id}
Delete a credential
POST
/credentials/{id}/transfer
Transfer credential to another project
请求方法路径描述
GET
/credentials
列出所有凭证
POST
/credentials
创建新凭证
DELETE
/credentials/{id}
删除凭证
POST
/credentials/{id}/transfer
将凭证转移至其他项目

List credentials

列出凭证

bash
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_HOST/api/v1/credentials?limit=50" | jq .
Query parameters:
  • limit
    (number) — results per page
  • cursor
    (string) — pagination cursor
bash
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_HOST/api/v1/credentials?limit=50" | jq .
查询参数：
  • limit
    （数字）——每页结果数
  • cursor
    （字符串）——分页游标

Create credential

创建凭证

bash
curl -s -X POST \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My API Key",
    "type": "httpHeaderAuth",
    "data": {
      "name": "Authorization",
      "value": "Bearer token123"
    }
  }' \
  "$N8N_HOST/api/v1/credentials" | jq .
Request body:
  • name
    (string, required) — credential name
  • type
    (string, required) — credential type (e.g., 
    httpHeaderAuth
    , 
    oAuth2Api
    , 
    httpBasicAuth
    )
  • data
    (object, required) — credential-specific data
Security note: The API does not return credential secrets in GET responses. Only metadata (id, name, type, createdAt, updatedAt) is returned.
bash
curl -s -X POST \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My API Key",
    "type": "httpHeaderAuth",
    "data": {
      "name": "Authorization",
      "value": "Bearer token123"
    }
  }' \
  "$N8N_HOST/api/v1/credentials" | jq .
请求体：
  • name
    （字符串，必填）——凭证名称
  • type
    （字符串，必填）——凭证类型（例如
    httpHeaderAuth
    , 
    oAuth2Api
    , 
    httpBasicAuth
    ）
  • data
    （对象，必填）——凭证专属数据
安全提示： API在GET响应中不会返回凭证密钥，仅返回元数据（ID、名称、类型、创建时间、更新时间）。

Tags

标签

MethodPathDescription
GET
/tags
List all tags
GET
/tags/{id}
Get a single tag
POST
/tags
Create a new tag
PUT
/tags/{id}
Update a tag
DELETE
/tags/{id}
Delete a tag
请求方法路径描述
GET
/tags
列出所有标签
GET
/tags/{id}
获取单个标签
POST
/tags
创建新标签
PUT
/tags/{id}
更新标签
DELETE
/tags/{id}
删除标签

List tags

列出标签

bash
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_HOST/api/v1/tags?limit=100" | jq .
bash
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_HOST/api/v1/tags?limit=100" | jq .

Create tag

创建标签

bash
curl -s -X POST \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "production"}' \
  "$N8N_HOST/api/v1/tags" | jq .
bash
curl -s -X POST \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "production"}' \
  "$N8N_HOST/api/v1/tags" | jq .

Update tag

更新标签

bash
curl -s -X PUT \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "staging"}' \
  "$N8N_HOST/api/v1/tags/{id}" | jq .
bash
curl -s -X PUT \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "staging"}' \
  "$N8N_HOST/api/v1/tags/{id}" | jq .

Variables

变量

MethodPathDescription
GET
/variables
List all variables
POST
/variables
Create a variable
PUT
/variables/{id}
Update a variable
DELETE
/variables/{id}
Delete a variable
请求方法路径描述
GET
/variables
列出所有变量
POST
/variables
创建变量
PUT
/variables/{id}
更新变量
DELETE
/variables/{id}
删除变量

List variables

列出变量

bash
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_HOST/api/v1/variables" | jq .
bash
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_HOST/api/v1/variables" | jq .

Create variable

创建变量

bash
curl -s -X POST \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "API_ENDPOINT", "value": "https://api.example.com"}' \
  "$N8N_HOST/api/v1/variables" | jq .
bash
curl -s -X POST \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "API_ENDPOINT", "value": "https://api.example.com"}' \
  "$N8N_HOST/api/v1/variables" | jq .

Update variable

更新变量

bash
curl -s -X PUT \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "API_ENDPOINT", "value": "https://api-v2.example.com"}' \
  "$N8N_HOST/api/v1/variables/{id}" | jq .
bash
curl -s -X PUT \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "API_ENDPOINT", "value": "https://api-v2.example.com"}' \
  "$N8N_HOST/api/v1/variables/{id}" | jq .

Users

用户

MethodPathDescription
GET
/users
List all users
GET
/users/{id}
Get user by ID (or 
email:{email}
)
请求方法路径描述
GET
/users
列出所有用户
GET
/users/{id}
根据ID（或
email:{email}
）获取用户

List users

列出用户

bash
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_HOST/api/v1/users?limit=50" | jq .
Query parameters:
  • limit
    (number) — results per page
  • cursor
    (string) — pagination cursor
  • includeRole
    (boolean) — include role in response
bash
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_HOST/api/v1/users?limit=50" | jq .
查询参数：
  • limit
    （数字）——每页结果数
  • cursor
    （字符串）——分页游标
  • includeRole
    （布尔值）——在响应中包含角色信息

Projects

项目

MethodPathDescription
GET
/projects
List all projects
GET
/projects/{id}
Get project by ID
POST
/projects
Create a project
PUT
/projects/{id}
Update a project
DELETE
/projects/{id}
Delete a project
请求方法路径描述
GET
/projects
列出所有项目
GET
/projects/{id}
根据ID获取项目
POST
/projects
创建项目
PUT
/projects/{id}
更新项目
DELETE
/projects/{id}
删除项目

List projects

列出项目

bash
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_HOST/api/v1/projects" | jq .
bash
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_HOST/api/v1/projects" | jq .

Create project

创建项目

bash
curl -s -X POST \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Marketing Automations"}' \
  "$N8N_HOST/api/v1/projects" | jq .
bash
curl -s -X POST \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Marketing Automations"}' \
  "$N8N_HOST/api/v1/projects" | jq .

Audit

审计

MethodPathDescription
POST
/audit
Generate a security audit report
请求方法路径描述
POST
/audit
生成安全审计报告

Generate audit

生成审计报告

bash
curl -s -X POST \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"additionalOptions": {"categories": ["credentials", "nodes", "instance"]}}' \
  "$N8N_HOST/api/v1/audit" | jq .
Audit categories: 
credentials
, 
nodes
, 
database
, 
filesystem
, 
instance
.
bash
curl -s -X POST \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"additionalOptions": {"categories": ["credentials", "nodes", "instance"]}}' \
  "$N8N_HOST/api/v1/audit" | jq .
审计类别：
credentials
, 
nodes
, 
database
, 
filesystem
, 
instance
。

Source Control

源代码控制

MethodPathDescription
GET
/source-control/preferences
Get source control preferences
POST
/source-control/preferences
Set source control preferences
POST
/source-control/pull
Pull changes from remote
POST
/source-control/push
Push changes to remote
GET
/source-control/status
Get modified resources status
POST
/source-control/disconnect
Disconnect from source control
请求方法路径描述
GET
/source-control/preferences
获取源代码控制偏好设置
POST
/source-control/preferences
设置源代码控制偏好设置
POST
/source-control/pull
从远程仓库拉取变更
POST
/source-control/push
将变更推送到远程仓库
GET
/source-control/status
获取已修改资源的状态
POST
/source-control/disconnect
断开与源代码控制的连接

Get status

获取状态

bash
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_HOST/api/v1/source-control/status" | jq .
bash
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_HOST/api/v1/source-control/status" | jq .

Pull from remote

从远程仓库拉取变更

bash
curl -s -X POST \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"force": false}' \
  "$N8N_HOST/api/v1/source-control/pull" | jq .
bash
curl -s -X POST \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"force": false}' \
  "$N8N_HOST/api/v1/source-control/pull" | jq .

Pagination

分页

The n8n API uses cursor-based pagination. Responses include:
json
{
  "data": [...],
  "nextCursor": "eyJsaW1pdCI6MTAsIm9mZnNldCI6MTB9"
}
To fetch the next page, pass 
?cursor=<nextCursor>
on the next request. When 
nextCursor
is 
null
, there are no more results.
n8n API使用基于游标的分页。响应包含以下结构：
json
{
  "data": [...],
  "nextCursor": "eyJsaW1pdCI6MTAsIm9mZnNldCI6MTB9"
}
要获取下一页数据，请在后续请求中传递
?cursor=<nextCursor>
参数。当
nextCursor
为
null
时，表示没有更多结果。

Common Patterns

常见模式

List all workflows with their status

列出所有工作流及其状态

bash
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_HOST/api/v1/workflows?limit=250" | \
  jq '.data[] | {id, name, active, updatedAt}'
bash
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_HOST/api/v1/workflows?limit=250" | \
  jq '.data[] | {id, name, active, updatedAt}'

Find failed executions for a workflow

查找某个工作流的失败执行记录

bash
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_HOST/api/v1/executions?workflowId=123&status=error&limit=50" | \
  jq '.data[] | {id, status, startedAt, stoppedAt}'
bash
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_HOST/api/v1/executions?workflowId=123&status=error&limit=50" | \
  jq '.data[] | {id, status, startedAt, stoppedAt}'

Trigger a workflow manually via webhook

通过Webhook手动触发工作流

If a workflow has a Webhook node, you can trigger it directly:
bash
curl -s -X POST \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}' \
  "$N8N_HOST/webhook/{webhook-path}"
Note: Webhook URLs use 
/webhook/
or 
/webhook-test/
path, not 
/api/v1/
.
如果工作流包含Webhook节点，可以直接触发它：
bash
curl -s -X POST \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}' \
  "$N8N_HOST/webhook/{webhook-path}"
注意： Webhook URL使用
/webhook/
或
/webhook-test/
路径，而非
/api/v1/
。

Export a workflow as JSON

将工作流导出为JSON

bash
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_HOST/api/v1/workflows/{id}" | jq . > workflow-backup.json
bash
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_HOST/api/v1/workflows/{id}" | jq . > workflow-backup.json

Import / restore a workflow from JSON

从JSON导入/恢复工作流

bash
curl -s -X POST \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d @workflow-backup.json \
  "$N8N_HOST/api/v1/workflows" | jq .
bash
curl -s -X POST \
  -H "X-N8N-API-KEY: $N8N_API_KEY" \
  -H "Content-Type: application/json" \
  -d @workflow-backup.json \
  "$N8N_HOST/api/v1/workflows" | jq .

Bulk activate all workflows

批量激活所有工作流

bash
undefined
bash
undefined

Get all inactive workflow IDs, then activate each

获取所有未激活的工作流ID，然后逐个激活

curl -s -H "X-N8N-API-KEY: $N8N_API_KEY"
"$N8N_HOST/api/v1/workflows?active=false&limit=250" |
jq -r '.data[].id' | while read id; do curl -s -X POST -H "X-N8N-API-KEY: $N8N_API_KEY"
"$N8N_HOST/api/v1/workflows/$id/activate" > /dev/null echo "Activated workflow $id" done
undefined
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY"
"$N8N_HOST/api/v1/workflows?active=false&limit=250" |
jq -r '.data[].id' | while read id; do curl -s -X POST -H "X-N8N-API-KEY: $N8N_API_KEY"
"$N8N_HOST/api/v1/workflows/$id/activate" > /dev/null echo "Activated workflow $id" done
undefined

Delete old executions (cleanup)

删除旧执行记录（清理）

bash
undefined
bash
undefined

Get executions older than a specific date and delete them

获取早于特定日期的执行记录并删除

curl -s -H "X-N8N-API-KEY: $N8N_API_KEY"
"$N8N_HOST/api/v1/executions?status=success&limit=100" |
jq -r '.data[].id' | while read id; do curl -s -X DELETE -H "X-N8N-API-KEY: $N8N_API_KEY"
"$N8N_HOST/api/v1/executions/$id" > /dev/null echo "Deleted execution $id" done

---
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY"
"$N8N_HOST/api/v1/executions?status=success&limit=100" |
jq -r '.data[].id' | while read id; do curl -s -X DELETE -H "X-N8N-API-KEY: $N8N_API_KEY"
"$N8N_HOST/api/v1/executions/$id" > /dev/null echo "Deleted execution $id" done

---

Error Handling

错误处理

Common HTTP status codes:
CodeMeaning
200Success
201Created
400Bad request (invalid parameters)
401Unauthorized (missing or invalid API key)
403Forbidden (insufficient permissions)
404Resource not found
500Internal server error
Error response format:
json
{
  "code": 404,
  "message": "The requested workflow was not found"
}
常见HTTP状态码：
状态码含义
200请求成功
201创建成功
400请求错误（参数无效）
401未授权（API密钥缺失或无效）
403禁止访问（权限不足）
404资源未找到
500服务器内部错误
错误响应格式：
json
{
  "code": 404,
  "message": "The requested workflow was not found"
}

Implementation Notes

实现注意事项

  • Always read 
    N8N_HOST
    and 
    N8N_API_KEY
    from environment variables — never hardcode them
  • Use 
    jq
    for JSON processing in shell scripts
  • For Node.js scripts, use 
    fetch()
    or 
    axios
    with the same headers
  • Rate limiting: n8n does not enforce strict rate limits by default, but be respectful on shared instances
  • Pagination: always handle 
    nextCursor
    for endpoints that return lists
  • Webhook URLs are separate from the API (
    /webhook/
    vs 
    /api/v1/
    )
  • Execution data can be large — use 
    includeData=false
    (default) when listing executions
  • Workflow JSON structure follows n8n's internal format (nodes + connections + settings)
  • 始终从环境变量中读取
    N8N_HOST
    和
    N8N_API_KEY
    ——切勿硬编码
  • 在Shell脚本中使用
    jq
    处理JSON数据
  • 对于Node.js脚本，使用
    fetch()
    或
    axios
    并携带相同的请求头
  • 速率限制：n8n默认不强制严格的速率限制，但在共享实例上请合理调用
  • 分页：对于返回列表的端点，务必处理
    nextCursor
    参数
  • Webhook URL与API是分开的（
    /webhook/
    vs 
    /api/v1/
    ）
  • 执行数据可能很大——列出执行记录时使用默认的
    includeData=false
  • 工作流JSON结构遵循n8n的内部格式（节点 + 连接 + 设置）

Node.js Example

Node.js示例

javascript
const N8N_HOST = process.env.N8N_HOST;
const N8N_API_KEY = process.env.N8N_API_KEY;

async function n8nApi(method, path, body = null) {
  const url = `${N8N_HOST}/api/v1${path}`;
  const options = {
    method,
    headers: {
      'X-N8N-API-KEY': N8N_API_KEY,
      'Content-Type': 'application/json',
    },
  };
  if (body) options.body = JSON.stringify(body);
  const res = await fetch(url, options);
  if (!res.ok) throw new Error(`n8n API ${res.status}: ${await res.text()}`);
  return res.json();
}

// List workflows
const workflows = await n8nApi('GET', '/workflows?limit=50');
console.log(workflows.data);

// Create a tag
const tag = await n8nApi('POST', '/tags', { name: 'automated' });
console.log(tag);
javascript
const N8N_HOST = process.env.N8N_HOST;
const N8N_API_KEY = process.env.N8N_API_KEY;

async function n8nApi(method, path, body = null) {
  const url = `${N8N_HOST}/api/v1${path}`;
  const options = {
    method,
    headers: {
      'X-N8N-API-KEY': N8N_API_KEY,
      'Content-Type': 'application/json',
    },
  };
  if (body) options.body = JSON.stringify(body);
  const res = await fetch(url, options);
  if (!res.ok) throw new Error(`n8n API ${res.status}: ${await res.text()}`);
  return res.json();
}

// 列出工作流
const workflows = await n8nApi('GET', '/workflows?limit=50');
console.log(workflows.data);

// 创建标签
const tag = await n8nApi('POST', '/tags', { name: 'automated' });
console.log(tag);

Python Example

Python示例

python
import os
import requests

N8N_HOST = os.environ["N8N_HOST"]
N8N_API_KEY = os.environ["N8N_API_KEY"]

HEADERS = {
    "X-N8N-API-KEY": N8N_API_KEY,
    "Content-Type": "application/json",
}

def n8n_api(method, path, json=None):
    url = f"{N8N_HOST}/api/v1{path}"
    resp = requests.request(method, url, headers=HEADERS, json=json)
    resp.raise_for_status()
    return resp.json()
python
import os
import requests

N8N_HOST = os.environ["N8N_HOST"]
N8N_API_KEY = os.environ["N8N_API_KEY"]

HEADERS = {
    "X-N8N-API-KEY": N8N_API_KEY,
    "Content-Type": "application/json",
}

def n8n_api(method, path, json=None):
    url = f"{N8N_HOST}/api/v1{path}"
    resp = requests.request(method, url, headers=HEADERS, json=json)
    resp.raise_for_status()
    return resp.json()

List workflows

列出工作流

workflows = n8n_api("GET", "/workflows?limit=50") for wf in workflows["data"]: print(f"{wf['id']}: {wf['name']} (active={wf['active']})")
workflows = n8n_api("GET", "/workflows?limit=50") for wf in workflows["data"]: print(f"{wf['id']}: {wf['name']} (active={wf['active']})")

Create a variable

创建变量

n8n_api("POST", "/variables", {"key": "ENV", "value": "production"})

---
n8n_api("POST", "/variables", {"key": "ENV", "value": "production"})

---

Verification

验证

After any API interaction, verify:
  • HTTP status code is 2xx
  • Response contains expected fields (
    id
    , 
    name
    , etc.)
  • For workflow creation/update: check workflow appears in the list
  • For activation: check 
    active
    field is 
    true
  • For executions: check 
    status
    matches expected outcome
完成任何API交互后，请验证：
  • HTTP状态码为2xx
  • 响应包含预期字段（如
    id
    、
    name
    等）
  • 对于工作流创建/更新：检查工作流是否出现在列表中
  • 对于激活操作：检查
    active
    字段是否为
    true
  • 对于执行记录：检查
    status
    是否符合预期结果

Failure Modes

失败场景

  • 401 Unauthorized: API key is missing, invalid, or expired. Regenerate in n8n UI > Settings > API.
  • 404 Not Found: Wrong workflow/execution ID, or the resource was deleted. Verify ID with a list call.
  • 400 Bad Request: Invalid JSON body or missing required fields. Check request structure.
  • Connection refused: Wrong 
    N8N_HOST
    or n8n instance is down. Verify URL and instance status.
  • Empty 
    data
    array    : No results match filters. Broaden query parameters.
  • 401未授权：API密钥缺失、无效或过期。请在n8n界面 > 设置 > API中重新生成。
  • 404未找到：工作流/执行记录ID错误，或资源已被删除。请通过列表调用验证ID。
  • 400请求错误：JSON请求体无效或缺少必填字段。请检查请求结构。
  • 连接被拒绝：
    N8N_HOST
    错误或n8n实例已下线。请验证URL和实例状态。
  • data
    数组为空    ：没有结果匹配筛选条件。请放宽查询参数。