Escalation 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 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
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"
    }
}'
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"
                }
            }
        ]
    },
    "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 here for more information
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":"user@opsgenie.com"
            }
        },
        {
            "delay" : {
                "timeAmount" : 5
            },
            "recipient" : {
                "type" : "schedule",
                "name" : "ops_team_schedule"
            }
        }
    ]
}'
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": "alp@opsgenie.com"
                    }
                }
            ]
        },
        {
            "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 here 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": "user@opsgenie.com"
    }
}
{
   "recipient": {
        "type": "schedule"
        "name": ScheduleName"
    }
}
delay field example:
{
    "delay": {
        "timeAmount": 5
    }
}