Cloud Studio IoT Alerts API

openapi: 3.2.0
info:
  title: Cloud Studio IoT Data Extraction Alerts API
  version: '2'
  summary: Read alerts, alarms, endpoint data, geozones and the instance map from a Cloud Studio IoT instance.
  description: 'HTTP API to extract data from the Cloud Studio IoT platform (Gear Studio):

    alert definitions, the alarm history, endpoint (sensor) readings, geozones

    and the client / facility / device / endpoint map of an instance.'
  contact:
    name: Cloud Studio IoT
    url: https://cloudstudioiot.com/contact
    email: info@cloud.studio
  termsOfService: https://cloudstudioiot.com/terms
servers:
- url: https://{host}
  description: A Cloud Studio IoT instance. Dedicated and on-premise instances use their own host.
  variables:
    host:
      default: gear.cloud.studio
security:
- bearerToken: []
- accessTokenQuery: []
tags:
- name: Alerts
  description: Alert definitions (the rules that open alarms).
  externalDocs:
    url: https://cloudstudioiot.com/docs/apis-de-extraccion-de-datos/alertas
paths:
  /api/v2/alerts:
    get:
      operationId: listAlerts
      tags:
      - Alerts
      summary: List alerts
      description: Send one, and only one, of `clientID`, `facilityID`, `deviceID` or `endpointID`.
      parameters:
      - $ref: '#/components/parameters/clientID'
      - $ref: '#/components/parameters/facilityID'
      - $ref: '#/components/parameters/deviceID'
      - $ref: '#/components/parameters/endpointID'
      - $ref: '#/components/parameters/maxCount'
      responses:
        '200':
          description: Matching alerts.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Alert'
        '500':
          $ref: '#/components/responses/ServiceException'
  /api/v2/alerts/incremental/{sequenceNumber}:
    get:
      operationId: listAlertsIncremental
      tags:
      - Alerts
      summary: List alerts changed since a sequence number
      description: 'Returns alerts whose `SequenceNumber` is higher than the one sent,

        deleted ones included (`Enabled: false`). Send one, and only one, of

        `clientID`, `facilityID`, `deviceID` or `endpointID`, and keep the same

        filter between calls.'
      parameters:
      - $ref: '#/components/parameters/sequenceNumber'
      - $ref: '#/components/parameters/clientID'
      - $ref: '#/components/parameters/facilityID'
      - $ref: '#/components/parameters/deviceID'
      - $ref: '#/components/parameters/endpointID'
      - $ref: '#/components/parameters/maxCount'
      responses:
        '200':
          description: Alerts changed since `sequenceNumber`. An empty list means there is nothing new.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Alert'
        '500':
          $ref: '#/components/responses/ServiceException'
  /api/v2/alerts/{alertID}:
    get:
      operationId: getAlert
      tags:
      - Alerts
      summary: Get an alert by ID
      parameters:
      - name: alertID
        in: path
        required: true
        description: Unique identifier of the alert.
        schema:
          type: integer
      responses:
        '200':
          description: The alert.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Alert'
        '500':
          $ref: '#/components/responses/ServiceException'
components:
  schemas:
    ConditionType:
      type: integer
      enum:
      - 1
      - 2
      - 3
      - 4
      - 5
      - 6
      description: 1 equal, 2 not equal, 3 greater, 4 greater or equal, 5 lower, 6 lower or equal.
    Alert:
      type: object
      description: Configuration of an alert.
      properties:
        AlertID:
          type: integer
        VariableTypeID:
          type: integer
          description: 'Variable the alert watches. User-defined variables are 1000 or

            higher. Predefined: 1 temperature, 2 humidity, 3 light level,

            4 setpoint, 5 volume, 6 active energy, 7 run time, 8 discrete

            sensor state, 9 dimmerization, 10 weight, 11 flow, 12 voltage,

            13 current, 14 active power, 15 reactive power, 16 apparent power,

            17 power factor, 18 pressure, 19 frequency, 20 ppm concentration,

            21 mass/volume concentration, 22 AQI, 23 people flow, 24 people

            count, 25 reactive energy, 26 apparent energy, 27 location.

            '
        EndpointID:
          type: integer
        FacilityID:
          type: integer
        ClientID:
          type: integer
        ConditionType:
          $ref: '#/components/schemas/ConditionType'
        Threshold:
          type: number
          format: double
          description: Value compared with `ConditionType` to trigger the alert.
        NormalConditionType:
          $ref: '#/components/schemas/ConditionType'
        NormalThreshold:
          type: number
          format: double
          description: Value compared with `NormalConditionType` to close the alert.
        MinimumDurationSeconds:
          type: integer
          description: Seconds the condition must hold before the alert triggers.
        NotificationEmails:
          type: array
          items:
            type: string
        NotificationSMSNumbers:
          type: array
          items:
            type: string
        NotificationVoiceNumbers:
          type: array
          items:
            type: string
        Tags:
          type: array
          items:
            type: string
        SequenceNumber:
          type: integer
          format: int64
        Enabled:
          type: boolean
          description: False when the alert was deleted. Deleted alerts only appear in the incremental list.
  parameters:
    maxCount:
      name: maxCount
      in: query
      description: Maximum number of items in the result.
      schema:
        type: integer
    endpointID:
      name: endpointID
      in: query
      description: Only items of this endpoint.
      schema:
        type: integer
    clientID:
      name: clientID
      in: query
      description: Only items of this client.
      schema:
        type: integer
    facilityID:
      name: facilityID
      in: query
      description: Only items of this facility.
      schema:
        type: integer
    deviceID:
      name: deviceID
      in: query
      description: Only items of this device.
      schema:
        type: integer
    sequenceNumber:
      name: sequenceNumber
      in: path
      required: true
      description: '`SequenceNumber` of the last item received. Use 0 to start from the beginning.'
      schema:
        type: integer
        format: int64
        minimum: 0
  responses:
    ServiceException:
      description: The request failed. A missing, invalid or expired access token is also reported this way.
      content:
        application/json:
          schema:
            type: object
            properties:
              Exception:
                type: object
                properties:
                  ClassName:
                    type: string
                  FaultCode:
                    type: string
                  FaultData:
                    type: string
                  Message:
                    type: string
          example:
            Exception:
              ClassName: ServiceException
              FaultCode: '8001'
              FaultData: ''
              Message: The access token is invalid or it doesn't have sufficient permissions to execute the requested operation
  securitySchemes:
    bearerToken:
      type: http
      scheme: bearer
      description: 'Persistent access token sent as `Authorization: Bearer {accessToken}`.'
    accessTokenQuery:
      type: apiKey
      in: query
      name: accessToken
      description: The same access token in the query string, for clients that cannot set headers.
externalDocs:
  description: Data Extraction APIs documentation
  url: https://cloudstudioiot.com/docs/apis-de-extraccion-de-datos