Aedifion Alert API

openapi: 3.2.0
info:
  description: 'Welcome to the interactive user interface (UI) for the aedifion REST API.


    This UI allows you to


    - browse documentation of all endpoints

    - explore schemas and examples of request parameters and responses

    - call endpoints and view responses


    Further documentation as well as extensive guides and tutorials are available in the official documentation.'
  title: Docs Alert API
  version: ''
servers:
- url: ''
tags:
- description: Creating, modifying, and accessing alerts and related resources.
  name: Alert
paths:
  /v2/alert/discrete:
    post:
      description: 'Creates a new discrete value alert, which fires while the datapoint''s value is one of a

        configured set of values (or, when negated, while it is not).

        The alert is directly enabled and will become active immediately after creation.'
      operationId: post_alert_discrete
      parameters:
      - description: The numeric id of the project in which to create the alert.
        in: query
        name: project_id
        required: true
        schema:
          format: int64
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewDiscreteAlert'
        description: The details of the alert to create.
        required: true
        x-body-name: new_alert
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alert'
          description: Success. The alert has been created. The created alert is returned in the response.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized request. Details of the error are returned in the 'error' field of the repsonse.
        '415':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unsuccessful request. Details on the error are returned in the 'error' field of the response.
          headers:
            WWW_Authenticate:
              schema:
                type: string
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Create a new discrete value alert
      tags:
      - Alert
      x-openapi-router-controller: app.controllers.alert_controller
  /v2/alert/threshold:
    post:
      description: Creates a new threshold alert. The alert is directly enabled and will become active immediately after creation.
      operationId: post_alert_threshold
      parameters:
      - description: The id of the project in which to create the alert.
        in: query
        name: project_id
        required: true
        schema:
          format: int64
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewThresholdAlert'
        description: The details of the alert to create.
        required: true
        x-body-name: new_alert
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alert'
          description: Success. The alert has been created. The created alert is returned in the response.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized request. Details of the error are returned in the 'error' field of the repsonse.
        '415':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unsuccessful request. Details on the error are returned in the 'error' field of the response.
          headers:
            WWW_Authenticate:
              schema:
                type: string
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Create a new threshold alert
      tags:
      - Alert
      x-openapi-router-controller: app.controllers.alert_controller
  /v2/alert/throughput:
    post:
      description: Creates a new throughput alert. The alert is directly enabled and will become active immediately after creation.
      operationId: post_alert_throughput
      parameters:
      - description: The numeric id of the project in which to create the alert.
        in: query
        name: project_id
        required: true
        schema:
          format: int64
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewThroughputAlert'
        description: The details of the alert to create.
        required: true
        x-body-name: new_alert
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alert'
          description: Success. The alert has been created. The created alert is returned in the response.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized request. Details of the error are returned in the 'error' field of the repsonse.
        '415':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unsuccessful request. Details on the error are returned in the 'error' field of the response.
          headers:
            WWW_Authenticate:
              schema:
                type: string
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Create a new throughput alert
      tags:
      - Alert
      x-openapi-router-controller: app.controllers.alert_controller
  /v2/alert/{alert_id}:
    delete:
      description: Delete an alert.
      operationId: delete_alert_new
      parameters:
      - description: The id of the alert.
        in: path
        name: alert_id
        required: true
        schema:
          format: int64
          type: integer
      responses:
        '204':
          content: {}
          description: 'Success. The alert has been deleted. Per REST semantics this response has an

            empty body (no content) — treat the 204 status itself as confirmation of deletion.

            '
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized request. Details on the error are returned in the 'error' field of the response.
          headers:
            WWW_Authenticate:
              schema:
                type: string
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: No alert was found for the given id. Details are returned in the 'error' field of the response.
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Delete an alert
      tags:
      - Alert
      x-openapi-router-controller: app.controllers.alert_controller
    get:
      description: Returns the details of a single alert.
      operationId: get_alert
      parameters:
      - description: The id of the alert.
        in: path
        name: alert_id
        required: true
        schema:
          format: int64
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alert'
          description: Success. The alert is returned in the response.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized request. Details on the error are returned in the 'error' field of the response.
          headers:
            WWW_Authenticate:
              schema:
                type: string
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: 'No alert was found for the given id, or the alert was created with a previous version of

            alerting and its definition can no longer be retrieved.

            Details are returned in the ''error'' field of the response.

            '
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Get an alert
      tags:
      - Alert
      x-openapi-router-controller: app.controllers.alert_controller
    patch:
      description: 'Partially updates an existing alert. Only the provided fields are changed; omitted fields

        keep their current values. The monitored datapoint and the alert type cannot be changed.'
      operationId: patch_alert
      parameters:
      - description: The id of the alert.
        in: path
        name: alert_id
        required: true
        schema:
          format: int64
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAlert'
        description: The fields to update.
        required: true
        x-body-name: update_alert
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alert'
          description: Success. The alert has been updated. The updated alert is returned in the response.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Invalid update. Details are returned in the 'error' field of the response.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized request. Details on the error are returned in the 'error' field of the response.
          headers:
            WWW_Authenticate:
              schema:
                type: string
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: No alert was found for the given id. Details are returned in the 'error' field of the response.
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Partially update an alert
      tags:
      - Alert
      x-openapi-router-controller: app.controllers.alert_controller
  /v2/alert/{alert_id}/disable:
    post:
      description: Disable an alert.
      operationId: disable_alert
      parameters:
      - description: The id of the alert.
        in: path
        name: alert_id
        required: true
        schema:
          format: int64
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alert'
          description: 'Success.

            The alert has been disabled or was already disabled.

            The affected alert is returned in the response.

            '
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized request. Details on the error are returned in the 'error' field of the response.
          headers:
            WWW_Authenticate:
              schema:
                type: string
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: No alert was found for the given id. Details are returned in the 'error' field of the response.
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Disable an alert
      tags:
      - Alert
      x-openapi-router-controller: app.controllers.alert_controller
  /v2/alert/{alert_id}/enable:
    post:
      description: Enable an alert.
      operationId: enable_alert
      parameters:
      - description: The id of the alert.
        in: path
        name: alert_id
        required: true
        schema:
          format: int64
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alert'
          description: 'Success.

            The alert has been enabled or was already enabled.

            The affected alert is returned in the response.

            '
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: Unauthorized request. Details on the error are returned in the 'error' field of the response.
          headers:
            WWW_Authenticate:
              schema:
                type: string
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: No alert was found for the given id. Details are returned in the 'error' field of the response.
      security:
      - basicAuth: []
      - openIDConnect: []
      summary: Enable an alert
      tags:
      - Alert
      x-openapi-router-controller: app.controllers.alert_controller
components:
  schemas:
    AlertNotification:
      additionalProperties: false
      description: Notification channels for an alert. Each channel is optional.
      properties:
        dashboard:
          $ref: '#/components/schemas/DashboardNotificationPoint'
        email:
          $ref: '#/components/schemas/EmailNotificationPoint'
        ms_teams:
          $ref: '#/components/schemas/MSTeamsNotificationPoint'
        telegram:
          $ref: '#/components/schemas/TelegramNotificationPoint'
      type: object
    TelegramNotificationPoint:
      additionalProperties: false
      properties:
        chat_ids:
          items:
            type: string
          type: array
      type: object
    NewThresholdAlert:
      additionalProperties: false
      description: "Definitions for a new threshold alert\n\n- When the alert stays on the same level, it is re-notified only after the 'repeat' duration; a 'repeat' of '0s' or 'never' disables re-notification, so you are notified only when the alert level changes.\n- The order of the alert (ascending or descending) is inferred from the thresholds when two or more levels are configured, and must be supplied explicitly (via the thresholds `order` field) when only a single level is configured.\n  - info < warn < crit makes an ascending alert that gets more critical as values get bigger.\n  - info > warn > crit makes a descending alert that gets more critical as values get smaller.\n"
      example:
        attributes:
          category: fire
          team: Operations
        dataPointID: CO2_Sensor_01
        description: 'Alert on indoor CO2 level with three severity levels.

          Normal outdoor CO2 levels range between 350-450 ppm(OK).

          Complaints of stuffiness and less comfortable breathing indoors occur at 600-1000 ppm (INFO).

          General drowsiness can occur at 1000-2500 ppm (WARNING).

          Adverse health effects can happen beyond 2500 ppm (CRITICAL).

          '
        name: Productivity Alert
        notification:
          dashboard:
            enabled: false
          email:
            recipients:
            - john.smith@example.com
            - john.doe@example.com
          ms_teams:
            webhook_urls:
            - https://example.webhook.office.com/webhookb2/00000000-0000-0000-0000-000000000000@11111111-1111-1111-1111-111111111111/IncomingWebhook/0123456789abcdef0123456789abcdef/22222222-2222-2222-2222-222222222222
          telegram:
            chat_ids:
            - '-12345'
            - '56789'
        repeat: 2h
        thresholds:
          crit: 2500
          crit_reset: 2000
          info: 600
          info_reset: 500
          warn: 1000
          warn_reset: 900
      properties:
        attributes:
          additionalProperties:
            type: string
          description: Attributes/tags to assign to the alert (key=value).
          type: object
        dataPointID:
          description: The datapoint whose values are to check.
          type: string
        delay:
          description: 'Optional debounce. The threshold condition must hold continuously for this duration

            (e.g. ''5m'') before the alarm fires; if it clears sooner, nothing is sent. Omit for the

            default (fire as soon as the condition is met). Threshold alarms only.

            '
          example: 5m
          pattern: ^\d+[wdhms]{1}$
          type: string
        description:
          description: Free text description of the alert.
          type: string
        disabled:
          default: false
          description: 'Create the alert in a paused (disabled) state: its task is created disabled and does not

            fire until the alert is enabled via the enable endpoint. Defaults to false (created enabled).

            '
          type: boolean
        name:
          description: The name of the alert.
          type: string
        notification:
          $ref: '#/components/schemas/AlertNotification'
        repeat:
          default: 1h
          description: 'Minimum interval after which an unchanged alert is re-notified (in addition to

            notifying on every level change). Use a duration like ''2h'' to re-notify periodically;

            ''0s'' or the keyword ''never'' disables re-notification (notify only on level changes).

            '
          example: 2d, 0.5h, 2.5m, 110s
          pattern: ^(\d+[wdhms]|never)$
          type: string
        thresholds:
          $ref: '#/components/schemas/AlertThresholds'
        timezone:
          description: 'Optional IANA timezone (e.g. ''Europe/Berlin'') used to render alert timestamps in

            notifications. Defaults to the project''s building timezone on create; falls back to ''UTC''

            when the building timezone is unresolved.

            '
          example: Europe/Berlin
          type: string
      required:
      - name
      - dataPointID
      - thresholds
    Alert:
      properties:
        alarm_dashboard:
          type: boolean
        alert_type:
          type: string
        attributes:
          type: string
        created:
          format: date-time
          type: string
        dataPointID:
          type: string
        delay:
          description: 'Debounce duration the condition must hold before the alarm fires (e.g.

            ''5m''). Only present for threshold and discrete alerts with a delay configured.

            '
          type: string
        description:
          type: string
        email:
          format: email
          type: string
        id:
          format: int64
          type: integer
        level:
          description: The severity a discrete alert fires at. Only set for discrete alerts.
          type: string
        name:
          type: string
        negate:
          description: 'Whether a discrete alert fires while the value is NOT one of its

            values. Only set for discrete alerts.

            '
          type: boolean
        period:
          description: Throughput measurement period as a duration string (e.g. '2h'). Only set for throughput alerts.
          type: string
        project_id:
          format: int64
          type: integer
        repeat:
          description: 'Re-notification interval as a duration string (e.g.

            ''2h''), or ''never'' (notify only on level changes).

            '
          type: string
        status:
          type: string
        teams_webhook:
          description: Comma-separated MS Teams webhook URLs configured for this alert.
          type: string
        telegram_chatid:
          type: string
        threshold_crit:
          type: number
        threshold_crit_reset:
          type: number
        threshold_dead:
          type: number
        threshold_info:
          type: number
        threshold_info_reset:
          type: number
        threshold_ok:
          type: number
        threshold_order:
          enum:
          - asc
          - desc
          type: string
        threshold_warn:
          type: number
        threshold_warn_reset:
          type: number
        timezone:
          description: IANA timezone used to render this alert's notification timestamps.
          type: string
        updated:
          format: date-time
          type: string
        values:
          description: The discrete values the alert fires on. Only set for discrete alerts.
          items:
            type: number
          type: array
      required:
      - id
      - name
      - description
      - project_id
      - created
      - alert_type
      - status
      type: object
    EmailNotificationPoint:
      additionalProperties: false
      properties:
        recipients:
          items:
            type: string
          type: array
      type: object
    Error:
      properties:
        details:
          properties: {}
          type: object
        error:
          type: string
        operation:
          enum:
          - ''
          - get
          - create
          - delete
          - update
          type: string
        success:
          default: false
          type: boolean
      required:
      - error
      type: object
    AlertThresholds:
      additionalProperties: false
      description: 'Trigger and reset thresholds per severity. At least one of ''info'', ''warn'', or ''crit'' must

        be provided; omitted levels are not evaluated. The ''order'' (ascending/descending) is

        inferred from the values when two or more levels are given (and validated if also supplied),

        and is REQUIRED when only a single level is configured, since one value cannot determine the

        direction. ''asc'' fires when the value rises to/above a level; ''desc'' fires when it falls

        to/below. Reset values default to their trigger value when omitted.

        '
      properties:
        crit:
          type:
          - number
          - 'null'
        crit_reset:
          type:
          - number
          - 'null'
        info:
          type:
          - number
          - 'null'
        info_reset:
          type:
          - number
          - 'null'
        order:
          description: 'Alarm direction. Optional when >=2 levels are configured (inferred from the values);

            required when exactly one level is configured.

            '
          enum:
          - asc
          - desc
          type: string
        warn:
          type:
          - number
          - 'null'
        warn_reset:
          type:
          - number
          - 'null'
      type: object
    NewThroughputAlert:
      additionalProperties: false
      description: "Definitions for a new throughput alert.\n\n- When the alert stays on the same level, new events are emitted only after the 'repeat' duration.\n- Throughput is measured as the number of values received during each 'period', and all provided thresholds are interpreted as *values per 'period'*.\n- Throughput is measured over 'period' before an alert is triggered. Thus, use a longer 'period' for more stable alerts that tolerate temporary drops/highs in throughput and use a shorter 'period' for more reactive alerts that also trigger on short temporary changes in throughput.\nA 'repeat' of '0s' or 'never' disables re-notification, so you are notified only when the alert level changes.\n- The order of the alert (ascending or descending) is inferred from the thresholds when two or more levels are configured, and must be supplied explicitly (via the thresholds `order` field) when only a single level is configured.\n    - info < warn < crit makes an ascending alert that gets more critical as throughput grows.\n    - info > warn > crit makes a descending alert that gets more critical as throughput drops.\n"
      example:
        attributes:
          category: network
          team: IT
        description: 'Alert on project ingress measured over a 10-minute period.

          During normal operation, we expect well beyond 50 values per period (INFO).

          If data ingress drops below 20 values per period, this could indicate connection problems or partial equipment failure (WARNING).

          If ingress goes to 0, this indicates connection loss or complete equipment failure (CRITICAL).

          '
        name: Ingress Alert
        notification:
          dashboard:
            enabled: false
          email:
            recipients:
            - john.smith@example.com
            - john.doe@example.com
          ms_teams:
            webhook_urls:
            - https://example.webhook.office.com/webhookb2/00000000-0000-0000-0000-000000000000@11111111-1111-1111-1111-111111111111/IncomingWebhook/0123456789abcdef0123456789abcdef/22222222-2222-2222-2222-222222222222
          telegram:
            chat_ids:
            - '-12345'
            - '56789'
        period: 10m
        repeat: 1d
        thresholds:
          crit: 0
          crit_reset: 2
          info: 50
          info_reset: 60
          warn: 20
          warn_reset: 25
      properties:
        attributes:
          additionalProperties:
            type: string
          description: Attributes/tags to assign to the alert (key=value).
          type: object
        dataPointID:
          description: The datapoint to check throughtput for. If not provided, throughput of the whole project is checked.
          type: string
        description:
          description: Free text description of the alert.
          type: string
        disabled:
          default: false
          description: 'Create the alert in a paused (disabled) state: its task is created disabled and does not

            fire until the alert is enabled via the enable endpoint. Defaults to false (created enabled).

            '
          type: boolean
        name:
          description: The name of the alert.
          type: string
        notification:
          $ref: '#/components/schemas/AlertNotification'
        period:
          description: Time period over which to measure throughput.
          pattern: ^\d+[wdhms]{1}$
          type: string
        repeat:
          default: 1d
          description: 'Minimum interval after which an unchanged alert is re-notified (in addition to

            notifying on every level change). Use a duration like ''2h'' to re-notify periodically;

            ''0s'' or the keyword ''never'' disables re-notification (notify only on level changes).

            '
          example: 2d, 0.5h, 2.5m, 110s
          pattern: ^(\d+[wdhms]|never)$
          type: string
        thresholds:
          $ref: '#/components/schemas/AlertThresholds'
        timezone:
          description: 'Optional IANA timezone (e.g. ''Europe/Berlin'') used to render alert timestamps in

            notifications. Defaults to the project''s building timezone on create; falls back to ''UTC''

            when the building timezone is unresolved.

            '
          example: Europe/Berlin
          type: string
      required:
      - name
      - thresholds
      - period
    NewDiscreteAlert:
      additionalProperties: false
      description: "Definitions for a new discrete value alert.\n\n- The alert fires while the datapoint's value is one of the values in 'values', and clears as\n  soon as the value is no longer one of them. Use it for enumerated signals — status, mode or\n  fault codes — where the interesting values are not a contiguous range and therefore cannot be\n  expressed as thresholds. A single value is the binary/equality case.\n- Set 'negate' to fire on the inverse: while the value is NOT one of the given values.\n- The alert fires at exactly one severity, chosen with 'level'. There is no ordering\n  (ascending/descending) and no reset value: membership is exact, so the alert clears\n  immediately when the value leaves the set.\n"
      example:
        attributes:
          category: fault
          team: Operations
        dataPointID: Chiller_01_StatusCode
        description: 'Alert while the chiller reports one of the fault codes 2, 5 or 7.

          Codes 3, 4 and 6 are informational and must not raise an alarm, which is why this cannot

          be expressed with thresholds.

          '
        level: crit
        name: Chiller fault code
        negate: false
        notification:
          email:
            recipients:
            - john.smith@example.com
        repeat: 2h
        values:
        - 2
        - 5
        - 7
      properties:
        attributes:
          additionalProperties:
            type: string
          description: Attributes/tags to assign to the alert (key=value).
          type: object
        dataPointID:
          description: The datapoint whose values are to check.
          type: string
        delay:
          description: 'Optional debounce. The membership condition must hold continuously for this duration

            (e.g. ''5m'') before the alarm fires; if the value leaves the set sooner, nothing is sent.

            Omit for the default (fire as soon as the value enters the set).

            '
          example: 5m
          pattern: ^\d+[wdhms]{1}$
          type: string
        description:
          description: Free text description of the alert.
          type: string
        disabled:
          default: false
          description: 'Create the alert in a paused (disabled) state: its task is created disabled and does not

            fire until the alert is enabled via the enable endpoint. Defaults to false (created enabled).

            '
          type: boolean
        level:
          default: crit
          description: The severity the alert fires at while the value matches.
          enum:
          - info
          - warn
          - crit
          type: string
        name:
          description: The name of the alert.
          type: string
        negate:
          default: false
          description: 'Fire while the value is NOT one of ''values'' instead of while it is.

            Defaults to false.

            '
          type: boolean
        notification:
          $ref: '#/components/schemas/AlertNotification'
        repeat:
          default: 1h
          description: 'Minimum interval after which an unchanged alert is re-notified (in addition to

            notifying on every level change). Use a duration like ''2h'' to re-notify periodically;

            ''0s'' or the keyword ''never'' disables re-notification (notify only on level changes).

            '
          example: 2d
          pattern: ^(\d+[wdhms]|never)$
          type: string
        timezone:
          description: 'Optional IANA timezone (e.g. ''Europe/Berlin'') used to render alert timestamps in

            notifications. Defaults to the project''s building timezone on create; falls back to ''UTC''

            when the building timezone is unresolved.

            '
          example: Europe/Berlin
          type: string
        values:
          description: The discrete values to alert on, e.g. the fault codes [2, 5, 7].
          items:
            type: number
          maxItems: 50
          minItems: 1
          type: array
          uniqueItems: true
      required:
      - name
      - dataPointID
      - values
    DashboardNotificationPoint:
      additionalProperties: false
      properties:
        enabled:
          type: boolean
      type: object
    UpdateAlert:
      additionalProperties: false
      description: 'Partial update for an existing alert. Only the provided fields are changed; omitted fields

        keep their current values. The monitored datapoint (dataPointID), the alert type, and the threshold

        order (ascending/descending) cannot be changed via PATCH — delete and recreate the alert for those.

        A throughput alert''s measurement period (period) can be changed in place. Very old alerts that predate the current

        alert templates (2023) cannot be updated via PATCH at all and must be deleted and recreated.

        Enabling/disabling is done via the ded

# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/aedifion/refs/heads/main/openapi/aedifion-alert-api-openapi.yml