Policy API

General Information

🚧
If using the EU instance of Opsgenie, the URL needs to be https://api.eu.opsgenie.com for requests to be successful.

📘
Create an API Integration and obtain your apiKey to make requests listed below. Please make sure that the integration is not restricted to access configurations.

Create Policy

Create policy 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/policies

Common JSON Body Fields

Fields	Mandatory	Description	Limit
type	true	Type of the policy. Should be one of alert and notification
name	true	Name of the policy	100 chars
enabled	true	Initial status of the integration.
policyDescription	false	Description of the policy	200 chars
filter	false	Conditions specified in this field must be met for this policy to work. You can refer to Filter for detailed information about filter and its fields
timeRestrictions	false	Time restrictions specified in this field must be met for this policy to work. You can refer to Time constraints and time zones for detailed information about time restriction and its fields

Query Parameters

Parameter	Mandatory	Description
teamId*	false	The identifier of the team that this policy belongs. Value should be null for global policies.

📘
You can make api requests with global integrations, for global and team-based policies. teamId parameter should be null for global policies. Can be any team id for global integrations.
You can make api requests with team-based integrations, for team-based policies only. teamId parameter cannot be null and should be the same with the integration's teamId.

Extra Fields for Alert Policy

Parameter	Mandatory	Description
message	true	Message of the alert
continue	false	Will trigger other modify policies if set to true. Default value is false
alias	false	Alias of the alert. You can use {{alias}} to refer to the original alias. Default value is {{alias}}
description	false	Description of the alert. You can use {{description}} to refer to the original alert description. Default value is {{description}}
entity	false	Entity field of the alert. You can use {{entity}} to refer to the original entity. Default value is {{entity}}
source	false	Source field of the alert. You can use {{source}} to refer to the original source. Default value is {{source}}
ignoreOriginalActions	false	If set to true, policy will ignore the original actions of the alert. Default value is false
actions	false	Actions as a list of strings to add to the alerts original actions value. If ignoreOriginalActions field is set to true, this will replace the original actions.
ignoreOriginalDetails	false	If set to true, policy will ignore the original details of the alert. Default value is false
details	false	Map of key-value pairs to use as custom properties of the alert details. If ignoreOriginalDetails field is set to true, this will replace the original details.
ignoreOriginalResponders	false	If set to true, policy will ignore the original responders of the alert. Default value is false
responders	false	Responders to add to the alerts original responders value as a list of teams, users or the reserved word none or all. If ignoreOriginalResponders field is set to true, this will replace the original responders. The possible values for responders are: user team You can refer below for example values
ignoreOriginalTags	false	If set to true, policy will ignore the original tags of the alert. Default value is false
tags	false	Tags to add to the alerts original tags value as a list of strings. If ignoreOriginalResponders field is set to true, this will replace the original responders.
priority	false	Priority of the alert. Should be one of P1, P2, P3, P4, or P5

📘
You can use string operations with alias, description, entity and source fields. For more detailed instructions, you can refer to string processing methods

Responders field example:

{
    "responders": [
        {
            "type": "team",
            "id": "0f5f6b40-7dca-44fc-8036-6d6d550e853f"
        },
        {
            "type": "user",
            "id": "dde5a8e0-5b8d-4270-9e94-b1bd8ba7a63b"
        }
    ]
}

Sample Requests

curl -X POST  'https://api.opsgenie.com/v2/policies'
    --header 'Authorization: GenieKey sdy4brs-faa2-4ba2-a551q-1brsf565c889'
    --header 'Content-Type: application/json'
    --data
'{
    "type":"alert",
    "policyDescription":"alert policy description ",
    "enabled":"true",
    "filter":{
        "type":"match-all-conditions",
        "conditions":[
            {
                "field":"message",
                "operation":"contains",
                "expectedValue":"dynamodb"
            }
        ]
    },
    "timeRestrictions":{
       "type":"weekday-and-time-of-day",
       "restrictions":[{
      		 "startDay":"monday",
       		 "endDay":"thursday",
			 "endHour":5,
			 "endMin":10,
			 "startHour":20,
		 	 "startMin":23	
       }]
    },
    "ignoreOriginalResponders": true,
    "ignoreOriginalTags": true,
    "continue": true,
    "name":"Alert Policy",
    "message":"{{message}} db error",
    "responders":[{"type":"user","id":"1e1d2ba1-4532-4602-878e-9db1aa927164"}],
    "alias":"{{alias.toLowerCase()}} dynamodb",
    "tags":["dynamodb"],
    "description":"{{description}}"
}'

Response:

{
    "data": {
        "id": "f3006e61-8b35-4f63-8272-9589622474bb",
        "name": "Alert Policy",
        "type": "alert",
        "enabled": true
    },
    "took": 0.142,
    "requestId": "0f5f6b40-7dca-44fc-8036-6d6d550e853f"
}

Extra Fields for Notification Policy

Parameter	Mandatory	Description
autoRestartAction	false	Auto Restart Action of the policy. You can refer You can refer here for details.
autoCloseAction	false	Auto Close Action of the policy. You can refer here for details.
deduplicationAction	false	Deduplication Action of the policy. You can refer here for details.
delayAction	false	Delay Action of the policy. You can refer here for details.
suppress	false	Suppress value of the policy. Default value is false.

Sample Requests

curl -X POST  'https://api.opsgenie.com/v2/policies'
    --header 'Authorization: GenieKey sdy4brs-faa2-4ba2-a551q-1brsf565c889'
    --header 'Content-Type: application/json'
    --data
'{
    "type":"notification",
    "policyDescription":"notification policy description ",
    "enabled":"true",
    "filter":{
        "type":"match-all-conditions",
        "conditions":[
            {
                "field":"message",
                "operation":"contains",
                "expectedValue":"message"
            }
        ]
    },
    "timeRestrictions":{
      "type":"time-of-day",
      "restriction":{
			"endHour":5,
			"endMin":10,
			"startHour":20,
			"startMin":23	
      }
   },
    "name":"Notification with Delay and Restart Actions",
    "delayAction":{
       "delayOption":"for-duration",
       "duration":{
   	     "timeUnit":"seconds",
   	     "timeAmount":5
       }
    },
    "autoRestartAction":{
       "duration":{
   	     "timeUnit":"minutes",
   	     "timeAmount":2
       },
       "maxRepeatCount":5
    }
}'

Response:

{
    "data": {
        "id": "f67c9562-4251-4b92-b0e7-147f3a2d28e2",
        "name": "Notification with Delay and Restart Actions",
        "type": "notification",
        "enabled": true
    },
    "took": 0.129,
    "requestId": "dde5a8e0-5b8d-4270-9e94-b1bd8ba7a63b"
}

Get Policy

HTTP Method	URL
GET	https://api.opsgenie.com/v2/policies/:identifier

In-Line Parameters

Referred Name	Description
identifier	Id of the policy

Query Parameters

Parameter	Mandatory	Description
teamId	false	The identifier of the team that this policy belongs. Value should be null for global policies.

Sample Request for Global Policy

curl -X GET  'https://api.opsgenie.com/v2/policies/2b228902-cc04-4f8a-b64f-a381f1289c9b'
    --header 'Authorization: GenieKey sdy4brs-faa2-4ba2-a551q-1brsf565c889'

Sample Request for Team Policy

curl -X GET  'https://api.opsgenie.com/v2/policies/2b228902-cc04-4f8a-b64f-a381f1289c9b?teamId=03b70a5b-3be4-43c1-a2b5-4d2f7e6b6ae8'
    --header 'Authorization: GenieKey sdy4brs-faa2-4ba2-a551q-1brsf565c889'

Response:

{
    "data": {
        "type": "notification",
        "name": "notification delayUntil",
        "enabled": true,
        "policyDescription": "",
        "id": "36b6f2e3-8f99-4a68-8f8f-a877873718d1",
        "filter": {
            "type": "match-all-conditions",
            "conditions": [
                {
                    "field": "message",
                    "not": false,
                    "operation": "contains",
                    "expectedValue": "message",
                    "order": 0
                },
                {
                    "field": "responders",
                    "not": true,
                    "operation": "contains",
                    "expectedValue": "recipient",
                    "order": 0
                }
            ]
        },
        "timeRestrictions": {
            "type": "time-of-day",
            "restriction": {
                "startHour": 20,
                "endHour": 5,
                "startMin": 23,
                "endMin": 10
            }
        },
        "delayAction": {
            "delayOption": "next-time",
            "duration": null,
            "untilHour": 1,
            "untilMinute": 5
        },
        "suppress": false
    },
    "took": 0.211,
    "requestId": "5120e157-ea9c-4865-8ab0-0ed8ed7a0955"
}

Update Policy

Update policy 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.

📘
This is a full update so it uses the same body fields and same query parameters with create requests.

HTTP Method	URL
PUT	https://api.opsgenie.com/v2/policies/:identifier

In-Line Parameters

Referred Name	Description
identifier	Identifier of the policy

Query Parameters

Parameter	Mandatory	Description
teamId	false	The identifier of the team that this policy belongs. Value should be null for global policies.

Sample Request for Global Policy

curl -X PUT 'https://api.opsgenie.com/v2/policies/c059164d-92dc-4a96-8caa-e70840a545a8'
    --header 'Authorization: GenieKey sdy43592-faa2-4ba2-a551q-1brsf565c889'
    --header 'Content-Type: application/json'
    --data
'{
    "type":"notification",
    "policyDescription":"updated description",
    "enabled":"true",
    "filter":{
        "type":"match-all-conditions",
        "conditions":[
            {
                "field":"responders",
                "operation":"contains",
                "expectedValue":"recipient",
                "not":true
            },
            {
                "field":"message",
                "operation":"contains",
                "expectedValue":"message"
            }
        ]
    },
    "name":"notification suppress",
    "suppress":true
}'

Response

{
    "result": "Updated",
    "took": 0.194,
    "requestId": "00bf03f6-ac9a-472c-91b2-80ca177b6471"
}

Delete Policy

Delete policy 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/policies/:identifier

In-Line Parameters

Referred Name	Description
identifier	Id of the policy

Query Parameters

Parameter	Mandatory	Description
teamId	false	The identifier of the team that this policy belongs. Value should be null for global policies.

Sample Request for Global Policy

curl -X DELETE 'https://api.opsgenie.com/v2/policies/53352b69-1ede-42c6-a0fe-73291019f18e'
    --header 'Authorization: GenieKey sdy43592-faa2-4ba2-a551q-1brsf565c889'

Sample Request for Team Policy

curl -X DELETE 'https://api.opsgenie.com/v2/policies/53352b69-1ede-42c6-a0fe-73291019f18e?teamId=03b70a5b-3be4-43c1-a2b5-4d2f7e6b6ae8
    --header 'Authorization: GenieKey sdy43592-faa2-4ba2-a551q-1brsf565c889'

Response:

{
    "result": "Deleted",
    "took": 0.254,
    "requestId": "a3886a19-ec77-468f-ae53-628f9e5909f2"
}

Disable Policy

Disable policy 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/policies/:identifier/disable

In-Line Parameters

Referred Name	Description
identifier	Id of the policy

Query Parameters

Parameter	Mandatory	Description
teamId	false	The identifier of the team that this policy belongs. Value should be null for global policies.

Sample Request for Global Policy

curl -X POST 'https://api.opsgenie.com/v2/policies/2b228902-cc04-4f8a-b64f-a381f1289c9b/disable'
    --header 'Authorization: GenieKey sdy43592-faa2-4ba2-a551q-1brsf565c889'

Sample Request for Team Policy

curl -X POST 'https://api.opsgenie.com/v2/policies/2b228902-cc04-4f8a-b64f-a381f1289c9b/disable?teamId=03b70a5b-3be4-43c1-a2b5-4d2f7e6b6ae8'
    --header 'Authorization: GenieKey sdy43592-faa2-4ba2-a551q-1brsf565c889'

Response:

{
    "result": "Disabled",
    "took": 0.031,
    "requestId": "3ef3e18e-f324-4a45-a31c-3b201d36aa2c"
}

Enable Policy

Enable policy 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/policies/:identifier/enable

In-Line Parameters

Referred Name	Description
identifier	Id of the policy

Query Parameters

Parameter	Mandatory	Description
teamId	false	The identifier of the team that this policy belongs. Value should be null for global policies.

Sample Request for Global Policy

curl -X POST 'https://api.opsgenie.com/v2/policies/2b228902-cc04-4f8a-b64f-a381f1289c9b/enable'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1brsf565c889'

Response:

{
    "result": "Enabled",
    "took": 0.034,
    "requestId": "89745648-19de-49da-a563-adb2243c212f"
}

Change Policy Order

Change order 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/policies/:identifier/change-order

In-Line Parameters

Referred Name	Description
identifier	Id of the policy

Query Parameters

Parameter	Mandatory	Description
teamId	false	The identifier of the team that this policy belongs. Value should be null for global policies.

JSON Body Fields

Fields	Mandatory	Description
targetIndex	true	Order of the target policy will be changed to this value. Larger values than policy count will put the target policy to last slot. Should be at least 0

Sample Request for Global Policy

curl -X POST 'https://api.opsgenie.com/v2/policies/2b228902-cc04-4f8a-b64f-a381f1289c9b/change-order'
    --header 'Authorization: GenieKey sdy43592-faa2-4ba2-a551q-1brsf565c889
    --header 'Content-Type: application/json'
    --data
'{
    "targetIndex":5
}';

Sample Request for Team Policy

curl -X POST 'https://api.opsgenie.com/v2/policies/2b228902-cc04-4f8a-b64f-a381f1289c9b/change-order?teamId=03b70a5b-3be4-43c1-a2b5-4d2f7e6b6ae8'
    --header 'Authorization: GenieKey sdy43592-faa2-4ba2-a551q-1brsf565c889
    --header 'Content-Type: application/json'
    --data
'{
    "targetIndex":5
}';

Response

{
    "result": "Order Changed",
    "took": 0.134,
    "requestId": "89745568-12ge-41aa-a8fe-abd224c3212f"
}

List Alert Policies

Used to get global and team-based alert policies.

📘
This API Call only allows a limit of 1000 results

HTTP Method	URL
GET	https://api.opsgenie.com/v2/policies/alert

Query Parameters

Parameter	Mandatory	Description
teamId	false	The identifier of the team for listing team-based alert policies. Should be null for global policies.

Sample Request for Global Policies

curl -X GET 'https://api.opsgenie.com/v2/policies/alert'
    --header 'Authorization: GenieKey sdy43592-faa2-4ba2-a551q-1brsf565c889'

Sample Request for Team Alert Policies

curl -X GET 'https://api.opsgenie.com/v2/policies/alert?teamId=03b70a5b-3be4-43c1-a2b5-4d2f7e6b6ae8'
    --header 'Authorization: GenieKey sdy43592-faa2-4ba2-a551q-1brsf565c889'

Response:

{
    "data": [
        {
            "id": "a697b628-e0e3-4043-b01f-6b587e5e98a0",
            "name": "Alert Policy",
            "type": "alert",
            "order": 0,
            "enabled": true
        },
        {
            "id": "2b228902-cc04-4f8a-b64f-a381f1289c9b",
            "name": "Alert Policy 2",
            "type": "alert",
            "order": 1,
            "enabled": true
        },
        {
            "id": "bcf68e62-bf5f-4483-8e57-554e4881420f",
            "name": "Alert Policy 3",
            "type": "alert",
            "order": 2,
            "enabled": true
        },
    ],
    "took": 0.2,
    "requestId": "bbe30c0b-c6e5-4102-92f1-d7dd8b645124"
}

List Notification Policies

Used to list team notification policies.

HTTP Method	URL
GET	https://api.opsgenie.com/v2/policies/notification

Query Parameters

Parameter	Mandatory	Description
teamId	true	The identifier of the team for listing team-based notification policies.

Sample Request

curl -X GET 'https://api.opsgenie.com/v2/policies/notification?teamId=03b70a5b-3be4-43c1-a2b5-4d2f7e6b6ae8'
    --header 'Authorization: GenieKey sdy43592-faa2-4ba2-a551q-1brsf565c889'

Response:

{
    "data": [
        {
            "id": "a697b628-e0e3-4043-b01f-6b587e5e98a0",
            "name": "Notification Policy with Delay Action",
            "type": "notification",
            "order": 0,
            "enabled": true
        },
        {
            "id": "2b228902-cc04-4f8a-b64f-a381f1289c9b",
            "name": "Notification Policy with Suppress",
            "type": "notification",
            "order": 1,
            "enabled": true
        },
        {
            "id": "bcf68e62-bf5f-4483-8e57-554e4881420f",
            "name": "Notification Policy with Delay and AutoRestart",
            "type": "notification",
            "order": 2,
            "enabled": true
        },
    ],
    "took": 0.009,
    "requestId": "bbe30c0b-c6e5-4102-92f1-d7dd8b645124"
}

Delay Action Fields

Field	Mandatory	Description
delayOption	true	Delay type. Should be one of for-duration, next-time, next-weekday, next-monday, next-tuesday, next-wednesday, next-thursday, next-friday, next-saturday, next-sunday
untilMinute	true*	Minute field of the Should be a number between 0-59
untilHour	true*	Should be a number between 0-23
duration	false*	Delay duration. You can refer here for details

🚧
If delayOption is for-duration, untilHour and untilMinute is redundant and duration is mandatory

Deduplication Action Fields

Field	Mandatory	Description
deduplicationActionType	true	Deduplication type. Should be one of value-based or frequency-based
count	true	Number of alerts before deduplication
duration	false	Interval to keep count of alerts for frequency based deduplication. You can refer here for details

Auto Restart Action Fields

Field	Mandatory	Description
duration	true	Duration to wait until restarting the alert flow. You can refer here for details
maxRepeatCount	true	Maximum count to restart notification flow

Auto Close Action Fields

Field	Mandatory	Description
duration	true	Duration to wait until closing the alert. You can refer here for details

Time Restriction Fields

Used to limit policies to certain day and time of the week, using multiple start and end times for each day of the week. This allows applying different policies at different times.

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:

Field	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


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

Filter Fields

Defines the conditions that will be checked before applying policies and type of the operations that will be applied on these conditions

JSON Body Fields

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

🚧
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, details, extra-properties, responders, 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

filter field example:

{
    "filter": {
        "type": "match-all"
    }
}

{
    "filter": {
        "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"
            }
        ]
    }
}

Duration Fields

Duration to wait until taking an action in time based policies

JSON Body Fields

Fields	Mandatory	Description
timeUnit	false	Time unit used in duration. Should be one of days, hours or minutes Default value is minutes
timeAmount	true	Amount of time

duration field example:

"duration":{
    "timeAmount":10,
    "timeUnit":"minutes"
}

"duration":{
    "timeAmount":5,
    "timeUnit":"days"
}