{ "openapi": "3.0.0", "info": { "title": "n8n 公共 API", "version": "1.1.1" }, "tags": [ { "name": "SourceControl", "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]+$" } } }, "responses": { "badRequest": { "description": "请求无效，或提供的数据格式错误。" }, "unauthorized": { "description": "未授权" }, "forbidden": { "description": "禁止访问" }, "unsupportedMediaType": { "description": "不支持的媒体类型。" }, "unprocessableEntity": { "description": "无法处理的实体" } } }, "paths": { "/source-control/pull": { "post": { "operationId": "pullSourceControl", "tags": [ "SourceControl" ], "summary": "从远程仓库拉取变更", "description": "将已连接 Git 分支中的变更获取到实例。", "parameters": [ { "$ref": "#/components/parameters/idempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "force": { "type": "boolean", "description": "丢弃本地变更，并强制完成拉取。" }, "autoPublish": { "type": "string", "enum": [ "none", "all", "published" ], "default": "none", "description": "控制导入后自动发布工作流的方式：\n- `none`：保留工作流在本地的发布状态（默认）。\n- `all`：发布所有导入的工作流。\n- `published`：仅发布导入前在本地已发布的工作流。" } } } } } }, "responses": { "200": { "description": "操作成功。", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "file": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "credential", "workflow", "tags", "variables", "file", "folders", "project", "datatable" ] }, "status": { "type": "string", "enum": [ "new", "modified", "deleted", "created", "renamed", "conflicted", "ignored", "staged", "unknown" ] }, "location": { "type": "string", "enum": [ "local", "remote" ] }, "conflict": { "type": "boolean" }, "updatedAt": { "type": "string" }, "pushed": { "type": "boolean" }, "isLocalPublished": { "type": "boolean" }, "isRemoteArchived": { "type": "boolean" }, "parentFolderId": { "type": "string", "nullable": true }, "folderPath": { "type": "array", "items": { "type": "string" } }, "remoteFolderPath": { "type": "array", "items": { "type": "string" } }, "owner": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "personal", "team" ] }, "projectId": { "type": "string" }, "projectName": { "type": "string" } }, "required": [ "type", "projectId", "projectName" ] }, "publishingError": { "type": "string" }, "publishingErrorDetails": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "review_pending", "changes_requested", "insufficient_api_key_scope", "insufficient_permissions" ] }, "workflowReviewRequestId": { "type": "string", "minLength": 1 }, "versionId": { "type": "string", "minLength": 1 } }, "required": [ "reason" ], "additionalProperties": false }, "contentImportPolicy": { "type": "object", "properties": { "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" ] } }, "checkErrors": { "type": "array", "items": { "type": "object", "properties": { "checkId": { "type": "string" }, "correlationId": { "type": "string" } }, "required": [ "checkId", "correlationId" ] } } }, "required": [ "violations", "checkErrors" ] } }, "required": [ "file", "id", "name", "type", "status", "location", "conflict", "updatedAt" ] } } } } }, "400": { "$ref": "#/components/responses/badRequest" }, "401": { "$ref": "#/components/responses/unauthorized" }, "403": { "$ref": "#/components/responses/forbidden" }, "409": { "description": "因未提交的本地变更或合并冲突而发生冲突。响应体列出拉取差异中的每个文件；导致冲突的文件会标有 `conflict: true` 或 `status: modified`。使用 `force: true` 重试，可丢弃本地变更。", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "file": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "credential", "workflow", "tags", "variables", "file", "folders", "project", "datatable" ] }, "status": { "type": "string", "enum": [ "new", "modified", "deleted", "created", "renamed", "conflicted", "ignored", "staged", "unknown" ] }, "location": { "type": "string", "enum": [ "local", "remote" ] }, "conflict": { "type": "boolean" }, "updatedAt": { "type": "string" }, "pushed": { "type": "boolean" }, "isLocalPublished": { "type": "boolean" }, "isRemoteArchived": { "type": "boolean" }, "parentFolderId": { "type": "string", "nullable": true }, "folderPath": { "type": "array", "items": { "type": "string" } }, "remoteFolderPath": { "type": "array", "items": { "type": "string" } }, "owner": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "personal", "team" ] }, "projectId": { "type": "string" }, "projectName": { "type": "string" } }, "required": [ "type", "projectId", "projectName" ] }, "publishingError": { "type": "string" }, "publishingErrorDetails": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "review_pending", "changes_requested", "insufficient_api_key_scope", "insufficient_permissions" ] }, "workflowReviewRequestId": { "type": "string", "minLength": 1 }, "versionId": { "type": "string", "minLength": 1 } }, "required": [ "reason" ], "additionalProperties": false }, "contentImportPolicy": { "type": "object", "properties": { "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" ] } }, "checkErrors": { "type": "array", "items": { "type": "object", "properties": { "checkId": { "type": "string" }, "correlationId": { "type": "string" } }, "required": [ "checkId", "correlationId" ] } } }, "required": [ "violations", "checkErrors" ] } }, "required": [ "file", "id", "name", "type", "status", "location", "conflict", "updatedAt" ] } } } } }, "415": { "$ref": "#/components/responses/unsupportedMediaType" }, "422": { "$ref": "#/components/responses/unprocessableEntity" } } } } } }