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 anAPI 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 Name

Description

teamIdentifier

Identifier of the team

Query Parameters

Parameter

Mandatory

Description

teamIdentifierType

false

Type 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

Fields

Mandatory

Description

name

false

Name of the team routing rule

order

false

The 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 isn-1(number of team routing rules is n)

timezone

false

Timezone 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.

criteria

false

You can refer Criteria for detailed information about criteria and its fields

timeRestriction

false

You can refer Time Restriction for detailed information about time restriction and its fields

notify

true

Target 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 Name

Description

teamIdentifier

Identifier of the team

id

Id of the team routing rule

Query Parameters

Parameter

Mandatory

Description

teamIdentifierType

false

Type 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 Name

Description

teamIdentifier

Identifier of the team

id

Id of the team routing rule

Query Parameters

Parameter

Mandatory

Description

teamIdentifierType

false

Type 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

Fields

Mandatory

Description

name

false

Name of the team routing rule

timezone

false

Timezone 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.

criteria

false

You can refer Criteria for detailed information about criteria and its fields

timeRestriction

false

You can refer Time Restriction for detailed information about time restriction and its fields

notify

false

Target 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 Name

Description

teamIdentifier

Identifier of the team

id

Id of the team routing rule

Query Parameters

Parameter

Mandatory

Description

teamIdentifierType

false

Type 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 Name

Description

teamIdentifier

Identifier of the team

Query Parameters

Parameter

Mandatory

Description

teamIdentifierType

false

Type 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 Name

Description

teamIdentifier

Identifier of the team

id

Id of the team routing rule

Query Parameters

Parameter

Mandatory

Description

teamIdentifierType

false

Type 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

Fields

Mandatory

Description

order

true

The 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

Fields

Mandatory

Description

type

true

Type of the operation will be applied on conditions. Should be one ofmatch-all, match-any-condition or match-all-conditions

conditions

true*

List of conditions will be checked before applying team routing rule

📘

If operationtype 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 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:

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 team routing rule start working

startMin

true

Value of the minute that team routing rule start working

endHour

true

Value of the hour that team routing rule end working

endMin

true

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:

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

startHour

true

Value of the hour that team routing rule start working

startMin

true

Value of the minute that team routing rule start working

endDay

true

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

endHour

true

Value of the hour that team routing rule end working

endMin

true

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