{ "openapi": "3.0.0", "info": { "title": "n8n 公共 API", "version": "1.1.1" }, "tags": [ { "name": "Workflow", "description": "工作流相关操作" } ], "servers": [ { "url": "/api/v1", "description": "当前 n8n 实例（自托管版本的内置测试台）" }, { "url": "{url}/api/v1", "description": "自托管 n8n 实例", "variables": { "url": { "default": "https://example.com" } } } ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] }, { "CookieAuth": [] } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-N8N-API-KEY" }, "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }, "CookieAuth": { "type": "apiKey", "in": "cookie", "name": "n8n-auth" } }, "schemas": { "workflowPublicDto.generated": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "active": { "type": "boolean", "description": "已弃用。请改为检查 `activeVersionId` 是否非 null。", "deprecated": true }, "activeVersionId": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "isArchived": { "type": "boolean" }, "versionId": { "type": "string" }, "versionCounter": { "type": "number" }, "sourceWorkflowId": { "type": "string", "nullable": true }, "triggerCount": { "type": "number" }, "nodes": { "type": "array", "description": "组成工作流的节点", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "webhookId": { "type": "string" }, "disabled": { "type": "boolean" }, "notesInFlow": { "type": "boolean" }, "notes": { "type": "string" }, "type": { "type": "string" }, "typeVersion": { "type": "number" }, "executeOnce": { "type": "boolean" }, "alwaysOutputData": { "type": "boolean" }, "retryOnFail": { "type": "boolean" }, "maxTries": { "type": "number" }, "waitBetweenTries": { "type": "number" }, "continueOnFail": { "type": "boolean", "description": "请改用 onError", "deprecated": true }, "onError": { "type": "string" }, "position": { "type": "array", "items": { "type": "number" } }, "parameters": { "type": "object", "additionalProperties": true }, "credentials": { "type": "object" }, "customTelemetryTags": { "type": "object", "properties": { "tag": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "string" } }, "required": [ "key", "value" ] } } } } } } }, "connections": { "type": "object", "description": "节点之间的连接，以源节点名称为键" }, "nodeGroups": { "type": "array", "description": "在画布上以框架显示的节点视觉分组", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "节点分组的唯一标识符" }, "name": { "type": "string", "description": "节点分组的显示名称" }, "description": { "type": "string", "maxLength": 155, "description": "节点分组的可选纯文本说明" }, "nodeIds": { "type": "array", "description": "属于此分组的节点 ID", "items": { "type": "string" } } }, "required": [ "id", "name", "nodeIds" ] } }, "settings": { "type": "object", "description": "工作流的执行和行为设置", "properties": { "saveExecutionProgress": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "DEFAULT" ] } ] }, "saveManualExecutions": { "oneOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "DEFAULT" ] } ] }, "saveDataErrorExecution": { "type": "string", "enum": [ "DEFAULT", "all", "none" ] }, "saveDataSuccessExecution": { "type": "string", "enum": [ "DEFAULT", "all", "none" ] }, "executionTimeout": { "type": "number" }, "errorWorkflow": { "type": "string", "description": "包含错误触发器节点的工作流 ID。" }, "timezone": { "type": "string" }, "executionOrder": { "type": "string" }, "binaryMode": { "type": "string", "enum": [ "separate", "combined" ], "description": "控制如何从节点输入中解析二进制数据。这是内部派生设置，不应通过编程方式设置。工作流响应中会包含此项以供参考，但创建或更新工作流时传入的任何值都会被忽略。" }, "engineType": { "type": "string", "nullable": true, "description": "运行此工作流的执行引擎。工作流响应中会包含此项以供参考，但创建或更新工作流时传入的任何值都会被忽略。" }, "callerPolicy": { "type": "string", "enum": [ "any", "none", "workflowsFromAList", "workflowsFromSameOwner" ], "description": "控制哪些工作流可以通过 Execute Workflow 节点调用此工作流，默认为 workflowsFromSameOwner。\n\n可选项：\n- `any`：任何工作流均可调用此工作流，不作限制。\n- `none`：其他工作流均不能调用此工作流，即完全阻止。\n- `workflowsFromSameOwner`（默认）：仅属于同一项目的工作流可以调用此工作流。\n- `workflowsFromAList`：仅 `callerIds` 中列出的工作流可以调用此工作流。" }, "callerIds": { "type": "string", "description": "允许调用此工作流的工作流 ID 列表，以逗号分隔，仅在 workflowsFromAList 策略下使用" }, "timeSavedMode": { "type": "string", "enum": [ "fixed", "dynamic" ], "description": "控制每次执行节省时间的计算方式。\n\n可选项：\n- `fixed`：使用 `timeSavedPerExecution` 的值，适用于每次执行节省时间相同的情况。\n- `dynamic`：根据实际执行指标计算节省时间，忽略 `timeSavedPerExecution`。" }, "timeSavedPerExecution": { "type": "number", "description": "每次执行预计节省的时间，单位为分钟" }, "redactionPolicy": { "type": "string", "enum": [ "none", "non-manual", "manual-only", "all" ], "description": "控制是否遮蔽此工作流的执行数据。\n\n可选项：\n- `none`（默认）：不遮蔽，存储所有执行数据。\n- `non-manual`：仅遮蔽生产执行，即非手动触发的执行。\n- `manual-only`：仅遮蔽手动触发的执行。\n- `all`：遮蔽手动和生产模式的全部执行。" }, "redactCallerExecutions": { "type": "boolean", "description": "控制将此工作流作为子工作流调用的工作流，是否也在相同通道上遮蔽其执行数据。调用方的执行记录会保留此工作流输出的副本。默认为 true，仅当此工作流的输出不敏感时才应关闭。此工作流从自身子工作流收到的遮蔽要求，始终会传递给调用方。" }, "availableInMCP": { "type": "boolean", "description": "控制能否通过模型上下文协议（MCP）访问此工作流。默认为 false。工作流必须处于激活状态，且至少包含一个激活的 Webhook 节点。" }, "customTelemetryTags": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "string" } }, "required": [ "key", "value" ] } }, "credentialResolverId": { "type": "string", "description": "为此工作流解析凭据的凭据解析器 ID。这是通过凭据解析器配置管理的内部派生设置，不应通过编程方式设置。工作流响应中会包含此项以供参考，但创建或更新工作流时传入的任何值都会被忽略。" } }, "nullable": true }, "staticData": { "type": "object", "description": "工作流在执行之间保留的数据", "nullable": true }, "pinData": { "type": "object", "description": "节点的固定示例数据，以节点名称为键", "nullable": true }, "meta": { "type": "object", "description": "工作流元数据，例如模板信息", "properties": { "onboardingId": { "type": "string" }, "templateId": { "type": "string" }, "instanceId": { "type": "string" }, "templateCredsSetupCompleted": { "type": "boolean" } }, "nullable": true }, "tags": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "name": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "id", "name", "createdAt", "updatedAt" ] } }, "shared": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "workflowId": { "type": "string" }, "projectId": { "type": "string" }, "project": { "type": "object", "properties": { "id": { "type": "string", "readOnly": true }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "personal", "team" ], "readOnly": true }, "icon": { "type": "object", "description": "项目图标；项目没有图标时为 null", "properties": { "type": { "type": "string", "enum": [ "emoji", "icon" ] }, "value": { "type": "string" }, "color": { "type": "string" } }, "required": [ "type", "value" ], "nullable": true }, "description": { "type": "string", "nullable": true }, "customTelemetryTags": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "string" } }, "required": [ "key", "value" ] } }, "creatorId": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "id", "name", "type", "icon", "description", "customTelemetryTags", "creatorId", "createdAt", "updatedAt" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "role", "workflowId", "projectId", "project", "createdAt", "updatedAt" ] } }, "activeVersion": { "type": "object", "nullable": true, "properties": { "versionId": { "type": "string" }, "workflowId": { "type": "string" }, "nodes": { "type": "array", "description": "组成工作流的节点", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "webhookId": { "type": "string" }, "disabled": { "type": "boolean" }, "notesInFlow": { "type": "boolean" }, "notes": { "type": "string" }, "type": { "type": "string" }, "typeVersion": { "type": "number" }, "executeOnce": { "type": "boolean" }, "alwaysOutputData": { "type": "boolean" }, "retryOnFail": { "type": "boolean" }, "maxTries": { "type": "number" }, "waitBetweenTries": { "type": "number" }, "continueOnFail": { "type": "boolean", "description": "请改用 onError", "deprecated": true }, "onError": { "type": "string" }, "position": { "type": "array", "items": { "type": "number" } }, "parameters": { "type": "object", "additionalProperties": true }, "credentials": { "type": "object" }, "customTelemetryTags": { "type": "object", "properties": { "tag": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "string" } }, "required": [ "key", "value" ] } } } } } } }, "connections": { "type": "object", "description": "节点之间的连接，以源节点名称为键" }, "nodeGroups": { "type": "array", "description": "在画布上以框架显示的节点视觉分组", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "节点分组的唯一标识符" }, "name": { "type": "string", "description": "节点分组的显示名称" }, "description": { "type": "string", "maxLength": 155, "description": "节点分组的可选纯文本说明" }, "nodeIds": { "type": "array", "description": "属于此分组的节点 ID", "items": { "type": "string" } } }, "required": [ "id", "name", "nodeIds" ] } }, "authors": { "type": "string" }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "autosaved": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "workflowPublishHistory": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" }, "workflowId": { "type": "string" }, "versionId": { "type": "string", "nullable": true }, "event": { "type": "string", "enum": [ "activated", "deactivated" ] }, "userId": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "workflowId", "versionId", "event", "userId", "createdAt" ] } } }, "required": [ "versionId", "workflowId", "nodes", "connections", "nodeGroups", "authors", "name", "description", "autosaved", "createdAt", "updatedAt", "workflowPublishHistory" ] } }, "required": [ "id", "name", "description", "active", "activeVersionId", "createdAt", "updatedAt", "isArchived", "versionId", "versionCounter", "sourceWorkflowId", "triggerCount", "nodes", "connections", "nodeGroups", "settings", "staticData", "meta", "shared", "activeVersion" ] } }, "responses": { "unauthorized": { "description": "未授权" }, "forbidden": { "description": "禁止访问" }, "notFound": { "description": "未找到指定资源。" } } }, "paths": { "/workflows/{workflowId}/archive": { "post": { "operationId": "archiveWorkflow", "tags": [ "Workflow" ], "summary": "归档工作流", "description": "通过归档软删除工作流。此操作具有幂等性：对已归档的工作流再次归档时，会返回 200 及当前工作流。", "parameters": [ { "schema": { "type": "string" }, "required": true, "description": "工作流的 ID。", "name": "workflowId", "in": "path" } ], "responses": { "200": { "description": "操作成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/workflowPublicDto.generated" } } } }, "401": { "$ref": "#/components/responses/unauthorized" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/notFound" } } } } } }