Opsgenie Docs

Notification Rule API

Suggest Edits

🚧

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

HTTP Method

URL

GET

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

HTTP Method

URL

POST

https://api.opsgenie.com/v2/users/:userIdentifier/notification-rules/:ruleId/enable

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

HTTP Method

URL

POST

https://api.opsgenie.com/v2/users/:userIdentifier/notification-rules/:ruleId/disable

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 or name 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 about a year ago

Notification Rule API

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.