openapi: 3.2.0 info: title: n8n Public Settings Otel API description: n8n Public API termsOfService: https://n8n.io/legal/#terms contact: email: hello@n8n.io license: name: Sustainable Use License url: https://github.com/n8n-io/n8n/blob/master/LICENSE.md version: 1.1.1 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: [] tags: - name: SettingsOtel description: Operations about OpenTelemetry settings paths: /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: 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 '401': description: Unauthorized '403': description: Forbidden operationId: getSettingsOtel x-operation-id-source: derived 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: 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 responses: '200': description: Operation successful. content: application/json: schema: 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 '400': description: The request is invalid or provides malformed data. '401': description: Unauthorized '403': description: Forbidden '409': description: Conflict operationId: putSettingsOtel x-operation-id-source: derived /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: 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 responses: '200': description: Operation successful. content: application/json: schema: 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' '400': description: The request is invalid or provides malformed data. '401': description: Unauthorized '403': description: Forbidden operationId: postSettingsOtelTestTrace x-operation-id-source: derived 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 externalDocs: description: n8n API documentation url: https://docs.n8n.io/api/ x-enable-proxy: false