n8n Public REST API
Use this skill when you need to drive n8n programmatically. It covers the same core actions you use in the UI: workflows, executions, tags, credentials, projects, and more.
Availability
- - The public API is unavailable during the free trial.
- Upgrade your plan to enable API access.
Configuration
Recommended environment variables (or store in .n8n-api-config):
CODEBLOCK0
Create the API key in: n8n Settings → n8n API → Create an API key.
Auth header
All requests require this header:
CODEBLOCK1
Playground
The API playground is only available on self-hosted n8n and operates on real data. For safe experiments, use a test workflow or a separate test instance.
Quick actions
Workflows: list
CODEBLOCK2
Workflows: details
CODEBLOCK3
Workflows: activate or deactivate
CODEBLOCK4
Webhook trigger
CODEBLOCK5
Executions: list
CODEBLOCK6
Executions: retry
CODEBLOCK7
Common flows
Health check summary
Count active workflows and recent failures:
CODEBLOCK8
Debug a failed run
- 1. List failed executions to get the execution ID.
- Fetch execution details and identify the failing node.
- Review node parameters and input data.
- Suggest a fix based on the error message.
Endpoint index
See assets/n8n-api.endpoints.md for the full list of endpoints.
REST basics (optional)
If you want a refresher, these are commonly recommended:
- - KnowledgeOwl: working with APIs (intro)
- IBM Cloud Learn Hub: what is an API / REST API
- MDN: overview of HTTP
Notes and tips
- - The n8n API node can call the public API from inside workflows.
- Webhook URLs are not the same as API URLs and do not use the API key header.
- Execution records may be pruned based on instance retention settings.
n8n 公共 REST API
当你需要通过编程方式驱动 n8n 时，可使用此技能。它涵盖了你在用户界面中使用的核心操作：工作流、执行记录、标签、凭据、项目等。
可用性
- - 免费试用期间公共 API 不可用。
- 升级你的套餐以启用 API 访问。
配置
推荐的环境变量（或存储在 .n8n-api-config 文件中）：
bash
export N8NAPIBASE_URL=https://your-instance.app.n8n.cloud/api/v1 # 或 http://localhost:5678/api/v1
export N8NAPIKEY=your-api-key-here
在以下位置创建 API 密钥：n8n 设置 → n8n API → 创建 API 密钥。
认证头
所有请求都需要此标头：
X-N8N-API-KEY: $N8NAPIKEY
测试环境
API 测试环境仅在自托管 n8n 上可用，并且操作真实数据。如需安全实验，请使用测试工作流或单独的测试实例。
快速操作
工作流：列表
bash
curl -s -H X-N8N-API-KEY: $N8N
APIKEY $N8N
APIBASE_URL/workflows \
| jq .data[] | {id, name, active}
工作流：详情
bash
curl -s -H X-N8N-API-KEY: $N8N
APIKEY $N8N
APIBASE_URL/workflows/{id}
工作流：激活或停用
bash
激活（发布）
curl -s -X POST -H X-N8N-API-KEY: $N8N
APIKEY \
-H Content-Type: application/json \
-d {versionId:,name:,description:} \
$N8N
APIBASE_URL/workflows/{id}/activate
停用
curl -s -X POST -H X-N8N-API-KEY: $N8N
APIKEY \
$N8N
APIBASE_URL/workflows/{id}/deactivate
Webhook 触发
bash
生产环境 webhook
curl -s -X POST $N8N
APIBASE_URL/../webhook/{webhook-path} \
-H Content-Type: application/json \
-d {key:value}
测试环境 webhook
curl -s -X POST $N8N
APIBASE_URL/../webhook-test/{webhook-path} \
-H Content-Type: application/json \
-d {key:value}
执行记录：列表
bash
最近的执行记录
curl -s -H X-N8N-API-KEY: $N8N
APIKEY \
$N8N
APIBASE_URL/executions?limit=10 \
| jq .data[] | {id, workflowId, status, startedAt}
仅失败记录
curl -s -H X-N8N-API-KEY: $N8N
APIKEY \
$N8N
APIBASE_URL/executions?status=error&limit=5
执行记录：重试
bash
curl -s -X POST -H X-N8N-API-KEY: $N8N
APIKEY \
-H Content-Type: application/json \
-d {loadWorkflow:true} \
$N8N
APIBASE_URL/executions/{id}/retry
常见流程
健康检查摘要
统计活跃工作流和近期失败记录：
bash
ACTIVE=$(curl -s -H X-N8N-API-KEY: $N8N
APIKEY \
$N8N
APIBASE_URL/workflows?active=true | jq .data | length)
FAILED=$(curl -s -H X-N8N-API-KEY: $N8NAPIKEY \
$N8NAPIBASE_URL/executions?status=error&limit=100 \
| jq [.data[] | select(.startedAt > (now - 86400 | todate))] | length)
echo 活跃工作流：$ACTIVE | 失败（24小时）：$FAILED
调试失败运行
- 1. 列出失败执行记录以获取执行 ID。
- 获取执行详情并识别失败节点。
- 检查节点参数和输入数据。
- 根据错误信息提出修复建议。
端点索引
完整端点列表请参见 assets/n8n-api.endpoints.md。
REST 基础知识（可选）
如需复习，以下资源通常被推荐：
- - KnowledgeOwl：使用 API（入门）
- IBM Cloud Learn Hub：什么是 API / REST API
- MDN：HTTP 概述
说明与提示
- - n8n API 节点可以在工作流内部调用公共 API。
- Webhook URL 与 API URL 不同，且不使用 API 密钥标头。
- 执行记录可能会根据实例保留设置被清理。
