Matching results

Alert


With AirVantage Alert features, you can monitor all your systems by defining rules.

These rules are made up of conditions which check attributes of your systems.

A condition is built with an operator and a list of operands. Details can be found here.

Attributes are information related to your systems:

  • system attributes like the name, the communication status, the gateway serial number, etc.
  • system data coming from the device communications,
  • and usage data coming from the operator.
The complete list of attributes are available here

When all the conditions of a rule are met for a specific system:

  • If the rule is stateless, an alert is generated. It is accessible from the Find history API.
  • If the rule is stateful and the state changed, an alert state is created/updated. It gives you the current state (true or false) of a system against a rule. It is accessible from Find current API. You can also access the state history with Find history API.


A rule defines the conditions under which a target becomes in alert or not.

This is a complete representation of an AlertRule.

{
    "targetType": "",
    "name": "",
    "message": "",
    "stateful": "",
    "active": ,
    "emails": [""],
    "notifMode": "",
    "conditions": [{
        "operator": "",
        "operands": [{
            "attributeId": {
                "targetId": ""
                "name": ""
            }, 
            "function": "", 
            "functionParam": "", 
            "valueStr": "",  
            "valueNum": ,
            "valuesStr": [""]
        }]
    }]
}

Field Description Type
targetType The type of target for which the rule applies: SYSTEM | COMPANY string
name The name of the rule string
message The message used in the Alert event in case of alert. string
stateful Indicates if the rule is stateful (ie. generates and maintains states) or not (ie. only generates events): true | false. Default value to true. boolean
active Indicates if the rule is enabled or not: true | false boolean
emails The list of emails to send notifications to. string array
notifMode
  • EVERY_TIME: every time an alert is generated.
  • WHEN_STATE_CHANGES: default, only when the state of an AlertState changes.
  • WHEN_STATE_TRUE: only when the state of an AlertState changes from false to true.
  • WHEN_STATE_FALSE: only when the state of an AlertState changes from true to false.
  • IN_ALL_CASES: either when an alert is generated or when the state changes.
string
conditions The list of conditions to be checked. array of conditions
conditions.operator The operator. string
conditions.operands Functions of the chosen operator, you have to define one or more operands. array of operands
conditions.operands.attributeId An attributeId is composed of a targetId and an attribute name. attributeId
conditions.operands.attributeId.targetId The id of the target: systemId, companyId or null to consider the current target (the one responsible for the rule evaluation) string
conditions.operands.attributeId.name The name of the attribute to consider string
conditions.operands.function The aggregation function to use in case of an aggregated attributeId (for instance AGG.room.temp/D)
  • MIN
  • MAX
  • MEAN
  • SUM
  • CNT
string
conditions.operands.valueStr A string value to compare with the attribute value functions of the selected operator. string
conditions.operands.valueNum A numeric value to compare with the attribute value functions of the selected operator. number
conditions.operands.valuesStr An array of strings to compare with the attribute value functions of the selected operator. array of strings

Here is a picture explaining how the notification mode works.


An attributeId is made up of a name and an optional targetId. If targetId is set, the condition only apply on the corresponding target, if not, the conditions applies on all targets of the company.

"attributeId": {
    "targetId": "",
    "name": ""
}

Here is the list of all attribute names available when creating alert rules. Some names are dynamic and use the following parameters:

  • {dataId}: the id of the data sent by the system or a data generated by the platform.
  • {timeScale}: for aggregated data, H (hourly), D (daily), M (monthly)

System attributes:

  • system.id
  • system.name
  • system.labels
  • system.state
  • system.activityState
  • system.lifeCycleState
  • system.commStatus
  • system.commStatus.changeDate
  • system.lastCommDate
  • system.heartbeat.state
  • system.heartbeat.period
  • system.heartbeat.errorSLA
  • system.heartbeat.warningSLA
  • system.offerId
  • system.defaultStatusReportState
  • system.defaultStatusReportPeriod
  • gateway.id
  • gateway.imei
  • gateway.mac.address
  • gateway.serial.number
  • subscription.id

System communication:

  • system.comm.protocol
  • DATA.{dataId}: raw data, for instance DATA.room.temp
  • DATA._LON_LAT: the GPS position of the system, used by geofencing operators
  • AGG.{dataId}/{timeScale}: aggregated data, for instance AGG.data.room.temp/D

Usage data:

  • system.usage.status
  • system.usage.record.voice.in.phone.number
  • system.usage.record.voice.out.phone.number
  • system.usage.record.sms.sent.phone.number
  • system.usage.record.sms.received.phone.number
  • system.usage.record.visited.country
  • system.usage.record.imei
  • AGG.DATA_SESSION/{timeScale}
  • AGG.DATA_DURATION/{timeScale}
  • AGG.DATA_BYTES_SENT/{timeScale}
  • AGG.DATA_BYTES_RECEIVED/{timeScale}
  • AGG.DATA_BYTES_TOTAL/{timeScale}
  • AGG.DATA_ROUNDED_BYTES_TOTAL/{timeScale}
  • AGG.VOICE_* attributes, only available for monthly timescale because voice usages are received from carriers few days after consumption.
    • AGG.VOICE_IN_SESSION/M
    • AGG.VOICE_IN_DURATION/M
    • AGG.VOICE_IN_ROUNDED_DURATION/M
    • AGG.VOICE_OUT_SESSION/M
    • AGG.VOICE_OUT_DURATION/M
    • AGG.VOICE_OUT_ROUNDED_DURATION/M
  • AGG.SMS_SENT/{timeScale}
  • AGG.SMS_RECEIVED/{timeScale}
  • AGG.MSU/{timeScale}

A condition is built with an operator and a list of operands. The first operand of all operators has to define the attribute to check on systems. Details about attributes can be found here

For each operand, one of the following field must be used.

{
    "attributeId": {}, 
    "valueStr": "",  
    "valueNum": ,
    "valuesStr": [""]
}

Geofencing operators use Well-Known-Text format to define shapes (POLYGON or POINT).

Here is the list of all operators with the operand fields available.

Name 1st operand 2nd operand 3rd operand
CHANGE attributeId
EQUALS attributeId attributeId/valueStr/valueNum
NOT_EQUALS attributeId attributeId/valueStr/valueNum
GREATER_THAN attributeId attributeId/valueNum
LESS_THAN attributeId attributeId/valueNum
EXISTS attributeId
NOT_EXISTS attributeId
IN attributeId attributeId/valuesStr
NOT_IN attributeId attributeId/valuesStr
CONTAINS attributeId attributeId/valueStr
NOT_CONTAINS attributeId attributeId/valueStr
STARTS_WITH attributeId attributeId/valueStr
ENDS_WITH attributeId attributeId/valueStr
GEO_WITHIN attributeId(name=DATA._LON_LAT) valueStr: a POLYGON described with WKT format
GEO_NOT_WITHIN attributeId(name=DATA._LON_LAT) valueStr: a POLYGON described with WKT format
GEO_DISTANCE_TOO_FAR attributeId(name=DATA._LON_LAT) attributeId(name=DATA._LON_LAT) or a valueStr containing a POINT in WKT format valueNum corresponding to the distance in km
GEO_DISTANCE_TOO_CLOSE attributeId(name=DATA._LON_LAT) attributeId(name=DATA._LON_LAT) or a valueStr containing a POINT in WKT format valueNum corresponding to the distance in km

An alert gathers all the information required to understand what happened on a target for a specific rule.

This is a complete representation of an Alert

{
    "companyId": "",
    "targetId": "", 
    "targetType": "",
    "ruleId": "" 
    "state": ,
    "stateChangeTs": ,
    "attributes": [{
        "id": {
            "name": "" // the name of the attribute
        },
        "value": { // the value of the attribute
            "valueStr": "",
            "valuesStr": "",
            "valueNum": ,
            "valueAgg": {
                "min": ,
                "max": ,
                "cnt": ,
                "sum": ,
                "mean": 
            }
        },
        "refTime": 
    }]
}

Field Description Type
companyId The id of the company the target belongs to string
targetId The id of the target string
targetType The type of the target: SYSTEM | COMPANY string
ruleId The id of the rule string
state True/False to indicate if the specified target is in alert for the specified sateful rule, or null if the rule is stateless boolean
stateChangeTs The timestamp when the state changes timestamp
attributes The list of attributes that brought to the current alert state list of Attribute

/api/v2/alertrules

Creates a new alert rule

Request

POST https://na.airvantage.net/api/v2/alertrules?company=74e52f0379ec3b4e75f91b4750824c22
Content-Type: application/json
...
{
    "targetType": "SYSTEM",
    "name": "Daily usage exceeded",
    "message": "Daily usage exceeded",
    "active": true,
    "emails": ["machin@truc.com"],
    "conditions": [{
        "operator": "GREATER_THAN",
        "operands": [
            {
                "attributeId": 
                {
                    "name": "AGG._DATA_BYTES_TOTAL_DELTA/D"
                }, 
                "function": "SUM"
            }, 
            {
                "valueNum": 1024
            }
        ]
    }]
}

Response
200 OK

HTTP/1.1 200 OK
Content-Type: application/json
...
{
    "id": "0f3919fd1ac0403ab9e70ae2c3729a21",
    "targetType": "SYSTEM",
    "name": "Daily usage exceeded",
    "message": "Daily usage exceeded",
    "active": true,
    "emails": ["machin@truc.com"],
    "conditions": [{
        "operator": "GREATER_THAN",
        "operands": [
            {
                "attributeId": 
                {
                    "name": "AGG._DATA_BYTES_TOTAL_DELTA/D"
                }, 
                "function": "SUM"
            }, 
            {
                "valueNum": 1024
            }
        ]
    }]
}
Name Description Use Default Type
company Set the context company. optional caller's company uid
Name Description
alert.rule.missing.operator A condition must have an operator
alert.rule.multiple.operand.type An operand can only be one of attributeId/valueStr/valueNum/valuesStr
alert.rule.invalid.number.of.operands Wrong number of operands for the chosen operator
alert.rule.invalid.operand.type An operand is not using the proper value for the chosen operator
alert.rule.geo.invalid.wkt The given WKT is not valid
alert.rule.geo.bad.attribute.id The geofencing rule is not using the right attributeId (DATA._LON_LAT)
alert.rule.invalid.function The given function is not available
alert.rule.missing.attr.operand First operand must be an attributeId
alert.rule.too.many The number of rules per company is greater than 50
alert.rule.condition.too.many The number of conditions per rule is greather than 10
alert.rule.incorrect.target.type The target type is missing or invalid
alert.rule.bad.voice.agg.usage AGG.VOICE_* attributes can only be used with monthly timescale
HTTP Method POST
Requires Authentication Yes
Rate Limited Yes
Headers None
Permissions entities.alerts.rule.create.edit.delete

/api/v2/alertrules

Retrieves all rules of your company sorted by name.

Request

GET https://na.airvantage.net/api/v2/alertrules?company=74e52f0379ec3b4e75f91b4750824c22

Response
200 OK

HTTP/1.1 200 OK
Content-Type: application/json
...
[
    {
        "id": "0f3919fd1ac0403ab9e70ae2c3729a21",
        "targetType": "SYSTEM",
        "name": "Daily usage exceeded",
        "message": "Daily usage exceeded",
        "active": true,
        "emails": ["machin@truc.com"],
        "conditions": [{
            "operator": "GREATER_THAN",
            "operands": [
                {
                    "attributeId": 
                    {
                        "name": "AGG._DATA_BYTES_TOTAL_DELTA/D"
                    }, 
                    "function": "SUM"
                }, 
                {
                    "valueNum": 1024
                }
            ]
        }]
    },
    ...
]
Name Description Use Default Type
company Set the context company. optional caller's company uid
HTTP Method GET
Requires Authentication Yes
Rate Limited Yes
Headers None
Permissions entities.alerts.rule.view

/api/v2/alertrules/{uid}

Returns detailed information about the specified rule.

Request

GET https://na.airvantage.net/api/v2/alertrules/0f3919fd1ac0403ab9e70ae2c3729a21?company=74e52f0379ec3b4e75f91b4750824c22

Response
200 OK

HTTP/1.1 200 OK
Content-Type: application/json
...
{
    "id": "0f3919fd1ac0403ab9e70ae2c3729a21",
    "targetType": "SYSTEM",
    "name": "Daily usage exceeded",
    "message": "Daily usage exceeded",
    "active": true,
    "emails": ["machin@truc.com"],
    "conditions": [{
        "operator": "GREATER_THAN",
        "operands": [
            {
                "attributeId": 
                {
                    "name": "AGG._DATA_BYTES_TOTAL_DELTA/D"
                }, 
                "function": "SUM"
            }, 
            {
                "valueNum": 1024
            }
        ]
    }]
}
Name Description Use Default Type
company Set the context company. optional caller's company uid
HTTP Method GET
Requires Authentication Yes
Rate Limited Yes
Headers None
Permissions entities.alerts.rule.view

/api/v2/alertrules/{uid}

Updates the specified alert rule. All alert rule fields are exepected in the body, not only the ones you want to modify.

Request

PUT https://na.airvantage.net/api/v2/alertrules/0f3919fd1ac0403ab9e70ae2c3729a21?company=74e52f0379ec3b4e75f91b4750824c22
Content-Type: application/json
...
{
    "targetType": "SYSTEM",
    "name": "Temperature exceeded",
    "message": "Temperature exceeded",
    "active": true,
    "emails": ["machin@truc.com"],
    "conditions": [{
        "operator": "GREATER_THAN",
        "operands": [
            {
                "attributeId": 
                {
                    "name": "DATA.room.temp"
                }
            }, 
            {
                "valueNum": 38
            }
        ]
    }]
}

Response
200 OK

HTTP/1.1 200 OK
Content-Type: application/json
...
{
    "id": "0f3919fd1ac0403ab9e70ae2c3729a21",
    "targetType": "SYSTEM",
    "name": "Temperature exceeded",
    "message": "Temperature exceeded",
    "active": true,
    "emails": ["machin@truc.com"],
    "conditions": [{
        "operator": "GREATER_THAN",
        "operands": [
            {
                "attributeId": 
                {
                    "name": "DATA.room.temp"
                }
            }, 
            {
                "valueNum": 38
            }
        ]
    }]
}
Name Description Use Default Type
company Set the context company. optional caller's company uid
Name Description
alert.rule.missing.id A rule id must be specified.
alert.rule.unknown.id The specified rule is unknown.
alert.rule.missing.operator A condition must have an operator
alert.rule.multiple.operand.type An operand can only be one of attributeId/valueStr/valueNum/valuesStr
alert.rule.invalid.number.of.operands Wrong number of operands for the chosen operator
alert.rule.invalid.operand.type An operand is not using the proper value for the chosen operator
alert.rule.geo.invalid.wkt The given WKT is not valid
alert.rule.geo.bad.attribute.id The geofencing rule is not using the right attributeId (DATA._LON_LAT)
alert.rule.invalid.function The given function is not available
alert.rule.missing.attr.operand First operand must be an attributeId
alert.rule.too.many The number of rules per company is greater than 50
alert.rule.condition.too.many The number of conditions per rule is greather than 10
alert.rule.incorrect.target.type The target type is missing or invalid
alert.rule.bad.voice.agg.usage AGG.VOICE_* attributes can only be used with monthly timescale
HTTP Method PUT
Requires Authentication Yes
Rate Limited Yes
Headers None
Permissions entities.alerts.rule.create.edit.delete

/api/v2/alertrules/{uid}

Deletes the specified alert rule

Request

DELETE https://na.airvantage.net/api/v2/alertrules/0f3919fd1ac0403ab9e70ae2c3729a21?company=74e52f0379ec3b4e75f91b4750824c22

Response
200 OK

HTTP/1.1 200 OK
Content-Type: application/json
"success"
Name Description Use Default Type
company Set the context company. optional caller's company uid
Name Description
alert.rule.missing.id A rule id must be specified.
alert.rule.unknown.id The specified rule is unknown.
HTTP Method DELETE
Requires Authentication Yes
Rate Limited Yes
Headers None
Permissions entities.alerts.rule.create.edit.delete

/api/v3/alerts/current

Finds current alerts

Returns a paginated list of alerts sorted by 'stateChangeTs' field.

It is possible to filter out the result list using criteria parameters. Note that all combinations of criteria are not possible. Here are all the possible combinations:

  • by target: GET /api/v3/alerts/current?company= &targetId= &offset= &size=
  • by target and rule: GET /api/v3/alerts/current?company= &targetId= &ruleId= &offset= &size=
  • by state: GET /api/v3/alerts/current?company= &state= &offset= &size=
  • by state and targetType: GET /api/v3/alerts/current?company= &state= &targetType= &offset= &size=
  • by state, targetType and rule: GET /api/v3/alerts/current?company= &state= &targetType= &ruleId= &offset= &size=

More information about paging here

Request

GET https://na.airvantage.net/api/v3/alerts/current?targetId=91b74e52f04750824c22379ec3b4e75f&offset=0&size=100&company=74e52f0379ec3b4e75f91b4750824c22

Response
200 OK

HTTP/1.1 200 OK
Content-Type: application/json
...
{
    "items": [{
        "companyId": "74e52f0379ec3b4e75f91b4750824c22",
        "targetId": "91b74e52f04750824c22379ec3b4e75f", 
        "targetType": "SYSTEM",
        "ruleId": "e52237824c29ecf003b4e7745f91b475" 
        "state": true,
        "stateChangeTs": 1469446036000,
        "attributes": [{
            "id": {
                "name": "DATA.room.temp"
            },
            "value": {
                "valueNum": 45
            },
            "refTime": 1466859976000
        }]
    }],
   "count": 1
}
Name Description Use Default Type
targetId Search alert states by target id. optional null string
ruleId Search alert states by rule id. Must be used together with targetId or targetType filter. optional null string
state Search alert states by state. optional null boolean
targetType Search alert states by target type. Must be used together with state filter. optional null string
company Set the context company. optional caller's company string
HTTP Method GET
Requires Authentication Yes
Rate Limited Yes
Headers None
Permissions entities.alerts.view

/api/v3/alerts/history

Finds stateful and stateless alerts between two dates.

Returns a maxium of 500 alerts sorted by 'ts' field.

Request

GET https://na.airvantage.net/api/v3/alerts/history?targetId=91b74e52f04750824c22379ec3b4e75f&to=1469451977000&company=74e52f0379ec3b4e75f91b4750824c22

Response
200 OK

HTTP/1.1 200 OK
Content-Type: application/json
...
{
    "items": [{
        "companyId": "74e52f0379ec3b4e75f91b4750824c22",
        "targetId": "91b74e52f04750824c22379ec3b4e75f",
        "targetType": "SYSTEM",
        "ts": 1466859977000,
        "ruleId": "0f3919fd1ac0403ab9e70ae2c3729a21",
        "state": null, // null because the rule is stateless
        "attributes": [{
            "id": {
                "name": "DATA.room.door.opened"
            },
            "value": {
                "valueStr": "true"
            },
            "refTime": 1466859976000
        }]
    },{
        "companyId": "74e52f0379ec3b4e75f91b4750824c22",
        "targetId": "91b74e52f04750824c22379ec3b4e75f",
        "targetType": "SYSTEM",
        "ts": 1466859967000,
        "ruleId": "04e70a0fb9ace2c3729a3919fd103a21",
        "state": true, // not null because the rule is stateful (can be true or false)
        "attributes": [{
            "id": {
                "name": "DATA.room.temp"
            },
            "value": {
                "valueNum": 45
            },
            "refTime": 1466859966000
        }]
    }
    ]
}
                
Name Description Use Default Type
targetId Search alerts for the specified target id. optional string
ruleIds Search alerts for the specified rule ids. optional string (ruleId separated by ",")
from/to Search alerts whose timestamp is between 'from' and 'to'.
  • if asc is true: ----from-[--------to-[----->
  • if asc is false: ----from-]--------to-]----->
optional to: now, from: now - 90 days timestamp
asc If true, sort alert by ts in ascending order, otherwise in descending order. optional false boolean
size Page size optional 100 number
company Set the context company. mandatory string
Name Description
missing.company 'company' parameter is mandatory.
system.invalid.timerange 'from' paramter needs to be lower than 'to' parameter.
HTTP Method GET
Requires Authentication Yes
Rate Limited Yes
Headers None
Permissions entities.alerts.view

/api/v2/alertstates

Finds current alert states

Returns a paginated list of alert states sorted by 'state_change_ts' field.

It is possible to filter out the result list using criteria parameters. Note that all combinations of criteria are not possible. Here are all the possible combinations:

  • by target: GET /api/v2/alertstates?company= &targetId= &offset= &size=
  • by target and rule: GET /api/v2/alertstates?company= &targetId= &ruleId= &offset= &size=
  • by state: GET /api/v2/alertstates?company= &state= &offset= &size=
  • by state and targetType: GET /api/v2/alertstates?company= &state= &targetType= &offset= &size=
  • by state, targetType and rule: GET /api/v2/alertstates?company= &state= &targetType= &ruleId= &offset= &size=

More information about paging here

Request

GET https://na.airvantage.net/api/v2/alertstates?targetId=91b74e52f04750824c22379ec3b4e75f&offset=0&size=100&company=74e52f0379ec3b4e75f91b4750824c22

Response
200 OK

HTTP/1.1 200 OK
Content-Type: application/json
...
{
    "items": [{
        "companyId": "74e52f0379ec3b4e75f91b4750824c22",
        "targetId": "91b74e52f04750824c22379ec3b4e75f", 
        "targetType": "SYSTEM",
        "ruleId": "e52237824c29ecf003b4e7745f91b475" 
        "state": true,
        "stateChangeTs": 1469446036000,
        "firstAlertId": "eecf003b4e7752237824c2945f91b475",
        "lastAlertId": "e24c2945fecf003b4e791b4775223785"
    }],
   "count": 1
}
Name Description Use Default Type
targetId Search alert states by target id. optional null string
ruleId Search alert states by rule id. Must be used together with targetId or targetType filter. optional null string
state Search alert states by state. optional null boolean
targetType Search alert states by target type. Must be used together with state filter. optional null string
company Set the context company. optional caller's company string
HTTP Method GET
Requires Authentication Yes
Rate Limited Yes
Headers None
Permissions entities.alerts.view

/api/v2/alertstates/history

Finds alert states history.

Returns a maximum of 500 alert states sorted by 'ts' field desc.

Request

GET https://na.airvantage.net/api/v2/alertstates/history?targetId=91b74e52f04750824c22379ec3b4e75f&ruleIds=e52237824c29ecf003b4e7745f91b475,0f3919fd1ac0403ab9e70ae2c3729a21&from=1495963827000&to=1496223027000&company=74e52f0379ec3b4e75f91b4750824c22

Response
200 OK

HTTP/1.1 200 OK
Content-Type: application/json
...
{
    "items": [{
        "id": "e52237991b748ec75024c2f043b4e75f"
        "companyId": "74e52f0379ec3b4e75f91b4750824c22",
        "targetId": "91b74e52f04750824c22379ec3b4e75f", 
        "targetType": "SYSTEM",
        "ruleId": "0f3919fd1ac0403ab9e70ae2c3729a21" 
        "state": false,
        "ts": 1496136627000,
        "firstAlertId": "4ef752237824c2003b945f91b7eec475"
    },{
        "id": "9ece74e52f037750824c223b475f91b4"
        "companyId": "74e52f0379ec3b4e75f91b4750824c22",
        "targetId": "91b74e52f04750824c22379ec3b4e75f", 
        "targetType": "SYSTEM",
        "ruleId": "e52237824c29ecf003b4e7745f91b475" 
        "state": true,
        "ts": 1496050227000,
        "firstAlertId": "eecf003b4e7752237824c2945f91b475"
    }]
}
Name Description Use Default Type
targetId Search alert states by target id. optional null string
ruleIds Search alert states by rule ids. optional null string (ruleIds separated by ",")
from/to Search alert states whose timestamp is between 'from' and 'to'.
  • if asc is true: ----from-[--------to-[----->
  • if asc is false: ----from-]--------to-]----->
optional to: now, from: now - 90 days timestamp
asc If true, sort alert states by ts in ascending order, otherwise in descending order. optional false boolean
size Page size. optional 100 number
company Set the context company. mandatory string
Name Description
missing.company 'company' parameter is mandatory.
system.invalid.timerange 'from' paramter needs to be lower than 'to' parameter.
HTTP Method GET
Requires Authentication Yes
Rate Limited Yes
Headers None
Permissions entities.alerts.view

/api/v2/alerts/history

Finds alerts for a given target between two dates.

Returns a maxium of 500 alerts sorted by 'ts' field.

Request

GET https://na.airvantage.net/api/v2/alerts/history?targetId=91b74e52f04750824c22379ec3b4e75f&to=1469451977000&company=74e52f0379ec3b4e75f91b4750824c22

Response
200 OK

HTTP/1.1 200 OK
Content-Type: application/json
...
{
    "items": [{
        "id": "89e59ec3b4e2f037075f91b4752",
        "companyId": "74e52f0379ec3b4e75f91b4750824c22",
        "targetId": "91b74e52f04750824c22379ec3b4e75f",
        "targetType": "SYSTEM",
        "ts": 1466859977000,
        "ruleId": "0f3919fd1ac0403ab9e70ae2c3729a21",
        "attributes": [{
            "id": {
                "targetId": "91b74e52f04750824c22379ec3b4e75f",
                "name": "DATA.room.temp"
            },
            "value": {
                "valueNum": 45
            },
            "refTime": 1466859976000
        }]
    }]
}
                
Name Description Use Default Type
targetId Search alerts for the specified target id. optional string
ruleIds Search alerts for the specified rule ids. optional string (ruleId separated by ",")
from/to Search alerts whose timestamp is between 'from' and 'to'.
  • if asc is true: ----from-[--------to-[----->
  • if asc is false: ----from-]--------to-]----->
optional to: now, from: now - 90 days timestamp
asc If true, sort alert states by ts in ascending order, otherwise in descending order. optional false boolean
size Page size optional 100 number
company Set the context company. mandatory string
Name Description
missing.company 'company' parameter is mandatory.
system.invalid.timerange 'from' paramter needs to be lower than 'to' parameter.
HTTP Method GET
Requires Authentication Yes
Rate Limited Yes
Headers None
Permissions entities.alerts.view

/api/v2/alerts/{uid}

This API doesn't give more details than the Find alerts history API. It is deprecated, please consider using "Find alerts history" instead.

Request

GET https://na.airvantage.net/api/v2/alerts/89e59ec3b4e2f037075f91b4752?company=74e52f0379ec3b4e75f91b4750824c22

Response
200 OK

HTTP/1.1 200 OK
Content-Type: application/json
...
[   
    {
        "id": "89e59ec3b4e2f037075f91b4752",
        "companyId": "74e52f0379ec3b4e75f91b4750824c22",
        "targetId": "91b74e52f04750824c22379ec3b4e75f",
        "targetType": "SYSTEM",
        "ts": 1466859977000,
        "ruleId": "0f3919fd1ac0403ab9e70ae2c3729a21",
        "attributes": [{
            "id": {
                "targetId": "91b74e52f04750824c22379ec3b4e75f",
                "name": "DATA.room.temp"
            },
            "value": {
                "valueNum": 45
            },
            "refTime": 1466859976000
        }]
    }
]
            
Name Description Use Default Type
company Set the context company. mandatory string
HTTP Method GET
Requires Authentication Yes
Rate Limited Yes
Headers None
Permissions entities.alerts.view

/api/v1/alerts/rules/{uid}/hooks

Configures notification hooks when the alert rule is triggered.
When a rule get trigged, a callback is invoked with the content described in Subscriber API tab below

Request

POST https://na.airvantage.net/api/v1/alerts/rules/edcda0dce0fb47948d03fbec5350c18e/hooks
Content-Type: application/json
...
{
    "callback" :  "http://www.mysite.com/callback"
}
        

Response
200 OK

{
"uid" : "48d03fbec5350c18eedcda0dce0fb479"
"callback" :  "http://www.mysite.com/callback"
}
Field Description Use Default Type
callback The url that will be called when the alert rule get triggerd. The url has the following pattern : http(s)://(user:password@)www.yourhost.com/your_rest_service mandatory - string
The callback endpoint will be requested with a POST method. Its content body is like the content below (JSON format):

Request

POST http://www.yoursite.com/your_callback
Content-Type: application/json
...
{
    "name":"event.alert.rule.triggered",
    "date":1385718100163,
    "content": {
        "alert.uid":"f04a77e306de463e919ec39c387fa016",
        "rule.uid":"7316ee643b17473381b61b8ac0afa824",
        "target.uid":"da687e2c39d54bc391633fa9c8d4c0da"
    }
}
                                    

Response

The response will not be parsed interpreted. If the http status is different from 2xx or 3xx, or if the callback takes more that 10 seconds to answer, the endpoint might be disactivated.
Name Description
alert.rule.unknown The specified uid does not match with any alert rule.
notification.endpoint.missing.uri The callback url was missing.
notification.endpoint.invalid.uri The callback url format isn't well formed or invalid.
notification.endpoint.unsupported.protocol Only HTTP protocols are supported.
HTTP Method POST
Requires Authentication Yes
Rate Limited Yes
Headers Content-type: application/json
Permissions entities.alerts.rule.subscribe

/api/v1/alerts/rules/{uid}/hooks

Gets the list of all notification hooks configured for a specific alert rule.

Request

GET https://na.airvantage.net/api/v1/alerts/rules/edcda0dce0fb47948d03fbec5350c18e/hooks
    

Response
200 OK

HTTP/1.1 200 OK
[
{
    "callback" : "http://www.mysite.com/callback",
    "uid" : "b88c03b43db74cacaab266e5c4481559"
},
{
    "callback" : "http://www.myothersite.com/callback",
    "uid" : "68c2bf58c6ee4484a92927c7afa9aaf5"
},
...
]
                                
Name Description
alert.rule.unknown The specified uid does not match with any alert rule.
HTTP Method GET
Requires Authentication Yes
Rate Limited Yes
Headers Content-type: application/json
Permissions entities.alerts.rule.subscribe

/api/v1/alerts/rules/{uid}/hooks/{uid}

Removes a specific notification hook for an operation.

Request

DELETE https://na.airvantage.net/api/v1/alerts/rules/edcda0dce0fb47948d03fbec5350c18e/hooks/4693044f8abc4b078d9fd65a9a3e45d9
        

Response
200 OK

HTTP/1.1 200 OK
Content-Length: 0
Name Description
alert.rule.unknown The specified uid does not match with any alert rule.
HTTP Method DELETE
Requires Authentication Yes
Rate Limited Yes
Headers Content-type: application/json
Permissions entities.alerts.rule.subscribe
TOP