openapi: 3.1.0
info:
  title: Siemens Building Operations Alarms API
  description: The Siemens Building Operations API is part of the Building X openness platform that enables integration with Siemens building automation systems. The API provides access to building operational data including HVAC systems, lighting, energy management, and building equipment monitoring. It enables facility managers and building operations teams to read sensor data, control building systems, receive alerts, and integrate with third-party applications for smart building use cases.
  version: '1.0'
  contact:
    name: Siemens Building X Developer Support
    url: https://developer.siemens.com/building-x-openness/api/building-operations/overview.html
  termsOfService: https://www.siemens.com/global/en/general/legal-notices.html
servers:
- url: https://buildingx.siemens.com/api/v1
  description: Siemens Building X Production API
security:
- BearerAuth: []
tags:
- name: Alarms
  description: Building alarm and alert management for monitoring critical equipment conditions and building system faults.
paths:
  /alarms:
    get:
      operationId: listAlarms
      summary: List Building Alarms
      description: Returns a list of active and historical building alarms. Alarms represent abnormal conditions in building systems requiring attention.
      tags:
      - Alarms
      parameters:
      - name: status
        in: query
        schema:
          type: string
          enum:
          - active
          - acknowledged
          - resolved
        description: Filter alarms by status
      - name: severity
        in: query
        schema:
          type: string
          enum:
          - critical
          - high
          - medium
          - low
        description: Filter alarms by severity level
      - name: from
        in: query
        schema:
          type: string
          format: date-time
        description: Return alarms from this timestamp
      - name: skip
        in: query
        schema:
          type: integer
          default: 0
      - name: top
        in: query
        schema:
          type: integer
          default: 50
      responses:
        '200':
          description: List of alarms returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlarmList'
        '401':
          description: Unauthorized
  /alarms/{alarmId}/acknowledge:
    post:
      operationId: acknowledgeAlarm
      summary: Acknowledge Building Alarm
      description: Acknowledges an active building alarm, indicating that the condition has been noted and is being addressed.
      tags:
      - Alarms
      parameters:
      - $ref: '#/components/parameters/alarmId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcknowledgeAlarmRequest'
      responses:
        '200':
          description: Alarm acknowledged successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alarm'
        '401':
          description: Unauthorized
        '404':
          description: Alarm not found
components:
  schemas:
    AcknowledgeAlarmRequest:
      type: object
      properties:
        comment:
          type: string
          description: Optional comment about the acknowledgment action
    Alarm:
      type: object
      properties:
        id:
          type: string
          description: Unique alarm identifier
        name:
          type: string
          description: Alarm name or description
        severity:
          type: string
          enum:
          - critical
          - high
          - medium
          - low
          description: Alarm severity level
        status:
          type: string
          enum:
          - active
          - acknowledged
          - resolved
          description: Current alarm status
        equipmentId:
          type: string
          description: Equipment associated with this alarm
        pointId:
          type: string
          description: Data point that triggered this alarm
        triggeredAt:
          type: string
          format: date-time
          description: When the alarm condition was first detected
        acknowledgedAt:
          type: string
          format: date-time
          description: When the alarm was acknowledged
        acknowledgedBy:
          type: string
          description: User who acknowledged the alarm
    AlarmList:
      type: object
      properties:
        value:
          type: array
          items:
            $ref: '#/components/schemas/Alarm'
        nextLink:
          type: string
  parameters:
    alarmId:
      name: alarmId
      in: path
      required: true
      schema:
        type: string
      description: Unique identifier of the building alarm
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 Bearer token from Siemens Building X identity service
externalDocs:
  description: Siemens Building Operations API Documentation
  url: https://developer.siemens.com/building-x-openness/api/building-operations/overview.html