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

Create Escalation

Create escalation request is used to add new escalations in Opsgenie and it 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/escalations

JSON Body Fields

Fields	Mandatory	Description
name	true	Name of the escalation
description	false	Description of the escalation
rules	true	List of the escalation rules. You can refer Escalation Rules for detailed information about members and their fields
ownerTeam	false	Owner team of the escalation, consisting `id` and/or `name` of the owner team
repeat	false	Repeat preferences of the escalation including repeat interval, count, reverting acknowledge and seen states back and closing an alert automatically as soon as repeats are completed. You can refer Escalation Repeat for detailed information about its fields.

🚧
If integration belongs to any team, it automatically overwrite ownerTeam object. Otherwise id or name fields should be specified in ownerTeam

ownerTeam field example

{
    "ownerTeam": {
        "name":"network_team"
    }
}

{
    "ownerTeam": {
        "id":"8418d193-2alp-4490-b331-8c02cdd196b7"
    }
}

Sample Request

curl -X POST 'https://api.opsgenie.com/v2/escalations'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889'
    --header 'Content-Type: application/json'
    --data
'{
    "name" : "newEscalation",
    "rules" : [
        {
            "delay": {
                "timeAmount" : 1
            },
            "recipient":{
                "type" : "schedule",
                "name": "ops_team_schedule"
            },
            "notifyType" : "default",
            "condition": "if-not-acked"
        }
    ],
    "ownerTeam" : {
        "name" : "ops_team"
    },
    "repeat": {
      "waitInterval": 15,
      "count": 13,
      "resetRecipientStates": true,
      "closeAlertAfterAll": true
    }
}'

Response:

{
    "result" : "Created"
    "data": {
        "name": "newEscalation",
        "id": "e64fd6f2-4721-4dae-b03f-1905bb3ed84a"
    },
    "took": 0.888,
    "requestId": "53ca115f-1b92-4cb3-983c-daea8fc33b69"
}

Get Escalation

Get escalation request is used to search and retrieve escalations in OpsGenie. It takes the following parameters:

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

In-Line Parameters

Referred Name	Description
identifier	Identifier of the escalation

Query Parameters

Parameter	Mandatory	Description
identifierType	false	Type of the 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/escalations/e64fd6f2-4721-4dae-b03f-1905bb3ed84a'
        --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889'

Response:

{
    "data": {
        "id": "4f5f0d44-e7bc-4f2a-a321-2f8d81cb7575",
        "name": "newEscalation",
        "description": "newEscalation description",
        "ownerTeam": {
            "id": "3d82c05a-2baa-47f1-bc9c-335018cf3269",
            "name" : "ops_team"
        },
        "rules": [
            {
                "condition": "if-not-acked",
                "notifyType": "default",
                "delay": {
                    "timeAmount": 1,
                    "timeUnit": "minutes"
                },
                "recipient": {
                    "type": "schedule",
                    "id": "03a30519-39aa-4e4b-94b6-29a5ea4faca1",
                    "name": "ops_team_schedule"
                }
            }
        ],
        "repeat": {
          "waitInterval": 15,
          "count": 13,
          "resetRecipientStates": true,
          "closeAlertAfterAll": true
      	}
    },
    "took": 0.034,
    "requestId": "1f8ea4fc-874a-45d9-b794-604fabec7f2d"
}

Update Escalation (Partial)

Update escalation request is used to update escalation in partial manner and it 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/escalations/:identifier

In-Line Parameters

Referred Name	Description
identifier	Identifier of the escalation

Query Parameters

Parameter	Mandatory	Description
identifierType	false	Type of the 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 escalation
description	false	Description of the escalation
rules	false	List of the escalation rules. You can refer Escalation Rules for detailed information about members and their fields
ownerTeam	false	Owner team of the escalation, consisting id and/or name of the owner team You can refer to below for more information
repeat	false	Repeat preferences of the escalation including repeat interval, count, reverting acknowledge and seen states back and closing an alert automatically as soon as repeats are completed options. You can refer Escalation Repeat for detailed information about its fields.

ownerTeam field example

{
    "ownerTeam": {
        "name":"network_team"
    }
}

{
    "ownerTeam": {
        "id":"8418d193-2alp-4490-b331-8c02cdd196b7"
    }
}

Sample Request

curl -X PATCH 'https://api.opsgenie.com/v2/escalations/e64fd6f2-4721-4dae-b03f-1905bb3ed84a'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889'
    --header 'Content-Type: application/json'
    --data
'{
    "name" : "newEscalation",
    "rules" : [
        {
            "delay": {
                "timeAmount": 2
            },
            "recipient": {
                "type":"user",
                "username":"[email protected]"
            },
            "notifyType" : "default",
            "condition": "if-not-acked"
        },
        {
            "delay" : {
                "timeAmount" : 5
            },
            "recipient" : {
                "type" : "schedule",
                "name" : "ops_team_schedule"
            },
            "notifyType" : "default",
            "condition": "if-not-acked"
        }
    ],
    "repeat": {
      "waitInterval": 0
    }

}'

Response:

{
    "result": "Updated",
    "data": {
        "id": "4f5f0d44-e7bc-4f2a-a321-2f8d81cb7575",
        "name": "newEscalation"
    },
    "took": 1.26,
    "requestId": "0f67ccc9-503a-4111-ae7b-59d0177aa1d5"
}

Delete Escalation

Delete escalation request is used to delete escalations in OpsGenie and it 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/escalations/:identifier

In-Line Parameters

Referred Name	Description
identifier	Identifier of the escalation

Query Parameters

Parameter	Mandatory	Description
identifierType	false	Type of the 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/escalations/e64fd6f2-4721-4dae-b03f-1905bb3ed84a'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889'

Response:

{
    "result": "Deleted",
    "took": 1.523,
    "requestId": "24c8be4b-e67d-473d-a7a9-f426dbb38bf5"
}

List Escalations

List escalations request is used to list escalations in OpsGenie. It takes the following parameters:

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

Sample Request

curl -X GET 'https://api.opsgenie.com/v2/escalations'
    --header 'Authorization: GenieKey eb243592-faa2-4ba2-a551q-1afdf565c889'

Response:

{
    "data": [
        {
            "id": "4e8de428-f403-4e82-b46a-4402b8e7a5ed",
            "name": "EscalationName",
            "description": "EscalationDescription",
            "rules": [
                {
                    "condition": "if-not-closed",
                    "notifyType": "default",
                    "delay": {
                        "timeAmount": 0,
                        "timeUnit": "minutes"
                    },
                    "recipient": {
                        "type": "user",
                        "id": "1a1b24d2-a218-4309-af6a-cca8a8e6d344",
                        "username": "[email protected]"
                    }
                }
            ],
            "repeat": {
              "waitInterval": 15,
              "count": 13,
              "resetRecipientStates": true,
              "closeAlertAfterAll": true
            }
        },
        {
            "id": "d8b704e3-665d-4387-8678-2816dc8d4d5a",
            "name": "ops_team_escalation",
            "ownerTeam": {
                "id": "0c55f7f6-e081-4915-91df-d35b459ecaa1",
                "name": "ops_team"
            },
            "rules": [
                {
                    "condition": "if-not-acked",
                    "notifyType": "default",
                    "delay": {
                        "timeAmount": 0,
                        "timeUnit": "minutes"
                    },
                    "recipient": {
                        "type": "schedule",
                        "id": "3bc03dcc-b5eb-475d-9d66-3c574c6a8d3f",
                        "name": "ops_team_schedule"
                    }
                },
                {
                    "condition": "if-not-acked",
                    "notifyType": "next",
                    "delay": {
                        "timeAmount": 5,
                        "timeUnit": "minutes"
                    },
                    "recipient": {
                        "type": "schedule",
                        "id": "3bc03dcc-b5eb-475d-9d66-3c574c6a8d3f",
                        "name": "ops_team_schedule"
                    }
                },
                {
                    "condition": "if-not-acked",
                    "notifyType": "all",
                    "delay": {
                        "timeAmount": 10,
                        "timeUnit": "minutes"
                    },
                    "recipient": {
                        "type": "team",
                        "id": "0c55f7f6-e081-4915-91df-d35b459ecaa1",
                        "name": "ops_team"
                    }
                }
            ]
        },
    ],
    "took": 0.99,
    "requestId": "c5bb2a56-b02d-49e9-b073-f5264fd4115d"
}

Escalation Rules Fields

JSON Body Fields

Fields	Mandatory	Description
condition	true	The condition for notifying the recipient of escalation rule that is based on the alert state. Possible values are: if-not-acked and if-not-closed. If not given, if-not-acked is used.
notifyType	true	Recipient calculation logic for schedules. Possible values are: default: on call users next: next users in rotation previous: previous users on rotation users: users of the team admins: admins of the team all: all members of the team If not given default is used.
recipient	true	Object of schedule, team, or users which will be notified in escalation. The possible values for participants are: user schedule * team You can refer below for example values
delay	true	Time delay of the escalation rule. This parameter takes an object that consists timeAmount field that takes time amount in minutes

🚧
If recipient type is schedule or team, you can use name or id fields for referring to notified. Otherwise (type is user), we use username or id for referencing

recipient field example

{
    "recipient": {
        "type": "team",
        "id": "b3578948-55b3-4acc-9bf1-2ce2db3alpa2"
    }
}

{
    "recipient": {
        "type": "user",
        "username": "[email protected]"
    }
}

{
   "recipient": {
        "type": "schedule"
        "name": ScheduleName"
    }
}

delay field example:

{
    "delay": {
        "timeAmount": 5
    }
}

Escalation Repeat Fields

JSON Body Fields

Fields	Mandatory	Description
waitInterval	false	The duration in minutes to repeat the escalation rules after processing the last escalation rule. It is mandatory if you would like to add or remove repeat option. 0 should be given as a value to disable repeat option. It is 0 by default.
count	false	Repeat time indicating how many times the repeat action will be performed. It is 1 by default.
resetRecipientStates	false	It is for reverting acknowledge and seen states back on each repeat turn if an alert is not closed. It is false by default.
closeAlertAfterAll	false	It is to close the alert automatically if escalation repeats are completed. It is false by default.