Policy API

General Information


Requests

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.

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/v1/policies

Common JSON Body Fields

Fields Mandatory Description Limit
type true Type of the policy. Should be one of auto-restart-notifications, auto-close, notification-suppress, notification-deduplication, notification-delay, modify
name true Name of the policy 512 chars
enabled true Initial status of the integration.
policyDescription false Description of the policy 512 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 Restriction for detailed information about time restriction and its fields

Extra Fields for Auto Close Policy

Parameter Mandatory Description
duration true Duration to wait until closing the alert. You can refer here for details
Sample Requests
curl -X POST  'https://api.opsgenie.com/v1/policies'
    --header 'Authorization: GenieKey eb24alp-faa2-4ba2-a551q-1alpf565c889'
    --header 'Content-Type: application/json'
    --data
'{
    "policyDescription":"auto close policy description",
    "enabled":"true",
    "filter":{
        "type":"match-all-conditions",
        "conditions":[
            {
                "field":"recipients",
                "operation":"contains",
                "expectedValue":"recipient",
                "not":true
            },
            {
                "field":"message",
                "operation":"contains",
                "expectedValue":"message"
            }
        ]
    },
    "timeRestrictions": {
        "type":"time-of-day",
        "restriction": {
            "endHour":5,
            "endMin":10,
            "startHour":20,
            "startMin":23
        }
    },
    "type":"auto-close",
    "name":"auto close policy",
    "duration":{
        "timeAmount":10,
        "timeUnit":"minutes"
    }
}'
Response:
{
    "data": {
        "id": "95579bd4-9820-4043-aa77-969026e56924",
        "name": "auto close policy2",
        "type": "auto-close",
        "enabled": true
    },
    "took": 0.119,
    "requestId": "f6ada606-5d5e-46e2-9294-27118d636b0f"
}

Extra Fields for Auto Restart Policy

Parameter 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
Sample Requests
curl -X POST  'https://api.opsgenie.com/v1/policies'
    --header 'Authorization: GenieKey eb24alp-faa2-4ba2-a551q-1alpf565c889'
    --header 'Content-Type: application/json'
    --data
'{
    "enabled":"true",
    "type":"auto-restart-notifications",
    "name":"auto restart policy",
    "duration":{
        "timeAmount":10,
        "timeUnit":"minutes"
    },
    "maxRepeatCount":10
}'
Response:
{
    "data": {
        "id": "d968cf48-e543-44be-8876-b8e153038595",
        "name": "auto restart policy2",
        "type": "auto-restart-notifications",
        "enabled": true
    },
    "took": 0.068,
    "requestId": "ee7ff973-a708-4982-ac62-6f40eeda0fa3"
}

Extra Fields for Notification Deduplication Policy

Parameter 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
Sample Requests
curl -X POST  'https://api.opsgenie.com/v1/policies'
    --header 'Authorization: GenieKey eb24brs-faa2-4ba2-a551q-1brsf565c889'
    --header 'Content-Type: application/json'
    --data
'{
    "enabled":"true",
    "type":"notification-deduplication",
    "name":"notification deduplication policy frequency",
    "deduplicationActionType":"frequency-based",
    "count":5,
    "duration":{
        "timeUnit":"seconds",
        "timeAmount":5
    }
}'
Response:
{
    "data": {
        "id": "7317bdef-afce-46fb-b246-89390ac39b82",
        "name": "notification deduplication policy frequency",
        "type": "notification-deduplication",
        "enabled": true
    },
    "took": 0.038,
    "requestId": "9d39867e-c214-4cc5-a505-8a478c062f3c"
}

Extra Fields for Notification Delay Policy

Parameter 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* Interval to keep count of alerts for frequency based deduplication
If delayOption is for-duration, untilHour and untilMinute is redundant and duration is mandotary
Sample Requests
curl -X POST  'https://api.opsgenie.com/v1/policies'
    --header 'Authorization: GenieKey eb24brs-faa2-4ba2-a551q-1brsf565c889'
    --header 'Content-Type: application/json'
    --data
'{
    "enabled":"true",
    "type":"notification-deduplication",
    "name":"notification deduplication policy frequency",
    "deduplicationActionType":"frequency-based",
    "count":5,
    "duration":{
        "timeUnit":"seconds",
        "timeAmount":5
    }
}'
Response:
{
    "data": {
        "id": "7317bdef-afce-46fb-b246-89390ac39b82",
        "name": "notification deduplication policy frequency",
        "type": "notification-deduplication",
        "enabled": true
    },
    "took": 0.038,
    "requestId": "9d39867e-c214-4cc5-a505-8a478c062f3c"
}

Extra Fields for Modify 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}}
ignoreOriginalAlertActions false If set to true, policy will ignore the original alert actions of the alert. Default value is false
alertActions false Alert actions as a list of strings to add to the alerts original actions value. If ignoreOriginalAlertActions 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 Custom properties to add to the alerts original details value as a list of strings. If ignoreOriginalDetails field is set to true, this will replace the original details.
ignoreOriginalRecipients false If set to true, policy will ignore the original recipients of the alert. Default value is false
recipients false Recipients to add to the alerts original recipients value as a list of escalations, schedules, teams, users or the reserved word none or all. If ignoreOriginalRecipients field is set to true, this will replace the original recipients. The possible values for recipients are:
  • user
  • escalation
  • team
  • schedule
  • none
  • all
You can refer here 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 ignoreOriginalRecipients field is set to true, this will replace the original recipients.
ignoreOriginalTeams false If set to true, policy will ignore the original teams of the alert. Default value is false
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
Recipients field example:
{
    "recipients": [
        {
            "type": "schedule",
            "id": "b3578948-55b3-4acc-9bf1-2ce2db3brsa2"
        },
        {
            "type": "team",
            "name": "ops_team"
        },
        {
            "type": "user",
            "username": "user@opsgenie.com"
        }
    ]
}
{
    "recipients": [
        {
            "type": "none"
        }
    ]
}
Sample Requests
curl -X POST  'https://api.opsgenie.com/v1/policies'
    --header 'Authorization: GenieKey eb24brs-faa2-4ba2-a551q-1brsf565c889'
    --header 'Content-Type: application/json'
    --data
'{
    "type":"modify",
    "description":"modify policy description",
    "enabled":"true",
    "filter":{
        "type":"match-all-conditions",
        "conditions":[
            {
                "field":"message",
                "operation":"contains",
                "expectedValue":"dynamodb"
            }
        ]
    },
    "ignoreOriginalRecipients": true,
    "ignoreOriginalTags": true,
    "continue": true,
    "name":"Modify Policy",
    "message":"{{message}} db error",
    "recipients":[{"type":"user","id":"1e1d2ba1-4532-4602-878e-9db1aa927164"}],
    "alias":"{{alias.toLowerCase()}} dynamodb",
    "tags":["dynamodb"],
    "alertDescription":"{{description}}"
}'
Response:
{
    "data": {
        "id": "7317bdef-afce-46fb-b246-89390ac39b82",
        "name": "notification deduplication policy frequency",
        "type": "notification-deduplication",
        "enabled": true
    },
    "took": 0.038,
    "requestId": "9d39867e-c214-4cc5-a505-8a478c062f3c"
}

Get Policy

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

In-Line Parameters

Referred Name Description
identifier Id of the policy
Sample Request
curl -X GET  'https://api.opsgenie.com/v1/policies//2b228902-cc04-4f8a-b64f-a381f1289c9b'
    --header 'Authorization: GenieKey eb24brs-faa2-4ba2-a551q-1brsf565c889'
Response:
{
    "data": {
        "type": "notification-deduplication",
        "policyDescription": "notification deduplication description",
        "id": "2b228902-cc04-4f8a-b64f-a381f1289c9b",
        "name": "notification deduplication policy value-based",
        "enabled": true,
        "filter": {
            "type": "match-all-conditions",
            "conditions": [
                {
                    "field": "message",
                    "not": false,
                    "operation": "contains",
                    "expectedValue": "message",
                    "order": 0
                },
                {
                    "field": "recipients",
                    "not": true,
                    "operation": "contains",
                    "expectedValue": "recipient",
                    "order": 0
                }
                ]
            },
            "timeRestrictions": {
                "type": "time-of-day",
                "restriction": {
                "startHour": 20,
                "endHour": 5,
                "startMin": 23,
                "endMin": 10
            }
        },
        "deduplicationActionType": "value-based",
        "count": 10
    },
    "took": 0.028,
    "requestId": "2c2ad4de-9e76-405d-ad13-e9367f524de3"
}

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 with create requests.

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

In-Line Parameters

Referred Name Description
identifier Identifier of the policy
Sample Request
curl -X PUT 'https://api.opsgenie.com/v1/policies/c059164d-92dc-4a96-8caa-e70840a545a8'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1brsf565c889'
    --header 'Content-Type: application/json'
    --data
'{
    "policyDescription":"updated description",
    "enabled":"true",
    "filter":{
        "type":"match-all-conditions",
        "conditions":[
            {
                "field":"recipients",
                "operation":"contains",
                "expectedValue":"recipient",
                "not":true
            },
            {
                "field":"message",
                "operation":"contains",
                "expectedValue":"message"
            }
        ]
    },
    "type":"notification-suppress",
    "name":"notification suppress"
}'
Response:
{
    "result": "Updated",
    "took": 0.038,
    "requestId": "23b33e2a-cc5c-457a-84a7-12d4171c7b7c"
}

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

In-Line Parameters

Referred Name Description
identifier Id of the policy
Sample Request
curl -X DELETE 'https://api.opsgenie.com/v1/policies/53352b69-1ede-42c6-a0fe-73291019f18e'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1brsf565c889'
Response:
{
    "result": "Deleted",
    "took": 0.059,
    "requestId": "3b2a3666-b3f6-4ac4-b6ca-5a84d395ce20"
}

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

In-Line Parameters

Referred Name Description
identifier Id of the policy
Sample Request
curl -X POST 'https://api.opsgenie.com/v1/policies/2b228902-cc04-4f8a-b64f-a381f1289c9b/disable'
    --header 'Authorization: GenieKey eb243592-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/v1/policies/:identifier/enable

In-Line Parameters

Referred Name Description
identifier Id of the policy
Sample Request
curl -X POST 'https://api.opsgenie.com/v1/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/v1/policies/:identifier/enable

In-Line Parameters

Referred Name Description
identifier Id of the policy

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
curl -X POST 'https://api.opsgenie.com/v1/policies/2b228902-cc04-4f8a-b64f-a381f1289c9b/change-order'
    --header 'Authorization: GenieKey eb243592-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 Policies

HTTP Method URL
GET https://api.opsgenie.com/v1/policies
Policies are ordered in groups (auto-restart, auto-close, notification and modify policies)
Sample Request
curl -X GET 'https://api.opsgenie.com/v1/policies'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1brsf565c889'
Response:
{
    "data": [
        {
            "id": "a697b628-e0e3-4043-b01f-6b587e5e98a0",
            "name": "notification suppress",
            "type": "notification-suppress",
            "order": 0,
            "enabled": true
        },
        {
            "id": "2b228902-cc04-4f8a-b64f-a381f1289c9b",
            "name": "notification deduplication policy value-based",
            "type": "notification-deduplication",
            "order": 1,
            "enabled": true
        },
        {
            "id": "df579b69-39ef-470e-a2e5-899045f74369",
            "name": "notification deduplication policy frequency",
            "type": "notification-deduplication",
            "order": 2,
            "enabled": true
        },
        {
            "id": "72343cf5-38f4-4641-96c4-f49b0a38ba29",
            "name": "notification delay-until",
            "type": "notification-delay",
            "order": 3,
            "enabled": true
        },
        {
            "id": "7317bdef-afce-46fb-b246-89390ac39b82",
            "name": "notification deduplication",
            "type": "notification-deduplication",
            "order": 4,
            "enabled": true
        },
        {
            "id": "1b4ccb42-32bb-477f-a48d-d4fa3c8ac250",
            "name": "auto restart policy",
            "type": "auto-restart-notifications",
            "order": 0,
            "enabled": true
        },
        {
            "id": "bcf68e62-bf5f-4483-8e57-554e4881420f",
            "name": "auto close policy",
            "type": "auto-close",
            "order": 0,
            "enabled": true
        },
    ],
    "took": 0.027,
    "requestId": "bbe30c0b-c6e5-4102-92f1-d7dd8b645124"
}

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

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

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, extra-properties, recipients or teams
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
timeAmount true Amount of time
duration field example:
"duration":{
    "timeAmount":10,
    "timeUnit":"minutes"
}
"duration":{
    "timeAmount":5,
    "timeUnit":"days"
}