n8n 公共 REST API

当您需要通过编程方式驱动 n8n 时，请使用此功能。它涵盖了您在用户界面中使用的相同核心操作：工作流、执行、标签、凭据、项目等。

可用性

• 公共 API 在免费试用期间不可用。
• 升级您的计划以启用 API 访问。

配置

推荐的环境变量（或存储在.n8n-api-config中）：

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

在以下位置创建 API 密钥：n8n 设置 → n8n API → 创建 API 密钥。

认证请求头

所有请求都需要此请求头：

X-N8N-API-KEY: $N8N_API_KEY

API 演练场

API 演练场仅在自托管的 n8n 上可用，并操作真实数据。要进行安全的实验，请使用测试工作流或单独的测试实例。

快速操作

工作流：列表

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

工作流：详情

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

工作流：激活或停用

# Activate (publish)
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"

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

Webhook 触发器

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

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

执行：列表

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

# Failed only
curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_API_BASE_URL/executions?status=error&limit=5"

执行：重试

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"

常用流程

健康检查摘要

统计活跃工作流和近期失败：

ACTIVE=$(curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_API_BASE_URL/workflows?active=true" | jq '.data | length')

FAILED=$(curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" \
  "$N8N_API_BASE_URL/executions?status=error&limit=100" \
  | jq '[.data[] | select(.startedAt > (now - 86400 | todate))] | length')

echo "Active workflows: $ACTIVE | Failed (24h): $FAILED"

调试失败的运行

1. 列出失败的执行以获取执行ID。
2. 获取执行详情并识别失败的节点。
3. 检查节点参数和输入数据。
4. 根据错误信息建议修复方案。

端点索引

参见assets/n8n-api.endpoints.md获取完整的端点列表。

REST基础（可选）

如需复习，以下为常用推荐资源：

• KnowledgeOwl：API使用入门（介绍）
• IBM Cloud学习中心：什么是API/REST API
• MDN：HTTP概述

注意事项与提示

• n8n API节点可从工作流内部调用公共API。
• Webhook URL与API URL不同，且不使用API密钥头部验证。
• 执行记录可能根据实例保留设置进行清理。