Alarming API specification (1.19.0)

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
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

labels
Array of object (AlarmCreationRequestLabel defines an alarm creation label payload) >= 1

list of labels to alarm

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 as

scenarioID
integer <int64> >= 1

id from the scenario

startTime
required
string <date-time>

Start time for this alarm

units
Array of integer <int64> >= 1

list of unitIDs to 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
{
  • "alarmTemplateID": 0,
  • "eventID": 0,
  • "eventName": "string",
  • "labels":
    [
    ],
  • "message": "string",
  • "mode": "string",
  • "optionalContent":
    {
    },
  • "organizationID": 0,
  • "scenarioID": 1,
  • "startTime": "2019-08-14T17:10:27Z",
  • "units":
    [
    ]
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "endDate": "2019-08-14T17:10:27Z",
  • "event":
    {
    },
  • "feedback":
    [
    ],
  • "feedbackPercentage":
    {
    },
  • "id": 1,
  • "message": "string",
  • "mode": "string",
  • "optionalContent":
    {
    },
  • "organizationID": 0,
  • "scenario":
    {
    },
  • "startDate": "2019-08-14T17:10:27Z",
  • "strength":
    {
    },
  • "success": 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
{
  • "endDate": "2019-08-14T17:10:28Z",
  • "event":
    {
    },
  • "feedback":
    [
    ],
  • "feedbackPercentage":
    {
    },
  • "id": 1,
  • "message": "string",
  • "mode": "string",
  • "optionalContent":
    {
    },
  • "organizationID": 0,
  • "scenario":
    {
    },
  • "startDate": "2019-08-14T17:10:28Z",
  • "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"
}

PreviewAlarm

Closes the alarm with the passed alarm id

path Parameters
alarmID
required
int64
scenarioID
required
int64

Responses

200

Requested alarm was successfully closed

400

Passed id is in the wrong format

500

Unexpected database error

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

Response samples

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

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
int64

id of an event, to get all alarms for this event

Responses

200

Alarm list for requested organization

400

Passed query parameters in wrong format

500

Unexpected database error

get /alarms
https://app.groupalarm.com/api/v1/alarms

Response samples

application/json
Copy
Expand all Collapse all
{
  • "alarms":
    [
    ],
  • "strength":
    {
    },
  • "totalAlarms": 0
}

CreateAlarmTemplate

Creates an alarm template with the passed parameters

Request Body schema: application/json
id
integer <int64>
message
string
name
string
organizationID
integer <int64>

Responses

201

Created alarm template with created id

400

Passed query parameters in wrong format

500

Unexpected database error

post /alarms/template
https://app.groupalarm.com/api/v1/alarms/template

Request samples

application/json
Copy
Expand all Collapse all
{
  • "id": 0,
  • "message": "string",
  • "name": "string",
  • "organizationID": 0
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": 0,
  • "message": "string",
  • "name": "string",
  • "organizationID": 0
}

GetAlarmTemplate

Returns a specific alarm template for passed template id

path Parameters
id
required
int64

id of the template

query Parameters
organization_id
required
int64

id of organization

Responses

200

Template list for requested organization

400

Passed query parameters in wrong format

500

Unexpected database error

get /alarms/template/:id
https://app.groupalarm.com/api/v1/alarms/template/:id

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

UpdateAlarmTemplate

Updates an alarm template with the passed parameters

path Parameters
id
required
int64

id of the alarm template

Request Body schema: application/json
id
integer <int64>
message
string
name
string
organizationID
integer <int64>

Responses

200

Update successfully processed

400

Passed query parameters in wrong format

500

Unexpected database error

put /alarms/template/{id}
https://app.groupalarm.com/api/v1/alarms/template/{id}

Request samples

application/json
Copy
Expand all Collapse all
{
  • "id": 0,
  • "message": "string",
  • "name": "string",
  • "organizationID": 0
}

DeleteAlarmTemplate

Updates an alarm template with the passed parameters

path Parameters
id
required
int64

id of the alarm template

Responses

200

Alarm template was successfully deleted

400

Passed query parameters in wrong format

500

Unexpected database error

delete /alarms/template/{id}
https://app.groupalarm.com/api/v1/alarms/template/{id}

GetAlarmTemplates

Returns all alarm templates for passed organization id

query Parameters
organization_id
required
int64

id of organization

Responses

200

Template list for requested organization

400

Passed query parameters in wrong format

500

Unexpected database error

get /alarms/templates
https://app.groupalarm.com/api/v1/alarms/templates

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

GetUsersAlarms

Returns all alarms of the current user

query Parameters
limit
int64 [ 1 .. 50 ]
Default: 10

defines the limit of entries for pagination

offset
int64 >= 0
Default: 0

defines the offset for pagination

Responses

200

list of alarms for current user

400

userID not found

500

unexpected database error

get /alarms/user
https://app.groupalarm.com/api/v1/alarms/user

Response samples

application/json
Copy
Expand all Collapse all
{
  • "alarms":
    [
    ],
  • "strength":
    {
    },
  • "totalAlarms": 0
}

event

CreateEvent

Creates an event with the passed event payload

Request Body schema: application/json
endDate
string <date-time>

time where this event was closed

id
integer <int64>

id for this event

name
required
string

user given name for this event

organizationID
required
integer <int64>

organization assignment by organization ID

scheduledEndtime
string <date-time>

time this event is scheduled for close

startDate
required
string <date-time>

time where this event starts

Responses

201

created event payload

400

Passed payload is in the wrong format

403

No payment setup for this organization

500

Unexpected database error

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

Request samples

application/json
Copy
Expand all Collapse all
{
  • "endDate": "2019-08-14T17:10:28Z",
  • "id": 0,
  • "name": "string",
  • "organizationID": 0,
  • "scheduledEndtime": "2019-08-14T17:10:28Z",
  • "startDate": "2019-08-14T17:10:28Z"
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "endDate": "2019-08-14T17:10:28Z",
  • "id": 0,
  • "name": "string",
  • "organizationID": 0,
  • "scheduledEndtime": "2019-08-14T17:10:28Z",
  • "startDate": "2019-08-14T17:10:28Z"
}

GetEvent

Creates an event with the passed event ID

path Parameters
eventID
required
int64

Responses

200

requested event payload

400

Passed id is in the wrong format

500

Unexpected database error

get /event/{eventID}
https://app.groupalarm.com/api/v1/event/{eventID}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "endDate": "2019-08-14T17:10:28Z",
  • "id": 0,
  • "name": "string",
  • "organizationID": 0,
  • "scheduledEndtime": "2019-08-14T17:10:28Z",
  • "startDate": "2019-08-14T17:10:28Z"
}

CloseEvent

Closes an event with the passed event ID

path Parameters
eventID
required
int64

Responses

200

response message

400

Passed id is in the wrong format

500

Unexpected database error

patch /event/{eventID}
https://app.groupalarm.com/api/v1/event/{eventID}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "message": "event 1 was successfully closed"
}

GetEvents

Returns paginated events of a passed organization

query Parameters
organization
required
int64

ID of an organization

limit
int64

max. amount of entries in list

offset
int64

amount of entries to skip

Responses

200

events for passed organization

400

Passed organization ID is in the wrong format

500

Unexpected database error

get /events
https://app.groupalarm.com/api/v1/events

Response samples

application/json
Copy
Expand all Collapse all
{
  • "events":
    [
    ],
  • "totalEvents": 0
}

GetOpenEvents

Returns all open events of a passed organization

query Parameters
organization
required
int64

ID of an organization

Responses

200

open events for passed organization

400

Passed organization ID is in the wrong format

500

Unexpected database error

get /events/open
https://app.groupalarm.com/api/v1/events/open

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

labels

CreateLabel

Creates a new label with the passed label payload parameters

Request Body schema: application/json
assignees
Array of integer <int64>

assigned user for this label

color
required
string

hex color code

description
string

description for this labels

id
integer <int64>

id for this label

name
required
string

name of this label

organizationID
required
integer <int64>

organization id for this label

substitute
object (Label describes a label payload) Recursive

This is used for the interaction with alarms

Responses

201

created label

400

Passed label payload in wrong format

500

Unexpected database error

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

Request samples

application/json
Copy
Expand all Collapse all
{
  • "assignees":
    [
    ],
  • "color": "string",
  • "description": "string",
  • "id": 0,
  • "name": "string",
  • "organizationID": 0,
  • "substitute": { }
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "assignees":
    [
    ],
  • "color": "string",
  • "description": "string",
  • "id": 0,
  • "name": "string",
  • "organizationID": 0,
  • "substitute": { }
}

GetLabel

Returns a specific label with passed ID

path Parameters
labelID
required
int64

Responses

200

requested label

400

Passed label ID in wrong format

500

Unexpected database error

get /label/{labelID}
https://app.groupalarm.com/api/v1/label/{labelID}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "assignees":
    [
    ],
  • "color": "string",
  • "description": "string",
  • "id": 0,
  • "name": "string",
  • "organizationID": 0,
  • "substitute": { }
}

UpdateLabel

Updates a specific label by a passed label ID and a label payload

path Parameters
labelID
required
int64
Request Body schema: application/json
assignees
Array of integer <int64>

assigned user for this label

color
required
string

hex color code

description
string

description for this labels

id
integer <int64>

id for this label

name
required