Notification Rule API
If using the EU instance of Opsgenie, the URL needs to be https://api.eu.opsgenie.com for requests to be successful.
General Information
Domains
Create an API Integration and obtain your apiKey to make requests listed above. Please make sure that the integration is not restricted to access configurations.
You can refer Create and manage notification preferences
for detailed information about the notification rules and their steps
Create Notification Rule
Create notification rule is a write request. If the integration of the API key configured as read-only, the request will not be accepted. For more information, you can refer to API Access Management
HTTP Method | URL |
---|---|
POST | https://api.opsgenie.com/v2/users/:userIdentifier/notification-rules |
In-Line Parameters
Referred Name | Description |
---|---|
userIdentifier | Identifier of the user for this notification rule. You should provide either id or username of the user |
JSON Body Fields
Field | Mandatory | Description |
---|---|---|
name | true | Name of the notification rule. |
actionType | true | Type of the action that notification rule will have. This parameter should be one of create-alert, acknowledged-alert, closed-alert, assigned-alert, add-note, schedule-start, schedule-end and incoming-call-routing. |
criteria | false | Defines the conditions that will be checked before applying notification rule and type of the operations that will be applied on conditions. Default value is matching all notification rules. You can refer here for more about the field definition. |
notificationTime | true (*) | List of Time Periods that notification for schedule start/end will be sent. This parameter should be one of just-before, 15-minutes-ago, 1-hour-ago and 1-day-ago |
timeRestriction | false | Time interval that notification rule will work. It can be just one restriction which will be applied all days, or list of restrictions will be applied to the specified days. You may refer here for more about the parameter definition. |
schedules | false | This field is valid for Schedule Start/End rules. It can be list of schedules that notification rule will be applied when on call of that schedule starts/ends. This field shall only be populated with the specified users' schedules. You refer here for schedule objects. |
order | false | The order of the notification rule within the notification rules with the same action type. order value is actually the index of the notification rule whose minimum value is 0 and whose maximum value is n-1 (number of notification rules with the same action type is n) |
steps | false | List of steps that will be added to notification rule. For further details of step object, you can refer here |
repeat | false | The amount of time in minutes that notification steps will be repeatedly apply. You may refer here for further information of this parameter. You may also check Create and manage notification preferences for detailed information about repeating |
enabled | true | If notification rule will be enabled or not when it is created |
If
actionType
is scheduleStart or scheduleEnd,notificationTime
is mandatory
Sample Requests:
curl -X POST 'https://api.opsgenie.com/v2/users/4b26961a-a837-49d2-a1fe-0973013e3c3b/notification-rules/'
--header 'Authorization: GenieKey 50b71849-6b09-46d8-bd7b-046b9d942eb4'
--header 'Content-Type: application/json'
--data
'{
"name": "Test Notification Rule",
"actionType": "schedule-start",
"enabled" : true,
"criteria" : {
"type" : "match-all"
},
"order": 1,
"notificationTime" : ["1-hour-ago"],
"schedules" : [
{
"name" : "test_schedule",
"type" : "schedule"
}
],
"repeat" : {
"loopAfter" : 2
},
"timeRestriction" : {
"type" : "time-of-day",
"restriction" : {
"startHour": 3,
"startMin" : 15,
"endHour" : 5,
"endMin" : 30
}
}'
curl -X POST 'https://api.opsgenie.com/v2/users/[email protected]/notification-rules/'
--header 'Authorization: GenieKey 50b71849-6b09-46d8-bd7b-046b9d942eb4'
--header 'Content-Type: application/json'
--data
'{
"name": "Create Alert Notification with step",
"actionType": "create-alert",
"enabled" : true,
"criteria" : {
"type" : "match-all"
},
"order": 1,
"repeat" : {
"loopAfter" : 2
},
"timeRestriction" : {
"type" : "time-of-day",
"restriction" : {
"startHour": 3,
"startMin" : 15,
"endHour" : 5,
"endMin" : 30
}
},
"steps" : [
{
"contact": {
"method": "email",
"to": "[email protected]"
},
"sendAfter": {
"timeAmount": 1
},
"enabled" : true
}
]
}'
Response:
{
"data": {
"id": "e3face00-e378-4eb1-8141-cd21103d1814",
"name": "Create Alert Notification with step",
"actionType": "create-alert",
"order": 3,
"enabled": true
},
"took": 0.828,
"requestId": "209ecfca-a25d-4a19-80c1-1f6d26fa95e9"
}
Get Notification Rule
In-Line Parameters
Referred Name | Description |
---|---|
userIdentifier | Identifier of the user for this notification rule. You should provide either id or username of the user. |
ruleId | Id of the notification rule |
Sample Request:
curl -X GET 'https://api.opsgenie.com/v2/users/[email protected]/notification-rules/6250e423-fd5e-451c-8573-a20c61fb9872'
--header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889'
Response:
{
"data": {
"id": "6250e423-fd5e-451c-8573-a20c61fb9872",
"name": "Test Notification Rule",
"actionType": "schedule-start",
"notificationTime": ["1-hour-ago"],
"order": 1,
"timeRestriction": {
"type": "time-of-day",
"restriction": {
"startHour": 3,
"endHour": 5,
"startMin": 15,
"endMin": 30
}
},
"steps": [],
"schedules": [
{
"id": "af072e63-5925-4609-b7de-d983ad8ce9c1",
"type": "schedule",
"name": "test_schedule"
}
],
"enabled": true
},
"took": 0.14,
"requestId": "a1f871a0-65e0-4a60-81ed-a5102a94617b"
}
Update Notification Rule (Partial)
Update notification rule request is a write request. If the integration of the API key configured as read-only, the request will not be accepted. For more information, you can refer to API Access Management
HTTP Method | URL |
---|---|
PATCH | https://api.opsgenie.com/v2/users/:userIdentifier/notification-rules/:ruleId |
In-Line Parameters
Referred Name | Description |
---|---|
userIdentifier | Identifier of the user for this notification rule. You should provide either id or username of the user |
ruleId | Id of the notification rule. |
JSON Body Fields
Field | Mandatory | Description |
---|---|---|
name | false | Name of the notification rule |
criteria | false | Defines the conditions that will be checked before applying notification rule and type of the operations that will be applied on conditions. Default value is matching all notification rules. You can refer here for more about the field definition. |
notificationTime | true* | List of Time Periods that notification for schedule start/end will be sent. This parameter should be one of just-before, 15-minutes-ago, 1-hour-ago and 1-day-ago |
timeRestriction | false | Time interval that notification rule will work. It can be just one restriction which will be applied all days, or list of restrictions will be applied to the specified days. You may refer here for more about the parameter definition. |
schedules | false | This field is valid for Schedule Start/End rules. It can be list of schedules that notification rule will be applied when on call of that schedule starts/ends. This field shall only be populated with the specified users' schedules. You refer here for schedule objects. |
steps | false | List of steps that will be added to notification rule. For further details of step object, you can refer here |
repeat | false | The amount of time in minutes that notification steps will be repeatedly apply. You may refer here for further information of this parameter. You may also check Create and manage notification preferences for detailed information about repeating |
order | false | The order of the notification rule within the notification rules with the same action type. order value is actually the index of the notification rule whose minimum value is 0 and whose maximum value is n-1 (number of notification rules with the same action type is n) |
enabled | false | If notification rule will be enabled or not when it is created |
If
actionType
is scheduleStart or scheduleEnd,notificationTime
is mandatory
Sample Request:
curl -X PATCH 'https://api.opsgenie.com/v2/users/[email protected]/notification-rules/6250e423-fd5e-451c-8573-a20c61fb9872
--header 'Authorization: GenieKey 50b71849-6b09-46d8-bd7b-046b9d942eb4'
--header 'Content-Type: application/json'
--data
'{
"name": "Updated preference",
"notificationTime": ["just-before", "15-minutes-ago" , "1-hour-ago"],
"schedules" : [
{
"name" : "schedule_test",
"type" : "schedule"
}
],
"timeRestriction" : {
"type" : "weekday-and-time-of-day",
"restrictions" : [
{
"startDay" : "monday",
"endDay" : "friday",
"startHour" : 13,
"startMin" : 0,
"endHour" : 18,
"endMin" : 0
}
]
}'
Response:
{
"data": {
"id": "6250e423-fd5e-451c-8573-a20c61fb9872",
"name": "Updated preference",
"actionType": "schedule-start",
"order": 1,
"enabled": true
},
"took": 0.409,
"requestId": "f55ce8ff-ac0a-41d6-8fe0-53c937709b0c"
}
Delete Notification Rule
Delete notification rule request is a write request. If the integration of the API key configured as read-only, the request will not be accepted. For more information, you can refer to API Access Management
HTTP Method | URL |
---|---|
DELETE | https://api.opsgenie.com/v2/users/:userIdentifier/notification-rules/:ruleId |
In-Line Parameters
Referred Name | Description |
---|---|
userIdentifier | Identifier of the user for this notification rule. You should provide either id or username of the user |
ruleId | Id of the notification rule. |
Sample Request:
curl -X DELETE 'https://api.opsgenie.com/v2/users/[email protected]/notification-rules/6250e423-fd5e-451c-8573-a20c61fb9872'
--header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889'
Response:
{
"result": "Deleted",
"took": 0.257,
"requestId": "88a7b84c-67f2-4671-9034-1e02a8ebf772"
}
List Notification Rule
HTTP Method | URL |
---|---|
GET | https://api.opsgenie.com/v2/users/:userIdentifier/notification-rules |
In-Line Parameters
Referred Name | Description |
---|---|
userIdentifier | Identifier of the user for this notification rule. You should provide either id or username of the user |
Sample Request:
curl -X GET 'https://api.opsgenie.com/v2/users/af072e63-5925-4609-b7de-d983ad8ce9c1/notification-rules/6250e423-fd5e-451c-8573-a20c61fb9872'
--header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889'
Response:
{
"data": [
{
"id": "af0bf74f-dd6f-469d-a2e2-e69d1f474c6a",
"name": "New Alert",
"actionType": "create-alert",
"order": 1,
"enabled": true
},
{
"id": "487622ab-b4bc-4aed-a043-640ffeb52393",
"name": "Acknowledged Alert",
"actionType": "acknowledged-alert",
"order": 2,
"enabled": true
},
{
"id": "610d9217-5557-4773-977b-e556639f36e6",
"name": "Closed Alert",
"actionType": "closed-alert",
"order": 3,
"enabled": true
},
{
"id": "34622362-2cb0-4bb5-b4f6-329aded25801",
"name": "Schedule Start",
"actionType": "schedule-start",
"order": 4,
"enabled": true
},
{
"id": "ae4bba81-fc97-4a39-a191-f6de0077d9be",
"name": "Assigned Alert",
"actionType": "assigned-alert",
"order": 6,
"enabled": true
},
{
"id": "904b3711-04df-453b-83d5-b432e44b94ec",
"name": "Add Note",
"actionType": "add-note",
"order": 7,
"enabled": true
},
{
"id": "7f395466-25a6-4e07-9e57-99e6d0d8e44c",
"name": "Incoming Call Routing",
"actionType": "incoming-call-routing",
"order": 8,
"enabled": true
}
],
"took": 0.117,
"requestId": "05c9f1a3-611b-4741-8615-fd9e237539d4"
}
Enable Notification Rule
Enable notification rule request is a write request. If the integration of the API key configured as read-only, the request will not be accepted. For more information, you can refer to API Access Management
In-Line Parameters
Referred Name | Description |
---|---|
userIdentifier | Identifier of the user for this notification rule. You should provide either id or username of the user |
ruleId | Id of the notification rule. |
Sample Request:
curl -X POST 'https://api.opsgenie.com/v2/users/af072e63-5925-4609-b7de-d983ad8ce9c1/notification-rules/6250e423-fd5e-451c-8573-a20c61fb9872/enable'
--header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889'
Response:
{
"result": "Enabled",
"data": {
"id": "a8e54bca-8f3f-45f9-b6a0-65487a81220c",
},
"took": 0.906,
requestId": "3e312a96-b750-40c2-a845-924c63f0d035"
}
Disable Notification Rule
Disable notification rule request is a write request. If the integration of the API key configured as read-only, the request will not be accepted. For more information, you can refer to API Access Management
In-Line Parameters
Referred Name | Description |
---|---|
userIdentifier | Identifier of the user for this notification rule. You should provide either id or username of the user. |
ruleId | Id of the notification rule. |
Sample Request:
curl -X POST 'https://api.opsgenie.com/v2/users/[email protected]/notification-rules/6250e423-fd5e-451c-8573-a20c61fb9872/disable'
--header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889'
Response:
{
"result": "Disabled",
"data": {
"id": "a8e54bca-8f3f-45f9-b6a0-65487a81220c",
},
"took": 0.906,
"requestId": "3e312a96-b750-40c2-a845-924c63f0d035"
}
Copy Notification Rules to Other Users
Copy notification rules to other users request is a write request. If the integration of the API key configured as read-only, the request will not be accepted. For more information, you can refer to API Access Management
HTTP Method | URL |
---|---|
POST, PUT, PATCH | https://api.opsgenie.com/v2/users/:userIdentifier/notification-rules/copy-to |
In-Line Parameters
Referred Name | Description |
---|---|
userIdentifier | Identifier of the user that the notification rules belong to originally. You should provide either id or username of the user. |
JSON Body Fields
Field | Mandatory | Description |
---|---|---|
toUsers | true | Specify a list of the users which you want to copy the rules to. You can use the username of a user, or to copy to all users, "all". |
ruleTypes | true | Specify a list of the action types you want to copy the rules of. It can contain "New Alert", "Acknowledged Alert" or for all types of notification rules, "all". The total list of valid types are: all, acknowledged-alert, renotified-alert, closed-alert, schedule-start, assigned-alert, add-note, new-alert |
Sample Requests:
curl -X PATCH 'https://api.opsgenie.com/v2/users/[email protected]/notification-rules/copy-to
--header 'Authorization: GenieKey 50b71849-6b09-46d8-bd7b-046b9d942eb4'
--header 'Content-Type: application/json'
--data
'{
"toUsers": ["username1", "username2" , "username3"],
"ruleTypes": ["new-alert", "schedule-start"]
}'
Response:
{
"result": "Started copying notification rules",
"took": 0.583,
"requestId": "f2ec7f39-4bc6-4e39-9d22-0d89882c5e73"
}
Fields of Step Object
Field | Mandatory | Description |
---|---|---|
contact | true | Defines the contact that notification will be sent to. contact parameter takes a contact object which is explained here with details. |
sendAfter | true* | Minute time period notification will be sent after. It should be given as an object which has a timeAmount field that takes amount as minutes |
enabled | true | This parameter is used to specify if given step will be enabled or not when it is created |
sendAfter
is only mandatory for new alert and assigned alert notification rules
step
Example:
{
"contact": {
"method": "email",
"to": "[email protected]"
},
"sendAfter": {
"timeAmount": 1
},
"enabled" : true
}
Fields of Contact Object
Parameter | Mandatory | Description |
---|---|---|
method | true | Contact method of user and should be one of email, sms, voice or mobile. |
to | true | Address of given method |
contact
field example:
{
"contact": {
"method": "email",
"to": "[email protected]"
}
}
Criteria Fields
Defines the conditions that will be checked before applying notification rules and type of the operations that will be applied on these conditions
JSON Body Fields
Field | Mandatory | Description |
---|---|---|
type | true | Type of the operation will be applied on conditions. Should be one of match-all, match-any-condition or match-all-conditions |
conditions | true* | List of conditions will be checked before applying team routing rule |
If operation
type
is match-all,conditions
field is not necessary/mandatory.
Fields of Conditions Object
Field | Mandatory | Description |
---|---|---|
field | true | Specifies which alert field will be used in condition. Possible values are message, alias, description, source, entity, tags, actions, extra-properties, recipients, teams or priority |
key | false | If field is set as extra-properties, key could be used for key-value pair |
not | false | Indicates behaviour of the given operation. Default value is false |
operation | true | It is the operation that will be executed for the given field and key. Possible operations are matches, contains, starts-with, ends-with, equals, contains-key, contains-value, greater-than, less-than, is-empty and equals-ignore-whitespace. Available operations changes according to the fields type: String Operations: contains , equals , starts-with , ends-with , matches , is-empty , equals-ignore-whitespace List Operations: contains , is-empty Map Operations: contains , contains-key , contains-value , is-empty Number Operations: matches , equals , greater-than , less-than * Boolean Operations: equals |
expectedValue | false | User defined value that will be compared with alert field according to the operation. Default value is empty string |
order | false | Order of the condition in conditions list |
criteria
field example:
{
"criteria": {
"type": "match-all"
}
}
{
"criteria": {
"type": "match-any-condition",
"conditions": [
{
"field": "message",
"not": false,
"operation": "contains",
"expectedValue": "expected1"
},
{
"field": "alias",
"not": true,
"operation": "starts-with",
"expectedValue": "expected2"
},
{
"field": "extra-properties",
"key": "expectedKey",
"not": true,
"operation": "starts-with",
"expectedValue": "expected3"
}
]
}
}
Time Restriction Fields
Used to limit notification rules to certain day and time of the week, using multiple start and end times for each day of the week.
Day Based Restriction
If the time restrictions will be configured as day based, this parameter should be used. timeRestriction
parameter for daily restrictions should have the following format:
Field | Mandatory | Description |
---|---|---|
type | true | This parameter should be set time-of-day |
restriction | true | It is a restriction object which is described below. In this case startDay /endDay fields are not supported |
Fields of Restriction Object
Field | Mandatory | Description |
---|---|---|
startHour | true | Value of the hour that frame will start |
startMin | true | Value of the minute that frame will start. |
endHour | true | Value of the hour that frame will end |
endMin | true | Value of the minute that frame will end. |
restriction
field example:
{
"timeRestriction": {
"type" : "time-of-day",
"restriction" :
{
"startHour" : 8,
"startMin" : 0,
"endHour" : 18,
"endMin" : 30
}
}
}
Week Based Restrictions
If the time restrictions will be configured as week based, this parameter should be used. timeRestriction parameter for weekly restrictions should have the following format:
Parameter | Mandatory | Description |
---|---|---|
type | true | This parameter should be set weekday-and-time-of-day |
restrictions | true | It is a list of restriction objects which are described below |
Fields of Restrictions Object
Field | Mandatory | Description |
---|---|---|
startDay | true | Name of day which time frame will start. May be one of monday, tuesday, wednesday, thursday, friday, saturday, sunday. Only used if type of restrictions is given weekday-and-time-of-day |
startHour | true | Value of the hour that frame will start |
startMin | true | Value of the minute that frame will start |
endDay | true | Name of day which time frame will end. May be one of monday, tuesday, wednesday, thursday, friday, saturday, sunday. Only used if type of restrictions is given weekday-and-time-of-day |
endHour | true | Value of the hour that frame will end |
endMin | true | Value of the minute that frame will end. |
restrictions
field example
{
"timeRestriction": {
"type" : "weekday-and-time-of-day",
"restrictions" : [
{
"startDay" : "monday",
"startHour" : 8,
"startMin" : 0,
"endDay" : "tuesday",
"endHour" : 18,
"endMin" : 30
},
{
"startDay" : "wednesday",
"startHour" : 8,
"startMin" : 0,
"endDay" : "thursday",
"endHour" : 18,
"endMin" : 30
}
]
}
}
Fields of Schedule Object
Field | Mandatory | Description |
---|---|---|
type | true | This parameter is mandatory and should be set as schedule |
name | false | Name of the schedule |
id | false | Id of the schedule |
One of the
id
orname
of the schedule should be provided
schedule
object example:
{
"type" : "schedule"
"name" : "test_schedule",
}
Fields of Repeat Object
Field | Mandatory | Description |
---|---|---|
loopAfter | true | This parameter is amount in minutes that notification steps will be repeatedly apply. It can not be less than 0. |
enabled | false | Determine whether loopAfter is enabled or not. If it is set to false, repeating will be disabled. |
repeat
field example:
{
"repeat" : {
"loopAfter" : 2,
"enabled" : true
}
}
Updated over 3 years ago