n8n API

# n8n Public REST API

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

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

## 配置

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

```bash 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 密钥。

## Auth 请求头

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

``` X-N8N-API-KEY: $N8N_API_KEY ```

## Playground

API Playground 仅在自托管 n8n 上可用，并且操作的是真实数据。为了安全起见进行实验，请使用测试工作流或单独的测试实例。

## 快速操作

### 工作流：列表 ```bash curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" "$N8N_API_BASE_URL/workflows" \ | jq '.data[] | {id, name, active}' ```

### 工作流：详情 ```bash curl -s -H "X-N8N-API-KEY: $N8N_API_KEY" "$N8N_API_BASE_URL/workflows/{id}" ```

### 工作流：激活或停用 ```bash # 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 触发器 ```bash # 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"}' ```

### 执行：列表 ```bash # 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" ```

### 执行：重试 ```bash 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" ```

## 常见流程

### 健康检查摘要

统计活跃工作流和最近的失败次数： ```bash 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 Learn Hub：什么是 API / REST API - MDN：HTTP 概述

## 注意事项和提示 - n8n API 节点可以从工作流内部调用公共 API。 - Webhook URL 与 API URL 不同，并且不使用 API 密钥请求头。 - 执行记录可能会根据实例保留设置被清理。