Team Routing 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

📘

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.

📘

All requests of Team Routing Rule API work under Team domain. It means that; If you are using apiKey belongs to a team integration, that team must allowed to access given team. Otherwise, we would respond with 403 - Forbidden (Unauthorized) with 40301 internal code (Response)

Create Team Routing Rule

Create team routing 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
teamIdentifierIdentifier of the team

Query Parameters

ParameterMandatoryDescription
teamIdentifierTypefalseType of the team identifier that is provided as an in-line parameter. Possible values are id and name . Default value is id

JSON Body Fields

FieldsMandatoryDescription
namefalseName of the team routing rule
orderfalseThe order of the team routing rule within the rules. order value is actually the index of the team routing rule whose minimum value is 0 and whose maximum value is n-1 (number of team routing rules is n)
timezonefalseTimezone of team routing rule. If timezone field is not given, account timezone is used as default. You can refer to Supported Locale IDs for available timezones. More information about timezones can be found in Time Constraints and Timezones document.
criteriafalseYou can refer Criteria for detailed information about criteria and its fields
timeRestrictionfalseYou can refer Time Restriction for detailed information about time restriction and its fields
notifytrueTarget entity of schedule, escalation, or the reserved word none which will be notified in routing rule. The possible values for notify type are:
schedule
escalation
* none
You can refer below for example values

notify field example:

{
    "notify": {
        "type": "escalation",
        "id": "b3578948-55b3-4acc-9bf1-2ce2db3alpa2"
    }
}
{
    "notify": {
        "type": "none"
    }
}
{
    "notify": {
        "type": "schedule",
        "name": "ScheduleName"
    }
}

Sample Request

curl -X POST  'https://api.opsgenie.com/v2/teams/TeamName/routing-rules?teamIdentifierType=name'
    --header 'Authorization: GenieKey eb24alp-faa2-4ba2-a551q-1alpf565c889'
    --header 'Content-Type: application/json'
    --data
'{
    "name": "RoutingRuleName",
    "order": 0,
    "timezone": "America/Los_Angeles",
    "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"
            }
        ]
    },
    "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
            }
        ]
    },
    "notify": {
        "id":"2alp0c95-8982-435c-b91d-bebe4f833b50",
        "type":"schedule"
    }
}'

Response:

{
    "result": "Created",
    "data": {
        "id": "dbe375e3-b7d4-4e18-balp-8c47fd4de27a"
    },
    "took": 0.085,
    "requestId": "23cefb5d-6475-47e0-alp9-b8481653ce6e"
}

Get Team Routing Rule

In-Line Parameters

Referred NameDescription
teamIdentifierIdentifier of the team
idId of the team routing rule

Query Parameters

ParameterMandatoryDescription
teamIdentifierTypefalseType of the team identifier that is provided as an in-line parameter. Possible values are id and name . Default value is id

Sample Request

curl -X GET  'https://api.opsgenie.com/v2/teams/TeamName/routing-rules/c8214a84-09e1-4961-9ee6-f977falp637d?teamIdentifierType=name'
    --header 'Authorization: GenieKey eb24alp-faa2-4ba2-a551q-1alpf565c889'

Response

{
    "data": {
        "id": "c8214a84-09e1-4961-9ee6-f977falp637d",
        "name": "RoutingRuleName",
        "isDefault": false,
        "order": 0,
        "criteria": {
            "type": "match-any-condition",
            "conditions": [
                {
                    "field": "message",
                    "not": false,
                    "operation": "contains",
                    "expectedValue": "expected1",
                    "order": 0
                },
                {
                    "field": "alias",
                    "not": true,
                    "operation": "starts-with",
                    "expectedValue": "expected2",
                    "order": 0
                },
                {
                    "field": "extra-properties",
                    "key": "expectedKey",
                    "not": true,
                    "operation": "starts-with",
                    "expectedValue": "expected3",
                    "order": 0
                }
            ]
        },
        "timezone": "America/Los_Angeles",
        "timeRestriction": {
            "type": "weekday-and-time-of-day",
            "restrictions": [
                {
                    "startDay": "monday",
                    "endDay": "tuesday",
                    "startHour": 8,
                    "endHour": 18,
                    "startMin": 0,
                    "endMin": 30
                },
                {
                    "startDay": "wednesday",
                    "endDay": "thursday",
                    "startHour": 8,
                    "endHour": 18,
                    "startMin": 0,
                    "endMin": 30
                }
            ]
        },
        "notify": {
            "type": "schedule",
            "id": "d875e654-9b4e-4219-a803-0c2693alp8de",
            "name": "ScheduleName"
        }
    },
    "took": 0.325,
    "requestId": "8alp66db-a250-4f5b-baa4-3765028954e3"
}

Update Team Routing Rule (Partial)

Update team routing 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
teamIdentifierIdentifier of the team
idId of the team routing rule

Query Parameters

ParameterMandatoryDescription
teamIdentifierTypefalseType of the team identifier that is provided as an in-line parameter. Possible values are id and name . Default value is id

JSON Body Field

FieldsMandatoryDescription
namefalseName of the team routing rule
timezonefalseTimezone of team routing rule. If timezone field is not given, account timezone is used as default. You can refer to Supported Locale IDs for available timezones. More information about timezones can be found in Time Constraints and Timezones
criteriafalseYou can refer Criteria for detailed information about criteria and its fields
timeRestrictionfalseYou can refer Time Restriction for detailed information about time restriction and its fields
notifyfalseTarget entity of schedule, escalation, or the reserved word none which will be notified in routing rule. The possible values for notify type are:
schedule
escalation
* none
You can refer below for example.

notify field example:

{
    "notify": {
        "type": "escalation",
        "id": "b3578948-55b3-4acc-9bf1-2ce2db3alpa2"
    }
}
{
    "notify": {
        "type": "none"
    }
}
{
    "notify": {
        "type": "schedule",
        "name": "ScheduleName"
    }
}

Sample Request

curl -X PATCH 'https://api.opsgenie.com/v2/teams/TeamName/routing-rules/c8214a84-09e1-4961-9ee6-f977falp637d?teamIdentifierType=name'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1alpf565c889'
    --header 'Content-Type: application/json'
    --data
'{
    "name": "UpdatedRoutingRuleName",
    "timezone": "America/Los_Angeles",
    "criteria": {
        "type": "match-all"
    },
    "notify": {
        "type":"none"
    }
}'

Response:

{
    "result": "Updated",
    "data": {
        "id": "c8214a84-09e1-4961-9ee6-f977falp637d"
    },
    "took": 0.355,
    "requestId": "8b8debbc-e1a4-4ac2-a27b-7bc2f6alpc06"
}

Delete Team Routing Rule

Delete team routing 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
teamIdentifierIdentifier of the team
idId of the team routing rule

Query Parameters

ParameterMandatoryDescription
teamIdentifierTypefalseType of the team identifier that is provided as an in-line parameter. Possible values are id and name . Default value is id

Sample Request

curl -X DELETE 'https://api.opsgenie.com/v2/teams/TeamName/routing-rules/c8214a84-09e1-4961-9ee6-f977falp637d?teamIdentifierType=name'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1alpf565c889'

Response:

{
    "result": "Deleted",
    "took": 0.063,
    "requestId": "eec8d515-alpb-47c2-8f64-54f555162658"
}

List Team Routing Rules

In-Line Parameters

Referred NameDescription
teamIdentifierIdentifier of the team

Query Parameters

ParameterMandatoryDescription
teamIdentifierTypefalseType of the team identifier that is provided as an in-line parameter. Possible values are id and name. Default value is id

Sample Request

curl -X GET 'https://api.opsgenie.com/v2/teams/TeamName/routing-rules?teamIdentifierType=name'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1alpf565c889'

Response:

{
    "data": [
        {
            "id": "27alpc95-8982-435c-b91d-bebe4f833b50",
            "name": "RoutingRuleName",
            "isDefault": false,
            "order": 0,
            "criteria": {
                "type": "match-any-condition",
                "conditions": [
                    {
                        "field": "message",
                        "not": false,
                        "operation": "contains",
                        "expectedValue": "expected1",
                        "order": 0
                    },
                    {
                        "field": "alias",
                        "not": true,
                        "operation": "starts-with",
                        "expectedValue": "expected2",
                        "order": 0
                    },
                    {
                        "field": "extra-properties",
                        "key": "expectedKey",
                        "not": true,
                        "operation": "starts-with",
                        "expectedValue": "expected3",
                        "order": 0
                    }
                ]
            },
            "timezone": "America/Los_Angeles",
            "timeRestriction": {
                "type": "weekday-and-time-of-day",
                "restrictions": [
                    {
                        "startDay": "monday",
                        "endDay": "tuesday",
                        "startHour": 8,
                        "endHour": 18,
                        "startMin": 0,
                        "endMin": 30
                    },
                    {
                        "startDay": "wednesday",
                        "endDay": "thursday",
                        "startHour": 8,
                        "endHour": 18,
                        "startMin": 0,
                        "endMin": 30
                    }
                ]
            },
            "notify": {
                "type": "schedule",
                "id": "d875e654-9b4e-4219-a803-0c2693alp8de",
                "name": "ScheduleName"
            }
        },
        {
            "id": "727alpd0-9e15-4b96-97f9-096fbb403c0d",
            "name": "",
            "isDefault": false,
            "order": 1,
            "criteria": {
                "type": "match-all"
            },
            "timezone": "America/Los_Angeles",
            "notify": {
                "type": "none"
            }
        },
        {
            "id": "420c1489-1d9b-430c-8025-115alp95d0ea",
            "name": "Default Routing Rule",
            "isDefault": true,
            "order": 2,
            "criteria": {
                "type": "match-all"
            },
            "timezone": "America/Los_Angeles",
            "notify": {
                "type": "escalation",
                "id": "8b8debbc-e1a4-4ac2-a27b-7bc2f6alpc06",
                "name": "TeamName_escalation"
            }
        }
    ],
    "took": 1.424,
    "requestId": "f6alp3f0-40bc-4c51-a824-59938591b835"
}

Change Team Routing Rule Order

Change team routing rule 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

In-Line Parameters

Referred NameDescription
teamIdentifierIdentifier of the team
idId of the team routing rule

Query Parameters

ParameterMandatoryDescription
teamIdentifierTypefalseType of the team identifier that is provided as an in-line parameter. Possible values are id and name . Default value is id

JSON Body Fields

FieldsMandatoryDescription
ordertrueThe order of the team routing rule within the rules. Value is actually the index of the team routing rule whose minimum value is 0 and whose maximum value is n-1 (number of team routing rules is n).

Sample Request

curl -X POST 'https://api.opsgenie.com/v2/teams/TeamName/routing-rules/13a3alp1-5f0c-4370-a033-87a7f3be5d0e/change-order?teamIdentifierType=name'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1alpf565c889'
    --data
'{
    "order": 666
'}

Response:

{
    "result": "Changed",
    "data": {
        "id": "13a3alp1-5f0c-4370-a033-87a7f3be5d0e"
    },
    "took": 0.155,
    "requestId": "1256ca0e-224d-4ec5-9a43-8b635f90alp2"
}

Criteria Fields

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

JSON Body Fields

FieldsMandatoryDescription
typetrue Type 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 team routing rule 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 team routing rule start working
startMintrue Value of the minute that team routing rule start working
endHourtrue Value of the hour that team routing rule end working
endMintrue Value of the minute that team routing rule end working

restriction field example:

{
    "timeRestriction": {
        "type" : "time-of-day",
        "restriction" :
        {
            "startHour" : 8,
            "startMin" : 20,
            "endHour" : 19,
            "endMin" : 40
        }
    }
}

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:

FieldMandatoryDescription
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 routing rule 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 team routing rule start working
startMintrue Value of the minute that team routing rule start working
endDaytrue Name of day which routing rule 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 team routing rule end working
endMintrueValue of the minute that team routing rule end working

restrictions field example:

{
    "timeRestriction": {
        "type" : "weekday-and-time-of-day",
        "restrictions" : [
            {
                "startDay" : "monday",
                "startHour" : 8,
                "startMin" : 20,
                "endDay" : "tuesday",
                "endHour" : 18,
                "endMin" : 45
            },
            {
                "startDay" : "wednesday",
                "startHour" : 8,
                "startMin" : 20,
                "endDay" : "thursday",
                "endHour" : 18,
                "endMin" : 45
            }
        ]
    }
}