{ "openapi": "3.0.0", "info": { "title": "n8n 公共 API", "version": "1.1.1" }, "components": { "schemas": { "importBlockingIssue.generated": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent-conflict" ] }, "kind": { "type": "string", "enum": [ "existing", "id", "task-id" ] }, "sourceAgentId": { "type": "string" }, "projectId": { "type": "string" }, "sourceTaskId": { "type": "string" }, "targetIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "type", "kind", "sourceAgentId", "projectId", "targetIds" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent-invalid" ] }, "sourceAgentId": { "type": "string" }, "path": { "type": "string" }, "message": { "type": "string" } }, "required": [ "type", "sourceAgentId", "path", "message" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent-dependency-unresolved" ] }, "sourceAgentId": { "type": "string" }, "projectId": { "type": "string" }, "dependencyType": { "type": "string", "enum": [ "agent", "workflow", "credential" ] }, "referenceId": { "type": "string" }, "path": { "type": "string" }, "reason": { "type": "string", "enum": [ "missing", "inaccessible", "ambiguous", "unsupported" ] } }, "required": [ "type", "sourceAgentId", "projectId", "dependencyType", "referenceId", "path", "reason" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "agent-policy-violation" ] }, "sourceAgentId": { "type": "string" }, "name": { "type": "string" }, "violations": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "checkId": { "type": "string" }, "message": { "type": "string" }, "subject": { "type": "string" }, "subjectType": { "type": "string" }, "scope": { "type": "string" }, "matchedRuleId": { "type": "string" }, "projectId": { "type": "string" }, "optInAvailable": { "type": "boolean" } }, "required": [ "kind", "checkId", "message" ] } } }, "required": [ "type", "sourceAgentId", "name", "violations" ] }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "workflow-conflict" ] }, "sourceWorkflowId": { "type": "string" }, "existingWorkflowId": { "type": "string" }, "name": { "type": "string" } }, "required": [ "type", "sourceWorkflowId", "existingWorkflowId", "name" ], "description": "`fail` 冲突策略下，源 id 已匹配到目标项目中现有工作流的工作流。" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "workflow-lineage-conflict" ] }, "sourceWorkflowId": { "type": "string" }, "projectId": { "type": "string" }, "existingWorkflows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "isArchived": { "type": "boolean" } }, "required": [ "id", "name", "isArchived" ] } } }, "required": [ "type", "sourceWorkflowId", "projectId", "existingWorkflows" ], "description": "包内某工作流的源 id 在目标项目中匹配到多个工作流，导入无法安全选择其中一个。" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "workflow-id-conflict" ] }, "sourceWorkflowId": { "type": "string" }, "existingWorkflowId": { "type": "string" }, "existingProjectId": { "type": "string", "nullable": true, "description": "现有工作流所属的项目；无法确定所属项目时为 null。" }, "isArchived": { "type": "boolean", "description": "现有工作流是否归档。" }, "name": { "type": "string" } }, "required": [ "type", "sourceWorkflowId", "existingWorkflowId", "existingProjectId", "isArchived", "name" ], "description": "`source` 策略下，id 已在实例上被占用的工作流。工作流 id 全局唯一，因此无法在目标项目中创建此 id。现有工作流可能属于其他项目、缺少所有者共享关系、使用不同源 id，也可能已归档。" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "workflow-folder-conflict" ] }, "sourceWorkflowId": { "type": "string" }, "existingWorkflowId": { "type": "string" }, "existingParentFolderId": { "type": "string", "nullable": true, "description": "匹配工作流当前所在的文件夹；位于项目根目录时为 null。" }, "targetFolderId": { "type": "string", "nullable": true, "description": "请求导入到的文件夹；项目包将工作流放在项目根目录时为 null。" }, "name": { "type": "string" } }, "required": [ "type", "sourceWorkflowId", "existingWorkflowId", "existingParentFolderId", "targetFolderId", "name" ], "description": "源 id 已匹配到目标项目中现有工作流，但现有工作流所在文件夹与导入目标不同。导入不能在原地更新工作流的同时移动它。对于项目包，项目根目录也属于目标位置。" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "workflow-archive-forbidden" ] }, "sourceWorkflowId": { "type": "string" }, "existingWorkflowId": { "type": "string" }, "name": { "type": "string" }, "projectId": { "type": "string", "description": "匹配工作流所属的项目。" }, "transition": { "type": "string", "enum": [ "archive", "unarchive" ], "description": "导入为使工作流与包中状态一致而需要执行的步骤。" } }, "required": [ "type", "sourceWorkflowId", "existingWorkflowId", "name", "projectId", "transition" ], "description": "匹配工作流的归档状态与包不同，因此导入需要归档或取消归档，但调用方缺少该工作流的 `workflow:delete` 权限。在计划阶段报告，不写入任何内容。" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "credential-unresolved" ] }, "kind": { "type": "string", "enum": [ "not_found", "unknown_type", "source_not_found", "type_mismatch" ] }, "sourceId": { "type": "string" }, "targetId": { "type": "string", "description": "目标凭据 id：对于 `not_found`，是无法解析的显式绑定；对于 `type_mismatch`，是通过显式绑定或自动匹配已解析到、但类型错误的凭据 id。" }, "expectedType": { "type": "string", "description": "对于 `type_mismatch`：包中工作流节点需要的凭据类型。" }, "actualType": { "type": "string", "description": "对于 `type_mismatch`：已解析目标凭据的实际类型。" }, "usedBy": { "type": "array", "items": { "$ref": "#/components/schemas/packageRequirementConsumer.generated" } } }, "required": [ "type", "kind", "sourceId", "usedBy" ], "description": "无法在目标项目中解析的凭据引用。" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "credential-conflict" ] }, "kind": { "type": "string", "enum": [ "differs", "divergent" ], "description": "`differs`：在 `credentialConflictPolicy=fail` 下，包会更改目标凭据的名称或值。`divergent`：在 `overwrite` 下，包内两个或多个名称或值不同的凭据解析到了同一个目标凭据。导入不会代为选择其中之一。" }, "targetId": { "type": "string", "description": "目标凭据的 id。" }, "sourceIds": { "type": "array", "items": { "type": "string" }, "description": "解析到该目标凭据的包内凭据 id。对于 `differs`，是会更改该目标凭据的包内凭据。" }, "name": { "type": "string", "description": "目标凭据的名称。" }, "usedBy": { "type": "array", "items": { "$ref": "#/components/schemas/packageRequirementConsumer.generated" }, "description": "包中使用所列包内凭据的使用方。" } }, "required": [ "type", "kind", "targetId", "sourceIds", "name", "usedBy" ], "description": "已匹配、但凭据冲突策略不允许导入更改的凭据。只检查导入有能力更新的凭据，即归导入所涉及项目所有的凭据。绝不报告值。" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "credential-update-forbidden" ] }, "targetId": { "type": "string", "description": "目标凭据的 id。" }, "sourceIds": { "type": "array", "items": { "type": "string" }, "description": "解析到此凭据的包内凭据 id。" }, "name": { "type": "string", "description": "目标凭据的名称。" }, "usedBy": { "type": "array", "items": { "$ref": "#/components/schemas/packageRequirementConsumer.generated" }, "description": "包中使用所列包内凭据的使用方。" } }, "required": [ "type", "targetId", "sourceIds", "name", "usedBy" ], "description": "导入有能力更新、但调用方缺少其 `credential:update` 权限的匹配凭据。仅在 `credentialConflictPolicy` 为 `overwrite` 或 `fail` 时适用。导入不会读取其值，因此即使包不会更改它，也会阻止导入。使用 `keep-existing` 可在不更改的情况下绑定它。" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "project-conflict" ] }, "kind": { "type": "string", "enum": [ "fail-policy" ] }, "sourceProjectId": { "type": "string" }, "name": { "type": "string", "description": "项目在包中的名称。" } }, "required": [ "type", "kind", "sourceProjectId", "name" ], "description": "`projectConflictPolicy=fail` 下，包定义的项目已存在于此实例。" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "folder-conflict" ] }, "kind": { "type": "string", "enum": [ "parent-mismatch", "id-in-other-project", "fail-policy" ] }, "sourceFolderId": { "type": "string" }, "name": { "type": "string" }, "existingParentFolderId": { "type": "string", "nullable": true, "description": "对于 `parent-mismatch`：目标上匹配文件夹的当前父文件夹。" }, "expectedParentFolderId": { "type": "string", "nullable": true, "description": "对于 `parent-mismatch`：包要求放置该文件夹的父文件夹。" }, "existingProjectId": { "type": "string", "nullable": true, "description": "对于 `id-in-other-project`：已拥有此 id 的项目。" } }, "required": [ "type", "kind", "sourceFolderId", "name" ], "description": "无法按原样导入的包内文件夹。`kind` 区分原因：`parent-mismatch`（按 id 匹配的文件夹所在父文件夹与包要求的位置不同）、`id-in-other-project`（文件夹 id 已存在于其他项目，id 全局唯一）或 `fail-policy`（文件夹已存在，且 `folderConflictPolicy` 为 `fail`）。" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "workflow-removal-forbidden" ] }, "workflowId": { "type": "string" }, "name": { "type": "string" }, "projectId": { "type": "string", "description": "当时对工作流进行对齐处理的项目。" } }, "required": [ "type", "workflowId", "name", "projectId" ], "description": "导入原本会移除、但调用方缺少其 `workflow:delete` 权限的工作流：可能因为 `folderConflictPolicy=overwrite` 要移除包未包含的工作流，或选择项中的 `deletedWorkflowIds` 指定了它。会报告问题，而不只移除其中一部分，以免项目既不匹配包，也不保持先前状态。" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "workflow-removal-conflict" ] }, "sourceWorkflowId": { "type": "string" }, "workflowId": { "type": "string", "description": "所选工作流的目标 id。" }, "projectId": { "type": "string" } }, "required": [ "type", "sourceWorkflowId", "workflowId", "projectId" ], "description": "某个所选工作流解析到的目标 id 出现在 `deletedWorkflowIds` 中。导入会在任何写入前停止，即使冲突策略为 `skip` 也如此。" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "folder-removal-forbidden" ] }, "folderId": { "type": "string" }, "name": { "type": "string" }, "projectId": { "type": "string", "description": "当时对文件夹进行对齐处理的项目。" } }, "required": [ "type", "folderId", "name", "projectId" ], "description": "`folderConflictPolicy=overwrite` 原本会删除的文件夹：包未定义它，且对齐处理后它为空，但调用方缺少目标项目的 `folder:delete` 权限。会报告问题，而不只移除其中一部分，以免项目既不匹配包，也不保持先前状态。" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "data-table-unresolved" ] }, "kind": { "type": "string", "enum": [ "missing", "id-conflict", "name-conflict", "schema-incompatible", "module-disabled", "permission-denied" ] }, "sourceId": { "type": "string", "description": "整个导入层面的失败（`module-disabled`、`permission-denied`）不返回此字段。" }, "name": { "type": "string" }, "existingProjectId": { "type": "string", "description": "对于 `id-conflict`：拥有冲突目标表的项目。" }, "missingColumns": { "type": "array", "items": { "type": "string" }, "description": "对于 `schema-incompatible`：目标表缺少的包内列。" }, "typeMismatches": { "type": "array", "items": { "type": "object", "properties": { "column": { "type": "string" }, "expectedType": { "type": "string" }, "actualType": { "type": "string" } }, "required": [ "column", "expectedType", "actualType" ] }, "description": "对于 `schema-incompatible`：目标类型不同的包内列。" }, "extraColumns": { "type": "array", "items": { "type": "string" }, "description": "对于 `schema-incompatible`，在 `fail` 策略下：目标上存在、但包内架构中没有的列。" }, "overwriteChanges": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "add-column" ] }, "column": { "type": "string" }, "type": { "type": "string", "enum": [ "string", "number", "boolean", "date" ] }, "destructive": { "type": "boolean", "enum": [ false ] } }, "required": [ "kind", "column", "type", "destructive" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "remove-column" ] }, "column": { "type": "string" }, "type": { "type": "string", "enum": [ "string", "number", "boolean", "date" ] }, "destructive": { "type": "boolean", "enum": [ true ] } }, "required": [ "kind", "column", "type", "destructive" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "change-column-type" ] }, "column": { "type": "string" }, "from": { "type": "string", "enum": [ "string", "number", "boolean", "date" ] }, "to": { "type": "string", "enum": [ "string", "number", "boolean", "date" ] }, "destructive": { "type": "boolean", "enum": [ true ] } }, "required": [ "kind", "column", "from", "to", "destructive" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "rename-column" ] }, "from": { "type": "string" }, "to": { "type": "string" }, "destructive": { "type": "boolean", "enum": [ false ] } }, "required": [ "kind", "from", "to", "destructive" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "reorder-columns" ] }, "destructive": { "type": "boolean", "enum": [ false ] } }, "required": [ "kind", "destructive" ] }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "rename-table" ] }, "from": { "type": "string" }, "to": { "type": "string" }, "destructive": { "type": "boolean", "enum": [ false ] } }, "required": [ "kind", "from", "to", "destructive" ] } ], "description": "`dataTableSchemaConflictPolicy=overwrite` 将对或已对匹配目标表的架构进行的单项变更。`destructive` 操作会移除相应列中的值。", "type": "object" }, "description": "对于 `schema-incompatible`：`overwrite` 将对目标表进行的变更。" }, "missingScope": { "type": "string", "enum": [ "dataTable:create", "dataTable:update" ], "description": "对于 `permission-denied`：用户缺少的项目作用域。" }, "conflictingTableId": { "type": "string", "description": "对于 `name-conflict`：已占用或声明使用该名称的其他表。" }, "currentName": { "type": "string", "description": "对于重命名的 `name-conflict`：匹配表的当前名称。" }, "usedBy": { "type": "array", "items": { "$ref": "#/components/schemas/packageRequirementConsumer.generated" } } }, "required": [ "type", "kind", "usedBy" ], "description": "包中工作流引用、但无法对照目标项目解析的数据表。原因可能来自 `dataTableMissingMode=must-preexist` 或 `dataTableSchemaConflictPolicy`，也可能是实例禁用了数据表模块，或调用方缺少解析所需的作用域。" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "tag-unresolved" ] }, "kind": { "type": "string", "enum": [ "rename-drift", "name-collision", "invalid-name", "invalid-id", "permission-denied" ] }, "sourceId": { "type": "string", "description": "标签在包中的 id。`permission-denied` 时不返回。" }, "name": { "type": "string", "description": "包内标签名称，已去除两端空白。`permission-denied` 时不返回。" }, "missingScope": { "type": "string", "enum": [ "tag:create", "tag:update" ], "description": "对于 `permission-denied`：导入用户缺少的全局作用域。" }, "existingTagId": { "type": "string", "description": "存在争用的目标标签 id：当前占用所需名称的其他标签，或原本要在对齐处理中更改 id、但该操作被阻止的目标标签。如果只是两个包内标签彼此冲突，而非争用目标标签，则不返回。" }, "existingName": { "type": "string", "description": "对于 `rename-drift`：相同 id 的目标标签当前名称。" }, "usedBy": { "type": "array", "items": { "$ref": "#/components/schemas/packageRequirementConsumer.generated" }, "description": "包中引用源标签的使用方。不包括被跳过的使用方，也不包括关联到争用目标标签的工作流。" } }, "required": [ "type", "kind", "usedBy" ], "description": "包中工作流引用、但无法在目标实例上解析的标签。`kind` 区分原因：`rename-drift`（相同 id 的目标标签名称不同，发生在 `tagConflictPolicy=fail` 下，或 `rename` 下包内名称被其他标签占用时）、`name-collision`（id 空闲，但在 `tagMissingMode=create` 且 `tagConflictPolicy=fail` 下，名称属于其他标签；两个包内标签相互冲突，或对齐处理中原本要更改 id 的目标标签被其他包内标签声明使用时，也会报告）、`invalid-name` / `invalid-id`（包内标签的名称或 id 无法写入此实例）或 `permission-denied`（导入用户缺少计划所需的全局 `tag:create` / `tag:update` 作用域）。" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "variable-unresolved" ] }, "name": { "type": "string", "description": "在目标项目和全局作用域中均无匹配项的需求名称。" }, "usedBy": { "type": "array", "items": { "$ref": "#/components/schemas/packageRequirementConsumer.generated" } } }, "required": [ "type", "name", "usedBy" ], "description": "`variableMissingMode=must-preexist` 下，无法在目标项目或全局作用域中解析的变量引用。" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "variable-conflict" ] }, "name": { "type": "string", "description": "值不同的变量名称。" }, "projectId": { "type": "string", "description": "已解析变量所属的项目；在全局作用域解析到时不返回。" }, "usedBy": { "type": "array", "items": { "$ref": "#/components/schemas/packageRequirementConsumer.generated" } } }, "required": [ "type", "name", "usedBy" ], "description": "`variableConflictPolicy=fail` 下，已在目标项目或全局作用域解析到、但其值与包内值不同的变量。在 `overwrite` 下，如果包中的项目解析到了同一行，却要求它使用不同值，也会按每个作用域报告一次。绝不报告值，只报告变量名称及解析到它的作用域。" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "variable-limit-exceeded" ] }, "limit": { "type": "integer", "description": "实例变量配额。" }, "remaining": { "type": "integer", "description": "配额内仍可创建的变量行数。导入被阻止是因为 `requested` 超过此剩余数，而非超过 `limit`。" }, "requested": { "type": "integer", "description": "导入原本会创建的新变量行数，已按目标去重。" }, "names": { "type": "array", "items": { "type": "string" }, "description": "导入原本会创建的唯一变量名称。" }, "usedBy": { "type": "array", "items": { "$ref": "#/components/schemas/packageRequirementConsumer.generated" }, "description": "包中引用任一所列变量的使用方。" } }, "required": [ "type", "limit", "remaining", "requested", "names", "usedBy" ], "description": "通过 `create-stub` 或 `create-with-value` 创建包内变量会超过实例变量配额（`quota:maxVariables`）。整个导入只报告一次，不创建任何内容。" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "missing-node-type" ] }, "nodeType": { "type": "string", "description": "包中工作流使用的完整节点类型名称。" }, "typeVersion": { "type": "number", "description": "包中工作流使用的节点类型版本。" }, "usedBy": { "type": "array", "items": { "$ref": "#/components/schemas/packageRequirementConsumer.generated" }, "description": "包中使用此节点类型和版本的使用方。" } }, "required": [ "type", "nodeType", "typeVersion", "usedBy" ], "description": "`missingNodeTypeMode=fail` 下，包内工作流使用了此实例未安装的节点类型或节点类型版本。每个缺失的 `(nodeType, typeVersion)` 组合报告一个问题。" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "policy-violation" ] }, "sourceWorkflowId": { "type": "string", "description": "工作流在包中的 id。" }, "name": { "type": "string" }, "violations": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "checkId": { "type": "string" }, "message": { "type": "string" }, "subject": { "type": "string" }, "subjectType": { "type": "string" }, "scope": { "type": "string" }, "matchedRuleId": { "type": "string" }, "projectId": { "type": "string" }, "optInAvailable": { "type": "boolean" } }, "required": [ "kind", "checkId", "message" ] } } }, "required": [ "type", "sourceWorkflowId", "name", "violations" ], "description": "被内容导入策略拒绝的工作流。这会使整个包失败，而非仅跳过该工作流：导入会将跨工作流引用重写为各工作流将获得的 id，丢弃其中一个工作流会使调用它的工作流指向从未写入的记录。" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "credential-policy-violation" ] }, "sourceId": { "type": "string", "description": "凭据在包中的 id。" }, "targetId": { "type": "string", "description": "目标实例上匹配凭据的 id。策略在 `credentialConflictPolicy=overwrite` 下拒绝更新此凭据时返回；策略拒绝的是导入原本会创建的凭据时不返回。" }, "name": { "type": "string" }, "credentialType": { "type": "string" }, "usedBy": { "type": "array", "items": { "$ref": "#/components/schemas/packageRequirementConsumer.generated" }, "description": "包中使用此凭据的使用方。" }, "violations": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string" }, "checkId": { "type": "string" }, "message": { "type": "string" }, "subject": { "type": "string" }, "subjectType": { "type": "string" }, "scope": { "type": "string" }, "matchedRuleId": { "type": "string" }, "projectId": { "type": "string" }, "optInAvailable": { "type": "boolean" } }, "required": [ "kind", "checkId", "message" ] } } }, "required": [ "type", "sourceId", "credentialType", "usedBy", "violations" ], "description": "导入原本会写入、但被凭据保存策略或内容导入策略拒绝的凭据，例如实例不允许的凭据类型的占位凭据，或对匹配凭据的更新。导入会在任何写入前停止。" } ], "type": "object" }, "packageRequirementConsumer.generated": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "workflow", "agent" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "kind", "id" ] } } } }