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

In-Line Parameters

Referred NameDescription
userIdentifierIdentifier of the user for this notification rule. You should provide either id or username of the user

JSON Body Fields

FieldMandatoryDescription
nametrue Name of the notification rule.
actionTypetrue 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.
criteriafalseDefines 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.
notificationTimetrue (*) 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
timeRestrictionfalseTime 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.
schedulesfalseThis 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.
orderfalseThe 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)
stepsfalseList of steps that will be added to notification rule. For further details of step object, you can refer here
repeatfalseThe 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
enabledtrue 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 NameDescription
userIdentifierIdentifier of the user for this notification rule. You should provide either id or username of the user.
ruleIdId 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

In-Line Parameters

Referred NameDescription
userIdentifierIdentifier of the user for this notification rule. You should provide either id or username of the user
ruleIdId of the notification rule.

JSON Body Fields

FieldMandatoryDescription
namefalseName of the notification rule
criteriafalseDefines 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.
notificationTimetrue*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
timeRestrictionfalseTime 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.
schedulesfalseThis 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.
stepsfalseList of steps that will be added to notification rule. For further details of step object, you can refer here
repeatfalseThe 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
orderfalseThe 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)
enabledfalseIf 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

In-Line Parameters

Referred NameDescription
userIdentifierIdentifier of the user for this notification rule. You should provide either id or username of the user
ruleIdId 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

In-Line Parameters

Referred NameDescription
userIdentifierIdentifier 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 NameDescription
userIdentifierIdentifier of the user for this notification rule. You should provide either id or username of the user
ruleIdId 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 NameDescription
userIdentifierIdentifier of the user for this notification rule. You should provide either id or username of the user.
ruleIdId 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

In-Line Parameters

Referred NameDescription
userIdentifierIdentifier of the user that the notification rules belong to originally. You should provide either id or username of the user.

JSON Body Fields

FieldMandatoryDescription
toUserstrueSpecify 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".
ruleTypestrueSpecify 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

FieldMandatoryDescription
contacttrueDefines the contact that notification will be sent to. contact parameter takes a contact object which is explained here with details.
sendAftertrue*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
enabledtrueThis 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

ParameterMandatoryDescription
methodtrueContact method of user and should be one of email, sms, voice or mobile.
totrueAddress 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

FieldMandatoryDescription
typetrueType of the operation will be applied on conditions. Should be one of match-all, match-any-condition or match-all-conditions
conditionstrue*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

FieldMandatoryDescription
fieldtrue 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
keyfalseIf field is set as extra-properties, key could be used for key-value pair
notfalseIndicates behaviour of the given operation. Default value is false
operationtrue 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
expectedValuefalseUser defined value that will be compared with alert field according to the operation. Default value is empty string
orderfalseOrder 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:

FieldMandatoryDescription
typetrue This parameter should be set time-of-day
restrictiontrue It is a restriction object which is described below. In this case startDay/endDay fields are not supported

Fields of Restriction Object

FieldMandatoryDescription
startHourtrue Value of the hour that frame will start
startMintrue Value of the minute that frame will start.
endHourtrue Value of the hour that frame will end
endMintrue 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:

ParameterMandatoryDescription
typetrue This parameter should be set weekday-and-time-of-day
restrictionstrue It is a list of restriction objects which are described below

Fields of Restrictions Object

FieldMandatoryDescription
startDaytrue 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
startHourtrueValue of the hour that frame will start
startMintrueValue of the minute that frame will start
endDaytrueName 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
endHourtrueValue of the hour that frame will end
endMintrueValue 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

FieldMandatoryDescription
typetrue This parameter is mandatory and should be set as schedule
namefalseName of the schedule
idfalseId of the schedule

🚧

One of the id or name of the schedule should be provided

schedule object example:

{
    "type" : "schedule"
    "name" : "test_schedule",
}

Fields of Repeat Object

FieldMandatoryDescription
loopAftertrue This parameter is amount in minutes that notification steps will be repeatedly apply. It can not be less than 0.
enabledfalseDetermine whether loopAfter is enabled or not. If it is set to false, repeating will be disabled.

repeat field example:

{
    "repeat" : {
        "loopAfter" : 2,
        "enabled" : true
    }
}