Ctrlk
ForumChangelog
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Promotions

Operations about promotion providers, connections, and package operations

List promotion providers

get
/promotions/providers

Returns a cursor-paginated list of providers, without their public keys.

Authorizations
X-N8N-API-KEYstringRequired
Query parameters
limitnumber · max: 250Optional

The maximum number of items to return.

Default: 100Example: 100
cursorstringOptional

Paginate by setting the cursor parameter to the nextCursor attribute returned by the previous request's response. Default value fetches the first "page" of the collection. See pagination for more detail.

Responses
200

Operation successful.

application/json
nextCursorstring · nullableRequired
get/promotions/providers
GET /api/v1/promotions/providers HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Accept: */*

{
  "data": [
    {
      "id": "text",
      "name": "text",
      "type": "git",
      "authType": "ssh-key",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "nextCursor": "text"
}

Create a promotion provider

post
/promotions/providers

Creates a provider and its authentication material. An SSH provider returns the generated public key; add it to the remote as a deploy key.

Authorizations
X-N8N-API-KEYstringRequired
Body
namestring · min: 1 · max: 128Required
typestring · enumRequiredPossible values:
authone ofRequired
or
Responses
201

Operation successful.

application/json
publicKeystring · nullableRequired
post/promotions/providers
POST /api/v1/promotions/providers HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 78

{
  "name": "text",
  "type": "git",
  "auth": {
    "authType": "ssh-key",
    "keyType": "ed25519"
  }
}
{
  "provider": {
    "id": "text",
    "name": "text",
    "type": "git",
    "authType": "ssh-key",
    "config": {
      "schemaVersion": 1,
      "publicKey": "text",
      "keyType": "ed25519"
    },
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  },
  "publicKey": "text"
}

Retrieve a promotion provider

get
/promotions/providers/{promotionProviderId}

Returns the provider with its public configuration. Secrets are never returned.

Authorizations
X-N8N-API-KEYstringRequired
Path parameters
promotionProviderIdstringRequired

The ID of the promotion provider.

Responses
200

Operation successful.

application/json
idstring · min: 1 · max: 36Required
namestringRequired
typestring · enumRequiredPossible values:
authTypestring · enumRequiredPossible values:
configany ofRequired
or
createdAtstring · date-timeRequired
updatedAtstring · date-timeRequired
get/promotions/providers/{promotionProviderId}
GET /api/v1/promotions/providers/{promotionProviderId} HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Accept: */*

{
  "id": "text",
  "name": "text",
  "type": "git",
  "authType": "ssh-key",
  "config": {
    "schemaVersion": 1,
    "publicKey": "text",
    "keyType": "ed25519"
  },
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}

Update a promotion provider

put
/promotions/providers/{promotionProviderId}

Renames the provider, and replaces its credentials when auth is sent. New credentials apply to every connection that uses this provider. The authentication method cannot change.

Authorizations
X-N8N-API-KEYstringRequired
Path parameters
promotionProviderIdstringRequired

The ID of the promotion provider.

Body
namestring · min: 1 · max: 128Optional
authone ofOptional
or
Responses
200

Operation successful.

application/json
idstring · min: 1 · max: 36Required
namestringRequired
typestring · enumRequiredPossible values:
authTypestring · enumRequiredPossible values:
configany ofRequired
or
createdAtstring · date-timeRequired
updatedAtstring · date-timeRequired
put/promotions/providers/{promotionProviderId}
PUT /api/v1/promotions/providers/{promotionProviderId} HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 65

{
  "name": "text",
  "auth": {
    "authType": "ssh-key",
    "keyType": "ed25519"
  }
}
{
  "id": "text",
  "name": "text",
  "type": "git",
  "authType": "ssh-key",
  "config": {
    "schemaVersion": 1,
    "publicKey": "text",
    "keyType": "ed25519"
  },
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}

Delete a promotion provider

delete
/promotions/providers/{promotionProviderId}

A provider used by a connection cannot be deleted.

Authorizations
X-N8N-API-KEYstringRequired
Path parameters
promotionProviderIdstringRequired

The ID of the promotion provider.

Responses
204

Operation successful.

No content
delete/promotions/providers/{promotionProviderId}
DELETE /api/v1/promotions/providers/{promotionProviderId} HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Accept: */*

No content

List promotion connections

get
/promotions/connections

Returns a cursor-paginated list of connections with their configurations. Filter by scope for the instance connection, or by providerId to see which connections a provider edit affects.

Authorizations
X-N8N-API-KEYstringRequired
Query parameters
limitnumber · max: 250Optional

The maximum number of items to return.

Default: 100Example: 100
cursorstringOptional

Paginate by setting the cursor parameter to the nextCursor attribute returned by the previous request's response. Default value fetches the first "page" of the collection. See pagination for more detail.

scopestring · enumOptionalPossible values:
providerIdstring · min: 1 · max: 36Optional
Responses
200

Operation successful.

application/json
nextCursorstring · nullableRequired
get/promotions/connections
GET /api/v1/promotions/connections HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Accept: */*

{
  "data": [
    {
      "id": "text",
      "name": "text",
      "scope": "instance",
      "target": {
        "schemaVersion": 1,
        "remoteUrl": "text"
      },
      "provider": {
        "id": "text",
        "name": "text",
        "type": "git",
        "authType": "ssh-key",
        "createdAt": "2026-01-01T00:00:00.000Z",
        "updatedAt": "2026-01-01T00:00:00.000Z"
      },
      "configs": {
        "apply": {
          "id": "text",
          "name": "text",
          "createdAt": "2026-01-01T00:00:00.000Z",
          "updatedAt": "2026-01-01T00:00:00.000Z",
          "settings": {
            "schemaVersion": 1,
            "branchName": "text"
          }
        },
        "promote": {
          "id": "text",
          "name": "text",
          "createdAt": "2026-01-01T00:00:00.000Z",
          "updatedAt": "2026-01-01T00:00:00.000Z",
          "settings": {
            "schemaVersion": 1,
            "baseBranchName": "text",
            "createBranchOnPromotion": true
          }
        }
      },
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "nextCursor": "text"
}

Create a promotion connection

post
/promotions/connections

Creates a connection on an existing provider, with up to one initial configuration for each direction. Only one instance connection can exist.

Authorizations
X-N8N-API-KEYstringRequired
Body
namestring · min: 1 · max: 128Required
scopestring · enumRequiredPossible values:
providerIdstring · min: 1 · max: 36Required
Responses
201

Operation successful.

application/json
idstring · min: 1 · max: 36Required
namestringRequired
scopestring · enumRequiredPossible values:
createdAtstring · date-timeRequired
updatedAtstring · date-timeRequired
post/promotions/connections
POST /api/v1/promotions/connections HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 301

{
  "name": "text",
  "scope": "instance",
  "providerId": "text",
  "target": {
    "schemaVersion": 1,
    "remoteUrl": "text"
  },
  "configs": {
    "apply": {
      "name": "text",
      "settings": {
        "schemaVersion": 1,
        "branchName": "text"
      }
    },
    "promote": {
      "name": "text",
      "settings": {
        "schemaVersion": 1,
        "baseBranchName": "text",
        "createBranchOnPromotion": true
      }
    }
  }
}
{
  "id": "text",
  "name": "text",
  "scope": "instance",
  "target": {
    "schemaVersion": 1,
    "remoteUrl": "text"
  },
  "provider": {
    "id": "text",
    "name": "text",
    "type": "git",
    "authType": "ssh-key",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  },
  "configs": {
    "apply": {
      "id": "text",
      "name": "text",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "checkout": {
        "hasCheckout": true,
        "matchesConfig": true
      },
      "settings": {
        "schemaVersion": 1,
        "branchName": "text"
      }
    },
    "promote": {
      "id": "text",
      "name": "text",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "checkout": {
        "hasCheckout": true,
        "matchesConfig": true
      },
      "settings": {
        "schemaVersion": 1,
        "baseBranchName": "text",
        "createBranchOnPromotion": true
      }
    }
  },
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}

Retrieve a promotion connection

get
/promotions/connections/{promotionConnectionId}

Returns the connection with its provider summary and its configurations.

Authorizations
X-N8N-API-KEYstringRequired
Path parameters
promotionConnectionIdstringRequired

The ID of the promotion connection.

Responses
200

Operation successful.

application/json
idstring · min: 1 · max: 36Required
namestringRequired
scopestring · enumRequiredPossible values:
createdAtstring · date-timeRequired
updatedAtstring · date-timeRequired
get/promotions/connections/{promotionConnectionId}
GET /api/v1/promotions/connections/{promotionConnectionId} HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Accept: */*

{
  "id": "text",
  "name": "text",
  "scope": "instance",
  "target": {
    "schemaVersion": 1,
    "remoteUrl": "text"
  },
  "provider": {
    "id": "text",
    "name": "text",
    "type": "git",
    "authType": "ssh-key",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  },
  "configs": {
    "apply": {
      "id": "text",
      "name": "text",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "checkout": {
        "hasCheckout": true,
        "matchesConfig": true
      },
      "settings": {
        "schemaVersion": 1,
        "branchName": "text"
      }
    },
    "promote": {
      "id": "text",
      "name": "text",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "checkout": {
        "hasCheckout": true,
        "matchesConfig": true
      },
      "settings": {
        "schemaVersion": 1,
        "baseBranchName": "text",
        "createBranchOnPromotion": true
      }
    }
  },
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}

Update a promotion connection

put
/promotions/connections/{promotionConnectionId}

Updates the name, target, or provider. Scope cannot change, and configurations have their own routes.

Authorizations
X-N8N-API-KEYstringRequired
Path parameters
promotionConnectionIdstringRequired

The ID of the promotion connection.

Body
namestring · min: 1 · max: 128Optional
providerIdstring · min: 1 · max: 36Optional
Responses
200

Operation successful.

application/json
idstring · min: 1 · max: 36Required
namestringRequired
scopestring · enumRequiredPossible values:
createdAtstring · date-timeRequired
updatedAtstring · date-timeRequired
put/promotions/connections/{promotionConnectionId}
PUT /api/v1/promotions/connections/{promotionConnectionId} HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 83

{
  "name": "text",
  "target": {
    "schemaVersion": 1,
    "remoteUrl": "text"
  },
  "providerId": "text"
}
{
  "id": "text",
  "name": "text",
  "scope": "instance",
  "target": {
    "schemaVersion": 1,
    "remoteUrl": "text"
  },
  "provider": {
    "id": "text",
    "name": "text",
    "type": "git",
    "authType": "ssh-key",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  },
  "configs": {
    "apply": {
      "id": "text",
      "name": "text",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "checkout": {
        "hasCheckout": true,
        "matchesConfig": true
      },
      "settings": {
        "schemaVersion": 1,
        "branchName": "text"
      }
    },
    "promote": {
      "id": "text",
      "name": "text",
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "checkout": {
        "hasCheckout": true,
        "matchesConfig": true
      },
      "settings": {
        "schemaVersion": 1,
        "baseBranchName": "text",
        "createBranchOnPromotion": true
      }
    }
  },
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}

Delete a promotion connection

delete
/promotions/connections/{promotionConnectionId}

Deletes the connection with its configurations, project links, and local checkouts. Its provider is kept.

Authorizations
X-N8N-API-KEYstringRequired
Path parameters
promotionConnectionIdstringRequired

The ID of the promotion connection.

Responses
204

Operation successful.

No content
delete/promotions/connections/{promotionConnectionId}
DELETE /api/v1/promotions/connections/{promotionConnectionId} HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Accept: */*

No content

Create or replace the Apply configuration

put
/promotions/connections/{promotionConnectionId}/configs/apply

Replaces the whole configuration, so an omitted name resets it to "Apply". Answers 200 whether it created or replaced.

Authorizations
X-N8N-API-KEYstringRequired
Path parameters
promotionConnectionIdstringRequired

The ID of the promotion connection.

Body
namestring · min: 1 · max: 128Optional
Responses
200

Operation successful.

application/json
idstring · min: 1 · max: 36Required
namestringRequired
createdAtstring · date-timeRequired
updatedAtstring · date-timeRequired
put/promotions/connections/{promotionConnectionId}/configs/apply
PUT /api/v1/promotions/connections/{promotionConnectionId}/configs/apply HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 66

{
  "name": "text",
  "settings": {
    "schemaVersion": 1,
    "branchName": "text"
  }
}
{
  "id": "text",
  "name": "text",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "checkout": {
    "hasCheckout": true,
    "matchesConfig": true
  },
  "settings": {
    "schemaVersion": 1,
    "branchName": "text"
  }
}

Create or replace the Promote configuration

put
/promotions/connections/{promotionConnectionId}/configs/promote

Replaces the whole configuration, so an omitted name resets it to "Promote" and createBranchOnPromotion is always required. Answers 200 whether it created or replaced.

Authorizations
X-N8N-API-KEYstringRequired
Path parameters
promotionConnectionIdstringRequired

The ID of the promotion connection.

Body
namestring · min: 1 · max: 128Optional
Responses
200

Operation successful.

application/json
idstring · min: 1 · max: 36Required
namestringRequired
createdAtstring · date-timeRequired
updatedAtstring · date-timeRequired
put/promotions/connections/{promotionConnectionId}/configs/promote
PUT /api/v1/promotions/connections/{promotionConnectionId}/configs/promote HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 101

{
  "name": "text",
  "settings": {
    "schemaVersion": 1,
    "baseBranchName": "text",
    "createBranchOnPromotion": true
  }
}
{
  "id": "text",
  "name": "text",
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z",
  "checkout": {
    "hasCheckout": true,
    "matchesConfig": true
  },
  "settings": {
    "schemaVersion": 1,
    "baseBranchName": "text",
    "createBranchOnPromotion": true
  }
}

Remove one direction

delete
/promotions/connections/{promotionConnectionId}/configs/{direction}

Deletes the configuration and its local checkout. Nothing in Git changes.

Authorizations
X-N8N-API-KEYstringRequired
Path parameters
promotionConnectionIdstringRequired

The ID of the promotion connection.

directionstring · enumRequired

The direction of the promotion: apply or promote.

Possible values:
Responses
204

Operation successful.

No content
delete/promotions/connections/{promotionConnectionId}/configs/{direction}
DELETE /api/v1/promotions/connections/{promotionConnectionId}/configs/{direction} HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Accept: */*

No content

Clone one direction's repository

post
/promotions/connections/{promotionConnectionId}/{direction}/clone

Clones the configured branch into local storage on the instance that handles the request. Safe to call repeatedly. Cloning one direction does not make the other ready.

Authorizations
X-N8N-API-KEYstringRequired
Path parameters
promotionConnectionIdstringRequired

The ID of the promotion connection.

directionstring · enumRequired

The direction of the promotion: apply or promote.

Possible values:
Responses
200

Operation successful.

application/json
connectionIdstring · min: 1 · max: 36Required
configIdstring · min: 1 · max: 36Required
directionstring · enumRequiredPossible values:
branchNamestringRequired
hasCheckoutbooleanRequired
post/promotions/connections/{promotionConnectionId}/{direction}/clone
POST /api/v1/promotions/connections/{promotionConnectionId}/{direction}/clone HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Accept: */*

{
  "connectionId": "text",
  "configId": "text",
  "direction": "apply",
  "branchName": "text",
  "hasCheckout": true
}

Remove one direction's local checkout

post
/promotions/connections/{promotionConnectionId}/{direction}/disconnect

Removes the local checkout and keeps the configuration, its credentials, and the trusted SSH host keys.

Authorizations
X-N8N-API-KEYstringRequired
Path parameters
promotionConnectionIdstringRequired

The ID of the promotion connection.

directionstring · enumRequired

The direction of the promotion: apply or promote.

Possible values:
Responses
200

Operation successful.

application/json
connectionIdstring · min: 1 · max: 36Required
configIdstring · min: 1 · max: 36Required
directionstring · enumRequiredPossible values:
branchNamestringRequired
hasCheckoutbooleanRequired
post/promotions/connections/{promotionConnectionId}/{direction}/disconnect
POST /api/v1/promotions/connections/{promotionConnectionId}/{direction}/disconnect HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Accept: */*

{
  "connectionId": "text",
  "configId": "text",
  "direction": "apply",
  "branchName": "text",
  "hasCheckout": true
}

List projects linked to a promotion connection

get
/promotions/connections/{promotionConnectionId}/projects
Authorizations
X-N8N-API-KEYstringRequired
Path parameters
promotionConnectionIdstringRequired

The ID of the promotion connection.

Responses
200

Operation successful.

application/json
projectIdsstring[]Required
get/promotions/connections/{promotionConnectionId}/projects
GET /api/v1/promotions/connections/{promotionConnectionId}/projects HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Accept: */*

{
  "projectIds": [
    "text"
  ]
}

Link a project to a promotion connection

post
/promotions/connections/{promotionConnectionId}/projects/{projectId}

Links a team project to a project-scoped connection. A project can be linked to only one connection.

Authorizations
X-N8N-API-KEYstringRequired
Path parameters
promotionConnectionIdstringRequired

The ID of the promotion connection.

projectIdstringRequired

The ID of the project.

Responses
200

Operation successful.

application/json
projectIdstring · min: 1 · max: 36Required
connectionIdstring · min: 1 · max: 36Required
post/promotions/connections/{promotionConnectionId}/projects/{projectId}
POST /api/v1/promotions/connections/{promotionConnectionId}/projects/{projectId} HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Accept: */*

{
  "projectId": "text",
  "connectionId": "text"
}

Unlink a project from a promotion connection

delete
/promotions/connections/{promotionConnectionId}/projects/{projectId}
Authorizations
X-N8N-API-KEYstringRequired
Path parameters
promotionConnectionIdstringRequired

The ID of the promotion connection.

projectIdstringRequired

The ID of the project.

Responses
204

Operation successful.

No content
delete/promotions/connections/{promotionConnectionId}/projects/{projectId}
DELETE /api/v1/promotions/connections/{promotionConnectionId}/projects/{projectId} HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Accept: */*

No content

Promote all team projects

post
/promotions/connections/{promotionConnectionId}/promote

Exports every team project, commits it, and pushes to the configured base branch or a new timestamped branch. The response reports the target branch in git.branchName. Personal projects are ignored. Requires the Promote direction to be cloned first, and is available on the instance connection only. The API key also needs variable:list when the workflows reference variables.

Authorizations
X-N8N-API-KEYstringRequired
Path parameters
promotionConnectionIdstringRequired

The ID of the promotion connection.

Body
commitMessagestring · min: 1 · max: 1000Required
forcebooleanOptional
Responses
200

Operation successful.

application/json
connectionIdstring · min: 1 · max: 36Required
configIdstring · min: 1 · max: 36Required
post/promotions/connections/{promotionConnectionId}/promote
POST /api/v1/promotions/connections/{promotionConnectionId}/promote HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 37

{
  "commitMessage": "text",
  "force": true
}
{
  "connectionId": "text",
  "configId": "text",
  "counts": {
    "workflows": 1,
    "folders": 1,
    "credentials": 1,
    "dataTables": 1,
    "variables": 1,
    "tags": 1
  },
  "git": {
    "commitSha": "text",
    "branchName": "text"
  }
}

Apply a package to the instance

post
/promotions/connections/{promotionConnectionId}/apply

Checks the full package at the configured branch tip. Optionally send expectedSource with the configId, branchName, and full commitSha from the reviewed change preview; status source-changed means the branch moved since that review and nothing was imported. Returns status blocked before import writes if bindings need setup. Retain configId and git for Continue. Status applied includes counts and warnings. Inspect status before reading counts. Existing target variable values, including empty strings, are preserved. Requires a cloned Apply direction on an instance connection. The API key needs the gitConnection:pull scope. The importer checks user write permissions; granular API-key write scopes are not passed to it.

Authorizations
X-N8N-API-KEYstringRequired
Path parameters
promotionConnectionIdstringRequired

The ID of the promotion connection.

Body
Responses
200

Operation successful.

application/json
or
or
post/promotions/connections/{promotionConnectionId}/apply
POST /api/v1/promotions/connections/{promotionConnectionId}/apply HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 77

{
  "expectedSource": {
    "configId": "text",
    "branchName": "text",
    "commitSha": "text"
  }
}
{
  "connectionId": "text",
  "configId": "text",
  "git": {
    "commitSha": "text",
    "branchName": "text"
  },
  "status": "applied",
  "counts": {
    "projects": {
      "created": 1,
      "updated": 1,
      "skipped": 1,
      "deleted": 1
    },
    "folders": {
      "created": 1,
      "skipped": 1,
      "removed": 1
    },
    "workflows": {
      "created": 1,
      "updated": 1,
      "skipped": 1,
      "archived": 1,
      "deleted": 1,
      "publishing": {
        "published": 1,
        "unpublished": 1,
        "unchanged": 1,
        "blocked": 1,
        "failed": 1
      }
    },
    "credentials": {
      "matched": 1,
      "stubbed": 1
    },
    "dataTables": {
      "matched": 1,
      "created": 1
    },
    "variables": {
      "matched": 1,
      "created": 1,
      "updated": 1,
      "stubbed": 1,
      "missing": 1
    },
    "tags": {
      "matched": 1,
      "created": 1,
      "renamed": 1,
      "reconciled": 1,
      "skipped": 1
    }
  },
  "warnings": [
    {
      "kind": "variable",
      "code": "variable-shadowed",
      "name": "text",
      "scope": {
        "kind": "global"
      },
      "consumers": [
        {
          "project": {
            "id": "text",
            "name": "text"
          },
          "workflows": [
            {
              "id": "text",
              "name": "text"
            }
          ]
        }
      ]
    }
  ]
}

Continue Apply after binding setup

post
/promotions/connections/{promotionConnectionId}/apply/continue

Rechecks the configured source and current target bindings. Send expectedSource with the configId, branchName, and full commitSha from the reviewed Apply result. Status source-changed requires a new Apply review. Status blocked returns fresh binding details without import writes. Status applied includes counts and warnings. Inspect status before reading counts. Existing target variable values are preserved. Requires the same cloned instance connection and permissions as Apply. The importer checks user write permissions; granular API-key write scopes are not passed to it. No server session or exactly-once guarantee is provided.

Authorizations
X-N8N-API-KEYstringRequired
Path parameters
promotionConnectionIdstringRequired

The ID of the promotion connection.

Body
Responses
200

Operation successful.

application/json
or
or
post/promotions/connections/{promotionConnectionId}/apply/continue
POST /api/v1/promotions/connections/{promotionConnectionId}/apply/continue HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 77

{
  "expectedSource": {
    "configId": "text",
    "branchName": "text",
    "commitSha": "text"
  }
}
{
  "connectionId": "text",
  "configId": "text",
  "git": {
    "commitSha": "text",
    "branchName": "text"
  },
  "status": "applied",
  "counts": {
    "projects": {
      "created": 1,
      "updated": 1,
      "skipped": 1,
      "deleted": 1
    },
    "folders": {
      "created": 1,
      "skipped": 1,
      "removed": 1
    },
    "workflows": {
      "created": 1,
      "updated": 1,
      "skipped": 1,
      "archived": 1,
      "deleted": 1,
      "publishing": {
        "published": 1,
        "unpublished": 1,
        "unchanged": 1,
        "blocked": 1,
        "failed": 1
      }
    },
    "credentials": {
      "matched": 1,
      "stubbed": 1
    },
    "dataTables": {
      "matched": 1,
      "created": 1
    },
    "variables": {
      "matched": 1,
      "created": 1,
      "updated": 1,
      "stubbed": 1,
      "missing": 1
    },
    "tags": {
      "matched": 1,
      "created": 1,
      "renamed": 1,
      "reconciled": 1,
      "skipped": 1
    }
  },
  "warnings": [
    {
      "kind": "variable",
      "code": "variable-shadowed",
      "name": "text",
      "scope": {
        "kind": "global"
      },
      "consumers": [
        {
          "project": {
            "id": "text",
            "name": "text"
          },
          "workflows": [
            {
              "id": "text",
              "name": "text"
            }
          ]
        }
      ]
    }
  ]
}

List the changes of a project in one direction

get
/promotions/projects/{projectId}/changes/{direction}

Compares a team project on this instance with the branch of its promotion configuration and lists the workflows that differ. For promote the rows are what a promotion sends to the branch, and the key needs the gitConnection:push scope. For apply the rows are what applying the branch changes on this instance, and the key needs the gitConnection:pull scope. commitSha is the commit the rows were read from. Requires the direction to be cloned first.

Authorizations
X-N8N-API-KEYstringRequired
Path parameters
projectIdstringRequired

The ID of the project.

directionstring · enumRequired

The direction of the promotion: apply or promote.

Possible values:
Query parameters
searchstringOptional
sortstring · enumOptionalDefault: namePossible values:
orderstring · enumOptionalDefault: ascPossible values:
Responses
200

Operation successful.

application/json
commitShastring · nullableRequired
get/promotions/projects/{projectId}/changes/{direction}
GET /api/v1/promotions/projects/{projectId}/changes/{direction} HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Accept: */*

{
  "commitSha": "text",
  "changes": [
    {
      "id": "text",
      "name": "text",
      "type": "workflow",
      "status": "new",
      "version": 1,
      "updatedAt": "text",
      "updatedBy": "text",
      "dependencyCount": 1
    }
  ]
}

Promote a selection of a project's workflows

post
/promotions/projects/{projectId}/promote

Promotes a chosen set of a team project's workflows to the Promote branch of the project's promotion configuration. Send workflow ids only; the server reads each one now, so the push carries the current state. Live and archived workflows the project owns are exported, so an archived id stays on the branch as archived; an id the project no longer owns (its workflow is gone, or moved to another project) leaves the branch, matching the project's change list. A deletion the branch does not hold under this project rejects the whole request before any write. Requires the Promote direction to be cloned first, and a promotion connection to resolve for the project (its own connection, otherwise the instance connection). The API key also needs variable:list when the workflows reference variables.

Authorizations
X-N8N-API-KEYstringRequired
Path parameters
projectIdstringRequired

The ID of the project.

Body
workflowIdsstring[] · min: 1Required
commitMessagestring · min: 1 · max: 1000Optional

Message for the promotion commit. A default is used when omitted.

Responses
200

Operation successful.

application/json
connectionIdstring · min: 1 · max: 36Required
configIdstring · min: 1 · max: 36Required
post/promotions/projects/{projectId}/promote
POST /api/v1/promotions/projects/{projectId}/promote HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 47

{
  "workflowIds": [
    "text"
  ],
  "commitMessage": "text"
}
{
  "connectionId": "text",
  "configId": "text",
  "counts": {
    "workflows": 1,
    "folders": 1,
    "credentials": 1,
    "dataTables": 1,
    "variables": 1,
    "tags": 1
  },
  "git": {
    "commitSha": "text",
    "branchName": "text"
  }
}

Apply a selection of a project's workflows

post
/promotions/projects/{projectId}/apply

Applies selected workflow changes from the project's Apply branch. Send the selected change-list IDs in workflowIds. The server imports IDs present on the branch for this project. It removes instance workflows owned by this project when their IDs are absent from the branch. Duplicate or invalid IDs reject the whole request. Unselected content stays unchanged. Optionally send expectedSource with the configId, branchName, and full commitSha from the reviewed change preview. Status source-changed means the source changed since that review and nothing was imported. Status blocked returns binding details before import writes when the selection needs binding setup. Retain configId and git for Continue. Status applied includes counts and warnings. Inspect status before reading counts. Requires a cloned Apply direction for the project's resolved promotion connection. The API key needs the gitConnection:pull scope. The importer checks user write permissions.

Authorizations
X-N8N-API-KEYstringRequired
Path parameters
projectIdstringRequired

The ID of the project.

Body
workflowIdsstring[] · min: 1Required
Responses
200

Operation successful.

application/json
or
or
post/promotions/projects/{projectId}/apply
POST /api/v1/promotions/projects/{projectId}/apply HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 100

{
  "workflowIds": [
    "text"
  ],
  "expectedSource": {
    "configId": "text",
    "branchName": "text",
    "commitSha": "text"
  }
}
{
  "connectionId": "text",
  "configId": "text",
  "git": {
    "commitSha": "text",
    "branchName": "text"
  },
  "status": "applied",
  "counts": {
    "projects": {
      "created": 1,
      "updated": 1,
      "skipped": 1,
      "deleted": 1
    },
    "folders": {
      "created": 1,
      "skipped": 1,
      "removed": 1
    },
    "workflows": {
      "created": 1,
      "updated": 1,
      "skipped": 1,
      "archived": 1,
      "deleted": 1,
      "publishing": {
        "published": 1,
        "unpublished": 1,
        "unchanged": 1,
        "blocked": 1,
        "failed": 1
      }
    },
    "credentials": {
      "matched": 1,
      "stubbed": 1
    },
    "dataTables": {
      "matched": 1,
      "created": 1
    },
    "variables": {
      "matched": 1,
      "created": 1,
      "updated": 1,
      "stubbed": 1,
      "missing": 1
    },
    "tags": {
      "matched": 1,
      "created": 1,
      "renamed": 1,
      "reconciled": 1,
      "skipped": 1
    }
  },
  "warnings": [
    {
      "kind": "variable",
      "code": "variable-shadowed",
      "name": "text",
      "scope": {
        "kind": "global"
      },
      "consumers": [
        {
          "project": {
            "id": "text",
            "name": "text"
          },
          "workflows": [
            {
              "id": "text",
              "name": "text"
            }
          ]
        }
      ]
    }
  ]
}

Continue applying a selection after binding setup

post
/promotions/projects/{projectId}/apply/continue

Rechecks the project's Apply source and the current bindings for the selection. Resend the full selection in workflowIds. Send the required expectedSource with the configId, branchName, and full commitSha from the reviewed Apply result. The server does not keep a session. Status source-changed requires a new Apply review. Status blocked returns fresh binding details before import writes. Status applied includes counts and warnings. Inspect status before reading counts. Unselected content stays unchanged. Requires the same cloned Apply direction and permissions as the initial selection apply. The API key needs the gitConnection:pull scope. The importer checks user write permissions.

Authorizations
X-N8N-API-KEYstringRequired
Path parameters
projectIdstringRequired

The ID of the project.

Body
workflowIdsstring[] · min: 1Required
Responses
200

Operation successful.

application/json
or
or
post/promotions/projects/{projectId}/apply/continue
POST /api/v1/promotions/projects/{projectId}/apply/continue HTTP/1.1
X-N8N-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 100

{
  "workflowIds": [
    "text"
  ],
  "expectedSource": {
    "configId": "text",
    "branchName": "text",
    "commitSha": "text"
  }
}
{
  "connectionId": "text",
  "configId": "text",
  "git": {
    "commitSha": "text",
    "branchName": "text"
  },
  "status": "applied",
  "counts": {
    "projects": {
      "created": 1,
      "updated": 1,
      "skipped": 1,
      "deleted": 1
    },
    "folders": {
      "created": 1,
      "skipped": 1,
      "removed": 1
    },
    "workflows": {
      "created": 1,
      "updated": 1,
      "skipped": 1,
      "archived": 1,
      "deleted": 1,
      "publishing": {
        "published": 1,
        "unpublished": 1,
        "unchanged": 1,
        "blocked": 1,
        "failed": 1
      }
    },
    "credentials": {
      "matched": 1,
      "stubbed": 1
    },
    "dataTables": {
      "matched": 1,
      "created": 1
    },
    "variables": {
      "matched": 1,
      "created": 1,
      "updated": 1,
      "stubbed": 1,
      "missing": 1
    },
    "tags": {
      "matched": 1,
      "created": 1,
      "renamed": 1,
      "reconciled": 1,
      "skipped": 1
    }
  },
  "warnings": [
    {
      "kind": "variable",
      "code": "variable-shadowed",
      "name": "text",
      "scope": {
        "kind": "global"
      },
      "consumers": [
        {
          "project": {
            "id": "text",
            "name": "text"
          },
          "workflows": [
            {
              "id": "text",
              "name": "text"
            }
          ]
        }
      ]
    }
  ]
}
PreviousProjects
NextRole

Last updated

Was this helpful?