{ "openapi": "3.0.0", "info": { "title": "n8n 公共 API", "version": "1.1.1" }, "tags": [ { "name": "Promotions", "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" } }, "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": { "promotionEnvironmentPublicDto.generated": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 36 }, "name": { "type": "string" }, "scope": { "type": "string", "enum": [ "instance", "projects" ] }, "remote": { "type": "object", "properties": { "schemaVersion": { "type": "number", "enum": [ 1 ] }, "remoteUrl": { "type": "string", "minLength": 1 }, "repositoryPath": { "type": "string", "description": "Git 主机远程地址所存储的仓库路径。将其用作 repositoryId 列出分支前，请进行 URL 编码。请求不接受此字段。" } }, "required": [ "schemaVersion", "remoteUrl" ], "additionalProperties": false }, "provider": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 36 }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "git", "gitlab" ] }, "authType": { "type": "string", "enum": [ "ssh-key", "token" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "type", "authType", "createdAt", "updatedAt" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "direction": { "type": "string", "enum": [ "apply" ] }, "settings": { "type": "object", "properties": { "schemaVersion": { "type": "number", "enum": [ 1 ] }, "branchName": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "schemaVersion", "branchName" ], "additionalProperties": false }, "checkout": { "type": "object", "properties": { "hasCheckout": { "type": "boolean" }, "matchesEnvironment": { "type": "boolean" } }, "required": [ "hasCheckout", "matchesEnvironment" ] } }, "required": [ "id", "name", "scope", "remote", "provider", "createdAt", "updatedAt", "direction", "settings", "checkout" ] }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 36 }, "name": { "type": "string" }, "scope": { "type": "string", "enum": [ "instance", "projects" ] }, "remote": { "type": "object", "properties": { "schemaVersion": { "type": "number", "enum": [ 1 ] }, "remoteUrl": { "type": "string", "minLength": 1 }, "repositoryPath": { "type": "string", "description": "Git 主机远程地址所存储的仓库路径。将其用作 repositoryId 列出分支前，请进行 URL 编码。请求不接受此字段。" } }, "required": [ "schemaVersion", "remoteUrl" ], "additionalProperties": false }, "provider": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 36 }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "git", "gitlab" ] }, "authType": { "type": "string", "enum": [ "ssh-key", "token" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "type", "authType", "createdAt", "updatedAt" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "direction": { "type": "string", "enum": [ "promote" ] }, "settings": { "type": "object", "properties": { "schemaVersion": { "type": "number", "enum": [ 1 ] }, "baseBranchName": { "type": "string", "minLength": 1, "maxLength": 255 }, "createBranchOnPromotion": { "type": "boolean" } }, "required": [ "schemaVersion", "baseBranchName", "createBranchOnPromotion" ], "additionalProperties": false }, "checkout": { "type": "object", "properties": { "hasCheckout": { "type": "boolean" }, "matchesEnvironment": { "type": "boolean" } }, "required": [ "hasCheckout", "matchesEnvironment" ] } }, "required": [ "id", "name", "scope", "remote", "provider", "createdAt", "updatedAt", "direction", "settings", "checkout" ] } ], "type": "object" } }, "responses": { "badRequest": { "description": "请求无效，或提供的数据格式错误。" }, "unauthorized": { "description": "未授权" }, "forbidden": { "description": "禁止访问" }, "notFound": { "description": "未找到指定资源。" }, "conflict": { "description": "冲突" }, "unsupportedMediaType": { "description": "不支持的媒体类型。" }, "unprocessableEntity": { "description": "无法处理的实体" }, "serviceUnavailable": { "description": "所请求的服务暂时不可用。" } } }, "paths": { "/promotions/environments": { "post": { "operationId": "createPromotionEnvironment", "tags": [ "Promotions" ], "summary": "创建晋升环境", "description": "在现有提供方上，为某一方向创建环境，设置必须与该方向匹配。GitLab 远程 URL 必须属于已保存的提供方；环境仅存储仓库路径，并根据提供方当前基础 URL 推导 remoteUrl。普通 Git 环境保留完整远程 URL。实例的每个方向可以有一个环境。", "parameters": [ { "$ref": "#/components/parameters/idempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128 }, "scope": { "type": "string", "enum": [ "instance", "projects" ] }, "providerId": { "type": "string", "minLength": 1, "maxLength": 36 }, "remote": { "type": "object", "properties": { "schemaVersion": { "type": "number", "enum": [ 1 ] }, "remoteUrl": { "type": "string", "minLength": 1 } }, "required": [ "schemaVersion", "remoteUrl" ], "additionalProperties": false }, "direction": { "type": "string", "enum": [ "apply" ] }, "settings": { "type": "object", "properties": { "schemaVersion": { "type": "number", "enum": [ 1 ] }, "branchName": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "schemaVersion", "branchName" ], "additionalProperties": false } }, "required": [ "name", "scope", "providerId", "remote", "direction", "settings" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 128 }, "scope": { "type": "string", "enum": [ "instance", "projects" ] }, "providerId": { "type": "string", "minLength": 1, "maxLength": 36 }, "remote": { "type": "object", "properties": { "schemaVersion": { "type": "number", "enum": [ 1 ] }, "remoteUrl": { "type": "string", "minLength": 1 } }, "required": [ "schemaVersion", "remoteUrl" ], "additionalProperties": false }, "direction": { "type": "string", "enum": [ "promote" ] }, "settings": { "type": "object", "properties": { "schemaVersion": { "type": "number", "enum": [ 1 ] }, "baseBranchName": { "type": "string", "minLength": 1, "maxLength": 255 }, "createBranchOnPromotion": { "type": "boolean" } }, "required": [ "schemaVersion", "baseBranchName", "createBranchOnPromotion" ], "additionalProperties": false } }, "required": [ "name", "scope", "providerId", "remote", "direction", "settings" ], "additionalProperties": false } ], "type": "object" } } } }, "responses": { "201": { "description": "操作成功。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/promotionEnvironmentPublicDto.generated" } } } }, "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" }, "503": { "$ref": "#/components/responses/serviceUnavailable" } } } } } }