Alarming API specification (1.21.7)

Download OpenAPI specification:Download

The alarming service implements the alarming logic and connected items, e.g. labels or units

Authentication

API_Token

To use this API, you need an API-Token from the RBAC settings of your GroupAlarm organization. Place the token inside the HTTP-Header API-Token for every request, otherwise the API will return an "401 Unauthorized" error for your request.

Security scheme type: API Key
header parameter name: API-TOKEN

Personal-Access-Token

To use this API, you need a Personal Access Token from your profile settings. Place the token inside the HTTP-Header Personal-Access-Token for every request, otherwise the API will return an "401 Unauthorized" error for your request.

Security scheme type: API Key
header parameter name: Personal-Access-Token

alarm

CreateAlarm

Creates an alarm for an event and calculate required user for a notification

Request Body schema: application/json
alarmResources
required
object (AlarmCreationResources contains an alarm's alarmed scenarios, units, labels and / or users.)

At least one of those arrays must contain data, otherwise the alarm can not be started.

alarmTemplateID
integer <int64>

Alarm message template ID

eventID
integer <int64>

id of an existing event

eventName
string

Name of an event; if event name is passed, a new event will be created with the passed name

message
required
string

Alarm message

mode
required
string

Alarm mode (strict|best-effort)

optionalContent
object (PropertyMap)

PropertyMap is used as container for additional data in alarms or messages it can be stored and retrieved easily in our Postgres database

organizationID
required
integer <int64>

ID of the organization to create the alarm in

scenarioID
integer <int64>

id of the alarmed scenario

DEPRECATED: this property is deprecated and will be removed soon, please use alarmResources instead

startTime
required
string <date-time>

Start time for this alarm

Responses

201

created alarm payload with passed parameters

400

Passed alarm payload was not in the correct format

403

No payment setup for this organization

500

Unexpected database error

post /alarm
https://app.groupalarm.com/api/v1/alarm

Request samples

application/json
Copy
Expand all Collapse all
{
  • "alarmResources":
    {
    },
  • "alarmTemplateID": 0,
  • "eventID": 0,
  • "eventName": "string",
  • "message": "string",
  • "mode": "string",
  • "optionalContent":
    {
    },
  • "organizationID": 0,
  • "scenarioID": 0,
  • "startTime": "2019-09-20T12:49:29Z"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "alarmResources":
    {
    },
  • "endDate": "2019-09-20T12:49:29Z",
  • "event":
    {
    },
  • "feedback":
    [
    ],
  • "feedbackPercentage":
    {
    },
  • "id": 1,
  • "message": "string",
  • "mode": "string",
  • "optionalContent":
    {
    },
  • "organizationID": 0,
  • "startDate": "2019-09-20T12:49:29Z",
  • "strength":
    {
    },
  • "success": true
}

PreviewAlarm

Returns a preview of a planned alarm using the given resources

Request Body schema: application/json
alarmResources
required
object (AlarmCreationResources contains an alarm's alarmed scenarios, units, labels and / or users.)

At least one of those arrays must contain data, otherwise the alarm can not be started.

alarmTemplateID
integer <int64>

Alarm message template ID

eventID
integer <int64>

id of an existing event

eventName
string

Name of an event; if event name is passed, a new event will be created with the passed name

message
required
string

Alarm message

mode
required
string

Alarm mode (strict|best-effort)

optionalContent
object (PropertyMap)

PropertyMap is used as container for additional data in alarms or messages it can be stored and retrieved easily in our Postgres database

organizationID
required
integer <int64>

ID of the organization to create the alarm in

scenarioID
integer <int64>

id of the alarmed scenario

DEPRECATED: this property is deprecated and will be removed soon, please use alarmResources instead

startTime
required
string <date-time>

Start time for this alarm

Responses

200

preview created

400

invalid creationRequest

500

unexpected error

post /alarm/preview
https://app.groupalarm.com/api/v1/alarm/preview

Request samples

application/json
Copy
Expand all Collapse all
{
  • "alarmResources":
    {
    },
  • "alarmTemplateID": 0,
  • "eventID": 0,
  • "eventName": "string",
  • "message": "string",
  • "mode": "string",
  • "optionalContent":
    {
    },
  • "organizationID": 0,
  • "scenarioID": 0,
  • "startTime": "2019-09-20T12:49:29Z"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "alarmResources":
    {
    },
  • "plan":
    [
    ],
  • "positionsFulfilled": true
}

GetAlarm

Returns an alarm payload for requested alarm id

path Parameters
alarmID
required
int64

Responses

200

Requested alarm payload

400

Passed id is in the wrong format

500

Unexpected database error

get /alarm/{alarmID}
https://app.groupalarm.com/api/v1/alarm/{alarmID}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "alarmResources":
    {
    },
  • "endDate": "2019-09-20T12:49:29Z",
  • "event":
    {
    },
  • "feedback":
    [
    ],
  • "feedbackPercentage":
    {
    },
  • "id": 1,
  • "message": "string",
  • "mode": "string",
  • "optionalContent":
    {
    },
  • "organizationID": 0,
  • "startDate": "2019-09-20T12:49:29Z",
  • "strength":
    {
    },
  • "success": true
}

CloseAlarm

Closes the alarm with the passed alarm id

path Parameters
alarmID
required
int64

Responses

200

Requested alarm was successfully closed

400

Passed id is in the wrong format

500

Unexpected database error

patch /alarm/{alarmID}
https://app.groupalarm.com/api/v1/alarm/{alarmID}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "message": "success"
}

GetAlarms

Returns all alarms

query Parameters
organization
required
int64

id of organization

limit
int64 [ 1 .. 50 ]
Default: 10

limits alarm list output to passed amount.

offset
int64
Default: 0

defines the offset for pagination

event