n8n Hub

本技能融合了两条工作路径：

1. 设计（Design）：规划高可靠性的自动化流程，并可选导出 workflow.json 文件。
2. 运行（Operate）：通过公开的 REST API 管理流程（workflows）与执行记录（executions）。

可用性

• 免费试用计划中，公共 API 访问功能默认禁用。
• 需升级至付费计划方可使用 API 功能。

配置

建议设置以下环境变量（或保存至 .n8n-api-config 文件中）：

export N8N_API_BASE_URL="https://your-instance.app.n8n.cloud/api/v1"  # 或 http://localhost:5678/api/v1
export N8N_API_KEY="your-api-key-here"

API 密钥创建路径：n8n 设置 → n8n API → 创建 API 密钥。

适用场景

• 您需要构建具备幂等性、重试机制、日志记录及审核队列能力的流程。
• 您需要可导入的 workflow.json 文件，以及配套的运行手册（runbook）模板。
• 您希望通过 API 列出、发布、停用或调试流程/执行记录。

不适用场景

• 您仅需纯代码自动化方案，无需 n8n 平台支持。
• 您试图绕过安全控制措施，或隐藏审计追踪痕迹。

输入项

必需输入

• 触发器类型 + 调度配置 / 时区
• 成功判定标准及目标位置（邮件 / Google Drive / 数据库等）

可选输入

• 已有 workflow JSON 内容
• 示例载荷（payloads）或样本数据记录（records）
• 去重键（dedup keys）

输出项

• 默认输出：设计规范文档（含节点拓扑、数据契约、故障模式分析等）
• 按需输出：workflow.json + workflow-lab.md（源自 assets/workflow-lab.md）

认证请求头

所有 API 请求必须包含以下请求头：

X-N8N-API-KEY: $N8N_API_KEY

快捷操作（API）

流程（Workflows）：列出全部

curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" "$N8N_API_BASE_URL/workflows" 
  | jq '.data[] | {id, name, active}'

流程（Workflows）：获取详情

curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" "$N8N_API_BASE_URL/workflows/{id}"

流程（Workflows）：启用或停用

# 启用（即发布）
curl -s -X POST -H "X-N8N-API-KEY: $N8N_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"versionId":"","name":"","description":""}' 
  "$N8N_API_BASE_URL/workflows/{id}/activate"

# 停用
curl -s -X POST -H "X-N8N-API-KEY: $N8N_API_KEY" 
  "$N8N_API_BASE_URL/workflows/{id}/deactivate"

Webhook 触发

curl -s -X POST "$N8N_API_BASE_URL/../webhook/{webhook-path}" 
  -H "Content-Type: application/json" 
  -d '{"key":"value"}'

执行记录（Executions）：列出最近 10 条

curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" 
  "$N8N_API_BASE_URL/executions?limit=10" 
  | jq '.data[] | {id, workflowId, status, startedAt}'

执行记录（Executions）：重试指定执行

curl -s -X POST -H "X-N8N-API-KEY: $N8N_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"loadWorkflow":true}' 
  "$N8N_API_BASE_URL/executions/{id}/retry"

流程设计检查清单

1. 确认触发器类型及调度配置 / 时区设置。
2. 明确定义输入、输出及校验规则。
3. 选择合适的去重键（dedup keys），确保各次执行具备幂等性。
4. 加入可观测性能力（如 run_id、日志、状态行等）。
5. 配置重试策略与错误分支处理逻辑。
6. 将失败任务自动转入审核队列（review queue）。
7. 添加防护机制（guardrails），防止静默失败（silent failure）。

端点索引

完整 API 端点列表请参阅 assets/endpoints-api.md。

注意事项与提示

• API 交互式调试界面（API playground）仅在自托管（self-hosted）版本的 n8n 中可用，且直接操作真实数据。
• n8n 的 API 节点（API node）可在流程内部调用公共 API。
• Webhook URL 不需要携带 X-N8N-API-KEY 请求头。
• 执行记录（execution data）可通过保留策略（retention settings）进行自动清理。