n8n-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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:

Variable	Description	Example
`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

工作流

Method	Path	Description
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 .

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

执行记录

Method	Path	Description
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

凭证

Method	Path	Description
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、名称、类型、创建时间、更新时间）。

Method	Path	Description
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}`	删除标签

Variables

变量

Method	Path	Description
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

用户

Method	Path	Description
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

项目

Method	Path	Description
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

审计

Method	Path	Description
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

源代码控制

Method	Path	Description
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

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

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

---

---

Error Handling

错误处理

Common HTTP status codes:

Code	Meaning
200	Success
201	Created
400	Bad request (invalid parameters)
401	Unauthorized (missing or invalid API key)
403	Forbidden (insufficient permissions)
404	Resource not found
500	Internal 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']})")

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
数组为空：没有结果匹配筛选条件。请放宽查询参数。

n8n-api

Original

Translation

n8n REST API Skill

n8n REST API Skill

Environment Variables (REQUIRED)

环境变量（必填）

Authentication

认证

API Endpoints

API端点

Workflows

工作流

List workflows

列出工作流

Get a workflow

获取单个工作流

Create a workflow

创建工作流

Update a workflow

更新工作流

Activate / Deactivate

激活/停用

Activate

激活

Deactivate

停用

Delete a workflow

删除工作流

Executions

执行记录

List executions

列出执行记录

Get execution details

获取执行记录详情

Stop a running execution

停止正在运行的执行记录

Credentials

凭证

List credentials

列出凭证

Create credential

创建凭证

Tags

标签

List tags

列出标签

Create tag

创建标签

Update tag

更新标签

Variables

变量

List variables

列出变量

Create variable

创建变量

Update variable

更新变量

Users

用户

List users

列出用户

Projects

项目

List projects

列出项目

Create project

创建项目

Audit

审计

Generate audit

生成审计报告

Source Control

源代码控制

Get status

获取状态

Pull from remote

从远程仓库拉取变更

Pagination