n8n 2.43.7 Public API 使用指南（实测）

n8n 2.43.7 Public API 实测：API Key 创建与 JWT 认证、工作流 CRUD（PUT 全量语义/PATCH 不可用）、cursor 分页、执行查询、标签与用户、受限端点 403 记录与 Webhook 触发回显。

n8nn8nAPI2026/10/17

n8n 2.43.7 Public API 使用指南（实测）

‍‍​​‌​> 目标：用 cURL 把 n8n Public API 的工作流、执行、标签、用户四大域跑通：创建 API Key → 认证 → CRUD → 分页 → 错误处理。全部请求在 n8n 2.43.7 实测（2026-10-17），回显为真实响应截选；个别受限端点如实标注 403。

一、准备工作

1.1 创建 API Key

前提：已完成 Owner 初始化（部署时设置管理员账号，见部署篇）。路径：编辑器右上角头像 → Settings → n8n API → Create an API key，起个标签名（如 doc-test-key）。

生成的 Key 是一段 JWT（实测格式）：

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI3MTI3ZmFjMS0...IiwiYXVkIjoicHVibGljLWFwaSJ9.xxxxx

💡 Key 明文只在创建时展示一次，数据库里以 JWT 形式可复核（user_api_keys 表）。泄露后直接在 UI 里删除重建。

1.2 认证方式与文档页

BASE=http://localhost:5678/api/v1
KEY=<你的APIKey>
curl -s -H "X-N8N-API-KEY: $KEY" "$BASE/workflows?limit=1"
  • 认证头固定为 X-N8N-API-KEY，作用域是 Key 所属账号的权限（Owner 为全量）；
  • 自带 Swagger 文档页：浏览器打开 /api/v1/docs（实测 HTTP 200）；
  • 错误 Key 实测：401 + {"message":"Unauthorized"}。

二、工作流 CRUD（✅ 全实测）

2.1 列表与字段

curl -s -H "X-N8N-API-KEY: $KEY" "$BASE/workflows?limit=5"

实测响应（截选）：

{"data":[{
  "id":"JB97JNkL2l1EVbyu",
  "name":"Webhook Echo Demo (API renamed)",
  "active":true,
  "activeVersionId":"64c8db35-...",
  "createdAt":"2026-10-17T10:47:09.970Z",
  "isArchived":false,
  "versionId":"64c8db35-...",
  "triggerCount":1,
  "nodes":[{"name":"Webhook","type":"n8n-nodes-base.webhook","parameters":{"path":"echo",...}}, ...]
}]}

列表直接内联 nodes 数组，导出备份一条 curl 就够。

2.2 分页（cursor 机制）

$ curl -s -H "X-N8N-API-KEY: $KEY" "$BASE/workflows?limit=1"
# → data:[第1条], nextCursor:"eyJsaW1pdCI6MSwib2Zmc2V0IjoxfQ=="
$ curl -s -H "X-N8N-API-KEY: $KEY" "$BASE/workflows?limit=1&cursor=eyJsaW1pdCI6MSwib2Zmc2V0IjoxfQ=="
# → data:[第2条]   （cursor 是 base64 的 {"limit":1,"offset":1}，实测翻页成功）

nextCursor 为 null 表示到底。

2.3 创建

curl -s -X POST -H "X-N8N-API-KEY: $KEY" -H 'Content-Type: application/json' \
  -d '{
    "name":"API Created Test WF",
    "nodes":[
      {"parameters":{},"id":"t1","name":"Manual Trigger","type":"n8n-nodes-base.manualTrigger","typeVersion":1,"position":[-100,0]},
      {"parameters":{"jsCode":"return [{json:{ok:true}}];"},"id":"t2","name":"Code","type":"n8n-nodes-base.code","typeVersion":2,"position":[100,0]}
    ],
    "connections":{"Manual Trigger":{"main":[[{"node":"Code","type":"main","index":0}]]}},
    "settings":{}
  }' "$BASE/workflows"
# → 200，返回含新 id 的完整对象（实测 id=7CmgVB7yh5b1X6QU）

⚠️ 实测发现：创建时不校验节点类型——type:"not-a-node.type" 也能建成功。导入外部 JSON 前先自检节点拼写。

2.4 更新：PUT 全量（PATCH 不可用）

2.43.7 实测更新工作流是 PUT 且必须带全量 nodes：

PATCH /workflows/{id}          → {"message":"PATCH method not allowed"}
PUT   /workflows/{id} (无nodes) → {"message":"request/body must have required property 'nodes'"}
PUT   /workflows/{id} (全量)    → 200

正确姿势（改名+改节点一次提交，实测 200）：

curl -s -X PUT -H "X-N8N-API-KEY: $KEY" -H 'Content-Type: application/json' \
  -d '{"name":"API PUT Renamed WF",
       "nodes":[ ...完整节点数组... ],
       "connections":{ ... },
       "settings":{}}' "$BASE/workflows/$WID"

典型脚本模式：先 GET 取回对象 → 改字段 → 原样 PUT 回去。

2.5 删除

$ curl -s -o /dev/null -w '%{http_code}\n' -X DELETE -H "X-N8N-API-KEY: $KEY" "$BASE/workflows/$WID"
200
$ curl -s -H "X-N8N-API-KEY: $KEY" "$BASE/workflows/$WID"
{"message":"Not Found"}          # 404

三、执行查询（✅ 实测）

$ curl -s -H "X-N8N-API-KEY: $KEY" "$BASE/executions?limit=3"
{"data":[{"id":"3","finished":true,"mode":"cli","status":"success",
  "startedAt":"2026-10-17T10:53:07.495Z","stoppedAt":"...","workflowId":"j14aJ0OcFlLHsq46"}, ...]}

$ curl -s -H "X-N8N-API-KEY: $KEY" "$BASE/executions/1"    # 单条详情（含各节点输入输出）

mode 字段能区分触发来源（webhook/cli/trigger…）。注意实测：POST /api/v1/workflows/{id}/run 在 2.43.7 返回 {"message":"POST method not allowed"}——API 不能主动触发单次执行，需要跑一次时用 CLI n8n execute --id=<id>（见 CLI 篇）。

四、标签与用户

$ curl -s -H "X-N8N-API-KEY: $KEY" "$BASE/tags"
{"data":[],"nextCursor":null}

$ curl -s -X POST -H "X-N8N-API-KEY: $KEY" -H 'Content-Type: application/json' \
    -d '{"name":"api-test-tag"}' "$BASE/tags"
{"id":"YrZKxz5zIhTIXHcg","name":"api-test-tag","createdAt":"...","updatedAt":"..."}

$ curl -s -H "X-N8N-API-KEY: $KEY" "$BASE/users"
{"data":[{"id":"7127fac1-...","email":"admin@n8n.local","firstName":"Admin",
  "lastName":"User","isPending":false,"mfaEnabled":false}],"nextCursor":null}

2.43.7 受限端点实测记录

以下端点在本版本实测返回 403 {"message":"Forbidden"}，写自动化脚本时不要依赖：

端点状态备注
GET /workflows/{id}/tags、PUT /workflows/{id}/tags403工作流打标签经 UI/编辑器接口完成
GET /tags/{id}、DELETE /tags/{id}403列表与创建可用
GET /credentials403凭证管理走 UI/CLI 导出
GET /projects403项目管理属企业版能力
GET /variables403变量为企业版功能

五、Webhook 触发（✅ 实测）

激活含 Webhook 节点的工作流后，生产地址直接可调（不带 API Key）：

$ curl -s -X POST http://localhost:5678/webhook/echo \
    -H 'Content-Type: application/json' -d '{"msg":"hello-n8n","n":42}'
{"status":"ok","youSent":{"msg":"hello-n8n","n":42},"receivedAt":"2026-10-17T20:51:59.456+08:00"}

路径不存在或工作流未激活时（实测原文）：

{"code":404,
 "message":"The requested webhook \"POST no-such-path\" is not registered.",
 "hint":"The workflow must be active for a production URL to run successfully. You can activate the workflow using ..."}

测试地址为 /webhook-test/<path>，仅在编辑器里监听。

六、速查表

目的请求
导出全部工作流 JSONGET /workflows（nodes 内联，配合 jq 存文件）
改名/改结构GET 取回 → PUT 全量回写
查最近失败GET /executions?status=error（配合 workflowId 过滤）
新建标签POST /tags {"name":"..."}
核对管理员GET /users
触发一次执行CLI：n8n execute --id=<id>

命令行侧的等价操作、备份与审计见《n8n 2.43.7 CLI 命令详解与实测》；API Key 相关的安全运维（轮换、审计）见《n8n 2.43.7 运维手册：备份、升级、日志与监控》。

相关文档