> For the complete documentation index, see [llms.txt](https://docs.n8n.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.n8n.io/connect/n8n-api/promotions.md).

# Promotions

Operations about promotion providers, connections, and package operations

## List promotion providers

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

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Promotions","description":"Operations about promotion providers, connections, and package operations"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","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":{"limit":{"name":"limit","in":"query","description":"The maximum number of items to return.","required":false,"schema":{"type":"number","default":100,"maximum":250}},"cursor":{"name":"cursor","in":"query","description":"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.","required":false,"style":"form","schema":{"type":"string"}}},"responses":{"badRequest":{"description":"The request is invalid or provides malformed data."},"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"serviceUnavailable":{"description":"The requested service is temporarily unavailable."}}},"paths":{"/promotions/providers":{"get":{"operationId":"getPromotionProviders","tags":["Promotions"],"summary":"List promotion providers","description":"Returns a cursor-paginated list of providers, without their public keys.","parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"}],"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":36},"name":{"type":"string"},"type":{"type":"string","enum":["git"]},"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"]}},"nextCursor":{"type":"string","nullable":true}},"required":["data","nextCursor"]}}}},"400":{"$ref":"#/components/responses/badRequest"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"503":{"$ref":"#/components/responses/serviceUnavailable"}}}}}}
```

## Create a promotion provider

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

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Promotions","description":"Operations about promotion providers, connections, and package operations"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","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"}},"responses":{"badRequest":{"description":"The request is invalid or provides malformed data."},"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"unsupportedMediaType":{"description":"Unsupported media type."},"serviceUnavailable":{"description":"The requested service is temporarily unavailable."}}},"paths":{"/promotions/providers":{"post":{"operationId":"createPromotionProvider","tags":["Promotions"],"summary":"Create a promotion provider","description":"Creates a provider and its authentication material. An SSH provider returns the generated public key; add it to the remote as a deploy key.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":128},"type":{"type":"string","enum":["git"]},"auth":{"oneOf":[{"type":"object","properties":{"authType":{"type":"string","enum":["ssh-key"]},"keyType":{"type":"string","enum":["ed25519","rsa"],"default":"ed25519"}},"required":["authType"],"additionalProperties":false},{"type":"object","properties":{"authType":{"type":"string","enum":["token"]},"username":{"type":"string","minLength":1},"password":{"type":"string","minLength":1}},"required":["authType","username","password"],"additionalProperties":false}]}},"required":["name","type","auth"],"additionalProperties":false}}}},"responses":{"201":{"description":"Operation successful.","content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":36},"name":{"type":"string"},"type":{"type":"string","enum":["git"]},"authType":{"type":"string","enum":["ssh-key","token"]},"config":{"anyOf":[{"type":"object","properties":{"schemaVersion":{"type":"number","enum":[1]},"publicKey":{"type":"string","minLength":1},"keyType":{"type":"string","enum":["ed25519","rsa"]}},"required":["schemaVersion","publicKey","keyType"],"additionalProperties":false},{"type":"object","properties":{"schemaVersion":{"type":"number","enum":[1]}},"required":["schemaVersion"],"additionalProperties":false}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","type","authType","config","createdAt","updatedAt"]},"publicKey":{"type":"string","nullable":true}},"required":["provider","publicKey"]}}}},"400":{"$ref":"#/components/responses/badRequest"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"415":{"$ref":"#/components/responses/unsupportedMediaType"},"503":{"$ref":"#/components/responses/serviceUnavailable"}}}}}}
```

## Retrieve a promotion provider

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

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Promotions","description":"Operations about promotion providers, connections, and package operations"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","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"}},"schemas":{"promotionProviderPublicDto.generated":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":36},"name":{"type":"string"},"type":{"type":"string","enum":["git"]},"authType":{"type":"string","enum":["ssh-key","token"]},"config":{"anyOf":[{"type":"object","properties":{"schemaVersion":{"type":"number","enum":[1]},"publicKey":{"type":"string","minLength":1},"keyType":{"type":"string","enum":["ed25519","rsa"]}},"required":["schemaVersion","publicKey","keyType"],"additionalProperties":false},{"type":"object","properties":{"schemaVersion":{"type":"number","enum":[1]}},"required":["schemaVersion"],"additionalProperties":false}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","type","authType","config","createdAt","updatedAt"]}},"responses":{"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."},"serviceUnavailable":{"description":"The requested service is temporarily unavailable."}}},"paths":{"/promotions/providers/{promotionProviderId}":{"get":{"operationId":"getPromotionProvider","tags":["Promotions"],"summary":"Retrieve a promotion provider","description":"Returns the provider with its public configuration. Secrets are never returned.","parameters":[{"schema":{"type":"string"},"required":true,"description":"The ID of the promotion provider.","name":"promotionProviderId","in":"path"}],"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/promotionProviderPublicDto.generated"}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"},"503":{"$ref":"#/components/responses/serviceUnavailable"}}}}}}
```

## Update a promotion provider

> 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.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Promotions","description":"Operations about promotion providers, connections, and package operations"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","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"}},"schemas":{"promotionProviderPublicDto.generated":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":36},"name":{"type":"string"},"type":{"type":"string","enum":["git"]},"authType":{"type":"string","enum":["ssh-key","token"]},"config":{"anyOf":[{"type":"object","properties":{"schemaVersion":{"type":"number","enum":[1]},"publicKey":{"type":"string","minLength":1},"keyType":{"type":"string","enum":["ed25519","rsa"]}},"required":["schemaVersion","publicKey","keyType"],"additionalProperties":false},{"type":"object","properties":{"schemaVersion":{"type":"number","enum":[1]}},"required":["schemaVersion"],"additionalProperties":false}]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","type","authType","config","createdAt","updatedAt"]}},"responses":{"badRequest":{"description":"The request is invalid or provides malformed data."},"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."},"unsupportedMediaType":{"description":"Unsupported media type."},"serviceUnavailable":{"description":"The requested service is temporarily unavailable."}}},"paths":{"/promotions/providers/{promotionProviderId}":{"put":{"operationId":"updatePromotionProvider","tags":["Promotions"],"summary":"Update a promotion provider","description":"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.","parameters":[{"schema":{"type":"string"},"required":true,"description":"The ID of the promotion provider.","name":"promotionProviderId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":128},"auth":{"oneOf":[{"type":"object","properties":{"authType":{"type":"string","enum":["ssh-key"]},"keyType":{"type":"string","enum":["ed25519","rsa"]}},"required":["authType"],"additionalProperties":false},{"type":"object","properties":{"authType":{"type":"string","enum":["token"]},"username":{"type":"string","minLength":1},"password":{"type":"string","minLength":1}},"required":["authType","username","password"],"additionalProperties":false}]}},"additionalProperties":false,"minProperties":1}}}},"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/promotionProviderPublicDto.generated"}}}},"400":{"$ref":"#/components/responses/badRequest"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"},"415":{"$ref":"#/components/responses/unsupportedMediaType"},"503":{"$ref":"#/components/responses/serviceUnavailable"}}}}}}
```

## Delete a promotion provider

> A provider used by a connection cannot be deleted.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Promotions","description":"Operations about promotion providers, connections, and package operations"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","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"}},"responses":{"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."},"conflict":{"description":"Conflict"},"serviceUnavailable":{"description":"The requested service is temporarily unavailable."}}},"paths":{"/promotions/providers/{promotionProviderId}":{"delete":{"operationId":"deletePromotionProvider","tags":["Promotions"],"summary":"Delete a promotion provider","description":"A provider used by a connection cannot be deleted.","parameters":[{"schema":{"type":"string"},"required":true,"description":"The ID of the promotion provider.","name":"promotionProviderId","in":"path"}],"responses":{"204":{"description":"Operation successful."},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"},"409":{"$ref":"#/components/responses/conflict"},"503":{"$ref":"#/components/responses/serviceUnavailable"}}}}}}
```

## List promotion 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.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Promotions","description":"Operations about promotion providers, connections, and package operations"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","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":{"limit":{"name":"limit","in":"query","description":"The maximum number of items to return.","required":false,"schema":{"type":"number","default":100,"maximum":250}},"cursor":{"name":"cursor","in":"query","description":"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.","required":false,"style":"form","schema":{"type":"string"}}},"responses":{"badRequest":{"description":"The request is invalid or provides malformed data."},"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"serviceUnavailable":{"description":"The requested service is temporarily unavailable."}}},"paths":{"/promotions/connections":{"get":{"operationId":"getPromotionConnections","tags":["Promotions"],"summary":"List promotion connections","description":"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.","parameters":[{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/cursor"},{"schema":{"type":"string","enum":["instance","projects"]},"required":false,"name":"scope","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":36},"required":false,"name":"providerId","in":"query"}],"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":36},"name":{"type":"string"},"scope":{"type":"string","enum":["instance","projects"]},"target":{"type":"object","properties":{"schemaVersion":{"type":"number","enum":[1]},"remoteUrl":{"type":"string","minLength":1}},"required":["schemaVersion","remoteUrl"],"additionalProperties":false},"provider":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":36},"name":{"type":"string"},"type":{"type":"string","enum":["git"]},"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"]},"configs":{"type":"object","properties":{"apply":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":36},"name":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"settings":{"type":"object","properties":{"schemaVersion":{"type":"number","enum":[1]},"branchName":{"type":"string","minLength":1,"maxLength":255}},"required":["schemaVersion","branchName"],"additionalProperties":false}},"required":["id","name","createdAt","updatedAt","settings"]},"promote":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":36},"name":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"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":["id","name","createdAt","updatedAt","settings"]}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","scope","target","provider","configs","createdAt","updatedAt"]}},"nextCursor":{"type":"string","nullable":true}},"required":["data","nextCursor"]}}}},"400":{"$ref":"#/components/responses/badRequest"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"503":{"$ref":"#/components/responses/serviceUnavailable"}}}}}}
```

## Create a promotion connection

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

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Promotions","description":"Operations about promotion providers, connections, and package operations"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","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"}},"schemas":{"promotionConnectionPublicDto.generated":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":36},"name":{"type":"string"},"scope":{"type":"string","enum":["instance","projects"]},"target":{"type":"object","properties":{"schemaVersion":{"type":"number","enum":[1]},"remoteUrl":{"type":"string","minLength":1}},"required":["schemaVersion","remoteUrl"],"additionalProperties":false},"provider":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":36},"name":{"type":"string"},"type":{"type":"string","enum":["git"]},"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"]},"configs":{"type":"object","properties":{"apply":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":36},"name":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"settings":{"type":"object","properties":{"schemaVersion":{"type":"number","enum":[1]},"branchName":{"type":"string","minLength":1,"maxLength":255}},"required":["schemaVersion","branchName"],"additionalProperties":false}},"required":["id","name","createdAt","updatedAt","settings"]},"promote":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":36},"name":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"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":["id","name","createdAt","updatedAt","settings"]}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","scope","target","provider","configs","createdAt","updatedAt"]}},"responses":{"badRequest":{"description":"The request is invalid or provides malformed data."},"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."},"conflict":{"description":"Conflict"},"unsupportedMediaType":{"description":"Unsupported media type."},"serviceUnavailable":{"description":"The requested service is temporarily unavailable."}}},"paths":{"/promotions/connections":{"post":{"operationId":"createPromotionConnection","tags":["Promotions"],"summary":"Create a promotion connection","description":"Creates a connection on an existing provider, with up to one initial configuration for each direction. Only one instance connection can exist.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":128},"scope":{"type":"string","enum":["instance","projects"]},"providerId":{"type":"string","minLength":1,"maxLength":36},"target":{"type":"object","properties":{"schemaVersion":{"type":"number","enum":[1]},"remoteUrl":{"type":"string","minLength":1}},"required":["schemaVersion","remoteUrl"],"additionalProperties":false},"configs":{"type":"object","properties":{"apply":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":128},"settings":{"type":"object","properties":{"schemaVersion":{"type":"number","enum":[1]},"branchName":{"type":"string","minLength":1,"maxLength":255}},"required":["schemaVersion","branchName"],"additionalProperties":false}},"required":["settings"],"additionalProperties":false},"promote":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":128},"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":["settings"],"additionalProperties":false}},"additionalProperties":false}},"required":["name","scope","providerId","target"],"additionalProperties":false}}}},"responses":{"201":{"description":"Operation successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/promotionConnectionPublicDto.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"},"503":{"$ref":"#/components/responses/serviceUnavailable"}}}}}}
```

## Retrieve a promotion connection

> Returns the connection with its provider summary and its configurations.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Promotions","description":"Operations about promotion providers, connections, and package operations"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","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"}},"schemas":{"promotionConnectionPublicDto.generated":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":36},"name":{"type":"string"},"scope":{"type":"string","enum":["instance","projects"]},"target":{"type":"object","properties":{"schemaVersion":{"type":"number","enum":[1]},"remoteUrl":{"type":"string","minLength":1}},"required":["schemaVersion","remoteUrl"],"additionalProperties":false},"provider":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":36},"name":{"type":"string"},"type":{"type":"string","enum":["git"]},"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"]},"configs":{"type":"object","properties":{"apply":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":36},"name":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"settings":{"type":"object","properties":{"schemaVersion":{"type":"number","enum":[1]},"branchName":{"type":"string","minLength":1,"maxLength":255}},"required":["schemaVersion","branchName"],"additionalProperties":false}},"required":["id","name","createdAt","updatedAt","settings"]},"promote":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":36},"name":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"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":["id","name","createdAt","updatedAt","settings"]}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","scope","target","provider","configs","createdAt","updatedAt"]}},"responses":{"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."},"serviceUnavailable":{"description":"The requested service is temporarily unavailable."}}},"paths":{"/promotions/connections/{promotionConnectionId}":{"get":{"operationId":"getPromotionConnection","tags":["Promotions"],"summary":"Retrieve a promotion connection","description":"Returns the connection with its provider summary and its configurations.","parameters":[{"schema":{"type":"string"},"required":true,"description":"The ID of the promotion connection.","name":"promotionConnectionId","in":"path"}],"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/promotionConnectionPublicDto.generated"}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"},"503":{"$ref":"#/components/responses/serviceUnavailable"}}}}}}
```

## Update a promotion connection

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

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Promotions","description":"Operations about promotion providers, connections, and package operations"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","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"}},"schemas":{"promotionConnectionPublicDto.generated":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":36},"name":{"type":"string"},"scope":{"type":"string","enum":["instance","projects"]},"target":{"type":"object","properties":{"schemaVersion":{"type":"number","enum":[1]},"remoteUrl":{"type":"string","minLength":1}},"required":["schemaVersion","remoteUrl"],"additionalProperties":false},"provider":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":36},"name":{"type":"string"},"type":{"type":"string","enum":["git"]},"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"]},"configs":{"type":"object","properties":{"apply":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":36},"name":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"settings":{"type":"object","properties":{"schemaVersion":{"type":"number","enum":[1]},"branchName":{"type":"string","minLength":1,"maxLength":255}},"required":["schemaVersion","branchName"],"additionalProperties":false}},"required":["id","name","createdAt","updatedAt","settings"]},"promote":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":36},"name":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"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":["id","name","createdAt","updatedAt","settings"]}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","name","scope","target","provider","configs","createdAt","updatedAt"]}},"responses":{"badRequest":{"description":"The request is invalid or provides malformed data."},"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."},"unsupportedMediaType":{"description":"Unsupported media type."},"serviceUnavailable":{"description":"The requested service is temporarily unavailable."}}},"paths":{"/promotions/connections/{promotionConnectionId}":{"put":{"operationId":"updatePromotionConnection","tags":["Promotions"],"summary":"Update a promotion connection","description":"Updates the name, target, or provider. Scope cannot change, and configurations have their own routes.","parameters":[{"schema":{"type":"string"},"required":true,"description":"The ID of the promotion connection.","name":"promotionConnectionId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":128},"target":{"type":"object","properties":{"schemaVersion":{"type":"number","enum":[1]},"remoteUrl":{"type":"string","minLength":1}},"required":["schemaVersion","remoteUrl"],"additionalProperties":false},"providerId":{"type":"string","minLength":1,"maxLength":36}},"additionalProperties":false,"minProperties":1}}}},"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/promotionConnectionPublicDto.generated"}}}},"400":{"$ref":"#/components/responses/badRequest"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"},"415":{"$ref":"#/components/responses/unsupportedMediaType"},"503":{"$ref":"#/components/responses/serviceUnavailable"}}}}}}
```

## Delete a promotion connection

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

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Promotions","description":"Operations about promotion providers, connections, and package operations"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","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"}},"responses":{"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."},"serviceUnavailable":{"description":"The requested service is temporarily unavailable."}}},"paths":{"/promotions/connections/{promotionConnectionId}":{"delete":{"operationId":"deletePromotionConnection","tags":["Promotions"],"summary":"Delete a promotion connection","description":"Deletes the connection with its configurations, project links, and local checkouts. Its provider is kept.","parameters":[{"schema":{"type":"string"},"required":true,"description":"The ID of the promotion connection.","name":"promotionConnectionId","in":"path"}],"responses":{"204":{"description":"Operation successful."},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"},"503":{"$ref":"#/components/responses/serviceUnavailable"}}}}}}
```

## Create or replace the Apply configuration

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

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Promotions","description":"Operations about promotion providers, connections, and package operations"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","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"}},"responses":{"badRequest":{"description":"The request is invalid or provides malformed data."},"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."},"conflict":{"description":"Conflict"},"unsupportedMediaType":{"description":"Unsupported media type."},"serviceUnavailable":{"description":"The requested service is temporarily unavailable."}}},"paths":{"/promotions/connections/{promotionConnectionId}/configs/apply":{"put":{"operationId":"upsertPromotionApplyConfig","tags":["Promotions"],"summary":"Create or replace the Apply configuration","description":"Replaces the whole configuration, so an omitted name resets it to \"Apply\". Answers 200 whether it created or replaced.","parameters":[{"schema":{"type":"string"},"required":true,"description":"The ID of the promotion connection.","name":"promotionConnectionId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":128},"settings":{"type":"object","properties":{"schemaVersion":{"type":"number","enum":[1]},"branchName":{"type":"string","minLength":1,"maxLength":255}},"required":["schemaVersion","branchName"],"additionalProperties":false}},"required":["settings"],"additionalProperties":false}}}},"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":36},"name":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"settings":{"type":"object","properties":{"schemaVersion":{"type":"number","enum":[1]},"branchName":{"type":"string","minLength":1,"maxLength":255}},"required":["schemaVersion","branchName"],"additionalProperties":false}},"required":["id","name","createdAt","updatedAt","settings"]}}}},"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"},"503":{"$ref":"#/components/responses/serviceUnavailable"}}}}}}
```

## Create or replace the Promote configuration

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

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Promotions","description":"Operations about promotion providers, connections, and package operations"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","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"}},"responses":{"badRequest":{"description":"The request is invalid or provides malformed data."},"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."},"conflict":{"description":"Conflict"},"unsupportedMediaType":{"description":"Unsupported media type."},"serviceUnavailable":{"description":"The requested service is temporarily unavailable."}}},"paths":{"/promotions/connections/{promotionConnectionId}/configs/promote":{"put":{"operationId":"upsertPromotionPromoteConfig","tags":["Promotions"],"summary":"Create or replace the Promote configuration","description":"Replaces the whole configuration, so an omitted name resets it to \"Promote\" and `createBranchOnPromotion` is always required. Answers 200 whether it created or replaced.","parameters":[{"schema":{"type":"string"},"required":true,"description":"The ID of the promotion connection.","name":"promotionConnectionId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":128},"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":["settings"],"additionalProperties":false}}}},"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":36},"name":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"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":["id","name","createdAt","updatedAt","settings"]}}}},"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"},"503":{"$ref":"#/components/responses/serviceUnavailable"}}}}}}
```

## Remove one direction

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

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Promotions","description":"Operations about promotion providers, connections, and package operations"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","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"}},"responses":{"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."},"serviceUnavailable":{"description":"The requested service is temporarily unavailable."}}},"paths":{"/promotions/connections/{promotionConnectionId}/configs/{direction}":{"delete":{"operationId":"deletePromotionConfig","tags":["Promotions"],"summary":"Remove one direction","description":"Deletes the configuration and its local checkout. Nothing in Git changes.","parameters":[{"schema":{"type":"string"},"required":true,"description":"The ID of the promotion connection.","name":"promotionConnectionId","in":"path"},{"schema":{"type":"string"},"required":true,"description":"The direction of the promotion: apply or promote.","name":"direction","in":"path"}],"responses":{"204":{"description":"Operation successful."},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"},"503":{"$ref":"#/components/responses/serviceUnavailable"}}}}}}
```

## Clone one direction's repository

> 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.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Promotions","description":"Operations about promotion providers, connections, and package operations"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","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"}},"schemas":{"promotionCheckoutPublicDto.generated":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1,"maxLength":36},"configId":{"type":"string","minLength":1,"maxLength":36},"direction":{"type":"string","enum":["apply","promote"]},"branchName":{"type":"string"},"hasCheckout":{"type":"boolean"}},"required":["connectionId","configId","direction","branchName","hasCheckout"]}},"responses":{"badRequest":{"description":"The request is invalid or provides malformed data."},"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."},"serviceUnavailable":{"description":"The requested service is temporarily unavailable."}}},"paths":{"/promotions/connections/{promotionConnectionId}/{direction}/clone":{"post":{"operationId":"clonePromotionCheckout","tags":["Promotions"],"summary":"Clone one direction's repository","description":"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.","parameters":[{"schema":{"type":"string"},"required":true,"description":"The ID of the promotion connection.","name":"promotionConnectionId","in":"path"},{"schema":{"type":"string"},"required":true,"description":"The direction of the promotion: apply or promote.","name":"direction","in":"path"}],"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/promotionCheckoutPublicDto.generated"}}}},"400":{"$ref":"#/components/responses/badRequest"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"},"503":{"$ref":"#/components/responses/serviceUnavailable"}}}}}}
```

## Remove one direction's local checkout

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

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Promotions","description":"Operations about promotion providers, connections, and package operations"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","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"}},"schemas":{"promotionCheckoutPublicDto.generated":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1,"maxLength":36},"configId":{"type":"string","minLength":1,"maxLength":36},"direction":{"type":"string","enum":["apply","promote"]},"branchName":{"type":"string"},"hasCheckout":{"type":"boolean"}},"required":["connectionId","configId","direction","branchName","hasCheckout"]}},"responses":{"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."},"serviceUnavailable":{"description":"The requested service is temporarily unavailable."}}},"paths":{"/promotions/connections/{promotionConnectionId}/{direction}/disconnect":{"post":{"operationId":"disconnectPromotionCheckout","tags":["Promotions"],"summary":"Remove one direction's local checkout","description":"Removes the local checkout and keeps the configuration, its credentials, and the trusted SSH host keys.","parameters":[{"schema":{"type":"string"},"required":true,"description":"The ID of the promotion connection.","name":"promotionConnectionId","in":"path"},{"schema":{"type":"string"},"required":true,"description":"The direction of the promotion: apply or promote.","name":"direction","in":"path"}],"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/promotionCheckoutPublicDto.generated"}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"},"503":{"$ref":"#/components/responses/serviceUnavailable"}}}}}}
```

## GET /promotions/connections/{promotionConnectionId}/projects

> List projects linked to a promotion connection

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Promotions","description":"Operations about promotion providers, connections, and package operations"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","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"}},"responses":{"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."},"serviceUnavailable":{"description":"The requested service is temporarily unavailable."}}},"paths":{"/promotions/connections/{promotionConnectionId}/projects":{"get":{"operationId":"getPromotionConnectionProjects","tags":["Promotions"],"summary":"List projects linked to a promotion connection","parameters":[{"schema":{"type":"string"},"required":true,"description":"The ID of the promotion connection.","name":"promotionConnectionId","in":"path"}],"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"type":"object","properties":{"projectIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":36}}},"required":["projectIds"]}}}},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"},"503":{"$ref":"#/components/responses/serviceUnavailable"}}}}}}
```

## Link a project to a promotion connection

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

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Promotions","description":"Operations about promotion providers, connections, and package operations"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","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"}},"responses":{"badRequest":{"description":"The request is invalid or provides malformed data."},"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."},"conflict":{"description":"Conflict"},"serviceUnavailable":{"description":"The requested service is temporarily unavailable."}}},"paths":{"/promotions/connections/{promotionConnectionId}/projects/{projectId}":{"post":{"operationId":"addProjectToPromotionConnection","tags":["Promotions"],"summary":"Link a project to a promotion connection","description":"Links a team project to a project-scoped connection. A project can be linked to only one connection.","parameters":[{"schema":{"type":"string"},"required":true,"description":"The ID of the promotion connection.","name":"promotionConnectionId","in":"path"},{"schema":{"type":"string"},"required":true,"description":"The ID of the project.","name":"projectId","in":"path"}],"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"type":"object","properties":{"projectId":{"type":"string","minLength":1,"maxLength":36},"connectionId":{"type":"string","minLength":1,"maxLength":36}},"required":["projectId","connectionId"]}}}},"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"},"503":{"$ref":"#/components/responses/serviceUnavailable"}}}}}}
```

## DELETE /promotions/connections/{promotionConnectionId}/projects/{projectId}

> Unlink a project from a promotion connection

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Promotions","description":"Operations about promotion providers, connections, and package operations"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","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"}},"responses":{"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."},"conflict":{"description":"Conflict"},"serviceUnavailable":{"description":"The requested service is temporarily unavailable."}}},"paths":{"/promotions/connections/{promotionConnectionId}/projects/{projectId}":{"delete":{"operationId":"removeProjectFromPromotionConnection","tags":["Promotions"],"summary":"Unlink a project from a promotion connection","parameters":[{"schema":{"type":"string"},"required":true,"description":"The ID of the promotion connection.","name":"promotionConnectionId","in":"path"},{"schema":{"type":"string"},"required":true,"description":"The ID of the project.","name":"projectId","in":"path"}],"responses":{"204":{"description":"Operation successful."},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"},"409":{"$ref":"#/components/responses/conflict"},"503":{"$ref":"#/components/responses/serviceUnavailable"}}}}}}
```

## Promote all team projects

> 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.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Promotions","description":"Operations about promotion providers, connections, and package operations"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","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"}},"responses":{"badRequest":{"description":"The request is invalid or provides malformed data."},"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."},"unsupportedMediaType":{"description":"Unsupported media type."},"serviceUnavailable":{"description":"The requested service is temporarily unavailable."}}},"paths":{"/promotions/connections/{promotionConnectionId}/promote":{"post":{"operationId":"promotePackage","tags":["Promotions"],"summary":"Promote all team projects","description":"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.","parameters":[{"schema":{"type":"string"},"required":true,"description":"The ID of the promotion connection.","name":"promotionConnectionId","in":"path"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"commitMessage":{"type":"string","minLength":1,"maxLength":1000},"force":{"type":"boolean"}},"required":["commitMessage"],"additionalProperties":false}}}},"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1,"maxLength":36},"configId":{"type":"string","minLength":1,"maxLength":36},"counts":{"type":"object","properties":{"workflows":{"type":"integer","minimum":0},"folders":{"type":"integer","minimum":0},"credentials":{"type":"integer","minimum":0},"dataTables":{"type":"integer","minimum":0},"variables":{"type":"integer","minimum":0},"tags":{"type":"integer","minimum":0}},"required":["workflows","folders","credentials","dataTables","variables","tags"]},"git":{"type":"object","properties":{"commitSha":{"type":"string"},"branchName":{"type":"string"}},"required":["commitSha","branchName"]}},"required":["connectionId","configId","counts","git"]}}}},"400":{"$ref":"#/components/responses/badRequest"},"401":{"$ref":"#/components/responses/unauthorized"},"403":{"$ref":"#/components/responses/forbidden"},"404":{"$ref":"#/components/responses/notFound"},"415":{"$ref":"#/components/responses/unsupportedMediaType"},"503":{"$ref":"#/components/responses/serviceUnavailable"}}}}}}
```

## Apply a package to the instance

> Resets the local checkout to the configured branch tip and imports the package, overwriting to match. Requires the Apply direction to be cloned first, and is available on the instance connection only.

```json
{"openapi":"3.0.0","info":{"title":"n8n Public API","version":"1.1.1"},"tags":[{"name":"Promotions","description":"Operations about promotion providers, connections, and package operations"}],"servers":[{"url":"/api/v1","description":"Current n8n instance (self-hosted built-in playground)"},{"url":"{url}/api/v1","description":"Self-hosted n8n instance","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"}},"responses":{"badRequest":{"description":"The request is invalid or provides malformed data."},"unauthorized":{"description":"Unauthorized"},"forbidden":{"description":"Forbidden"},"notFound":{"description":"The specified resource was not found."},"conflict":{"description":"Conflict"},"unprocessableEntity":{"description":"Unprocessable Entity"},"serviceUnavailable":{"description":"The requested service is temporarily unavailable."}}},"paths":{"/promotions/connections/{promotionConnectionId}/apply":{"post":{"operationId":"applyPackage","tags":["Promotions"],"summary":"Apply a package to the instance","description":"Resets the local checkout to the configured branch tip and imports the package, overwriting to match. Requires the Apply direction to be cloned first, and is available on the instance connection only.","parameters":[{"schema":{"type":"string"},"required":true,"description":"The ID of the promotion connection.","name":"promotionConnectionId","in":"path"}],"responses":{"200":{"description":"Operation successful.","content":{"application/json":{"schema":{"type":"object","properties":{"connectionId":{"type":"string","minLength":1,"maxLength":36},"configId":{"type":"string","minLength":1,"maxLength":36},"counts":{"type":"object","properties":{"projects":{"type":"object","properties":{"created":{"type":"integer","minimum":0},"updated":{"type":"integer","minimum":0},"skipped":{"type":"integer","minimum":0},"deleted":{"type":"integer","minimum":0}},"required":["created","updated","skipped","deleted"]},"folders":{"type":"object","properties":{"created":{"type":"integer","minimum":0},"skipped":{"type":"integer","minimum":0},"removed":{"type":"integer","minimum":0}},"required":["created","skipped","removed"]},"workflows":{"type":"object","properties":{"created":{"type":"integer","minimum":0},"updated":{"type":"integer","minimum":0},"skipped":{"type":"integer","minimum":0},"archived":{"type":"integer","minimum":0},"deleted":{"type":"integer","minimum":0},"publishing":{"type":"object","properties":{"published":{"type":"integer","minimum":0},"unpublished":{"type":"integer","minimum":0},"unchanged":{"type":"integer","minimum":0},"blocked":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0}},"required":["published","unpublished","unchanged","blocked","failed"]}},"required":["created","updated","skipped","archived","deleted","publishing"]},"credentials":{"type":"object","properties":{"matched":{"type":"integer","minimum":0},"stubbed":{"type":"integer","minimum":0}},"required":["matched","stubbed"]},"dataTables":{"type":"object","properties":{"matched":{"type":"integer","minimum":0},"created":{"type":"integer","minimum":0}},"required":["matched","created"]},"variables":{"type":"object","properties":{"matched":{"type":"integer","minimum":0},"created":{"type":"integer","minimum":0},"updated":{"type":"integer","minimum":0},"stubbed":{"type":"integer","minimum":0},"missing":{"type":"integer","minimum":0}},"required":["matched","created","updated","stubbed","missing"]},"tags":{"type":"object","properties":{"matched":{"type":"integer","minimum":0},"created":{"type":"integer","minimum":0},"renamed":{"type":"integer","minimum":0},"reconciled":{"type":"integer","minimum":0},"skipped":{"type":"integer","minimum":0}},"required":["matched","created","renamed","reconciled","skipped"]}},"required":["projects","folders","workflows","credentials","dataTables","variables","tags"]},"git":{"type":"object","properties":{"commitSha":{"type":"string"},"branchName":{"type":"string"}},"required":["commitSha","branchName"]}},"required":["connectionId","configId","counts","git"]}}}},"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"},"422":{"$ref":"#/components/responses/unprocessableEntity"},"503":{"$ref":"#/components/responses/serviceUnavailable"}}}}}}
```