openapi: 3.1.0
info:
  title: Siemens Building Operations Alarms Trends 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: Trends
  description: Historical trend data for building system data points over specified time ranges.
paths:
  /points/{pointId}/trends:
    get:
      operationId: getPointTrend
      summary: Get Point Historical Trend Data
      description: Returns historical trend data for a building data point over a specified time range. Data is returned as timestamped value pairs.
      tags:
      - Trends
      parameters:
      - $ref: '#/components/parameters/pointId'
      - name: from
        in: query
        required: true
        schema:
          type: string
          format: date-time
        description: Start of time range (ISO 8601)
      - name: to
        in: query
        required: true
        schema:
          type: string
          format: date-time
        description: End of time range (ISO 8601)
      - name: resolution
        in: query
        schema:
          type: string
          enum:
          - raw
          - minute
          - hour
          - day
        description: Data resolution for aggregation
      responses:
        '200':
          description: Historical trend data returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrendData'
        '400':
          description: Invalid time range parameters
        '401':
          description: Unauthorized
        '404':
          description: Point not found
components:
  schemas:
    PointValue:
      type: object
      properties:
        value:
          description: Current value (type depends on point type)
          oneOf:
          - type: number
          - type: boolean
          - type: string
        timestamp:
          type: string
          format: date-time
          description: When this value was recorded
        quality:
          type: string
          enum:
          - good
          - bad
          - uncertain
          description: Data quality indicator
    TrendData:
      type: object
      properties:
        pointId:
          type: string
        from:
          type: string
          format: date-time
        to:
          type: string
          format: date-time
        values:
          type: array
          items:
            $ref: '#/components/schemas/PointValue'
  parameters:
    pointId:
      name: pointId
      in: path
      required: true
      schema:
        type: string
      description: Unique identifier of the building data point
  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