n8n 2.32.5 → 2.33.0

package/dist/public-api/v1/openapi.yml

@@ -47,6 +47,8 @@ tags:
     description: Operations about projects
   - name: SecurityPolicy
     description: Operations about the instance security policy settings
+  - name: SettingsOtel
+    description: Operations about OpenTelemetry settings
   - name: SettingsSsoSaml
     description: Operations about SAML SSO settings
   - name: SourceControl
@@ -158,6 +160,88 @@ paths:
           $ref: '#/components/responses/forbidden'
         '409':
           $ref: '#/components/responses/conflict'
+  /settings/otel:
+    get:
+      x-eov-operation-id: getOtelSettings
+      x-required-scope: otel:manage
+      x-eov-operation-handler: v1/handlers/otel/otel.handler
+      tags:
+        - SettingsOtel
+      summary: Retrieve the OpenTelemetry configuration
+      description: |
+        Retrieve the current OpenTelemetry configuration, including every field exposed in the UI. Requires the `otel:manage` scope.
+      responses:
+        '200':
+          description: Operation successful.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/otel-settings'
+        '401':
+          $ref: '#/components/responses/unauthorized'
+        '403':
+          $ref: '#/components/responses/forbidden'
+    put:
+      x-eov-operation-id: updateOtelSettings
+      x-required-scope: otel:manage
+      x-eov-operation-handler: v1/handlers/otel/otel.handler
+      tags:
+        - SettingsOtel
+      summary: Set the OpenTelemetry configuration
+      description: |
+        Set the OpenTelemetry configuration. This is a full replacement: every field must be provided, and a partial body is rejected. The update takes effect exactly as it would from the UI, using the same validation, and is applied to the running instance immediately. Fields managed declaratively via environment variables are read-only: attempting to change one is rejected with 409, while re-submitting its current value (as returned by GET) is accepted. Requires the `otel:manage` scope.
+      requestBody:
+        description: The OpenTelemetry configuration to set.
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/otel-settings'
+      responses:
+        '200':
+          description: Operation successful.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/otel-settings'
+        '400':
+          $ref: '#/components/responses/badRequest'
+        '401':
+          $ref: '#/components/responses/unauthorized'
+        '403':
+          $ref: '#/components/responses/forbidden'
+        '409':
+          $ref: '#/components/responses/conflict'
+  /settings/otel/test-trace:
+    post:
+      x-eov-operation-id: testOtelTrace
+      x-required-scope: otel:manage
+      x-eov-operation-handler: v1/handlers/otel/otel.handler
+      tags:
+        - SettingsOtel
+      summary: Test the connection to an OTLP collector
+      description: |
+        Send a single test span to the given OTLP collector and report whether it was accepted. This tests the supplied connection details without changing the stored configuration. Fields managed declaratively via environment variables are overridden with their effective value before the test is sent. Requires the `otel:manage` scope.
+      requestBody:
+        description: The connection details to test.
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/otel-test-trace'
+      responses:
+        '200':
+          description: Operation successful.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/otel-test-trace-result'
+        '400':
+          $ref: '#/components/responses/badRequest'
+        '401':
+          $ref: '#/components/responses/unauthorized'
+        '403':
+          $ref: '#/components/responses/forbidden'
   /settings/sso/saml:
     get:
       x-eov-operation-id: getSamlConfiguration
@@ -785,9 +869,8 @@ paths:
         '409':
           $ref: '#/components/responses/conflict'
     get:
-      x-eov-operation-id: getTags
+      operationId: getTags
       x-required-scope: tag:list
-      x-eov-operation-handler: v1/handlers/tags/tags.handler
       tags:
         - Tags
       summary: Retrieve all tags
@@ -1048,6 +1131,32 @@ paths:
           $ref: '#/components/responses/unauthorized'
         '404':
           $ref: '#/components/responses/notFound'
+  /workflows/{id}/history:
+    get:
+      operationId: getWorkflowHistory
+      x-required-scope: workflow:read
+      tags:
+        - Workflow
+      summary: Retrieve workflow version history
+      description: Returns a paginated list of workflow versions (version IDs and metadata) for a workflow.
+      parameters:
+        - $ref: '#/components/parameters/workflowId'
+        - $ref: '#/components/parameters/limit'
+        - $ref: '#/components/parameters/offset'
+        - $ref: '#/components/parameters/cursor'
+      responses:
+        '200':
+          description: Operation successful.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/workflowVersionHistoryList'
+        '400':
+          $ref: '#/components/responses/badRequest'
+        '401':
+          $ref: '#/components/responses/unauthorized'
+        '404':
+          $ref: '#/components/responses/notFound'
   /workflows/{id}/{versionId}:
     get:
       x-eov-operation-id: getWorkflowVersion
@@ -1085,7 +1194,8 @@ paths:
       tags:
         - Workflow
       summary: Publish a workflow
-      description: Publish a workflow. In n8n v1, this action was termed activating a workflow.
+      description: 'Deprecated: use POST /workflows/{id}/publish instead. Publish a workflow. In n8n v1, this action was termed activating a workflow.'
+      deprecated: true
       parameters:
         - $ref: '#/components/parameters/workflowId'
       requestBody:
@@ -1126,7 +1236,71 @@ paths:
       tags:
         - Workflow
       summary: Deactivate a workflow
-      description: Deactivate a workflow.
+      description: 'Deprecated: use POST /workflows/{id}/unpublish instead. Deactivate a workflow.'
+      deprecated: true
+      parameters:
+        - $ref: '#/components/parameters/workflowId'
+      responses:
+        '200':
+          description: Workflow object
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/workflow'
+        '401':
+          $ref: '#/components/responses/unauthorized'
+        '404':
+          $ref: '#/components/responses/notFound'
+  /workflows/{id}/publish:
+    post:
+      x-eov-operation-id: publishWorkflow
+      x-required-scope: workflow:activate
+      x-eov-operation-handler: v1/handlers/workflows/workflows.handler
+      tags:
+        - Workflow
+      summary: Publish a workflow
+      description: Publish a workflow. In n8n v1, this action was termed activating a workflow.
+      parameters:
+        - $ref: '#/components/parameters/workflowId'
+      requestBody:
+        description: Optional parameters to publish the workflow.
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                versionId:
+                  type: string
+                  description: The specific version ID to publish. If not provided, the latest version is used.
+                name:
+                  type: string
+                  description: Optional name for the workflow version during publication.
+                description:
+                  type: string
+                  description: Optional description for the workflow version during publication.
+        required: false
+      responses:
+        '200':
+          description: Workflow object
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/workflow'
+        '400':
+          $ref: '#/components/responses/badRequest'
+        '401':
+          $ref: '#/components/responses/unauthorized'
+        '404':
+          $ref: '#/components/responses/notFound'
+  /workflows/{id}/unpublish:
+    post:
+      x-eov-operation-id: unpublishWorkflow
+      x-required-scope: workflow:deactivate
+      x-eov-operation-handler: v1/handlers/workflows/workflows.handler
+      tags:
+        - Workflow
+      summary: Unpublish a workflow
+      description: Unpublish a workflow. In n8n v1, this action was termed deactivating a workflow.
       parameters:
         - $ref: '#/components/parameters/workflowId'
       responses:
@@ -3097,6 +3271,14 @@ paths:
       responses:
         '200':
           description: A gzipped tar archive containing the exported package contents.
+          headers:
+            X-N8n-Export-Counts:
+              description: |
+                JSON-serialized per-entity counts of what actually ended up in the
+                package (after folder bundling and auto-inclusion), e.g.
+                `{"workflows":2,"folders":1,"credentials":0,"dataTables":0,"variables":0}`.
+              schema:
+                type: string
           content:
             application/gzip:
               schema:
@@ -3195,9 +3377,17 @@ paths:
                   enum:
                     - new
                     - source
-                  default: new
+                  default: source
                   description: |
-                    Controls the id each newly created workflow receives. `new` (default) mints a fresh id and records the package id as `sourceWorkflowId`, so the same package can be imported repeatedly without id collisions. `source` reuses the package's own workflow id on the target instance. Workflows matched to an existing workflow in the target project (status `updated` or `skipped`) always keep that workflow's current id, regardless of policy.
+                    Controls the id each newly created workflow receives. `source` (default) reuses the package's own workflow id on the target instance, which best fits promotion use cases where the same workflow moves between environments. `new` mints a fresh id and records the package id as `sourceWorkflowId`, so the same package can be imported repeatedly without id collisions — best suited to marketplace imports. Workflows matched to an existing workflow in the target project (status `updated` or `skipped`) always keep that workflow's current id, regardless of policy.
+                missingNodeTypeMode:
+                  type: string
+                  enum:
+                    - fail
+                    - import-anyway
+                  default: fail
+                  description: |
+                    What to do when a workflow in the package uses a node type — or a version of a node type — this instance does not have. `fail` (default) rejects the import before anything is written, listing every missing `(nodeType, typeVersion)` pair and the workflows that use it. `import-anyway` imports the package; workflows containing missing node types are never published by this import, regardless of `workflowPublishingPolicy`.
                 workflowPublishingPolicy:
                   type: string
                   enum:
@@ -3240,6 +3430,14 @@ paths:
                   default: keep-existing
                   description: |
                     How strictly a matched data table's schema is compared. `keep-existing` (default) accepts a target table that has every package column with the same name and type, even when the target table also has additional columns of its own. `fail` is the strict drift-detection choice: any difference, including such target-only columns, rejects the import. A missing package column or a type mismatch always rejects. Both policies are non-destructive — the matched target table is never altered, and package columns are never added to it.
+                variableMissingMode:
+                  type: string
+                  enum:
+                    - do-nothing
+                    - must-preexist
+                  default: do-nothing
+                  description: |
+                    Controls what happens when a variable referenced by the package's workflows is absent from the target project and the global scope (lookup order: project, then global). `do-nothing` (default) imports the workflows without creating the missing variable and lists its name under `variables.missing` in the response so the caller can fill it in afterwards. `must-preexist` rejects the import unless every referenced variable already resolves. Neither mode ever creates a variable.
       responses:
         '200':
           description: Import succeeded; the listed workflows were written to the target project.
@@ -3254,6 +3452,7 @@ paths:
                   - projects
                   - bindings
                   - credentials
+                  - variables
                 properties:
                   package:
                     type: object
@@ -3318,7 +3517,7 @@ paths:
                                 - blocked
                                 - failed
                               description: |
-                                `blocked` means the imported version could not be published and no version is active (for example because the workflow uses a stubbed credential). When a prior published version remains active, `state` is `unchanged` with `skippedPublishReason` instead. `failed` means publish or unpublish was attempted but did not succeed.
+                                `blocked` means the imported version could not be published and no version is active (for example because the workflow uses a stubbed credential, or uses a node type this instance does not have). When a prior published version remains active, `state` is `unchanged` with `skippedPublishReason` instead. `failed` means publish or unpublish was attempted but did not succeed.
                             error:
                               type: string
                               description: |
@@ -3327,12 +3526,14 @@ paths:
                               type: string
                               enum:
                                 - stub-credential
+                                - missing-node-type
                               description: |
                                 Present when `state` is `blocked`: the imported version could not be published and no version is active.
                             skippedPublishReason:
                               type: string
                               enum:
                                 - stub-credential
+                                - missing-node-type
                               description: |
                                 Present when `state` is `unchanged` but the policy wanted to publish the imported version: a prior published version is still active (for example after an update with stubbed credentials).
                         status:
@@ -3418,6 +3619,26 @@ paths:
                           type: string
                         description: |
                           Source credential ids for which empty placeholder credentials were created in the target project.
+                  variables:
+                    type: object
+                    description: |
+                      Resolution of the package's variable requirements. Names only — values never travel in the response. For project packages, resolution runs per project, so a name that resolves in some projects but not others appears in both lists.
+                    required:
+                      - matched
+                      - missing
+                    properties:
+                      matched:
+                        type: array
+                        items:
+                          type: string
+                        description: |
+                          Variable names that resolved to an existing variable (importing project's scope first, then global).
+                      missing:
+                        type: array
+                        items:
+                          type: string
+                        description: |
+                          Variable names that did not resolve. Under `variableMissingMode=do-nothing` these are warnings — the import still succeeds and nothing is created.
                   bindings:
                     type: object
                     description: |
@@ -3463,7 +3684,7 @@ paths:
                       $ref: '#/components/schemas/importBlockingIssue'
         '422':
           description: |
-            Import blocked by non-conflict issues only (e.g. unresolved credentials).
+            Import blocked by non-conflict issues only (e.g. unresolved credentials or variables, or node types this instance does not have under `missingNodeTypeMode=fail`).
           content:
             application/json:
               schema:
@@ -3848,6 +4069,123 @@ components:
           type: integer
           description: |
             Read-only usage count returned by GET. Ignored on write so a GET response can be sent back as a PUT body.
+    otel-settings:
+      type: object
+      additionalProperties: false
+      description: |
+        The OpenTelemetry configuration, matching the fields exposed in the UI. On a write this is a full replacement: every field must be provided. Fields managed declaratively via environment variables are returned with their effective value and ignored on write.
+      required:
+        - enabled
+        - exporterEndpoint
+        - exporterTracingPath
+        - exporterServiceName
+        - exporterHeaders
+        - tracesSampleRate
+        - startupConnectivityTimeoutMs
+        - includeNodeSpans
+        - injectOutbound
+        - productionExecutionsOnly
+      properties:
+        enabled:
+          type: boolean
+          description: Whether OpenTelemetry tracing is enabled.
+          example: true
+        exporterEndpoint:
+          type: string
+          format: uri
+          description: The base URL of the OTLP collector to export traces to.
+          example: http://localhost:4318
+        exporterTracingPath:
+          type: string
+          description: The path appended to the endpoint for the OTLP traces signal.
+          example: /v1/traces
+        exporterServiceName:
+          type: string
+          minLength: 1
+          description: The `service.name` resource attribute reported on every span.
+          example: n8n
+        exporterHeaders:
+          type: string
+          description: |
+            Additional headers sent to the OTLP collector, as a single string of comma-separated `key=value` pairs (e.g. `authorization=Bearer my-token,x-tenant-id=acme`). Whitespace around each key and value is trimmed; a value may contain spaces but not commas. Use an empty string when unused.
+          example: authorization=Bearer my-token,x-tenant-id=acme
+        tracesSampleRate:
+          type: number
+          minimum: 0
+          maximum: 1
+          description: The ratio of traces to sample, between 0 (none) and 1 (all).
+          example: 1
+        startupConnectivityTimeoutMs:
+          type: integer
+          minimum: 0
+          description: |
+            How long, in milliseconds, to wait when checking the collector is reachable. Also used as the timeout for the test-trace endpoint.
+          example: 2000
+        includeNodeSpans:
+          type: boolean
+          description: Whether to emit a span for each node execution in addition to the workflow span.
+          example: true
+        injectOutbound:
+          type: boolean
+          description: Whether to inject trace context headers into outbound HTTP requests made by nodes.
+          example: true
+        productionExecutionsOnly:
+          type: boolean
+          description: |
+            When true, only production executions of published (active) workflows are traced, not manual/test runs.
+          example: true
+    otel-test-trace:
+      type: object
+      additionalProperties: false
+      description: |
+        The connection details to test against an OTLP collector. Fields managed declaratively via environment variables are overridden with their effective value before the test is sent.
+      required:
+        - exporterEndpoint
+        - exporterTracingPath
+        - exporterServiceName
+        - exporterHeaders
+        - startupConnectivityTimeoutMs
+      properties:
+        exporterEndpoint:
+          type: string
+          format: uri
+          description: The base URL of the OTLP collector to export traces to.
+          example: http://localhost:4318
+        exporterTracingPath:
+          type: string
+          description: The path appended to the endpoint for the OTLP traces signal.
+          example: /v1/traces
+        exporterServiceName:
+          type: string
+          minLength: 1
+          description: The `service.name` resource attribute reported on the test span.
+          example: n8n
+        exporterHeaders:
+          type: string
+          description: |
+            Additional headers sent to the OTLP collector, as a single string of comma-separated `key=value` pairs (e.g. `authorization=Bearer my-token,x-tenant-id=acme`). Whitespace around each key and value is trimmed; a value may contain spaces but not commas. Use an empty string when unused.
+          example: authorization=Bearer my-token,x-tenant-id=acme
+        startupConnectivityTimeoutMs:
+          type: integer
+          minimum: 0
+          description: How long, in milliseconds, to wait for the collector to respond.
+          example: 2000
+    otel-test-trace-result:
+      type: object
+      additionalProperties: false
+      description: The outcome of the test connection to the OTLP collector.
+      required:
+        - success
+      properties:
+        success:
+          type: boolean
+          description: Whether the test span was accepted by the collector.
+          example: true
+        error:
+          type: string
+          description: |
+            The error reported by the collector or exporter. Present only when `success` is false.
+          example: 'Failed to connect: 401 Unauthorized'
     saml-configuration:
       type: object
       additionalProperties: false
@@ -4664,6 +5002,16 @@ components:
         executionOrder:
           type: string
           example: v1
+        binaryMode:
+          type: string
+          enum:
+            - separate
+            - combined
+          description: |
+            Controls how binary data is resolved from a node's input. This is a derived,
+            internal setting rather than something intended to be set programmatically.
+            It is included in workflow responses for reference, but any value sent when
+            creating or updating a workflow is ignored.
         callerPolicy:
           type: string
           enum:
@@ -4689,6 +5037,20 @@ components:
           type: string
           description: Comma-separated list of workflow IDs allowed to call this workflow (only used with workflowsFromAList policy)
           example: 14, 18, 23
+        timeSavedMode:
+          type: string
+          enum:
+            - fixed
+            - dynamic
+          description: |
+            Controls how the time saved per execution is calculated.
+            Available options:
+            - `fixed`: Uses a predetermined time value specified in the `timeSavedPerExecution` field.
+              * Requires the `timeSavedPerExecution` field to be set
+              * Use when the time saved is consistent across all executions
+            - `dynamic`: Automatically calculates time saved based on actual execution metrics
+              * The `timeSavedPerExecution` field is ignored when this mode is active
+              * Use when time saved varies between executions
         timeSavedPerExecution:
           type: number
           description: Estimated time saved per execution in minutes
@@ -4746,6 +5108,14 @@ components:
                 type: string
               value:
                 type: string
+        credentialResolverId:
+          type: string
+          description: |
+            ID of the credential resolver used to resolve credentials for this workflow.
+            This is a derived, internal setting managed via the workflow's credential
+            resolver configuration rather than something intended to be set programmatically.
+            It is included in workflow responses for reference, but any value sent when
+            creating or updating a workflow is ignored.
     sharedWorkflow:
       type: object
       additionalProperties: false
@@ -5048,6 +5418,63 @@ components:
             $ref: '#/components/schemas/sharedWorkflow'
         activeVersion:
           $ref: '#/components/schemas/activeVersion'
+    workflowVersionListItem:
+      type: object
+      additionalProperties: false
+      required:
+        - versionId
+        - workflowId
+        - authors
+      properties:
+        versionId:
+          type: string
+          readOnly: true
+          description: The version ID of this workflow snapshot
+          example: abc123-def456
+        workflowId:
+          type: string
+          readOnly: true
+          description: The workflow ID this version belongs to
+          example: 2tUt1wbLX592XDdX
+        authors:
+          type: string
+          readOnly: true
+          description: Authors who created this version
+          example: John Doe
+        name:
+          type: string
+          nullable: true
+          description: Workflow name at this version
+          example: Workflow 1
+        description:
+          type: string
+          nullable: true
+          description: Workflow description at this version
+        createdAt:
+          type: string
+          format: date-time
+          readOnly: true
+          description: When this version was created
+        updatedAt:
+          type: string
+          format: date-time
+          readOnly: true
+          description: When this version was last updated
+    workflowVersionHistoryList:
+      type: object
+      required:
+        - data
+        - nextCursor
+      properties:
+        data:
+          type: array
+          items:
+            $ref: '#/components/schemas/workflowVersionListItem'
+        nextCursor:
+          type: string
+          description: Paginate through workflow versions by setting the cursor parameter to a nextCursor attribute returned by a previous request. Default value fetches the first "page" of the collection.
+          nullable: true
+          example: MTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDA
     workflowVersion:
       type: object
       additionalProperties: false
@@ -6138,7 +6565,7 @@ components:
             - fail
             - reference-only
             - include-in-package
-          description: Policy for missing static sub-workflow dependencies. Currently only `fail` is supported; `reference-only` and `include-in-package` are reserved for upcoming export modes.
+          description: Policy for missing static sub-workflow dependencies. `fail` aborts the export when any static sub-workflow is missing from the package; `include-in-package` automatically adds missing static sub-workflows. `reference-only` is reserved for a future export mode.
           example: fail
           default: fail
     importBlockingIssue:
@@ -6255,6 +6682,30 @@ components:
               type: string
               nullable: true
               description: 'For `id-in-other-project`: the project that already owns the id.'
+        - type: object
+          description: |
+            A node type — or a version of a node type — used by a package workflow that this instance does not have, under `missingNodeTypeMode=fail`. One issue is reported per missing `(nodeType, typeVersion)` pair.
+          required:
+            - type
+            - nodeType
+            - typeVersion
+            - usedByWorkflows
+          properties:
+            type:
+              type: string
+              enum:
+                - missing-node-type
+            nodeType:
+              type: string
+              description: Full node type name as used by the package's workflows.
+            typeVersion:
+              type: number
+              description: Node type version the package's workflows use.
+            usedByWorkflows:
+              type: array
+              items:
+                type: string
+              description: Package workflow ids that use this node type and version.
         - type: object
           description: A credential reference that could not be resolved in the target project.
           required:
@@ -6291,6 +6742,25 @@ components:
               type: array
               items:
                 type: string
+        - type: object
+          description: |
+            A variable reference that could not be resolved in the target project or the global scope, under `variableMissingMode=must-preexist`.
+          required:
+            - type
+            - name
+            - usedByWorkflows
+          properties:
+            type:
+              type: string
+              enum:
+                - variable-unresolved
+            name:
+              type: string
+              description: Requirement name with no match in the target project or global scope.
+            usedByWorkflows:
+              type: array
+              items:
+                type: string
     event-types:
       type: object
       additionalProperties: false
@@ -6757,6 +7227,16 @@ components:
       required: true
       schema:
         type: string
+    offset:
+      name: offset
+      in: query
+      description: The number of items to skip before starting to collect the result set.
+      required: false
+      schema:
+        type: number
+        example: 0
+        default: 0
+        minimum: 0
     testRunWorkflowId:
       name: id
       in: path
@@ -6771,16 +7251,6 @@ components:
       required: true
       schema:
         type: string
-    offset:
-      name: offset
-      in: query
-      description: The number of items to skip before starting to collect the result set.
-      required: false
-      schema:
-        type: number
-        example: 0
-        default: 0
-        minimum: 0
     includeRole:
       name: includeRole
       in: query
@@ -6825,6 +7295,8 @@ components:
       $ref: '#/components/parameters/cursor'
     Limit:
       $ref: '#/components/parameters/limit'
+    Offset:
+      $ref: '#/components/parameters/offset'
     ExecutionId:
       $ref: '#/components/parameters/executionId'
     WorkflowId: