{ "openapi": "3.0.0", "info": { "title": "n8n 公共 API", "version": "1.1.1" }, "tags": [ { "name": "N8nPackage", "description": "Beta 阶段，即使不提升主版本号，也可能出现破坏性变更。" } ], "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" } }, "parameters": { "idempotencyKey": { "name": "Idempotency-Key", "in": "header", "description": "此 POST 请求的安全重试键。使用 1 到 128 个可见 ASCII 字符。相同的键配合相同的请求，会返回首次成功的响应。使用此键发送不同请求时返回 422。首次请求仍在处理时重试，会返回 409。", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[\\x21-\\x7E]+$" } } }, "schemas": { "importResultDto.generated": { "type": "object", "properties": { "package": { "type": "object", "properties": { "sourceN8nVersion": { "type": "string" }, "sourceId": { "type": "string" }, "exportedAt": { "type": "string", "format": "date-time" } }, "required": [ "sourceN8nVersion", "sourceId", "exportedAt" ] }, "workflows": { "type": "array", "items": { "type": "object", "properties": { "sourceWorkflowId": { "type": "string", "description": "工作流在包中的 id。" }, "localId": { "type": "string", "description": "目标实例上的工作流 id：`created` 时新建（`workflowIdPolicy=new` 时生成新 id，`source` 时使用包中的 id）；`updated`/`skipped` 时使用现有工作流的 id。" }, "name": { "type": "string" }, "projectId": { "type": "string" }, "parentFolderId": { "type": "string", "nullable": true }, "activeVersionId": { "type": "string", "nullable": true, "description": "目标实例上的已发布版本（如有）。导入后工作流未发布时为 `null`。" }, "isArchived": { "type": "boolean", "description": "导入后工作流在目标上是否归档。采用 `new-version` 时，遵循包中的 `isArchived` 标记；被跳过的工作流保留自身状态。" }, "publishing": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "published", "unpublished", "unchanged", "blocked", "failed" ], "description": "`blocked` 表示导入版本无法发布，且没有激活版本，例如工作流使用了空白或不完整凭据，或使用实例未安装的节点类型。如果先前发布的版本仍处于激活状态，`state` 会为 `unchanged`，并附带 `skippedPublishReason`。`failed` 表示尝试了发布或取消发布，但操作未成功。" }, "error": { "type": "string", "description": "`state` 为 `failed` 时返回，说明无法应用发布或取消发布操作的原因。" }, "blockedReason": { "type": "string", "enum": [ "stub-credential", "incomplete-credential", "missing-node-type" ], "description": "`state` 为 `blocked` 时返回：导入版本无法发布，且没有激活版本。" }, "skippedPublishReason": { "type": "string", "enum": [ "stub-credential", "incomplete-credential", "missing-node-type" ], "description": "`state` 为 `unchanged`，但策略原本要求发布导入版本时返回：先前发布的版本仍处于激活状态，例如更新后凭据为空或不完整。" } }, "required": [ "state" ], "description": "将所选发布策略应用到此工作流的结果。" }, "status": { "type": "string", "enum": [ "created", "updated", "skipped" ], "description": "此包中工作流的导入结果。" } }, "required": [ "sourceWorkflowId", "localId", "name", "projectId", "parentFolderId", "activeVersionId", "isArchived", "publishing", "status" ] } }, "removedWorkflows": { "type": "array", "items": { "type": "object", "properties": { "workflowId": { "type": "string", "description": "此实例上被移除工作流的 id。" }, "name": { "type": "string" }, "projectId": { "type": "string", "description": "对工作流进行对齐处理的项目。" }, "parentFolderId": { "type": "string", "nullable": true, "description": "工作流原所在文件夹；位于项目根目录时为 null。" }, "deletion": { "type": "string", "enum": [ "archived", "deleted" ], "description": "实际发生的结果，而非 `overwriteDeletionPolicy` 请求的操作：如果请求 `hard-delete`，但相应记录尚不能删除，则报告为 `archived`。" } }, "required": [ "workflowId", "name", "projectId", "parentFolderId", "deletion" ] }, "description": "此次导入期间从目标移除的工作流。" }, "removedFolders": { "type": "array", "items": { "type": "object", "properties": { "folderId": { "type": "string" }, "name": { "type": "string" }, "projectId": { "type": "string" }, "parentFolderId": { "type": "string", "nullable": true, "description": "原所在文件夹；位于项目根目录时为 null。" } }, "required": [ "folderId", "name", "projectId", "parentFolderId" ] }, "description": "包未定义、且在对齐处理后变为空的文件夹，由 `folderConflictPolicy=overwrite` 移除。仍包含任何内容的文件夹会保留，因此不会一并清理仅存在于目标的内容。其他策略下始终为空。" }, "folders": { "type": "array", "items": { "type": "object", "properties": { "sourceFolderId": { "type": "string", "description": "文件夹在包中的 id。" }, "localId": { "type": "string", "description": "目标实例上的文件夹 id，等于 `sourceFolderId`，即复用文件夹 id。" }, "name": { "type": "string" }, "parentFolderId": { "type": "string", "nullable": true, "description": "目标上解析得到的父文件夹；位于项目根目录时为 `null`。" }, "status": { "type": "string", "enum": [ "created", "skipped" ], "description": "此包中文件夹的导入结果。" } }, "required": [ "sourceFolderId", "localId", "name", "parentFolderId", "status" ] }, "description": "在目标项目中创建或跳过的文件夹结构。" }, "projects": { "type": "array", "items": { "type": "object", "properties": { "sourceProjectId": { "type": "string", "description": "项目在包中的 id。" }, "localId": { "type": "string", "description": "目标实例上的项目 id，等于 `sourceProjectId`，即复用项目 id。" }, "name": { "type": "string", "description": "目标上的项目名称：采用 `overwrite` 时使用包中的名称，采用 `merge` 时使用原有名称。" }, "status": { "type": "string", "enum": [ "created", "updated", "skipped" ], "description": "此包中项目的导入结果。`skipped` 表示项目已存在，且 `projectConflictPolicy=merge` 保留了原项目详情；项目内容仍会导入。" } }, "required": [ "sourceProjectId", "localId", "name", "status" ] }, "description": "创建的项目结构，或匹配后更新或保留原样的项目结构，参见 `projectConflictPolicy`。项目包中会返回；导入独立工作流或文件夹时为空。" }, "bindings": { "type": "object", "properties": { "workflows": { "type": "object", "additionalProperties": { "type": "string" } }, "credentials": { "type": "object", "additionalProperties": { "type": "string" }, "description": "包清单 `requirements.credentials` 中的凭据 id → 目标实例上解析得到的凭据 id。同时涵盖匹配的现有凭据，以及通过 `credentialMissingMode=create-stub` 或 `create-with-values` 创建的凭据。" } }, "required": [ "workflows", "credentials" ], "description": "导入产生的源 id → 目标 id 映射，每种实体类型一个映射。每个值都将实体在包中的 id 映射到目标实例上的 id。" }, "credentials": { "type": "object", "properties": { "matched": { "type": "array", "items": { "type": "string" }, "description": "包中匹配到目标实例现有凭据的源凭据 id。" }, "stubbed": { "type": "array", "items": { "type": "string" }, "description": "已在目标项目中为其创建空白占位凭据的源凭据 id。" }, "seeded": { "type": "array", "items": { "type": "string" }, "description": "已在目标项目中为其创建凭据的源凭据 id；这些凭据包含包内表达式值携带的全部源数据。" }, "incomplete": { "type": "array", "items": { "type": "string" }, "description": "已在目标项目中使用包内表达式值创建凭据的源凭据 id，但包未确认其包含全部源数据。这些凭据还需补充信息。导入不会发布使用它们的工作流导入版本，原因为 `incomplete-credential`。" }, "updated": { "type": "array", "items": { "type": "string" }, "description": "此次导入通过 `credentialConflictPolicy=overwrite` 更改了其匹配凭据的源凭据 id。这些 id 不会列在 `matched` 中。其他策略下为空。" } }, "required": [ "matched", "stubbed", "seeded", "incomplete", "updated" ], "description": "按解析结果分组的源凭据 id：匹配现有凭据、创建空白占位凭据、创建带初始数据的凭据、创建不完整凭据，或匹配到此次导入已更新的凭据。完整的源→目标 id 映射见 `bindings.credentials`。" }, "dataTables": { "type": "object", "properties": { "matched": { "type": "integer", "minimum": 0 }, "created": { "type": "integer", "minimum": 0 }, "updated": { "type": "integer", "minimum": 0 } }, "required": [ "matched", "created", "updated" ] }, "variables": { "type": "object", "properties": { "matched": { "type": "array", "items": { "type": "string" }, "description": "解析到现有变量且保持不变的变量名，优先查找导入项目作用域，再查找全局作用域。此次导入重写的已解析变量会列在 `updated` 中。" }, "missing": { "type": "array", "items": { "type": "string" }, "description": "导入后仍未解析到的变量名。`variableMissingMode=do-nothing` 下，这些仅为警告：导入仍成功，不创建任何变量。成功的 `create-stub` 或 `create-with-value` 导入通常使此列表为空。" }, "created": { "type": "array", "items": { "type": "string" }, "description": "通过 `variableMissingMode=create-with-value` 使用包内值创建的变量名。空白占位变量会列在 `stubbed` 中。" }, "stubbed": { "type": "array", "items": { "type": "string" }, "description": "此次导入创建为空值的变量名：使用了 `variableMissingMode=create-stub`，或 `create-with-value` 没有可导出的值。其他结果下为空。" }, "updated": { "type": "array", "items": { "type": "string" }, "description": "此次导入通过 `variableConflictPolicy=overwrite`，将其现有值替换为包内值的变量名。其他策略下为空。" } }, "required": [ "matched", "missing", "created", "stubbed", "updated" ], "description": "包的变量需求解析结果。仅返回名称，响应绝不包含值。对于项目包，这些数组是在包级别汇总各目标结果得到的并集，可能重叠，例如某名称在一个项目中创建时带有值，在另一个项目中创建为空白占位变量；存在外部并发写入时，只能尽力准确分类。" }, "tags": { "type": "object", "properties": { "matched": { "type": "array", "items": { "type": "string" }, "description": "解析到 id 和名称均相同的现有标签，按原样附加。" }, "created": { "type": "array", "items": { "type": "string" }, "description": "此次导入通过 `tagMissingMode=create` 创建的标签，按名称列出。" }, "renamed": { "type": "array", "items": { "type": "string" }, "description": "通过 `tagConflictPolicy=rename` 重命名为包内名称的目标标签，按新名称列出。" }, "reconciled": { "type": "array", "items": { "type": "string" }, "description": "发生名称冲突时，通过 `tagConflictPolicy=rename` 将 id 改为包（源）id 的现有目标标签；其名称、工作流标签关联和文件夹标签关联均保留。" }, "skipped": { "type": "array", "items": { "type": "string" }, "description": "通过 `tagMissingMode=do-nothing` 或 `tagConflictPolicy=skip` 从导入中丢弃的标签：不创建、不重命名，也不附加到任何导入工作流。" } }, "required": [ "matched", "created", "renamed", "reconciled", "skipped" ], "description": "导入工作流引用的标签的解析结果，按源 id 匹配，仅包含标签名称。" } }, "required": [ "package", "workflows", "removedWorkflows", "removedFolders", "folders", "projects", "bindings", "credentials", "dataTables", "variables", "tags" ] }, "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" ] } }, "responses": { "badRequest": { "description": "请求无效，或提供的数据格式错误。" }, "unauthorized": { "description": "未授权" }, "forbidden": { "description": "禁止访问" }, "notFound": { "description": "未找到指定资源。" }, "contentTooLarge": { "description": "内容过大。" }, "unsupportedMediaType": { "description": "不支持的媒体类型。" }, "internalServerError": { "description": "服务器内部错误。" } } }, "paths": { "/n8n-packages/import-selection": { "post": { "operationId": "importPackageSelection", "tags": [ "N8nPackage" ], "summary": "Beta：从 n8n 包导入所选工作流子集", "description": "**Beta**——即使不提升主版本号，也可能出现破坏性变更。\n\n从 gzip 压缩的 tar 包（`.n8np`）的一个源项目中导入所选工作流子集，而非整个包。使用 multipart 字段 `package` 发送归档。导入采用**增量选择**方式（cherry-pick），绝不移除选择中省略的工作流：仅创建或更新 `selectedWorkflowIds` 指定的工作流，仅删除 `deletedWorkflowIds` 指定的目标工作流。\n\n`selectedProjectId` 指定此次选择所属的单个源项目，使用它在包中的 id。所选工作流写入实例上 id 与源项目相同的项目；项目不存在时创建，没有单独的目标项目字段。`selectedWorkflowIds` 是该项目内的源 id，属于其他项目的 id 会被丢弃。`deletedWorkflowIds` 是同一项目中的目标 id；不存在的 id 视为可接受的空操作，删除需要 `workflow:delete` 作用域。删除 id 不得与任何所选工作流的目标 id 相同，即使 `workflowConflictPolicy=skip` 也不允许；重叠会在任何写入前返回 409。\n\n必须使用项目包，工作流包会以 400 拒绝。选择导入的文件夹、标签和项目冲突策略固定，不接受配置；仅 `workflowConflictPolicy`、`workflowIdPolicy` 和 `overwriteDeletionPolicy` 可配置。最大上传大小为 `N8N_ENDPOINTS_PAYLOAD_SIZE_MAX` MB，默认 16。调用方通过 `workflow:import` 作用域获得授权。", "parameters": [ { "$ref": "#/components/parameters/idempotencyKey" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "package": { "type": "string", "description": "gzip 压缩的 tar 包（`.n8np`）。", "format": "binary" }, "selectedProjectId": { "type": "string", "minLength": 1, "description": "此次选择所属的单个源项目 id，使用它在包中的值。" }, "selectedWorkflowIds": { "type": "string", "description": "以 JSON 编码的源工作流 id 数组，指定从 `selectedProjectId` 导入的工作流，例如 `[\"wf-1\",\"wf-2\"]`。允许空数组（`[]`），适合仅删除的请求。不属于指定项目的 id 会被丢弃。" }, "deletedWorkflowIds": { "type": "string", "description": "可选的 JSON 编码目标工作流 id 数组，指定从相应项目移除的工作流，例如 `[\"wf-3\"]`。即使采用增量方式，仍执行移除，具体方式遵循 `overwriteDeletionPolicy`，默认归档。不存在的 id 视为空操作，除非它也是选定目标。不得包含所选工作流的目标 id。需要 `workflow:delete` 作用域。" }, "workflowConflictPolicy": { "type": "string", "enum": [ "new-version", "fail", "skip" ], "default": "new-version", "description": "所选工作流按源 id 匹配到目标项目现有工作流时如何处理。`new-version`（默认）更新并创建新版本；`fail` 在存在任何匹配工作流时拒绝导入；`skip` 保留匹配工作流不变。更改归档状态还需要 `workflow:delete` 作用域。" }, "workflowIdPolicy": { "type": "string", "enum": [ "new", "source" ], "default": "source", "description": "控制新建工作流获得的 id。`source`（默认）在目标实例上复用包内工作流 id；`new` 生成新 id，并将包内 id 记录为 `sourceWorkflowId`。已匹配到现有工作流的工作流，无论策略如何，都保留现有工作流当前的 id。" }, "overwriteDeletionPolicy": { "type": "string", "enum": [ "archive", "hard-delete" ], "default": "archive", "description": "如何移除 `deletedWorkflowIds` 中的 id。`archive`（默认）将其归档，使工作流及执行历史仍可恢复。`hard-delete` 先归档以取消发布（仅删除本身不会完成取消发布），然后永久删除工作流及其执行记录。`removedWorkflows` 中每个条目的 `deletion` 字段报告实际结果：如果请求 `hard-delete`，但取消发布延迟了触发器清理，导致记录尚不能删除，则保留为 `archived`，而不使内容已经写入的导入失败。" } }, "required": [ "package", "selectedProjectId", "selectedWorkflowIds" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "操作成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/importResultDto.generated" } } } }, "400": { "$ref": "#/components/responses/badRequest" }, "401": { "$ref": "#/components/responses/unauthorized" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/notFound" }, "409": { "description": "至少存在一项冲突而阻止导入，例如 `workflowConflictPolicy=fail` 下的工作流源 id 冲突，或选定目标同时被指定删除（`workflow-removal-conflict`）。", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/importBlockingIssue.generated" } } }, "required": [ "message", "issues" ] } } } }, "413": { "$ref": "#/components/responses/contentTooLarge" }, "415": { "$ref": "#/components/responses/unsupportedMediaType" }, "422": { "description": "仅因非冲突问题而阻止导入，例如调用方无权进行的删除（`workflow-removal-forbidden`）、未解析的凭据，或实例未安装的节点类型。", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "issues": { "type": "array", "items": { "$ref": "#/components/schemas/importBlockingIssue.generated" } } }, "required": [ "message", "issues" ] } } } }, "500": { "$ref": "#/components/responses/internalServerError" } } } } } }