openapi: 3.0.2
info:
  description: |
    Fire API
  version: 0.0.18
  title: Fire API
  contact:
    name: Siemens Regional Contact
  x-logo:
    url: logo.png
    altText: Siemens logo
servers:
  - url: https://api.bpcloud.siemens.com/fire/partitions/{partitionId}
    description: Production Endpoint
    variables:
      partitionId:
        default: REQUIRED
components:
  securitySchemes:
    service_auth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  parameters:
    deviceId:
      name: deviceId
      in: path
      description: Device ID
      required: true
      schema:
        type: string
    locationId:
      name: locationId
      in: path
      description: Location ID
      required: true
      schema:
        type: string
    pageLimit:
      name: page[limit]
      in: query
      description: Maximum number of items to return in a single page
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    pageCursor:
      name: page[cursor]
      in: query
      description: Cursor representing which page to fetch
      required: false
      schema:
        type: string
  schemas:
    CommandPatchRequest:
      type: object
      properties:
        value:
          description: the value is the command to be set for the location
          type: string
          enum:
            - ACKNOWLEDGE
            - RESET
            - SILENCE
            - UNSILENCE
    CommandPatchResponse:
      type: object
      properties:
        commandId:
          type: string
        createdAt:
          type: string
        value:
          type: string
          enum:
            - ACKNOWLEDGE
            - RESET
            - SILENCE
            - UNSILENCE
    DeviceList:
      type: object
      required:
        - links
        - data
      properties:
        links:
          type: object
          required:
            - self
          properties:
            self:
              type: string
              example: /partitions/b2ae267d-1d74-4e2a-bff8-e7c90a3b854a/devices
            next:
              type: string
              example: >-
                /partitions/b2ae267d-1d74-4e2a-bff8-e7c90a3b854a/devices?page[cursor]=qwerty
        data:
          type: array
          items:
            $ref: '#/components/schemas/Device'
    EventList:
      type: object
      required:
        - links
        - data
      properties:
        links:
          type: object
          required:
            - self
          properties:
            self:
              type: string
              example: >-
                /partitions/b2ae267d-1d74-4e2a-bff8-e7c90a3b854a/devices/7026ab05-2d02-47b4-bc26-c033939d5823/events
            next:
              type: string
              example: >-
                /partitions/b2ae267d-1d74-4e2a-bff8-e7c90a3b854a/devices/7026ab05-2d02-47b4-bc26-c033939d5823/events?page[cursor]=qwerty
        data:
          type: array
          items:
            $ref: '#/components/schemas/Event'
    Event:
      type: object
      required:
        - type
        - id
      properties:
        type:
          type: string
          enum:
            - Event
        id:
          type: string
          example: 1bcaafc3-d4d3-43e1-ab64-89d8518d5951
        attributes:
          type: object
          properties:
            eventType:
              type: string
              description: >-
                The cloud event category like ALARM, PREALARM, TROUBLE,
                ISOLATION
              example: ALARM
            panelAddress:
              type: string
              description: panel address
              example: '1'
            message:
              type: string
              description: The event message
              example: The filter is clogged
            address:
              type: string
              description: The addressText from incident containing also child address
              example: 1/2/11
            elementCategoryText:
              type: string
              description: The elementCategoryText from incident
            customerText:
              type: string
              description: The customerText from incident
            parentCustomerText1:
              type: string
              description: The parent customerText level 1 from incident
            parentCustomerText2:
              type: string
              description: The parent customerText level 2 from incident
            parentCustomerText3:
              type: string
              description: The parent customerText level 3 from incident
            timestamp:
              type: string
              description: Time when incident state changed (see state property)
              example: '2023-04-28T12:31:11.329683036Z'
            state:
              type: string
              description: >

                The state of the event. Common values include:


                | Value | Description |

                | ----- | ----- |

                | Active | indicates that the alarm condition is active |

                | ActiveAcknowledged | the active state has been acknowledged |

                | Inactive | the underlying alarm condition is no longer active
                |

                | InactiveAcknowledged | the transition to Inactive was
                acknowledged by the user |

                | Closed | The alarm lifecycle is not considered to be ended.
                The transition to this state may be triggered by an explicit
                action or automatically |
              example: Active
        meta:
          type: object
          required:
            - createdAt
          properties:
            createdAt:
              type: string
              format: date-time
            updatedAt:
              type: string
              format: date-time
    Device:
      type: object
      required:
        - type
        - id
      properties:
        type:
          type: string
          enum:
            - Device
        id:
          type: string
          example: 1bcaafc3-d4d3-43e1-ab64-89d8518d5951
        attributes:
          type: object
          properties:
            modelName:
              type: string
              description: The model name of the device
              example: MSIB CCA
            serialNumber:
              type: string
              description: The serial number of the device
              example: L7955828
            profile:
              type: object
              description: >-
                Cloud attributes of a device are the data assigned by the user
                to a device in the cloud
              properties:
                name:
                  type: string
                  description: Name given to a device by the user
                  example: X300-5
                notes:
                  type: string
                  description: Notes written for a device by the user
                  example: In basement, ask Bruno for key
              required:
                - name
                - notes
        relationships:
          type: object
          properties:
            hasGateway:
              description: Refers to another device that this devices uses as a gateway
              required:
                - data
              properties:
                data:
                  properties:
                    type:
                      enum:
                        - Device
                    id:
                      type: string
                      example: 1bcaafc3-d4d3-43e1-ab64-89d8518d5951
                      pattern: >-
                        ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
                  required:
                    - type
                    - id
            hasLocation:
              description: Refers to the location where this device is located
              required:
                - data
              properties:
                data:
                  properties:
                    type:
                      enum:
                        - Building
                    id:
                      type: string
                      example: 598a0329-2cca-4227-aea5-629862864cdf
                      pattern: >-
                        ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
                  required:
                    - type
                    - id
            hasFeatures:
              required:
                - data
              properties:
                data:
                  items:
                    properties:
                      type:
                        enum:
                          - DeviceInfo
                          - Connectivity
                      id:
                        type: string
                        example: 598a0329-2cca-4227-aea5-629862864cdf
                        pattern: >-
                          ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
                    required:
                      - type
                      - id
    Location:
      oneOf:
        - $ref: '#/components/schemas/Building'
    LocationList:
      type: object
      required:
        - links
        - data
      properties:
        links:
          type: object
          required:
            - self
          properties:
            self:
              type: string
              example: /locations
            next:
              type: string
              example: /locations?page[number]=1
        data:
          type: array
          items:
            $ref: '#/components/schemas/Location'
    Building:
      description: Represents a Building
      type: object
      required:
        - attributes
        - id
        - relationships
        - type
      properties:
        id:
          type: string
          description: UUID of this object
          example: 05085306-9c1d-4cee-b92a-04c07e4b1945
        type:
          type: string
          enum:
            - Building
          description: Type of this object
        attributes:
          type: object
          required:
            - label
            - timeZone
          properties:
            timeZone:
              type: string
              example: Europe/Zurich
            label:
              x-filterable: true
              type: string
              maxLength: 256
              minLength: 1
            description:
              type: string
              maxLength: 3000
              minLength: 1
            geoLocation:
              type: object
              description: Represents an location in space
              required:
                - geometry
              properties:
                geometry:
                  description: Represents an 2D- or 3D-Point in space
                  required:
                    - type
                    - coordinates
                  type: object
                  properties:
                    type:
                      type: string
                      enum:
                        - Point
                    coordinates:
                      type: array
                      minItems: 2
                      maxItems: 3
                      items:
                        type: number
                      example:
                        - 8.48281
                        - 47.19717
              nullable: true
        meta:
          description: Object meta-data
          additionalProperties: false
          properties:
            createdAt:
              type: string
              format: date-time
            updatedAt:
              type: string
              format: date-time
    Error:
      type: object
      description: |
        [More error information](docs/api-errors.html)
      required:
        - errors
      additionalProperties: false
      properties:
        errors:
          type: array
          items:
            type: object
            required:
              - id
              - status
              - title
            properties:
              id:
                type: string
                example: e31f00cc-7a5d-46c2-a272-771e6a8d6ff0
                description: >-
                  A unique identifier for this particular occurrence of the
                  problem.
              code:
                type: string
                description: >-
                  An application-specific error code, expressed as a string
                  value.
                example: 200-0201
              status:
                type: string
                example: '403'
                description: >-
                  The HTTP status code applicable to this problem, expressed as
                  a string value.
              title:
                type: string
                description: >-
                  A short, human-readable summary of the problem that SHOULD NOT
                  change from occurrence to occurrence of the problem, except
                  for purposes of localization.
                example: Forbidden to perform this action
              detail:
                type: string
                description: >-
                  a human-readable explanation specific to this occurrence of
                  the problem. Like title, this field’s value can be localized.
                example: Forbidden to perform this action
paths:
  /devices:
    get:
      x-horizon-permission: api.fire
      tags:
        - Devices
      summary: List Devices
      description: List Devices
      operationId: listDevices
      parameters:
        - $ref: '#/components/parameters/pageCursor'
      responses:
        '200':
          description: OK
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/DeviceList'
              examples:
                Devices:
                  value:
                    links:
                      self: /partitions/b2ae267d-1d74-4e2a-bff8-e7c90a3b854a/devices
                      next: >-
                        /partitions/b2ae267d-1d74-4e2a-bff8-e7c90a3b854a/devices?page[cursor]=qwerty
                    data:
                      - type: Device
                        id: 1bcaafc3-d4d3-43e1-ab64-89d8518d5951
                        attributes:
                          modelName: MSIB CCA
                          serialNumber: L7955828
                          profile:
                            name: X300-5
                            notes: In basement, ask Bruno for key
                        relationships:
                          hasGateway:
                            data:
                              type: Device
                              id: 1bcaafc3-d4d3-43e1-ab64-89d8518d5951
                          hasLocation:
                            data:
                              type: Building
                              id: 598a0329-2cca-4227-aea5-629862864cdf
                          hasFeatures:
                            data:
                              - type: DeviceInfo
                                id: 598a0329-2cca-4227-aea5-629862864cdf
                Panels:
                  value:
                    links:
                      self: /partitions/b2ae267d-1d74-4e2a-bff8-e7c90a3b854a/devices
                      next: >-
                        /partitions/b2ae267d-1d74-4e2a-bff8-e7c90a3b854a/devices?page[cursor]=qwerty
                    data:
                      - type: Device
                        id: 1bcaafc3-d4d3-43e1-ab64-89d8518d5951
                        attributes:
                          modelName: Panel
                          serialNumber: ''
                          profile:
                            name: Magazzini Generali
                            notes: ''
                            externalId: 1
                        relationships:
                          hasLocation:
                            data:
                              type: Building
                              id: 598a0329-2cca-4227-aea5-629862864cdf
        4XX:
          description: Client Error
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Server Error
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Error'
  /devices/{deviceId}/events:
    get:
      x-horizon-permission: api.fire
      tags:
        - Events
      summary: List Events
      description: List Event (including Alerts)
      operationId: listEvents
      parameters:
        - $ref: '#/components/parameters/deviceId'
        - $ref: '#/components/parameters/pageCursor'
        - in: query
          name: filter[timestamp][to]
          required: false
          schema:
            type: string
          description: >-
            Only return items were 'timestamp' is less than to the specificed
            RFC3339 value, i.e. to-time. Default is `now`-time.
        - in: query
          name: filter[timestamp][from]
          required: false
          schema:
            type: string
            description: >-
              Only return items were 'timestamp' is equal to or greater than the
              specificed RFC3339 value, i.e. from-time.
      responses:
        '200':
          description: OK
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/EventList'
        4XX:
          description: Client Error
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Server Error
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Error'
  /locations:
    get:
      x-horizon-permission: api.fire
      tags:
        - Locations(Deprecated)
      summary: List Locations
      operationId: listLocation
      description: List Locations
      responses:
        '200':
          description: OK
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/LocationList'
        4XX:
          description: Client Error
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Server Error
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Error'
      parameters:
        - in: query
          required: true
          description: Filter by 'type'
          name: filter[type]
          schema:
            enum:
              - Building
  /locations/{locationId}/commands:
    get:
      x-horizon-permission: api.fire
      tags:
        - Commands
      summary: List Commands for a given site
      description: List commands
      operationId: listCommands
      parameters:
        - $ref: '#/components/parameters/locationId'
      responses:
        '200':
          description: List commands for a given site
          content:
            application/vnd.api+json:
              schema:
                type: array
                items:
                  type: string
                  enum:
                    - ACKNOWLEDGE
                    - RESET
                    - SILENCE
                    - UNSILENCE
              examples:
                commandResponse:
                  value:
                    - ACKNOWLEDGE
                    - RESET
        4XX:
          description: Client Error
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Server Error
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      x-horizon-permission: api.fire
      tags:
        - Commands
      summary: Command for a given site
      description: Command a given site
      operationId: commandSite
      parameters:
        - $ref: '#/components/parameters/locationId'
      requestBody:
        description: set command value for a given site
        required: true
        content:
          application/vnd.api+json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/CommandPatchRequest'
            examples:
              setDesire:
                summary: Set desire command
                value:
                  value: ACKNOWLEDGE
      responses:
        '202':
          description: Accepted
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/CommandPatchResponse'
              examples:
                setCommandResponse:
                  value:
                    commandId: d8c2a54e-fc12-4878-87a6-2daf8c73f95a
                    createdAt: '2024-11-21T06:12:08.742Z'
                    value: ACKNOWLEDGE
        4XX:
          description: Client Error
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Server Error
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Error'
security:
  - service_auth:
      - ops.read
tags:
  - name: Locations(Deprecated)
    description: Location Information
  - name: Devices
    description: Device Information
  - name: Events
    description: Event Information
