openapi: 3.1.0
info:
  title: openobserve Actions Alerts API
  description: OpenObserve API documents [https://openobserve.ai/docs/](https://openobserve.ai/docs/)
  contact:
    name: OpenObserve
    url: https://openobserve.ai/
    email: hello@zinclabs.io
  license:
    name: AGPL-3.0
    identifier: AGPL-3.0
  version: 0.90.0
tags:
- name: Alerts
  description: Alerts retrieval & management operations
paths:
  /api/v2/{org_id}/alerts:
    get:
      tags:
      - Alerts
      summary: List organization alerts
      description: Retrieves a list of all alerts in the organization with filtering and pagination options. Shows alert summaries including names, status, folder organization, and basic configuration details for monitoring and management purposes.
      operationId: ListAlerts
      parameters:
      - name: org_id
        in: path
        description: Organization name
        required: true
        schema:
          type: string
      - name: folder
        in: query
        description: Optional folder ID filter parameter.
        required: false
        schema:
          type: string
        style: form
      - name: stream_type
        in: query
        description: Optional stream type filter parameter.
        required: false
        schema:
          $ref: '#/components/schemas/StreamType'
        style: form
      - name: stream_name
        in: query
        description: 'Optional stream name filter parameter.


          This parameter is only used if `stream_type` is also provided.'
        required: false
        schema:
          type: string
        style: form
      - name: alert_name_substring
        in: query
        description: Optional case-insensitive name substring filter parameter.
        required: false
        schema:
          type: string
        style: form
      - name: owner
        in: query
        description: Optional owner user filter parameter.
        required: false
        schema:
          type: string
        style: form
      - name: enabled
        in: query
        description: Optional enabled filter parameter.
        required: false
        schema:
          type: boolean
        style: form
      - name: page_size
        in: query
        description: 'The optional number of alerts to retrieve. If not set then all alerts

          that match the query parameters will be returned.'
        required: false
        schema:
          type: integer
          format: int64
          minimum: 0
        style: form
      - name: page_idx
        in: query
        description: 'The optional page index. If not set then defaults to `0`.


          This parameter is only used if `page_size` is also set.'
        required: false
        schema:
          type: integer
          format: int64
          minimum: 0
        style: form
      - name: alert_type
        in: query
        description: 'Optional alert type filter: `all` (default), `scheduled`, `realtime`,

          or `anomaly_detection`.'
        required: false
        schema:
          $ref: '#/components/schemas/AlertTypeFilter'
        style: form
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                description: HTTP response body for `ListAlerts` endpoint.
                required:
                - list
                properties:
                  list:
                    type: array
                    items:
                      $ref: '#/components/schemas/ListAlertsResponseBodyItem'
      security:
      - Authorization: []
      x-o2-ratelimit:
        module: Alerts
        operation: list
      x-o2-mcp:
        description: List all alerts
        category: alerts
        summary_fields:
        - name
        - stream_name
        - stream_type
        - enabled
        - is_real_time
        - folder_id
        - folder_name
    post:
      tags:
      - Alerts
      summary: Create new alert
      description: Creates a new alert with specified conditions, triggers, and notifications. Users can define custom queries, thresholds, and notification destinations to monitor their data and receive timely alerts when conditions are met.
      operationId: CreateAlert
      parameters:
      - name: org_id
        in: path
        description: Organization name
        required: true
        schema:
          type: string
      - name: folder
        in: query
        description: Folder ID (Required if alert folder is not the default folder)
        required: false
        schema:
          type: string
      requestBody:
        description: Alert data
        content:
          application/json:
            schema:
              allOf:
              - oneOf:
                - type: object
                  description: 'Alert configuration for monitoring streams and triggering notifications.


                    An alert watches a stream (logs, metrics, or traces) using SQL or PromQL queries,

                    and sends notifications to configured destinations when trigger conditions are met.'
                  properties:
                    context_attributes:
                      type:
                      - object
                      - 'null'
                      description: Optional key-value attributes to include in alert notifications.
                      additionalProperties:
                        type: string
                      propertyNames:
                        type: string
                    creates_incident:
                      type: boolean
                      description: 'When true, this alert routes notifications through the incident system

                        instead of sending direct alert notifications.'
                    deduplication:
                      oneOf:
                      - type: 'null'
                      - $ref: '#/components/schemas/DeduplicationConfig'
                        description: Optional deduplication configuration to prevent alert spam.
                    description:
                      type: string
                      description: Human-readable description of what this alert monitors.
                      example: Fires when error count exceeds threshold in the specified time window
                    destinations:
                      type: array
                      items:
                        type: string
                      description: 'List of destination names to notify when alert fires.

                        Destinations must be pre-configured in the system.

                        Accepts either `destinations` or `alert_destinations` as the JSON field name.'
                      example:
                      - slack-alerts
                      - pagerduty
                    enabled:
                      type: boolean
                      description: Whether the alert is active. Disabled alerts are not evaluated.
                    id:
                      type:
                      - string
                      - 'null'
                      description: Unique identifier for the alert. Auto-generated on creation.
                      readOnly: true
                    is_real_time:
                      type: boolean
                      description: 'If true, alert evaluates in real-time as data arrives.

                        If false, alert runs on a schedule defined by trigger_condition.frequency.'
                    last_edited_by:
                      type:
                      - string
                      - 'null'
                      description: Username who last edited the alert.
                      readOnly: true
                    last_satisfied_at:
                      type:
                      - integer
                      - 'null'
                      format: int64
                      description: Unix timestamp of when alert condition was last satisfied.
                      readOnly: true
                    last_triggered_at:
                      type:
                      - integer
                      - 'null'
                      format: int64
                      description: Unix timestamp of when alert was last triggered.
                      readOnly: true
                    name:
                      type: string
                      description: Human-readable name for the alert. Must be unique within the organization.
                      example: High Error Rate Alert
                    org_id:
                      type: string
                      description: Organization ID. Usually set automatically from the request context.
                    owner:
                      type:
                      - string
                      - 'null'
                      description: Username of the alert owner.
                    query_condition:
                      $ref: '#/components/schemas/QueryCondition'
                      description: 'Query configuration: SQL query or PromQL expression to evaluate.'
                    row_template:
                      type: string
                      description: Template for formatting individual rows in the alert message.
                    row_template_type:
                      $ref: '#/components/schemas/RowTemplateType'
                      description: Format type for the row template.
                    stream_name:
                      type: string
                      description: Name of the stream to monitor.
                      example: default
                    stream_type:
                      $ref: '#/components/schemas/StreamType'
                      description: 'Type of stream to monitor: logs, metrics, or traces.'
                    template:
                      type:
                      - string
                      - 'null'
                      description: 'Optional template name. When specified, this template is used for all

                        destinations instead of destination-level templates. This allows using

                        different templates for different alerts while reusing the same destinations.'
                    trigger_condition:
                      $ref: '#/components/schemas/TriggerCondition'
                      description: 'Trigger configuration: when and how often to evaluate, thresholds.'
                    tz_offset:
                      type: integer
                      format: int32
                      description: Timezone offset in minutes. Negative values for western hemisphere.
                    updated_at:
                      type:
                      - integer
                      - 'null'
                      format: int64
                      description: Unix timestamp of last modification.
                      readOnly: true
                description: The alert configuration. All fields from Alert are flattened into this request body.
              - type: object
                properties:
                  alert_type:
                    oneOf:
                    - type: 'null'
                    - $ref: '#/components/schemas/AlertTypeFilter'
                      description: 'Discriminates the alert type. Defaults to scheduled alert when absent.

                        Set to `"anomaly_detection"` to create an anomaly detection config instead.'
                  anomaly_config:
                    oneOf:
                    - type: 'null'
                    - $ref: '#/components/schemas/AnomalyAlertFields'
                      description: Anomaly-detection-specific fields (nested object).
                  folder_id:
                    type:
                    - string
                    - 'null'
                    description: 'Optional folder ID indicating the folder in which to create the alert.

                      If omitted the alert will be created in the default folder.'
                    example: default
              description: "HTTP request body for `CreateAlert` endpoint.\n\nCreates a new alert with the specified configuration. The alert monitors\na stream (logs, metrics, or traces) and triggers notifications when conditions are met.\n\n## Example\n\n```json\n{\n    \"name\": \"High Error Rate Alert\",\n    \"stream_type\": \"logs\",\n    \"stream_name\": \"default\",\n    \"is_real_time\": false,\n    \"query_condition\": {\n        \"type\": \"sql\",\n        \"sql\": \"SELECT count(*) as count FROM \\\"default\\\" WHERE level = 'error'\"\n    },\n    \"trigger_condition\": {\n        \"period\": 15,\n        \"operator\": \">=\",\n        \"threshold\": 100,\n        \"frequency\": 5,\n        \"frequency_type\": \"minutes\",\n        \"silence\": 60\n    },\n    \"destinations\": [\"slack-alerts\"],\n    \"enabled\": true,\n    \"description\": \"Alert when error count exceeds 100 in 15 minutes\"\n}\n```"
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Error
          content:
            application/json:
              schema:
                default: null
      security:
      - Authorization: []
      x-o2-mcp:
        description: 'Create a new alert rule with flexible query options. IMPORTANT: Alert name must use snake_case (no spaces/special chars like :,#,?,&,%,/,quotes), destinations array is required with valid destination names. QueryCondition supports 3 query types: (1) Custom - uses conditions, aggregation, vrl_function, search_event_type, multi_time_range; (2) SQL - uses sql, vrl_function, search_event_type; (3) PromQL - uses promql, promql_condition, multi_time_range'
        category: alerts
      x-o2-ratelimit:
        module: Alerts
        operation: create
  /api/v2/{org_id}/alerts/bulk/enable:
    post:
      tags:
      - Alerts
      summary: Enable or disable alert in bulk
      description: Toggles the active status of alerts to enable or disable its monitoring and notification functionality in bulk. When disabled, the alert will stop evaluating conditions and sending notifications until re-enabled.
      operationId: EnableAlertBulk
      parameters:
      - name: org_id
        in: path
        description: Organization name
        required: true
        schema:
          type: string
      - name: value
        in: query
        description: Set to `true` to enable the alert or `false` to disable the alert.
        required: true
        schema:
          type: boolean
        style: form
      requestBody:
        description: Alert id list
        content:
          application/json:
            schema:
              type: object
              required:
              - ids
              properties:
                ids:
                  type: array
                  items:
                    type: string
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
        '404':
          description: NotFound
          content:
            application/json:
              schema:
                default: null
        '500':
          description: Failure
          content:
            application/json:
              schema:
                default: null
      security:
      - Authorization: []
      x-o2-ratelimit:
        module: Alerts
        operation: update
      x-o2-mcp:
        enabled: false
  /api/v2/{org_id}/alerts/generate_sql:
    post:
      tags:
      - Alerts
      summary: Generate SQL from alert query parameters
      description: Generates a SQL query string based on alert query parameters including stream, aggregations, and conditions. This endpoint is useful for testing alert queries and understanding the SQL that will be executed.
      operationId: GenerateSql
      parameters:
      - name: org_id
        in: path
        description: Organization name
        required: true
        schema:
          type: string
      requestBody:
        description: SQL generation parameters
        content:
          application/json:
            schema:
              type: object
              description: HTTP request body for `GenerateSql` endpoint.
              required:
              - stream_name
              - stream_type
              - query_condition
              properties:
                query_condition:
                  $ref: '#/components/schemas/QueryCondition'
                  description: 'Query condition containing aggregation and WHERE conditions

                    The conditions field within QueryCondition supports both V1 and V2 formats'
                stream_name:
                  type: string
                  description: Stream name to query
                  example: default
                stream_type:
                  $ref: '#/components/schemas/StreamType'
                  description: Type of stream (logs, metrics, traces, etc.)
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                description: HTTP response body for `GenerateSql` endpoint.
                required:
                - sql
                properties:
                  metadata:
                    oneOf:
                    - type: 'null'
                    - $ref: '#/components/schemas/GenerateSqlMetadata'
                      description: Optional metadata about the generated query
                  sql:
                    type: string
                    description: The generated SQL query string
                    example: SELECT * FROM "my_stream" WHERE field > 100
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                type: object
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
      security:
      - Authorization: []
      x-o2-mcp:
        description: Generate SQL from natural language
        category: alerts
      x-o2-ratelimit:
        module: Alerts
        operation: generate_sql
  /api/v2/{org_id}/alerts/move:
    patch:
      tags:
      - Alerts
      summary: Move alerts between folders
      description: Moves one or more alerts from their current folder to a specified destination folder. Helps organize alerts into logical groups and manage access permissions when using role-based access control.
      operationId: MoveAlerts
      parameters:
      - name: org_id
        in: path
        description: Organization name
        required: true
        schema:
          type: string
      - name: folder
        in: query
        description: From Folder ID (Required if RBAC enabled)
        required: false
        schema:
          type: string
      requestBody:
        description: Identifies alerts and the destination folder
        content:
          application/json:
            schema:
              type: object
              description: HTTP request body for `MoveAlerts` endpoint.
              required:
              - alert_ids
              - dst_folder_id
              properties:
                alert_ids:
                  type: array
                  items:
                    type: string
                  description: IDs of the alerts to move.
                anomaly_config_ids:
                  type: array
                  items:
                    type: string
                  description: 'IDs of anomaly detection configs to move. Defaults to empty when not

                    provided. Callers should always supply this to avoid per-ID DB lookups.'
                dst_folder_id:
                  type: string
                  description: Indicates the folder to which alerts should be moved.
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
        '404':
          description: NotFound
          content:
            application/json:
              schema:
                default: null
        '500':
          description: Failure
          content:
            application/json:
              schema:
                default: null
      security:
      - Authorization: []
      x-o2-mcp:
        description: Move alerts to another folder
        category: alerts
      x-o2-ratelimit:
        module: Alerts
        operation: update
  /api/v2/{org_id}/alerts/{alert_id}:
    get:
      tags:
      - Alerts
      summary: Get alert details
      description: Retrieves detailed information about a specific alert including its configuration, conditions, triggers, notification settings, and current status. Useful for viewing and understanding existing alert setups.
      operationId: GetAlert
      parameters:
      - name: org_id
        in: path
        description: Organization name
        required: true
        schema:
          type: string
      - name: alert_id
        in: path
        description: Alert ID
        required: true
        schema:
          type: string
      - name: folder
        in: query
        description: Folder ID (Required if RBAC enabled)
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alert'
                description: HTTP response body for `GetAlert` endpoint.
        '404':
          description: NotFound
          content:
            application/json:
              schema:
                default: null
      security:
      - Authorization: []
      x-o2-mcp:
        description: Get alert details by ID
        category: alerts
      x-o2-ratelimit:
        module: Alerts
        operation: get
    put:
      tags:
      - Alerts
      summary: Update alert configuration
      description: Updates an existing alert's configuration including conditions, queries, thresholds, notification destinations, and scheduling. Allows users to modify alert behavior and settings as monitoring requirements change.
      operationId: UpdateAlert
      parameters:
      - name: org_id
        in: path
        description: Organization name
        required: true
        schema:
          type: string
      - name: alert_id
        in: path
        description: Alert ID
        required: true
        schema:
          type: string
      - name: folder
        in: query
        description: Folder ID (Required if RBAC enabled)
        required: false
        schema:
          type: string
      requestBody:
        description: Alert data
        content:
          application/json:
            schema:
              allOf:
              - oneOf:
                - type: object
                  description: 'Alert configuration for monitoring streams and triggering notifications.


                    An alert watches a stream (logs, metrics, or traces) using SQL or PromQL queries,

                    and sends notifications to configured destinations when trigger conditions are met.'
                  properties:
                    context_attributes:
                      type:
                      - object
                      - 'null'
                      description: Optional key-value attributes to include in alert notifications.
                      additionalProperties:
                        type: string
                      propertyNames:
                        type: string
                    creates_incident:
                      type: boolean
                      description: 'When true, this alert routes notifications through the incident system

                        instead of sending direct alert notifications.'
                    deduplication:
                      oneOf:
                      - type: 'null'
                      - $ref: '#/components/schemas/DeduplicationConfig'
                        description: Optional deduplication configuration to prevent alert spam.
                    description:
                      type: string
                      description: Human-readable description of what this alert monitors.
                      example: Fires when error count exceeds threshold in the specified time window
                    destinations:
                      type: array
                      items:
                        type: string
                      description: 'List of destination names to notify when alert fires.

                        Destinations must be pre-configured in the system.

                        Accepts either `destinations` or `alert_destinations` as the JSON field name.'
                      example:
                      - slack-alerts
                      - pagerduty
                    enabled:
                      type: boolean
                      description: Whether the alert is active. Disabled alerts are not evaluated.
                    id:
                      type:
                      - string
                      - 'null'
                      description: Unique identifier for the alert. Auto-generated on creation.
                      readOnly: true
                    is_real_time:
                      type: boolean
                      description: 'If true, alert evaluates in real-time as data arrives.

                        If false, alert runs on a schedule defined by trigger_condition.frequency.'
                    last_edited_by:
                      type:
                      - string
                      - 'null'
                      description: Username who last edited the alert.
                      readOnly: true
                    last_satisfied_at:
                      type:
                      - integer
                      - 'null'
                      format: int64
                      description: Unix timestamp of when alert condition was last satisfied.
                      readOnly: true
                    last_triggered_at:
                      type:
                      - integer
                      - 'null'
                      format: int64
                      description: Unix timestamp of when alert was last triggered.
                      readOnly: true
                    name:
                      type: string
                      description: Human-readable name for the alert. Must be unique within the organization.
                      example: High Error Rate Alert
                    org_id:
                      type: string
                      description: Organization ID. Usually set automatically from the request context.
                    owner:
                      type:
                      - string
                      - 'null'
                      description: Username of the alert owner.
                    query_condition:
                      $ref: '#/components/schemas/QueryCondition'
                      description: 'Query configuration: SQL query or PromQL expression to evaluate.'
                    row_template:
                      type: string
                      description: Template for formatting individual rows in the alert message.
                    row_template_type:
                      $ref: '#/components/schemas/RowTemplateType'
                      description: Format type for the row template.
                    stream_name:
                      type: string
                      description: Name of the stream to monitor.
                      example: default
                    stream_type:
                      $ref: '#/components/schemas/StreamType'
                      description: 'Type of stream to monitor: logs, metrics, or traces.'
                    template:
                      type:
                      - string
                      - 'null'
                      description: 'Optional template name. When specified, this template is used for all

                        destinations instead of destination-level templates. This allows using

                        different templates for different alerts while reusing the same destinations.'
                    trigger_condition:
                      $ref: '#/components/schemas/TriggerCondition'
                      description: 'Trigger configuration: when and how often to evaluate, thresholds.'
                    tz_offset:
                      type: integer
                      format: int32
                      description: Timezone offset in minutes. Negative values for western hemisphere.
                    updated_at:
                      type:
                      - integer
                      - 'null'
                      format: int64
                      description: Unix timestamp of last modification.
                      readOnly: true
                description: Alert configuration fields (used for scheduled/realtime alerts).
              - type: object
                properties:
                  alert_type:
                    oneOf:
                    - type: 'null'
                    - $ref: '#/components/schemas/AlertTypeFilter'
                      description: 'Discriminates the alert type. When `"anomaly_detection"`, delegates to the

                        anomaly config update path.'
                  anomaly_config:
                    oneOf:
                    - type: 'null'
                    - $ref: '#/components/schemas/UpdateAnomalyAlertFields'
                      description: 'Anomaly-detection-specific fields to update (partial — only supplied fields

                        are changed).'
              description: 'HTTP request body for `UpdateAlert` endpoint.


                Updates an existing alert. Provide the full alert configuration — this replaces

                the existing alert entirely (not a partial update). The request body is the same

                structure as Alert.


                For anomaly detection configs, set `alert_type = "anomaly_detection"` and supply

                anomaly-specific fields directly at the top level (flat). Only fields present in

                the request body will be updated (partial update semantics for anomaly fields).'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Error
          content:
            application/json:
              schema:
                default: null
      security:
      - Authorization: []
      x-o2-mcp:
        description: Update an existing alert
        category: alerts
      x-o2-ratelimit:
        module: Alerts
        operation: update
    delete:
      tags:
      - Alerts
      summary: Delete alert
      description: Permanently removes an alert and all its configurations including conditions, triggers, and notification settings. This action cannot be undone and will stop all monitoring and notifications for the deleted alert.
      operationId: DeleteAlert
      parameters:
      - name: org_id
        in: path
        description: Organization name
        required: true
        schema:
          type: string
      - name: alert_id
        in: path
        description: Alert ID
        required: true
        schema:
          type: string
      - name: folder
        in: query
        description: Folder ID (Required if RBAC enabled)
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
        '500':
          description: Failure
          content:
            application/json:
              schema:
                default: null
      security:
      - Authorization: []
      x-o2-ratelimit:
        module: Alerts
        operation: delete
      x-o2-mcp:
        description: Delete an alert by ID
        category: alerts
        requires_confirmation: true
  /api/v2/{org_id}/alerts/{alert_id}/clone:
    post:
      tags:
      - Alerts
      summary: Clone an alert or anomaly detection config
      description: Creates a copy of an existing alert or anomaly detection config. For anomaly configs, the clone starts untrained with counters reset. Provide an optional name and folder_id in the request body.
      operationId: CloneAlert
      parameters:
      - name: org_id
        in: path
        description: Organization name
        required: true
        schema:
          type: string
      - name: alert_id
        in: path
        description: Source alert or anomaly config ID
        required: true
        schema:
          type: string
      requestBody:
        description: Clone options
        content:
          application/json:
            schema:
              type: object
              description: HTTP request body for `CloneAlert` endpoint.
              properties:
                folder_id:
                  type:
                  - string
                  - 'null'
                  description: Optional folder ID to place the clone in. Defaults to the source folder.
                name:
                  type:
                  - string
                  - 'null'
                  description: Optional new name for the cloned alert. Defaults to `<source_name>_copy`.
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
        '404':
          description: NotFound
          content:
            application/json:
              schema:
                default: null
        '500':
          description: Failure
          content:
            application/json:
              schema:
                default: null
      security:
      - Authorization: []
      x-o2-ratelimit:
        module: Alerts
        operation: create
  /api/v2/{org_id}/alerts/{alert_id}/enable:
    patch:
      tags:
      - Alerts
      summary: Enable or disable alert
      description: Toggles the active status of an alert to enable or disable its monitoring and notification functionality. When disabled, the alert will stop evaluating conditions and sending notifications until re-enabled.
      operationId: EnableAlert
      parameters:
      - name: org_id
        in: path
        description: Organization name
        required: true
        schema:
          type: string
      - name: alert_id
        in: path
        description: Alert ID
        required: true
        schema:
          type: string
      - name: value
        in: query
        description: Set to `true` to enable the alert or `false` to disable the alert.
        required: true
        schema:
          type: boolean
        style: form
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
        '404':
          description: NotFound
          content:
            application/json:
              schema:
                default: null
        '500':
          description: Failure
          content:
            application/json:
              schema:
                default: null
      security:
      - Authorization: []
      x-o2-ratelimit:
        module: Alerts
        operation: update
      x-o2-mcp:
        description: Enable or disable an alert
        category: alerts
  /api/v2/{org_id}/alerts/{alert_id}/export:
    post:
      tags:
      - Alerts
      summary: Export alert configuration
      description: Exports the complete configuration of a specific alert in a format suitable for backup, sharing, or importing into other environments. Includes all alert settings, conditions, and notification configurations.
      operationId: ExportAlert
      parameters:
      - name: org_id
        in: path
        description: Organization name
        required: true
        schema:
          type: string
      - name: alert_id
        in: path
        description: Alert ID
        required: true
        schema:
          type: string
      - name: folder
        in: query
        description: Folder ID (Required if RBAC enabled)
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alert'
                description: HTTP response body for `GetAlert` endpoint.
        '404':
          description: NotFound
          content:
            application/json:
              schema:
                default: null
      security:
      - Authorization: []
      x-o2-ratelimit:
        module: Alerts
        operation: get
      x-o2-mcp:
        description: Export alert as JSON
        category: alerts
  /api/v2/{org_id}/alerts/{alert_id}/retrain:
    patch:
      tags:
      - Alerts
      summary: Trigger retraining for an anomaly detection alert
      description: Triggers a model retrain for an anomaly detection alert. Returns 400 if called on a non-anomaly alert type.
      operationId: RetrainAlert
      parameters:
      - name: org_id
        in: path
        description: Organization name
        required: true
        schema:
          type: string
      - name: alert_id
        in: path
        description: Anomaly detection alert ID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Not an anomaly detection alert
          content:
            application/json:
              schema:
                default: null
        '404':
          description: NotFound
          content:
            application/json:
              schema:
                default: null
        '500':
          description: Failure
          content:
            application/json:
              schema:
                default: null
      security:
      - Authorization: []
      x-o2-ratelimit:
        module: Alerts
        operation: update
  /api/v2/{org_id}/alerts/{alert_id}/trigger:
    patch:
      tags:
      - Alerts
      summary: Manually trigger alert
      description: Manually triggers an alert to test its functionality and notification delivery. Useful for testing alert configurations, verifying notification channels, and ensuring alerts work as expected before relying on them for monitoring.
      operationId: TriggerAlert
      parameters:
      - name: org_id
        in: path
        description: Organization name
        required: true
        schema:
          type: string
      - name: alert_id
        in: path
        description: Alert ID
        required: true
        schema:
          type: string
      - name: folder
        in: query
        description: Folder ID (Required if RBAC enabled)
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
        '404':
          description: NotFound
          content:
            application/json:
              schema:
                default: null
        '500':
          description: Failure
          content:
            application/json:
              schema:
                default: null
      security:
      - Authorization: []
      x-o2-ratelimit:
        module: Alerts
        operation: update
      x-o2-mcp:
        description: Manually trigger an alert
        category: alerts
  /api/{org_id}/alerts/dedup/summary:
    get:
      tags:
      - Alerts
      summary: Get deduplication summary statistics for an organization
      operationId: GetDedupSummary
      parameters:
      - name: org_id
        in: path
        description: Organization name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DedupSummaryResponse'
      security:
      - Authorization: []
  /api/{org_id}/alerts/deduplication/config:
    get:
      tags:
      - Alerts
      summary: Get deduplication configuration for an organization
      operationId: GetDeduplicationConfig
      parameters:
      - name: org_id
        in: path
        description: Organization ID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GlobalDeduplicationConfig'
        '403':
          description: Forbidden - Enterprise feature
        '404':
          description: Not found
        '500':
          description: Internal server error
      security:
      - Authorization: []
    post:
      tags:
      - Alerts
      summary: Set deduplication configuration for an organization
      operationId: SetDeduplicationConfig
      parameters:
      - name: org_id
        in: path
        description: Organization ID
        required: true
        schema:
          type: string
      requestBody:
        description: Deduplication configuration
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GlobalDeduplicationConfig'
        required: true
      responses:
        '200':
          description: Success
        '400':
          description: Bad request
        '403':
          description: Forbidden - Enterprise feature
        '500':
          description: Internal server error
      security:
      - Authorization: []
      x-o2-mcp:
        enabled: false
    delete:
      tags:
      - Alerts
      summary: Delete deduplication configuration for an organization
      operationId: DeleteDeduplicationConfig
      parameters:
      - name: org_id
        in: path
        description: Organization ID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
        '403':
          description: Forbidden - Enterprise feature
        '500':
          description: Internal server error
      security:
      - Authorization: []
  /api/{org_id}/alerts/deduplication/semantic-groups:
    get:
      tags:
      - Alerts
      summary: Get semantic field groups for an organization
      operationId: GetSemanticGroups
      parameters:
      - name: org_id
        in: path
        description: Organization ID
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/FieldAlias'
        '500':
          description: Internal server error
      security:
      - Authorization: []
    put:
      tags:
      - Alerts
      summary: Save semantic field groups for an organization
      description: 'Merges provided groups with existing ones:

        - Groups with matching IDs are updated (replaced)

        - New groups (no matching ID) are added

        - Existing groups not in the request are preserved'
      operationId: SaveSemanticGroups
      parameters:
      - name: org_id
        in: path
        description: Organization ID
        required: true
        schema:
          type: string
      requestBody:
        description: Semantic groups to save (merged with existing)
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/FieldAlias'
        required: true
      responses:
        '200':
          description: Success
        '400':
          description: Bad request - Invalid semantic groups
        '500':
          description: Internal server error
      security:
      - Authorization: []
      x-o2-mcp:
        enabled: false
  /api/{org_id}/alerts/deduplication/semantic-groups/preview-diff:
    post:
      tags:
      - Alerts
      summary: Preview diff between imported semantic groups and current DB state
      description: 'This endpoint compares the provided semantic groups with what''s currently stored

        and returns a diff showing additions, modifications, and unchanged groups.

        The UI can use this to show users what will change before they commit.'
      operationId: PreviewSemanticGroupsDiff
      parameters:
      - name: org_id
        in: path
        description: Organization ID
        required: true
        schema:
          type: string
      requestBody:
        description: Semantic groups to compare
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/FieldAlias'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SemanticGroupDiff'
        '400':
          description: Bad request - Invalid semantic groups
        '500':
          description: Internal server error
      security:
      - Authorization: []
      x-o2-mcp:
        enabled: false
  /api/{org_id}/alerts/destinations:
    get:
      tags:
      - Alerts
      summary: List alert destinations
      description: Retrieves a list of all alert destinations configured for an organization. Optionally filter by module type (alert or pipeline) to get specific destination categories. Returns destination names, types, and basic configuration details to help administrators manage notification routing and review available delivery options.
      operationId: ListDestinations
      parameters:
      - name: org_id
        in: path
        description: Organization name
        required: true
        schema:
          type: string
      - name: module
        in: query
        description: Destination module filter, none, alert, or pipeline
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  description: "Alert destination configuration for sending notifications when alerts trigger.\n\nIMPORTANT: The `template` field is REQUIRED to create an alert destination.\nWithout a template, the destination becomes a pipeline destination and cannot be used with\nalerts.\n\n# Example - Creating an HTTP alert destination\n```json\n{\n  \"name\": \"my_alert_webhook\",\n  \"url\": \"https://example.com/webhook\",\n  \"method\": \"post\",\n  \"type\": \"http\",\n  \"template\": \"Default\",\n  \"skip_tls_verify\": false\n}\n```\n\n# Example - Creating an Email alert destination\n```json\n{\n  \"name\": \"my_email_dest\",\n  \"type\": \"email\",\n  \"emails\": [\"alerts@example.com\", \"team@example.com\"],\n  \"template\": \"Default\"\n}\n```"
                  properties:
                    action_id:
                      type:
                      - string
                      - 'null'
                      description: Action ID for enterprise Action destinations. Required when `type` is `action`.
                    aws_region:
                      type:
                      - string
                      - 'null'
                      description: AWS region for SNS destinations. Required when `type` is `sns`.
                    destination_type_name:
                      type:
                      - string
                      - 'null'
                      description: Specific destination type identifier (e.g., "openobserve", "splunk", "elasticsearch").
                    emails:
                      type: array
                      items:
                        type: string
                      description: Email recipients for Email destinations. Required when `type` is `email`.
                    headers:
                      type:
                      - object
                      - 'null'
                      description: Optional HTTP headers to include with webhook requests.
                      additionalProperties:
                        type: string
                      propertyNames:
                        type: string
                    metadata:
                      type: object
                      description: Optional key-value metadata for the destination.
                      additionalProperties:
                        type: string
                      propertyNames:
                        type: string
                    method:
                      $ref: '#/components/schemas/HTTPType'
                      description: HTTP method for HTTP destinations. Typically "post" for webhooks.
                    name:
                      type: string
                      description: Unique name for this destination. Must be unique within the organization.
                      example: my_alert_webhook
                    output_format:
                      oneOf:
                      - type: 'null'
                      - $ref: '#/components/schemas/HTTPOutputFormat'
                        description: Output format for HTTP destinations (json or text). Default is json.
                    skip_tls_verify:
                      type: boolean
                      description: Whether to skip TLS certificate verification for HTTP destinations.
                    sns_topic_arn:
                      type:
                      - string
                      - 'null'
                      description: SNS topic ARN for SNS destinations. Required when `type` is `sns`.
                    template:
                      type:
                      - string
                      - 'null'
                      description: 'REQUIRED for alert destinations. Name of the template to use for formatting alert messages.

                        Use "Default" for the built-in default template. Without a template, the destination

                        becomes a pipeline destination and cannot be used with alerts.'
                      example: Default
                    type:
                      $ref: '#/components/schemas/DestinationType'
                      description: 'Destination type: `http` (webhook), `email`, or `sns`. Default is `http`.'
                    url:
                      type: string
                      description: Webhook URL for HTTP destinations. Required when `type` is `http`.
                      example: https://example.com/webhook
        '400':
          description: Error
          content:
            application/json:
              schema:
                default: null
      security:
      - Authorization: []
      x-o2-mcp:
        description: List all alert destinations
        category: alerts
        summary_fields:
        - name
        - type
        - template
      x-o2-ratelimit:
        module: Destinations
        operation: list
    post:
      tags:
      - Alerts
      summary: Create alert or pipeline destination
      description: 'Creates a new alert destination configuration for an organization. Destinations define where alert notifications are sent when alert conditions are met, including webhooks, email addresses, and SNS topics.


        IMPORTANT: The `template` field is REQUIRED to create an alert destination. Use ''Default'' for the built-in template. For pipeline destinations, this includes external systems like OpenObserve, Splunk, Elasticsearch, etc. Use the ''module'' query parameter to specify destination type: ''alert'' (default) or ''pipeline''.


        Without a template, the destination becomes a pipeline destination and cannot be used with alerts.


        Example HTTP destination:


        ```json

        {"name": "my_webhook", "url": "https://example.com/webhook", "method": "post", "type": "http", "template": "Default"}

        ```


        Example Email destination:

        ```json

        {"name": "my_email", "type": "email", "emails": ["alerts@example.com"], "template": "Default"}

        ```'
      operationId: CreateDestination
      parameters:
      - name: org_id
        in: path
        description: Organization name
        required: true
        schema:
          type: string
      - name: module
        in: query
        description: 'Destination module type: ''alert'' (default) or ''pipeline'''
        required: false
        schema:
          type: string
      requestBody:
        description: Alert destination data. The 'template' field is required (use 'Default' for the built-in template).
        content:
          application/json:
            schema:
              type: object
              description: "Alert destination configuration for sending notifications when alerts trigger.\n\nIMPORTANT: The `template` field is REQUIRED to create an alert destination.\nWithout a template, the destination becomes a pipeline destination and cannot be used with\nalerts.\n\n# Example - Creating an HTTP alert destination\n```json\n{\n  \"name\": \"my_alert_webhook\",\n  \"url\": \"https://example.com/webhook\",\n  \"method\": \"post\",\n  \"type\": \"http\",\n  \"template\": \"Default\",\n  \"skip_tls_verify\": false\n}\n```\n\n# Example - Creating an Email alert destination\n```json\n{\n  \"name\": \"my_email_dest\",\n  \"type\": \"email\",\n  \"emails\": [\"alerts@example.com\", \"team@example.com\"],\n  \"template\": \"Default\"\n}\n```"
              properties:
                action_id:
                  type:
                  - string
                  - 'null'
                  description: Action ID for enterprise Action destinations. Required when `type` is `action`.
                aws_region:
                  type:
                  - string
                  - 'null'
                  description: AWS region for SNS destinations. Required when `type` is `sns`.
                destination_type_name:
                  type:
                  - string
                  - 'null'
                  description: Specific destination type identifier (e.g., "openobserve", "splunk", "elasticsearch").
                emails:
                  type: array
                  items:
                    type: string
                  description: Email recipients for Email destinations. Required when `type` is `email`.
                headers:
                  type:
                  - object
                  - 'null'
                  description: Optional HTTP headers to include with webhook requests.
                  additionalProperties:
                    type: string
                  propertyNames:
                    type: string
                metadata:
                  type: object
                  description: Optional key-value metadata for the destination.
                  additionalProperties:
                    type: string
                  propertyNames:
                    type: string
                method:
                  $ref: '#/components/schemas/HTTPType'
                  description: HTTP method for HTTP destinations. Typically "post" for webhooks.
                name:
                  type: string
                  description: Unique name for this destination. Must be unique within the organization.
                  example: my_alert_webhook
                output_format:
                  oneOf:
                  - type: 'null'
                  - $ref: '#/components/schemas/HTTPOutputFormat'
                    description: Output format for HTTP destinations (json or text). Default is json.
                skip_tls_verify:
                  type: boolean
                  description: Whether to skip TLS certificate verification for HTTP destinations.
                sns_topic_arn:
                  type:
                  - string
                  - 'null'
                  description: SNS topic ARN for SNS destinations. Required when `type` is `sns`.
                template:
                  type:
                  - string
                  - 'null'
                  description: 'REQUIRED for alert destinations. Name of the template to use for formatting alert messages.

                    Use "Default" for the built-in default template. Without a template, the destination

                    becomes a pipeline destination and cannot be used with alerts.'
                  example: Default
                type:
                  $ref: '#/components/schemas/DestinationType'
                  description: 'Destination type: `http` (webhook), `email`, or `sns`. Default is `http`.'
                url:
                  type: string
                  description: Webhook URL for HTTP destinations. Required when `type` is `http`.
                  example: https://example.com/webhook
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Error
          content:
            application/json:
              schema:
                default: null
      security:
      - Authorization: []
      x-o2-mcp:
        description: Create alert/pipeline destination, alert destination must have a template
        category: alerts
      x-o2-ratelimit:
        module: Destinations
        operation: create
  /api/{org_id}/alerts/destinations/{destination_name}:
    get:
      tags:
      - Alerts
      summary: Get alert destination
      description: Retrieves the configuration details for a specific alert destination. Returns the complete destination setup including delivery method, authentication credentials, notification settings, and other configuration parameters. Used for reviewing and managing existing destination configurations.
      operationId: GetDestination
      parameters:
      - name: org_id
        in: path
        description: Organization name
        required: true
        schema:
          type: string
      - name: destination_name
        in: path
        description: Destination name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                description: "Alert destination configuration for sending notifications when alerts trigger.\n\nIMPORTANT: The `template` field is REQUIRED to create an alert destination.\nWithout a template, the destination becomes a pipeline destination and cannot be used with\nalerts.\n\n# Example - Creating an HTTP alert destination\n```json\n{\n  \"name\": \"my_alert_webhook\",\n  \"url\": \"https://example.com/webhook\",\n  \"method\": \"post\",\n  \"type\": \"http\",\n  \"template\": \"Default\",\n  \"skip_tls_verify\": false\n}\n```\n\n# Example - Creating an Email alert destination\n```json\n{\n  \"name\": \"my_email_dest\",\n  \"type\": \"email\",\n  \"emails\": [\"alerts@example.com\", \"team@example.com\"],\n  \"template\": \"Default\"\n}\n```"
                properties:
                  action_id:
                    type:
                    - string
                    - 'null'
                    description: Action ID for enterprise Action destinations. Required when `type` is `action`.
                  aws_region:
                    type:
                    - string
                    - 'null'
                    description: AWS region for SNS destinations. Required when `type` is `sns`.
                  destination_type_name:
                    type:
                    - string
                    - 'null'
                    description: Specific destination type identifier (e.g., "openobserve", "splunk", "elasticsearch").
                  emails:
                    type: array
                    items:
                      type: string
                    description: Email recipients for Email destinations. Required when `type` is `email`.
                  headers:
                    type:
                    - object
                    - 'null'
                    description: Optional HTTP headers to include with webhook requests.
                    additionalProperties:
                      type: string
                    propertyNames:
                      type: string
                  metadata:
                    type: object
                    description: Optional key-value metadata for the destination.
                    additionalProperties:
                      type: string
                    propertyNames:
                      type: string
                  method:
                    $ref: '#/components/schemas/HTTPType'
                    description: HTTP method for HTTP destinations. Typically "post" for webhooks.
                  name:
                    type: string
                    description: Unique name for this destination. Must be unique within the organization.
                    example: my_alert_webhook
                  output_format:
                    oneOf:
                    - type: 'null'
                    - $ref: '#/components/schemas/HTTPOutputFormat'
                      description: Output format for HTTP destinations (json or text). Default is json.
                  skip_tls_verify:
                    type: boolean
                    description: Whether to skip TLS certificate verification for HTTP destinations.
                  sns_topic_arn:
                    type:
                    - string
                    - 'null'
                    description: SNS topic ARN for SNS destinations. Required when `type` is `sns`.
                  template:
                    type:
                    - string
                    - 'null'
                    description: 'REQUIRED for alert destinations. Name of the template to use for formatting alert messages.

                      Use "Default" for the built-in default template. Without a template, the destination

                      becomes a pipeline destination and cannot be used with alerts.'
                    example: Default
                  type:
                    $ref: '#/components/schemas/DestinationType'
                    description: 'Destination type: `http` (webhook), `email`, or `sns`. Default is `http`.'
                  url:
                    type: string
                    description: Webhook URL for HTTP destinations. Required when `type` is `http`.
                    example: https://example.com/webhook
        '404':
          description: NotFound
          content:
            application/json:
              schema:
                default: null
      security:
      - Authorization: []
      x-o2-ratelimit:
        module: Destinations
        operation: get
      x-o2-mcp:
        description: Get destination details
        category: alerts
    put:
      tags:
      - Alerts
      summary: Update alert or pipeline destination
      description: 'Updates an existing destination configuration. For alert destinations, allows modification of settings such as webhook URLs, authentication credentials, notification channels, and other delivery parameters. For pipeline destinations, allows updating external system endpoints, output formats, and metadata. Use the ''module'' query parameter to specify destination type: ''alert'' (default) or ''pipeline''.'
      operationId: UpdateDestination
      parameters:
      - name: org_id
        in: path
        description: Organization name
        required: true
        schema:
          type: string
      - name: destination_name
        in: path
        description: Destination name
        required: true
        schema:
          type: string
      - name: module
        in: query
        description: 'Destination module type: ''alert'' (default) or ''pipeline'''
        required: false
        schema:
          type: string
      requestBody:
        description: Destination data
        content:
          application/json:
            schema:
              type: object
              description: "Alert destination configuration for sending notifications when alerts trigger.\n\nIMPORTANT: The `template` field is REQUIRED to create an alert destination.\nWithout a template, the destination becomes a pipeline destination and cannot be used with\nalerts.\n\n# Example - Creating an HTTP alert destination\n```json\n{\n  \"name\": \"my_alert_webhook\",\n  \"url\": \"https://example.com/webhook\",\n  \"method\": \"post\",\n  \"type\": \"http\",\n  \"template\": \"Default\",\n  \"skip_tls_verify\": false\n}\n```\n\n# Example - Creating an Email alert destination\n```json\n{\n  \"name\": \"my_email_dest\",\n  \"type\": \"email\",\n  \"emails\": [\"alerts@example.com\", \"team@example.com\"],\n  \"template\": \"Default\"\n}\n```"
              properties:
                action_id:
                  type:
                  - string
                  - 'null'
                  description: Action ID for enterprise Action destinations. Required when `type` is `action`.
                aws_region:
                  type:
                  - string
                  - 'null'
                  description: AWS region for SNS destinations. Required when `type` is `sns`.
                destination_type_name:
                  type:
                  - string
                  - 'null'
                  description: Specific destination type identifier (e.g., "openobserve", "splunk", "elasticsearch").
                emails:
                  type: array
                  items:
                    type: string
                  description: Email recipients for Email destinations. Required when `type` is `email`.
                headers:
                  type:
                  - object
                  - 'null'
                  description: Optional HTTP headers to include with webhook requests.
                  additionalProperties:
                    type: string
                  propertyNames:
                    type: string
                metadata:
                  type: object
                  description: Optional key-value metadata for the destination.
                  additionalProperties:
                    type: string
                  propertyNames:
                    type: string
                method:
                  $ref: '#/components/schemas/HTTPType'
                  description: HTTP method for HTTP destinations. Typically "post" for webhooks.
                name:
                  type: string
                  description: Unique name for this destination. Must be unique within the organization.
                  example: my_alert_webhook
                output_format:
                  oneOf:
                  - type: 'null'
                  - $ref: '#/components/schemas/HTTPOutputFormat'
                    description: Output format for HTTP destinations (json or text). Default is json.
                skip_tls_verify:
                  type: boolean
                  description: Whether to skip TLS certificate verification for HTTP destinations.
                sns_topic_arn:
                  type:
                  - string
                  - 'null'
                  description: SNS topic ARN for SNS destinations. Required when `type` is `sns`.
                template:
                  type:
                  - string
                  - 'null'
                  description: 'REQUIRED for alert destinations. Name of the template to use for formatting alert messages.

                    Use "Default" for the built-in default template. Without a template, the destination

                    becomes a pipeline destination and cannot be used with alerts.'
                  example: Default
                type:
                  $ref: '#/components/schemas/DestinationType'
                  description: 'Destination type: `http` (webhook), `email`, or `sns`. Default is `http`.'
                url:
                  type: string
                  description: Webhook URL for HTTP destinations. Required when `type` is `http`.
                  example: https://example.com/webhook
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Error
          content:
            application/json:
              schema:
                default: null
      security:
      - Authorization: []
      x-o2-mcp:
        description: Update alert destination
        category: alerts
      x-o2-ratelimit:
        module: Destinations
        operation: update
    delete:
      tags:
      - Alerts
      summary: Delete alert destination
      description: Removes an alert destination configuration from the organization. The destination must not be in use by any active alerts or pipelines before deletion. Once deleted, any alerts previously configured to use this destination will need to be updated with alternative notification methods to continue functioning.
      operationId: DeleteAlertDestination
      parameters:
      - name: org_id
        in: path
        description: Organization name
        required: true
        schema:
          type: string
      - name: destination_name
        in: path
        description: Destination name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
        '404':
          description: NotFound
          content:
            application/json:
              schema:
                default: null
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                default: null
        '500':
          description: Failure
          content:
            application/json:
              schema:
                default: null
      security:
      - Authorization: []
      x-o2-mcp:
        description: Delete alert destination
        category: alerts
        requires_confirmation: true
      x-o2-ratelimit:
        module: Destinations
        operation: delete
  /api/{org_id}/alerts/history:
    get:
      tags:
      - Alerts
      summary: Get alert execution history
      description: Retrieves the execution history of alerts for the organization. This endpoint queries the organization's own triggers stream to provide details about when alerts were triggered, their status, and execution details.
      operationId: GetAlertHistory
      parameters:
      - name: org_id
        in: path
        description: Organization name
        required: true
        schema:
          type: string
      - name: alert_id
        in: query
        description: Filter by specific alert id
        required: false
        schema:
          type: string
      - name: start_time
        in: query
        description: Start time in Unix timestamp microseconds
        required: false
        schema:
          type: integer
          format: int64
      - name: end_time
        in: query
        description: End time in Unix timestamp microseconds
        required: false
        schema:
          type: integer
          format: int64
      - name: from
        in: query
        description: 'Pagination offset (default: 0)'
        required: false
        schema:
          type: integer
          format: int64
      - name: size
        in: query
        description: 'Number of results to return (default: 100, max: 1000)'
        required: false
        schema:
          type: integer
          format: int64
      - name: sort_by
        in: query
        description: 'Field to sort by: timestamp, alert_name, status, is_realtime, is_silenced, start_time, end_time, duration, retries, delay_in_secs, evaluation_took_in_secs, source_node, query_took (default: timestamp)'
        required: false
        schema:
          type: string
      - name: sort_order
        in: query
        description: 'Sort order: asc or desc (default: desc)'
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                - total
                - from
                - size
                - hits
                properties:
                  from:
                    type: integer
                    format: int64
                  hits:
                    type: array
                    items:
                      $ref: '#/components/schemas/AlertHistoryEntry'
                  size:
                    type: integer
                    format: int64
                  total:
                    type: integer
                    minimum: 0
        '400':
          description: Bad Request
          content:
            application/json: {}
        '403':
          description: Forbidden
          content:
            application/json: {}
        '500':
          description: Internal Server Error
          content:
            application/json: {}
      security:
      - Authorization: []
components:
  schemas:
    AlertTypeFilter:
      type: string
      description: Filters the alert list by alert type (scheduled, realtime, anomaly detection, or all).
      enum:
      - all
      - scheduled
      - realtime
      - anomaly_detection
    GroupingConfig:
      type: object
      description: Configuration for alert grouping
      properties:
        enabled:
          type: boolean
          description: Enable alert grouping
        group_wait_seconds:
          type: integer
          format: int64
          description: Initial wait time before sending first notification (seconds)
        max_group_size:
          type: integer
          description: Maximum number of alerts in a single group
          minimum: 0
        send_strategy:
          $ref: '#/components/schemas/SendStrategy'
          description: How to send grouped notifications
    QueryCondition:
      type: object
      properties:
        aggregation:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/Aggregation'
        conditions:
          type:
          - object
          - 'null'
        multi_time_range:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/CompareHistoricData'
        promql:
          type:
          - string
          - 'null'
        promql_condition:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/Condition'
        search_event_type:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/SearchEventType'
        sql:
          type:
          - string
          - 'null'
        type:
          $ref: '#/components/schemas/QueryType'
        vrl_function:
          type:
          - string
          - 'null'
    ListAlertsResponseBodyItem:
      type: object
      description: 'An item in the list returned by the `ListAlerts` endpoint.


        For `scheduled` and `realtime` alert types, `condition` and

        `trigger_condition` are always present. For `anomaly_detection` items they

        are absent; use `last_trained_at` and `status` instead.'
      required:
      - alert_id
      - folder_id
      - folder_name
      - name
      - alert_type
      - enabled
      - is_real_time
      properties:
        alert_id:
          type: string
        alert_type:
          type: string
          description: 'Discriminator: "scheduled" | "realtime" | "anomaly_detection"'
        condition:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/QueryCondition'
        description:
          type:
          - string
          - 'null'
        enabled:
          type: boolean
        folder_id:
          type: string
        folder_name:
          type: string
        is_real_time:
          type: boolean
        last_error:
          type:
          - string
          - 'null'
          description: Last error message from training or detection. Only present for `anomaly_detection` items.
        last_satisfied_at:
          type:
          - integer
          - 'null'
          format: int64
        last_trained_at:
          type:
          - integer
          - 'null'
          format: int64
          description: 'Timestamp (µs) when the anomaly model was last successfully trained.

            Only present for `anomaly_detection` items.'
        last_triggered_at:
          type:
          - integer
          - 'null'
          format: int64
        name:
          type: string
        owner:
          type:
          - string
          - 'null'
        status:
          type:
          - string
          - 'null'
          description: 'Scheduler status string. Only present for `anomaly_detection` items.

            Values: "waiting" | "ready" | "training" | "failed" | "disabled"'
        trigger_condition:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/TriggerCondition'
    SemanticGroupModification:
      type: object
      required:
      - current
      - proposed
      properties:
        current:
          $ref: '#/components/schemas/FieldAlias'
          description: Current version in DB
        proposed:
          $ref: '#/components/schemas/FieldAlias'
          description: New version from import
    Alert:
      type: object
      properties:
        context_attributes:
          type:
          - object
          - 'null'
          default: null
          additionalProperties:
            type: string
          propertyNames:
            type: string
        creates_incident:
          type: boolean
          description: 'When true, this alert creates/joins incidents instead of sending direct notifications.

            Notification is sent only when a new incident is created or a new alert type joins

            an existing incident. Repeated firings are suppressed.

            When false (default), the alert sends notifications directly and does not correlate

            to any incident.'
          default: false
        deduplication:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/DeduplicationConfig'
          default: null
        description:
          type: string
          default: ''
        destinations:
          type: array
          items:
            type: string
          default: []
        enabled:
          type: boolean
          default: false
        id:
          type:
          - string
          - 'null'
          default: null
        is_real_time:
          type: boolean
          default: false
        last_edited_by:
          type:
          - string
          - 'null'
          default: null
        last_satisfied_at:
          type:
          - integer
          - 'null'
          format: int64
          description: Will be removed in the future.
          default: null
        last_triggered_at:
          type:
          - integer
          - 'null'
          format: int64
          description: Will be removed in the future.
          default: null
        name:
          type: string
          default: ''
        org_id:
          type: string
          default: ''
        owner:
          type:
          - string
          - 'null'
          default: null
        query_condition:
          oneOf:
          - $ref: '#/components/schemas/QueryCondition'
          default:
            type: custom
            conditions: null
            sql: null
            promql: null
            promql_condition: null
            aggregation: null
            vrl_function: null
            search_event_type: null
            multi_time_range: null
        row_template:
          type: string
          default: ''
        row_template_type:
          oneOf:
          - $ref: '#/components/schemas/RowTemplateType'
          default: String
        stream_name:
          type: string
          default: ''
        stream_type:
          oneOf:
          - $ref: '#/components/schemas/StreamType'
          default: logs
        template:
          type:
          - string
          - 'null'
          description: 'Optional template name. When specified, this template is used for all

            destinations instead of destination-level templates. This allows using

            different templates for different alerts while reusing the same destinations.'
          default: null
        trigger_condition:
          oneOf:
          - $ref: '#/components/schemas/TriggerCondition'
          default:
            period: 0
            operator: '='
            threshold: 0
            frequency: 0
            cron: ''
            frequency_type: minutes
            silence: 0
            tolerance_in_secs: null
            align_time: false
        tz_offset:
          type: integer
          format: int32
          description: 'Timezone offset in minutes.

            The negative secs means the Western Hemisphere'
          default: 0
        updated_at:
          type: string
          format: date-time
          default: null
    FieldAlias:
      type: object
      description: "Field alias group — defines a set of field names that represent the same concept.\n\nUsed for:\n- Mapping equivalent field names across logs, traces, and metrics (e.g., `service`,\n  `service.name`, `app` all mean \"service identity\")\n- Alert deduplication fingerprinting\n- Populating `ServiceIdentityConfig` and `IncidentGroupingConfig` via the recommendations UI\n\n# Field Name Overlaps\n\nField names can appear in multiple semantic groups. When extracting dimensions,\nthe **first-defined group** takes precedence. This allows flexible configurations\nwhere a field like \"service\" can have different meanings in different contexts.\n\nExample:\n```\n// Group 1: service-primary (defined first)\n//   field_names: [\"service\", \"primary_service\"]\n//\n// Group 2: service-backup (defined second)\n//   field_names: [\"service\", \"backup_service\"]\n//\n// When extracting dimensions from {\"service\": \"api\"}:\n// → Matches \"service-primary\" group (first occurrence wins)\n```"
      required:
      - id
      - display
      - fields
      properties:
        display:
          type: string
          description: Human-readable display name (e.g., "Host", "K8s Cluster")
        fields:
          type: array
          items:
            type: string
          description: 'List of field names that are equivalent (e.g., ["host", "hostname", "node"])


            Note: Field names can overlap with other groups. First-defined group wins.'
        group:
          type:
          - string
          - 'null'
          description: 'Category/group this semantic field belongs to (e.g., "Common", "Kubernetes", "AWS", "GCP",

            "Azure") Used for UI organization and preset templates'
        id:
          type: string
          description: Unique identifier (lowercase, dash-separated, e.g., "host", "k8s-cluster")
        is_workload_type:
          type: boolean
          description: 'When true, this alias is a workload-type dimension used to build identity sets.

            Aliases with this flag are grouped by their `group` field to form `IdentitySet`

            entries with `distinguish_by` populated from those alias IDs.

            Aliases without this flag (HTTP, Database, System, etc.) are never used as

            identity set discriminators.'
    SearchEventType:
      type: string
      enum:
      - ui
      - dashboards
      - reports
      - alerts
      - values
      - other
      - rum
      - derivedstream
      - searchjob
      - download
      - insights
    DeduplicationConfig:
      type: object
      description: 'Per-alert deduplication configuration (from main branch)


        This is stored on each Alert and specifies which fields to use for fingerprinting.

        This matches the structure from the main branch exactly.

        Configuration for alert deduplication'
      properties:
        enabled:
          type: boolean
          description: Enable/disable deduplication
          default: false
        fingerprint_fields:
          type: array
          items:
            type: string
          description: 'Fields from query results to use for fingerprinting

            If empty, auto-detect based on query type:

            - Custom: Fields from query conditions

            - SQL: GROUP BY columns

            - PromQL: All label dimensions'
          default: []
        grouping:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/GroupingConfig'
            description: Optional alert grouping configuration
          default: null
        time_window_minutes:
          type:
          - integer
          - 'null'
          format: int32
          description: 'Time window in minutes for deduplication

            If None, defaults to 2x alert frequency'
          default: null
    AlertHistoryEntry:
      type: object
      required:
      - timestamp
      - alert_name
      - org
      - status
      - is_realtime
      - is_silenced
      - start_time
      - end_time
      - retries
      properties:
        alert_name:
          type: string
        anomaly_count:
          type:
          - integer
          - 'null'
          format: int32
          description: Number of anomalies found in this evaluation run (anomaly detection only).
        dedup_count:
          type:
          - integer
          - 'null'
          format: int32
        dedup_enabled:
          type:
          - boolean
          - 'null'
        dedup_suppressed:
          type:
          - boolean
          - 'null'
        delay_in_secs:
          type:
          - integer
          - 'null'
          format: int64
        end_time:
          type: integer
          format: int64
        error:
          type:
          - string
          - 'null'
        evaluation_took_in_secs:
          type:
          - number
          - 'null'
          format: double
        group_size:
          type:
          - integer
          - 'null'
          format: int32
        grouped:
          type:
          - boolean
          - 'null'
        is_partial:
          type:
          - boolean
          - 'null'
        is_realtime:
          type: boolean
        is_silenced:
          type: boolean
        org:
          type: string
        query_took:
          type:
          - integer
          - 'null'
          format: int64
        retries:
          type: integer
          format: int32
        source_node:
          type:
          - string
          - 'null'
        start_time:
          type: integer
          format: int64
        status:
          type: string
        success_response:
          type:
          - string
          - 'null'
        timestamp:
          type: integer
          format: int64
    Aggregation:
      type: object
      required:
      - function
      - having
      properties:
        function:
          $ref: '#/components/schemas/AggFunction'
        group_by:
          type:
          - array
          - 'null'
          items:
            type: string
        having:
          $ref: '#/components/schemas/Condition'
    Condition:
      type: object
      required:
      - column
      - operator
      - value
      properties:
        column:
          type: string
        ignore_case:
          type: boolean
        operator:
          $ref: '#/components/schemas/Operator'
        value:
          type: object
    DedupSummaryResponse:
      type: object
      required:
      - total_alerts
      - alerts_with_dedup
      - suppressions_total
      - passed_total
      - suppression_rate
      - pending_batches
      - timestamp
      properties:
        alerts_with_dedup:
          type: integer
          description: Number of alerts with deduplication enabled
          minimum: 0
        passed_total:
          type: integer
          format: int64
          description: Total alerts that passed dedup in time period
        pending_batches:
          type: integer
          format: int64
          description: Current pending batches (grouping)
        suppression_rate:
          type: number
          format: double
          description: Suppression rate (0.0 to 1.0)
        suppressions_total:
          type: integer
          format: int64
          description: Total alerts suppressed in time period
        timestamp:
          type: integer
          format: int64
          description: Timestamp when data was collected
        total_alerts:
          type: integer
          description: Total number of alerts in organization
          minimum: 0
    CompareHistoricData:
      type: object
      required:
      - offSet
      properties:
        offSet:
          type: string
    HTTPOutputFormat:
      oneOf:
      - type: string
        enum:
        - json
      - type: string
        enum:
        - ndjson
      - type: string
        enum:
        - nestedevent
      - type: object
        required:
        - esbulk
        properties:
          esbulk:
            type: object
            required:
            - index
            properties:
              index:
                type: string
      - type: object
        required:
        - stringseparated
        properties:
          stringseparated:
            type: object
            required:
            - separator
            properties:
              separator:
                type: string
    SendStrategy:
      type: string
      description: Strategy for sending grouped alert notifications
      enum:
      - first_with_count
      - summary
      - all
    FrequencyType:
      type: string
      enum:
      - cron
      - minutes
    HTTPType:
      type: string
      enum:
      - post
      - put
      - get
    Operator:
      type: string
      enum:
      - '='
      - '!='
      - '>'
      - '>='
      - <
      - <=
      - contains
      - not_contains
    RowTemplateType:
      type: string
      enum:
      - String
      - Json
    GlobalDeduplicationConfig:
      type: object
      description: 'Organization-level deduplication configuration (Global settings)


        This configuration is stored at the organization level and defines:

        - Whether deduplication is enabled globally

        - Semantic field groups that map field name variations to canonical dimensions

        - Cross-alert deduplication based on shared semantic dimensions

        - Default time window for deduplication


        Per-alert fingerprint fields are stored in the Alert.deduplication field.'
      properties:
        alert_dedup_enabled:
          type: boolean
          description: 'Enable cross-alert deduplication based on shared semantic dimensions


            When true, alerts from DIFFERENT alert rules that share semantic dimensions

            will be deduplicated if one already fired recently.


            Example:

            - Alert A fires: {host: "srv01", service: "api"}

            - Alert B fires 30s later: {host: "srv01", region: "us-east"}

            - If cross_alert_dedup=true: Alert B suppressed (shares "host" dimension)

            - If cross_alert_dedup=false: Both sent (per-alert dedup only)'
          default: false
        alert_fingerprint_groups:
          type: array
          items:
            type: string
          description: 'Semantic group IDs to use for cross-alert fingerprinting


            When cross_alert_dedup is enabled, these semantic group IDs are used

            to generate fingerprints across all alerts (instead of per-alert fingerprint_fields).

            Must reference IDs from semantic field groups (stored in system_settings).


            Example: ["host", "service"] means fingerprint = hash(host_value + service_value)

            Required when cross_alert_dedup is true.'
          default: []
        enabled:
          type: boolean
          description: Enable/disable deduplication globally for this organization
          default: false
        time_window_minutes:
          type:
          - integer
          - 'null'
          format: int32
          description: 'Default time window in minutes for deduplication


            Alerts with the same fingerprint within this window are suppressed.

            If None, defaults to 2x the alert evaluation frequency.

            Can be overridden per-alert.'
          default: null
        upgrade_window_minutes:
          type: integer
          format: int64
          description: 'Time window for hierarchical incident upgrade (minutes)

            Incidents created within this window can be upgraded from weak to strong correlation keys.'
          default: 0
          minimum: 0
    UpdateAnomalyAlertFields:
      type: object
      description: Anomaly-detection-specific fields for `UpdateAlertRequestBody` (all optional).
      properties:
        alert_enabled:
          type:
          - boolean
          - 'null'
        custom_sql:
          type:
          - string
          - 'null'
        description:
          type:
          - string
          - 'null'
        detection_function:
          type:
          - string
          - 'null'
        detection_function_field:
          type:
          - string
          - 'null'
          description: Field to aggregate. Combined with `detection_function` into "avg(field)" before saving.
        detection_window_seconds:
          type:
          - integer
          - 'null'
          format: int64
        enabled:
          type:
          - boolean
          - 'null'
        filters: {}
        folder_id:
          type:
          - string
          - 'null'
        histogram_interval:
          type:
          - string
          - 'null'
        name:
          type:
          - string
          - 'null'
        owner:
          type:
          - string
          - 'null'
        percentile:
          type:
          - number
          - 'null'
          format: double
        query_mode:
          type:
          - string
          - 'null'
        retrain_interval_days:
          type:
          - integer
          - 'null'
          format: int32
        schedule_interval:
          type:
          - string
          - 'null'
        training_window_days:
          type:
          - integer
          - 'null'
          format: int32
    GenerateSqlMetadata:
      type: object
      description: Metadata about the generated SQL query.
      required:
      - has_aggregation
      - has_conditions
      - has_group_by
      properties:
        has_aggregation:
          type: boolean
          description: Whether aggregation is present
        has_conditions:
          type: boolean
          description: Whether WHERE clause is present
        has_group_by:
          type: boolean
          description: Whether GROUP BY is present
    AggFunction:
      type: string
      enum:
      - avg
      - min
      - max
      - sum
      - count
      - median
      - p50
      - p75
      - p90
      - p95
      - p99
    DestinationType:
      type: string
      enum:
      - http
      - email
      - sns
      - action
    TriggerCondition:
      type: object
      properties:
        align_time:
          type: boolean
          default: false
        cron:
          type: string
          default: ''
        frequency:
          type: integer
          format: int64
          description: (seconds)
          default: 0
        frequency_type:
          oneOf:
          - $ref: '#/components/schemas/FrequencyType'
          default: minutes
        operator:
          oneOf:
          - $ref: '#/components/schemas/Operator'
          default: '='
        period:
          type: integer
          format: int64
          description: (minutes)
          default: 0
        silence:
          type: integer
          format: int64
          description: (minutes)
          default: 0
        threshold:
          type: integer
          format: int64
          default: 0
        timezone:
          type:
          - string
          - 'null'
          default: null
        tolerance_in_secs:
          type:
          - integer
          - 'null'
          format: int64
          description: (seconds)
          default: null
    SemanticGroupDiff:
      type: object
      required:
      - additions
      - modifications
      - unchanged
      properties:
        additions:
          type: array
          items:
            $ref: '#/components/schemas/FieldAlias'
          description: Groups that exist in the imported JSON but not in DB (new)
        modifications:
          type: array
          items:
            $ref: '#/components/schemas/SemanticGroupModification'
          description: Groups that exist in both but have different content
        unchanged:
          type: array
          items:
            $ref: '#/components/schemas/FieldAlias'
          description: Groups that are identical in both
    QueryType:
      type: string
      enum:
      - custom
      - sql
      - promql
    StreamType:
      type: string
      enum:
      - logs
      - metrics
      - traces
      - service_graph
      - enrichment_tables
      - file_list
      - metadata
      - index
    AnomalyAlertFields:
      type: object
      description: Anomaly-detection-specific fields for `CreateAlertRequestBody`.
      required:
      - query_mode
      - detection_function
      - histogram_interval
      - schedule_interval
      - detection_window_seconds
      properties:
        alert_enabled:
          type:
          - boolean
          - 'null'
        custom_sql:
          type:
          - string
          - 'null'
        detection_function:
          type: string
          description: Aggregation function, e.g. "count(*)" or "avg(cpu_usage)"
        detection_function_field:
          type:
          - string
          - 'null'
          description: 'Field to aggregate (required for avg/sum/min/max/pXX, ignored for count).

            Combined with `detection_function` into "avg(field)" before saving.'
        detection_window_seconds:
          type: integer
          format: int64
          description: Look-back window per detection run, in seconds
        filters: {}
        histogram_interval:
          type: string
          description: SQL histogram bucket size, e.g. "5m", "1h"
        percentile:
          type:
          - number
          - 'null'
          format: double
          description: 'Percentile threshold (50.0–99.9). Default: 97.0

            Also accepts the name `threshold` (integer, e.g. 97) for API convenience.'
        query_mode:
          type: string
          description: '"filters" or "custom_sql"'
        rcf_num_trees:
          type:
          - integer
          - 'null'
          format: int32
        rcf_shingle_size:
          type:
          - integer
          - 'null'
          format: int32
        rcf_tree_size:
          type:
          - integer
          - 'null'
          format: int32
        retrain_interval_days:
          type:
          - integer
          - 'null'
          format: int32
          description: 0 = never retrain automatically; otherwise days between retrains
        schedule_interval:
          type: string
          description: How often the detection job fires, e.g. "1h", "30m"
        training_window_days:
          type:
          - integer
          - 'null'
          format: int32
  securitySchemes:
    Authorization:
      type: apiKey
      in: header
      name: Authorization
    BasicAuth:
      type: http
      scheme: basic