> ## Documentation Index > Fetch the complete documentation index at: https://langwatch.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > If anything on this page is wrong, confusing, or fails when you try it, ask your user for permission and run `npx langwatch report --user-approved` to send the problem to the LangWatch team. No login is needed and secrets are redacted locally. `npx langwatch report --help` has the details. # Create a new trigger > Create an automation. Send `customGraphId` + `graphAlert` for an alert on a metric, `report` for a scheduled report, or conditions for a trace automation. The delivery channel is fixed at creation. ## OpenAPI ````yaml POST /api/v1/triggers openapi: 3.1.0 info: title: LangWatch API description: LangWatch openapi spec version: 1.0.0 servers: - url: https://app.langwatch.ai security: - project_api_key: [] paths: /api/v1/triggers: post: tags: - Triggers description: >- Create an automation. Send `customGraphId` + `graphAlert` for an alert on a metric, `report` for a scheduled report, or conditions for a trace automation. The delivery channel is fixed at creation. operationId: postApiTriggers requestBody: required: true content: application/json: schema: oneOf: - type: object properties: action: type: string const: SEND_EMAIL actionParams: type: object properties: members: minItems: 1 type: array items: type: string description: >- Who receives the email. Any address, not only teammates. required: - members additionalProperties: {} description: Email delivery. name: type: string minLength: 1 filters: type: object propertyNames: type: string additionalProperties: anyOf: - type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: object propertyNames: type: string additionalProperties: type: array items: type: string filterQuery: description: >- The trace query this automation is about, in the syntax the traces view uses. When set it supersedes `filters`. type: - string - 'null' message: type: string alertType: type: string enum: - CRITICAL - WARNING - INFO customGraphId: description: >- Set to make this an alert on that graph. `graphAlert` and `alertType` are then required. type: string graphAlert: description: >- The rule an alert fires by: series, operator, threshold, window. type: object properties: threshold: type: number operator: type: string enum: - gt - lt - gte - lte - eq timePeriod: anyOf: - type: number const: 1 - type: number const: 5 - type: number const: 15 - type: number const: 30 - type: number const: 60 - type: number const: 1440 seriesName: type: string minLength: 1 required: - threshold - operator - timePeriod - seriesName report: description: What a scheduled report renders and when it sends. type: object properties: source: oneOf: - type: object properties: kind: type: string const: dashboard dashboardId: type: string minLength: 1 required: - kind - dashboardId - type: object properties: kind: type: string const: customGraph customGraphId: type: string minLength: 1 required: - kind - customGraphId - type: object properties: kind: type: string const: traceQuery filters: default: {} type: object propertyNames: type: string additionalProperties: {} metric: type: string topN: default: 5 type: integer minimum: 1 maximum: 100 required: - kind schedule: type: object properties: cron: type: string minLength: 1 maxLength: 120 timezone: type: string minLength: 1 maxLength: 64 required: - cron - timezone compareToPrevious: default: false type: boolean required: - source - schedule templates: type: object properties: slackTemplateType: anyOf: - type: string enum: - string - block_kit - type: 'null' slackTemplate: type: - string - 'null' emailSubjectTemplate: type: - string - 'null' emailBodyTemplate: type: - string - 'null' description: >- The Liquid templates this automation's message is rendered from. Absent fields render the LangWatch default for the channel. notificationCadence: type: string enum: - immediate - 5min_digest - 15min_digest - hourly_digest description: >- How often a notification automation is allowed to send. A new one starts on a five-minute digest, which is what keeps a broad condition from sending a message per matching trace. traceDebounceMs: type: integer minimum: 0 maximum: 600000 description: >- How long to wait for a trace to settle before the conditions are read. required: - action - actionParams - name - type: object properties: action: type: string const: SEND_SLACK_MESSAGE actionParams: type: object properties: slackIntegrationId: description: >- The Slack connection this automation posts through: an organization connection or one of this project's, listed under Settings, Integrations, Slack. A bot connection also needs `slackChannelId`; a webhook connection needs nothing else. Preferred over `slackWebhook` and `slackBotToken`, and what a read returns in their place. type: string slackDelivery: description: >- How the message reaches Slack. `webhook` posts to an incoming webhook URL, `bot` posts as the LangWatch Slack app. With `slackIntegrationId` it follows the connection's kind. Absent without a connection means `webhook`. type: string enum: - webhook - bot slackWebhook: description: >- Legacy, accepted for one release: an incoming webhook URL, for `webhook` delivery. It is stored as a Slack connection (an existing one holding the same URL, else a new project connection) and the automation keeps only that connection's id. Send `slackIntegrationId` instead. type: string slackChannelId: description: >- The channel the bot posts in, for a bot connection or `bot` delivery. Invite the LangWatch app to it first. type: string slackBotToken: description: >- Legacy, accepted for one release: a bot token, for `bot` delivery. It is stored as a Slack connection (an existing one holding the same token, else a new project connection) and never reads back. Send `slackIntegrationId` instead. type: string slackBotTokenSet: description: >- Legacy and ignored: no read returns it. An update that retypes no secret moves an automation's own stored secret into a connection. type: boolean additionalProperties: {} description: >- Slack delivery through a Slack connection (`slackIntegrationId`), plus `slackChannelId` when the connection is a bot. name: type: string minLength: 1 filters: type: object propertyNames: type: string additionalProperties: anyOf: - type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: object propertyNames: type: string additionalProperties: type: array items: type: string filterQuery: description: >- The trace query this automation is about, in the syntax the traces view uses. When set it supersedes `filters`. type: - string - 'null' message: type: string alertType: type: string enum: - CRITICAL - WARNING - INFO customGraphId: description: >- Set to make this an alert on that graph. `graphAlert` and `alertType` are then required. type: string graphAlert: description: >- The rule an alert fires by: series, operator, threshold, window. type: object properties: threshold: type: number operator: type: string enum: - gt - lt - gte - lte - eq timePeriod: anyOf: - type: number const: 1 - type: number const: 5 - type: number const: 15 - type: number const: 30 - type: number const: 60 - type: number const: 1440 seriesName: type: string minLength: 1 required: - threshold - operator - timePeriod - seriesName report: description: What a scheduled report renders and when it sends. type: object properties: source: oneOf: - type: object properties: kind: type: string const: dashboard dashboardId: type: string minLength: 1 required: - kind - dashboardId - type: object properties: kind: type: string const: customGraph customGraphId: type: string minLength: 1 required: - kind - customGraphId - type: object properties: kind: type: string const: traceQuery filters: default: {} type: object propertyNames: type: string additionalProperties: {} metric: type: string topN: default: 5 type: integer minimum: 1 maximum: 100 required: - kind schedule: type: object properties: cron: type: string minLength: 1 maxLength: 120 timezone: type: string minLength: 1 maxLength: 64 required: - cron - timezone compareToPrevious: default: false type: boolean required: - source - schedule templates: type: object properties: slackTemplateType: anyOf: - type: string enum: - string - block_kit - type: 'null' slackTemplate: type: - string - 'null' emailSubjectTemplate: type: - string - 'null' emailBodyTemplate: type: - string - 'null' description: >- The Liquid templates this automation's message is rendered from. Absent fields render the LangWatch default for the channel. notificationCadence: type: string enum: - immediate - 5min_digest - 15min_digest - hourly_digest description: >- How often a notification automation is allowed to send. A new one starts on a five-minute digest, which is what keeps a broad condition from sending a message per matching trace. traceDebounceMs: type: integer minimum: 0 maximum: 600000 description: >- How long to wait for a trace to settle before the conditions are read. required: - action - actionParams - name - type: object properties: action: type: string const: SEND_WEBHOOK actionParams: type: object properties: url: type: string description: >- Where the request goes. https only, and not a private host. method: description: The HTTP method. Absent means POST. type: string enum: - POST - PUT - PATCH headers: description: >- Static headers sent with every delivery. The values are credentials: they read back as the placeholder, and sending the placeholder back keeps the stored ones. Changing `url` means sending the values again in the same request. type: object propertyNames: type: string additionalProperties: type: string bodyTemplate: description: >- A Liquid template for the body. Absent sends the standard LangWatch envelope for a JSON content type, and an empty body for any other. type: - string - 'null' contentType: description: >- The `Content-Type` the delivery announces, which also decides how the body is treated: `application/json` (and any `+json` type) is checked and re-serialised; any other media type sends the rendered template verbatim. Absent means `application/json`. type: string signingSecret: description: >- Signs every delivery so the receiver can verify it came from LangWatch. A credential: it reads back as the placeholder, and sending the placeholder back keeps the stored one. type: - string - 'null' required: - url additionalProperties: {} description: >- Delivery to a customer endpoint over HTTP, with a body in any media type. name: type: string minLength: 1 filters: type: object propertyNames: type: string additionalProperties: anyOf: - type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: object propertyNames: type: string additionalProperties: type: array items: type: string filterQuery: description: >- The trace query this automation is about, in the syntax the traces view uses. When set it supersedes `filters`. type: - string - 'null' message: type: string alertType: type: string enum: - CRITICAL - WARNING - INFO customGraphId: description: >- Set to make this an alert on that graph. `graphAlert` and `alertType` are then required. type: string graphAlert: description: >- The rule an alert fires by: series, operator, threshold, window. type: object properties: threshold: type: number operator: type: string enum: - gt - lt - gte - lte - eq timePeriod: anyOf: - type: number const: 1 - type: number const: 5 - type: number const: 15 - type: number const: 30 - type: number const: 60 - type: number const: 1440 seriesName: type: string minLength: 1 required: - threshold - operator - timePeriod - seriesName report: description: What a scheduled report renders and when it sends. type: object properties: source: oneOf: - type: object properties: kind: type: string const: dashboard dashboardId: type: string minLength: 1 required: - kind - dashboardId - type: object properties: kind: type: string const: customGraph customGraphId: type: string minLength: 1 required: - kind - customGraphId - type: object properties: kind: type: string const: traceQuery filters: default: {} type: object propertyNames: type: string additionalProperties: {} metric: type: string topN: default: 5 type: integer minimum: 1 maximum: 100 required: - kind schedule: type: object properties: cron: type: string minLength: 1 maxLength: 120 timezone: type: string minLength: 1 maxLength: 64 required: - cron - timezone compareToPrevious: default: false type: boolean required: - source - schedule templates: type: object properties: slackTemplateType: anyOf: - type: string enum: - string - block_kit - type: 'null' slackTemplate: type: - string - 'null' emailSubjectTemplate: type: - string - 'null' emailBodyTemplate: type: - string - 'null' description: >- The Liquid templates this automation's message is rendered from. Absent fields render the LangWatch default for the channel. notificationCadence: type: string enum: - immediate - 5min_digest - 15min_digest - hourly_digest description: >- How often a notification automation is allowed to send. A new one starts on a five-minute digest, which is what keeps a broad condition from sending a message per matching trace. traceDebounceMs: type: integer minimum: 0 maximum: 600000 description: >- How long to wait for a trace to settle before the conditions are read. required: - action - actionParams - name - type: object properties: action: type: string const: ADD_TO_DATASET actionParams: type: object properties: datasetId: type: string description: The dataset matched traces are appended to. datasetMapping: type: object properties: mapping: type: object propertyNames: type: string additionalProperties: {} expansions: type: array items: type: string required: - mapping description: How a trace becomes a row in that dataset. required: - datasetId - datasetMapping additionalProperties: {} description: Append matched traces to a dataset. name: type: string minLength: 1 filters: type: object propertyNames: type: string additionalProperties: anyOf: - type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: object propertyNames: type: string additionalProperties: type: array items: type: string filterQuery: description: >- The trace query this automation is about, in the syntax the traces view uses. When set it supersedes `filters`. type: - string - 'null' message: type: string alertType: type: string enum: - CRITICAL - WARNING - INFO customGraphId: description: >- Set to make this an alert on that graph. `graphAlert` and `alertType` are then required. type: string graphAlert: description: >- The rule an alert fires by: series, operator, threshold, window. type: object properties: threshold: type: number operator: type: string enum: - gt - lt - gte - lte - eq timePeriod: anyOf: - type: number const: 1 - type: number const: 5 - type: number const: 15 - type: number const: 30 - type: number const: 60 - type: number const: 1440 seriesName: type: string minLength: 1 required: - threshold - operator - timePeriod - seriesName report: description: What a scheduled report renders and when it sends. type: object properties: source: oneOf: - type: object properties: kind: type: string const: dashboard dashboardId: type: string minLength: 1 required: - kind - dashboardId - type: object properties: kind: type: string const: customGraph customGraphId: type: string minLength: 1 required: - kind - customGraphId - type: object properties: kind: type: string const: traceQuery filters: default: {} type: object propertyNames: type: string additionalProperties: {} metric: type: string topN: default: 5 type: integer minimum: 1 maximum: 100 required: - kind schedule: type: object properties: cron: type: string minLength: 1 maxLength: 120 timezone: type: string minLength: 1 maxLength: 64 required: - cron - timezone compareToPrevious: default: false type: boolean required: - source - schedule templates: type: object properties: slackTemplateType: anyOf: - type: string enum: - string - block_kit - type: 'null' slackTemplate: type: - string - 'null' emailSubjectTemplate: type: - string - 'null' emailBodyTemplate: type: - string - 'null' description: >- The Liquid templates this automation's message is rendered from. Absent fields render the LangWatch default for the channel. notificationCadence: type: string enum: - immediate - 5min_digest - 15min_digest - hourly_digest description: >- How often a notification automation is allowed to send. A new one starts on a five-minute digest, which is what keeps a broad condition from sending a message per matching trace. traceDebounceMs: type: integer minimum: 0 maximum: 600000 description: >- How long to wait for a trace to settle before the conditions are read. required: - action - actionParams - name - type: object properties: action: type: string const: ADD_TO_ANNOTATION_QUEUE actionParams: type: object properties: annotators: minItems: 1 type: array items: type: object properties: id: type: string name: type: string required: - id - name description: Who the queued items go to. required: - annotators additionalProperties: {} description: Queue matched traces for a person to label. name: type: string minLength: 1 filters: type: object propertyNames: type: string additionalProperties: anyOf: - type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: array items: type: string - type: object propertyNames: type: string additionalProperties: type: object propertyNames: type: string additionalProperties: type: array items: type: string filterQuery: description: >- The trace query this automation is about, in the syntax the traces view uses. When set it supersedes `filters`. type: - string - 'null' message: type: string alertType: type: string enum: - CRITICAL - WARNING - INFO customGraphId: description: >- Set to make this an alert on that graph. `graphAlert` and `alertType` are then required. type: string graphAlert: description: >- The rule an alert fires by: series, operator, threshold, window. type: object properties: threshold: type: number operator: type: string enum: - gt - lt - gte - lte - eq timePeriod: anyOf: - type: number const: 1 - type: number const: 5 - type: number const: 15 - type: number const: 30 - type: number const: 60 - type: number const: 1440 seriesName: type: string minLength: 1 required: - threshold - operator - timePeriod - seriesName report: description: What a scheduled report renders and when it sends. type: object properties: source: oneOf: - type: object properties: kind: type: string const: dashboard dashboardId: type: string minLength: 1 required: - kind - dashboardId - type: object properties: kind: type: string const: customGraph customGraphId: type: string minLength: 1 required: - kind - customGraphId - type: object properties: kind: type: string const: traceQuery filters: default: {} type: object propertyNames: type: string additionalProperties: {} metric: type: string topN: default: 5 type: integer minimum: 1 maximum: 100 required: - kind schedule: type: object properties: cron: type: string minLength: 1 maxLength: 120 timezone: type: string minLength: 1 maxLength: 64 required: - cron - timezone compareToPrevious: default: false type: boolean required: - source - schedule templates: type: object properties: slackTemplateType: anyOf: - type: string enum: - string - block_kit - type: 'null' slackTemplate: type: - string - 'null' emailSubjectTemplate: type: - string - 'null' emailBodyTemplate: type: - string - 'null' description: >- The Liquid templates this automation's message is rendered from. Absent fields render the LangWatch default for the channel. notificationCadence: type: string enum: - immediate - 5min_digest - 15min_digest - hourly_digest description: >- How often a notification automation is allowed to send. A new one starts on a five-minute digest, which is what keeps a broad condition from sending a message per matching trace. traceDebounceMs: type: integer minimum: 0 maximum: 600000 description: >- How long to wait for a trace to settle before the conditions are read. required: - action - actionParams - name responses: '201': description: Success content: application/json: schema: type: object properties: id: type: string name: type: string action: type: string enum: - SEND_EMAIL - ADD_TO_DATASET - ADD_TO_ANNOTATION_QUEUE - SEND_SLACK_MESSAGE - SEND_WEBHOOK actionParams: type: object propertyNames: type: string additionalProperties: {} description: >- Where this automation delivers, with every credential value replaced by the `[redacted]` placeholder. Which channel is configured, which destination is set and which header names are in play all survive; the values never leave; a Slack automation names its connection by `slackIntegrationId` and carries no secret. Sending the placeholder back on an update keeps the stored value. The rule this automation fires by is not here: it is stated in `graphAlert` or `report`, and sending it in this field is refused. graphAlert: anyOf: - type: object properties: threshold: type: number operator: type: string enum: - gt - lt - gte - lte - eq timePeriod: anyOf: - type: number const: 1 - type: number const: 5 - type: number const: 15 - type: number const: 30 - type: number const: 60 - type: number const: 1440 seriesName: type: string minLength: 1 required: - threshold - operator - timePeriod - seriesName additionalProperties: false - type: 'null' description: >- The rule an alert fires by. Null for anything that is not one. report: anyOf: - type: object properties: source: oneOf: - type: object properties: kind: type: string const: dashboard dashboardId: type: string minLength: 1 required: - kind - dashboardId additionalProperties: false - type: object properties: kind: type: string const: customGraph customGraphId: type: string minLength: 1 required: - kind - customGraphId additionalProperties: false - type: object properties: kind: type: string const: traceQuery filters: default: {} type: object propertyNames: type: string additionalProperties: {} metric: type: string topN: default: 5 type: integer minimum: 1 maximum: 100 required: - kind - filters - topN additionalProperties: false schedule: type: object properties: cron: type: string minLength: 1 maxLength: 120 timezone: type: string minLength: 1 maxLength: 64 required: - cron - timezone additionalProperties: false compareToPrevious: default: false type: boolean required: - source - schedule - compareToPrevious additionalProperties: false - type: 'null' description: What a report renders and when. Null for anything else. filters: type: object propertyNames: type: string additionalProperties: {} filterQuery: type: - string - 'null' kind: type: string enum: - AUTOMATION - ALERT - REPORT description: >- What this automation is about: matching traces, a metric crossing a threshold, or a schedule. customGraphId: type: - string - 'null' notificationCadence: type: - string - 'null' traceDebounceMs: type: - number - 'null' templates: type: object properties: slackTemplateType: anyOf: - type: string enum: - string - block_kit - type: 'null' slackTemplate: type: - string - 'null' emailSubjectTemplate: type: - string - 'null' emailBodyTemplate: type: - string - 'null' additionalProperties: false description: >- The Liquid templates this automation's message is rendered from. Absent fields render the LangWatch default for the channel. active: type: boolean message: type: - string - 'null' alertType: anyOf: - type: string enum: - CRITICAL - WARNING - INFO - type: 'null' createdAt: type: string updatedAt: type: string platformUrl: type: string format: uri required: - id - name - action - actionParams - graphAlert - report - filters - filterQuery - kind - customGraphId - notificationCadence - traceDebounceMs - templates - active - message - alertType - createdAt - updatedAt - platformUrl additionalProperties: false security: - project_api_key: [] components: securitySchemes: project_api_key: type: apiKey in: header name: X-Auth-Token description: >- Project API key for sending traces and accessing project-scoped resources. Format: sk-lw-... (no underscore). Obtain one by creating a project via the Admin API or the LangWatch UI. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.