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: parameters: facilityID: name: facilityID in: query description: Only items of this facility. 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 clientID: name: clientID in: query description: Only items of this client. schema: type: integer endpointID: name: endpointID in: query description: Only items of this endpoint. schema: type: integer deviceID: name: deviceID in: query description: Only items of this device. schema: type: integer maxCount: name: maxCount in: query description: Maximum number of items in the result. schema: type: integer schemas: 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. 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. 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