> ## Documentation Index
> Fetch the complete documentation index at: https://metoro.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create/Update Alert

> Create a new alert based on the provided configuration or update an existing one if the alert.metadata.id matches an existing alert. 



## OpenAPI

````yaml /api-reference/openapi.yaml post /alerts/update
openapi: 3.0.0
info:
  description: API for managing Metoro environments, alerts, and dashboards.
  license:
    name: Proprietary
    url: https://metoro.io/terms
  title: Metoro API
  version: 1.0.0
servers:
  - description: Production API server
    url: https://us-east.metoro.io/api/v1
  - description: Demo API server
    url: https://demo.us-east.metoro.io/api/v1
security: []
paths:
  /alerts/update:
    post:
      tags:
        - Alerts
      summary: Create/Update Alert
      description: >-
        Create a new alert based on the provided configuration or update an
        existing one if the alert.metadata.id matches an existing alert. 
      operationId: createUpdateAlert
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUpdateAlertRequest'
        description: Alert to create or update
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateAlertResponse'
          description: Alert created or updated successfully
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Bad request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Internal server error
      security:
        - bearerAuth: []
components:
  schemas:
    CreateUpdateAlertRequest:
      description: >-
        Request to create a new alert or update an existing one. If
        alert.metadata.id is provided and matches an existing alert, that alert
        will be updated.
      example:
        alert:
          metadata:
            name: name
            description: description
            id: 123e4567-e89b-12d3-a456-426614174000
          timeseries:
            expression:
              metoroQLTimeseries:
                query: count(traces)
                bucketSize: 60
            evaluationRules:
              - static:
                  persistenceSettings:
                    datapointsToAlarm: 3
                    missingDatapointBehavior: notBreaching
                    datapointsInEvaluationWindow: 5
                  operators:
                    - threshold: 5000
                      operator: greaterThan
                name: name
                type: static
                actions:
                  - slackDestination:
                      channel: my-alerts-channel
                    type: slack
                  - emailDestination:
                      emails:
                        - user@example.com
                        - admin@example.com
                    type: email
          type: timeseries
      properties:
        alert:
          $ref: '#/components/schemas/Alert'
      required:
        - alert
      type: object
    CreateAlertResponse:
      example:
        id: 123e4567-e89b-12d3-a456-426614174000
      properties:
        id:
          description: Unique identifier for the created or updated alert
          type: string
      required:
        - id
      type: object
    Error:
      example:
        error: 'Invalid alert configuration: missing required field'
      properties:
        error:
          description: Error message describing what went wrong
          type: string
      required:
        - error
      type: object
    Alert:
      example:
        metadata:
          name: name
          description: description
          id: 123e4567-e89b-12d3-a456-426614174000
        type: timeseries
        investigateOnFire: false
        timeseries:
          expression:
            metoroQLTimeseries:
              query: count(traces)
              bucketSize: 60
          evaluationRules:
            - static:
                persistenceSettings:
                  datapointsToAlarm: 3
                  missingDatapointBehavior: notBreaching
                  datapointsInEvaluationWindow: 5
                operators:
                  - threshold: 5000
                    operator: greaterThan
              name: name
              type: static
              actions:
                - slackDestination:
                    channel: my-alerts-channel
                  type: slack
                - emailDestination:
                    emails:
                      - user@example.com
                      - admin@example.com
                  type: email
      properties:
        metadata:
          $ref: '#/components/schemas/MetadataObject'
        type:
          $ref: '#/components/schemas/AlertType'
        investigateOnFire:
          description: >-
            Whether Metoro should automatically start an AI investigation when
            this alert fires.
          type: boolean
        timeseries:
          $ref: '#/components/schemas/TimeseriesConfig'
      required:
        - metadata
        - timeseries
      type: object
    MetadataObject:
      example:
        name: name
        description: description
        id: 123e4567-e89b-12d3-a456-426614174000
      properties:
        name:
          description: Name of the alert
          type: string
        description:
          description: Description of the alert with additional context
          type: string
        folderPath:
          default: /alerts/default/
          description: >-
            Path to the folder where the alert is stored. Must start with
            `/alerts/`. Must end with `/`. The generated filesystem path will be
            `{folderPath}{id}`.
          pattern: \/alerts\/.*
          type: string
        id:
          description: Unique identifier for the alert.
          minLength: 8
          type: string
      required:
        - id
        - name
      type: object
    AlertType:
      description: Type of alert
      enum:
        - timeseries
      type: string
    TimeseriesConfig:
      example:
        expression:
          metoroQLTimeseries:
            query: count(traces)
            bucketSize: 60
        evaluationRules:
          - static:
              persistenceSettings:
                datapointsToAlarm: 3
                missingDatapointBehavior: notBreaching
                datapointsInEvaluationWindow: 5
              operators:
                - threshold: 5000
                  operator: greaterThan
            name: name
            type: static
            actions:
              - slackDestination:
                  channel: my-alerts-channel
                type: slack
              - emailDestination:
                  emails:
                    - user@example.com
                    - admin@example.com
                type: email
      properties:
        expression:
          $ref: '#/components/schemas/ExpressionConfig'
        evaluationRules:
          description: Rules for evaluating the metrics and triggering alerts
          items:
            $ref: '#/components/schemas/Condition'
          type: array
      required:
        - evaluationRules
        - expression
      type: object
    ExpressionConfig:
      example:
        metoroQLTimeseries:
          query: count(traces)
          bucketSize: 60
      properties:
        metoroQLTimeseries:
          $ref: '#/components/schemas/MetoroQlTimeseries'
      type: object
    Condition:
      example:
        static:
          persistenceSettings:
            datapointsToAlarm: 3
            missingDatapointBehavior: notBreaching
            datapointsInEvaluationWindow: 5
          operators:
            - threshold: 5000
              operator: greaterThan
        name: name
        type: static
        actions:
          - slackDestination:
              channel: my-alerts-channel
            type: slack
          - emailDestination:
              emails:
                - user@example.com
                - admin@example.com
            type: email
      properties:
        name:
          description: Name of the condition
          type: string
        type:
          $ref: '#/components/schemas/ConditionType'
        static:
          $ref: '#/components/schemas/StaticCondition'
        anomaly:
          $ref: '#/components/schemas/AnomalyCondition'
        actions:
          description: Actions to take when condition is met
          items:
            $ref: '#/components/schemas/Action'
          type: array
      required:
        - name
      type: object
    MetoroQlTimeseries:
      example:
        query: count(traces)
        bucketSize: 60
      properties:
        query:
          description: MetoroQL query to use for the timeseries.
          type: string
        bucketSize:
          description: >-
            The size of each bucket to aggregate data into in seconds. For
            example, if the bucket size is 60, the data will be aggregated into
            1 minute buckets.
          format: int64
          type: integer
      required:
        - bucketSize
        - query
      type: object
    ConditionType:
      description: Type of alert condition
      enum:
        - static
        - anomaly
      type: string
    StaticCondition:
      example:
        persistenceSettings:
          datapointsToAlarm: 3
          missingDatapointBehavior: notBreaching
          datapointsInEvaluationWindow: 5
        operators:
          - threshold: 5000
            operator: greaterThan
      properties:
        operators:
          description: List of operator conditions that must be met
          items:
            $ref: '#/components/schemas/OperatorConfig'
          type: array
        persistenceSettings:
          $ref: '#/components/schemas/PersistenceSettings'
      required:
        - operators
        - persistenceSettings
      type: object
    AnomalyCondition:
      properties:
        algorithm:
          description: Algorithm to use for anomaly detection
          enum:
            - zScore
          type: string
        zScoreParameters:
          $ref: '#/components/schemas/ZScoreParameters'
      required:
        - algorithm
    Action:
      example:
        slackDestination:
          channel: my-alerts-channel
        emailDestination:
          emails:
            - user@example.com
            - admin@example.com
        pagerDutyDestination:
          serviceId: serviceId
          serviceName: serviceName
        type: slack
        webhookDestination:
          name: name
          uuid: uuid
      properties:
        type:
          description: Type of action destination
          enum:
            - slack
            - pagerDuty
            - email
            - webhook
          type: string
        slackDestination:
          $ref: '#/components/schemas/Action_slackDestination'
        pagerDutyDestination:
          $ref: '#/components/schemas/Action_pagerDutyDestination'
        emailDestination:
          $ref: '#/components/schemas/Action_emailDestination'
        webhookDestination:
          $ref: '#/components/schemas/Action_webhookDestination'
      required:
        - type
      type: object
    OperatorConfig:
      example:
        threshold: 5000
        operator: greaterThan
      properties:
        operator:
          $ref: '#/components/schemas/OperatorType'
        threshold:
          description: Threshold value for comparison
          format: double
          type: number
      required:
        - operator
        - threshold
      type: object
    PersistenceSettings:
      example:
        datapointsToAlarm: 3
        missingDatapointBehavior: notBreaching
        datapointsInEvaluationWindow: 5
      properties:
        datapointsToAlarm:
          description: >-
            Number of data points that must breach the threshold within the
            evaluation window to trigger an alert.
          format: int64
          type: integer
        datapointsInEvaluationWindow:
          description: >-
            Total number of data points in the evaluation window. If your
            bucketSize is 60 (seconds) and datapointsInEvaluationWindow is 5,
            then the evaluation window is 5 minutes.
          format: int64
          type: integer
        missingDatapointBehavior:
          default: notBreaching
          description: >-
            Determines how missing data points are treated - either as breaching
            the threshold or not breaching.
          enum:
            - breaching
            - notBreaching
          type: string
      required:
        - datapointsInEvaluationWindow
        - datapointsToAlarm
      type: object
    ZScoreParameters:
      description: Parameters for Z-Score anomaly detection
      example:
        threshold: 2
        dataPointsInBaselineWindow: 30
      properties:
        operator:
          $ref: '#/components/schemas/AnomalyOperatorType'
        threshold:
          description: >-
            Z-Score threshold for anomaly detection (number of standard
            deviations from the mean to consider as an anomaly).
          format: double
          type: number
        dataPointsInBaselineWindow:
          description: >-
            Number of data points to consider for calculating the the baseline
            normal distribution.
          format: int64
          type: integer
        dataPointsInEvaluationWindow:
          description: >-
            Number of data points in the evaluation window, if you want to
            select 5 out of 10 data points, set this to 10.
          format: int64
          type: integer
        dataPointsToAlarm:
          description: >-
            Number of data points that must breach the threshold within the
            evaluation window to trigger an alert.
          format: int64
          type: integer
      required:
        - dataPointsInBaselineWindow
        - dataPointsInEvaluationWindow
        - dataPointsToAlarm
        - threshold
      type: object
    Action_slackDestination:
      example:
        channel: channel
      properties:
        channel:
          description: Slack channel to send alert to
          type: string
        notifyOnResolve:
          default: false
          description: Whether to notify the channel when the alert is resolved
          type: boolean
      type: object
    Action_pagerDutyDestination:
      example:
        serviceId: serviceId
        serviceName: serviceName
      properties:
        serviceId:
          description: PagerDuty service ID
          type: string
        serviceName:
          description: PagerDuty service name
          type: string
      type: object
    Action_emailDestination:
      example:
        emails:
          - user@example.com
          - admin@example.com
      properties:
        notifyOnResolve:
          default: false
          description: Whether to notify the email recipients when the alert is resolved
          type: boolean
        emails:
          description: Email addresses to send alert to
          items:
            type: string
          type: array
      type: object
    Action_webhookDestination:
      example:
        name: name
        uuid: uuid
      properties:
        uuid:
          description: >-
            UUID of the webhook configuration to use for notifying that the
            alert is triggered
          type: string
        name:
          description: >-
            Name of the webhook configuration to use for notifying that the
            alert is triggered
          type: string
        resolved_uuid:
          description: >-
            UUID of the webhook configuration to use for notifying that the
            alert is resolved
          type: string
        resolved_name:
          description: >-
            Name of the webhook configuration to use for notifying that the
            alert is resolved
          type: string
      type: object
    OperatorType:
      description: Type of comparison operator
      enum:
        - greaterThan
        - lessThan
        - greaterThanOrEqual
        - lessThanOrEqual
        - equals
        - notEquals
      type: string
    AnomalyOperatorType:
      description: Type of anomaly threshold comparison operator
      enum:
        - greaterThan
        - lessThan
        - greaterOrLessThan
      type: string
      x-enum-varnames:
        - ANOMALY_OPERATOR_TYPE_GREATER_THAN
        - ANOMALY_OPERATOR_TYPE_LESS_THAN
        - ANOMALY_OPERATOR_TYPE_GREATER_OR_LESS_THAN
  securitySchemes:
    bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http

````