{
  "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]+$"
        }
      }
    },
    "responses": {
      "badRequest": {
        "description": "请求无效，或提供的数据格式错误。"
      },
      "unauthorized": {
        "description": "未授权"
      },
      "forbidden": {
        "description": "禁止访问"
      },
      "notFound": {
        "description": "未找到指定资源。"
      },
      "conflict": {
        "description": "冲突"
      },
      "unsupportedMediaType": {
        "description": "不支持的媒体类型。"
      },
      "unprocessableEntity": {
        "description": "无法处理的实体"
      }
    }
  },
  "paths": {
    "/n8n-packages/export": {
      "post": {
        "operationId": "exportPackage",
        "tags": [
          "N8nPackage"
        ],
        "summary": "Beta：将智能体、工作流、文件夹或项目导出为 n8n 包",
        "description": "**Beta**——即使不提升主版本号，也可能出现破坏性变更。\n\n将智能体、工作流、文件夹或整个项目导出为 gzip 压缩的 tar 归档（.n8np）。提供 `agentIds`/`workflowIds`/`folderIds`，或 `projectIds`，两组不可混用。每个导出文件夹都包含其嵌套文件夹。启用智能体模块时，整个项目的导出会包含其智能体；显式选择智能体需要启用智能体模块。空项目仅导出项目元数据。`versionPolicy` 选择智能体和工作流的版本，默认为 `latest`。`dependencyPolicy` 应用于两类实体，所需定义未包含在包中时，默认采用 `fail`。响应以 `application/gzip` 流式传输，并包含 `Content-Disposition` 附件响应头。需要获得 n8n Packages 功能许可。\n\nAPI 密钥作用域：显式选择智能体需要 `agent:export`；显式选择工作流或文件夹需要 `workflow:export`；导出整个项目只需 `project:export`，其中包括项目的智能体和工作流。包含的依赖项无需额外 API 密钥作用域。调用方的项目权限适用于所有包含的实体。`includeVariableValues` 为 true（默认），且导出实体引用变量时，还需要 `variable:list`；未引用变量的导出无需此作用域。\n\n智能体定义包含引用的技能、自定义工具和计划。不包含知识库文件和运行时数据。智能体包导入仍不可用。\n",
        "parameters": [
          {
            "$ref": "#/components/parameters/idempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "agentIds": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "minLength": 1
                    },
                    "minItems": 1,
                    "maxItems": 300,
                    "description": "要包含的智能体 ID，需要启用智能体模块。"
                  },
                  "workflowIds": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "minLength": 1
                    },
                    "minItems": 1,
                    "maxItems": 300,
                    "description": "导出包中要包含的工作流 ID。"
                  },
                  "folderIds": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "minLength": 1
                    },
                    "minItems": 1,
                    "maxItems": 300,
                    "description": "导出包中要包含的文件夹 ID，每个文件夹连同其嵌套文件夹一起导出。"
                  },
                  "projectIds": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "minLength": 1
                    },
                    "minItems": 1,
                    "maxItems": 300,
                    "description": "导出包中要包含的项目 ID，启用智能体模块时包括其智能体。"
                  },
                  "includeVariableValues": {
                    "type": "boolean",
                    "default": true,
                    "description": "是否将导出实体引用的变量值包含在包中。为 `false` 时，变量仍以名称／类型文件形式包含在包中，并列在包需求中，但包不携带任何变量值。"
                  },
                  "includeTags": {
                    "type": "boolean",
                    "default": true,
                    "description": "是否将导出工作流关联的标签包含在包中。为 `false` 时，包不携带任何标签文件、标签引用或标签需求。"
                  },
                  "dependencyPolicy": {
                    "type": "string",
                    "enum": [
                      "fail",
                      "reference-only",
                      "include-in-package"
                    ],
                    "default": "fail",
                    "description": "处理所选包内容之外的工作流和智能体依赖项的策略，包括静态工作流引用和已禁用的智能体引用。`fail` 在所需工作流或智能体未包含在包中时中止导出。`include-in-package` 递归加入可访问的依赖项。`reference-only` 记录外部需求，不包含对应定义。相同策略同时适用于工作流和智能体。"
                  },
                  "versionPolicy": {
                    "type": "string",
                    "enum": [
                      "published-strict",
                      "prefer-published",
                      "ignore-unpublished",
                      "latest"
                    ],
                    "default": "latest",
                    "description": "包携带的各工作流和智能体版本。`latest` 导出当前草稿；`published-strict` 要求存在已发布版本；`prefer-published` 优先使用已发布版本，没有时使用草稿；`ignore-unpublished` 跳过未发布的选择项。只有 `dependencyPolicy` 为 `fail` 或 `include-in-package` 时，无法包含的依赖项才导致导出失败；为 `reference-only` 时，将它们记录为外部需求。所选版本提供定义及其引用。工作流名称、设置和标签始终使用当前值；智能体 ID、名称和 MCP 可用性也始终使用当前值。"
                  },
                  "credentialExportPolicy": {
                    "type": "string",
                    "enum": [
                      "expression-values-only",
                      "no-values"
                    ],
                    "default": "expression-values-only",
                    "description": "是否将凭据数据中的表达式值包含在包中。`expression-values-only` 包含值为 n8n 表达式的凭据字段，例如 `={{ $secrets.apiKey }}`；两种方式都绝不携带字面值。`no-values` 完全排除凭据数据，因此每个凭据文件只携带 id、名称和类型。"
                  },
                  "includeArchivedWorkflows": {
                    "type": "boolean",
                    "default": false,
                    "description": "文件夹和项目导出是否包含已归档工作流。为 `false`（默认）时排除；为 `true` 时，以 `isArchived: true` 携带，并在导入时归档。`workflowIds` 中明确列出的工作流始终导出，即使已归档。"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "包含导出包内容的 gzip 压缩 tar 归档。",
            "headers": {
              "X-N8n-Export-Counts": {
                "description": "实际包含在包中的各实体数量，以 JSON 序列化表示，已完成文件夹打包和自动包含处理，例如\n`{\"agents\":1,\"workflows\":2,\"folders\":1,\"credentials\":0,\"dataTables\":0,\"variables\":0,\"tags\":0}`。\n",
                "required": true,
                "schema": {
                  "type": "string"
                }
              }
            },
            "content": {
              "application/gzip": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/badRequest"
          },
          "401": {
            "$ref": "#/components/responses/unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/forbidden"
          },
          "404": {
            "$ref": "#/components/responses/notFound"
          },
          "409": {
            "$ref": "#/components/responses/conflict"
          },
          "415": {
            "$ref": "#/components/responses/unsupportedMediaType"
          },
          "422": {
            "$ref": "#/components/responses/unprocessableEntity"
          }
        }
      }
    }
  }
}