Migration Guide for Alert Rest API

API v1 was deprecated on May 2017 when Rest API was released. As of June 30, 2018, API v1 is going to be inaccessible for all customers (Currently, only the customers that were signed up before October 2017 have access to API v1).

This documentation is a general guideline to migrate to Alert Rest API.

📘

Lamp Command Line

If you're using Lamp: Command Line to access the Alert API, updating your Lamp to the latest version will automatically route your requests to the new Rest API.

1. Base URL

Base URL of the Alert Rest API is https://api.opsgenie.com/v2/alerts. It was https://api.opsgenie.com/v1/json/alert for Alert API v1.

2. Authentication

API Key is moved to Authentication header instead of request payloads. You can refer Rest API Authentication for further information.

3. Asynchronous Actions

Alert creation, deletion and action requests are processed asynchronously to provide higher availability and scalability, therefore valid requests for those endpoints are responded with 202 - Accepted. The status / result of the request can be tracked via Get Request Status endpoint using the universally unique identifier of the request that you want to track. Please note: ID of the request is provided within the response of the request that you want to track.

The following is an example response for a valid create, delete or action request:

{
    "result": "Request will be processed",
    "took": 0.302,
    "requestId": "43a29c5c-3dbf-4fa4-9c26-f4f71023e120"
}

The following is an example response of the Get Request Status endpoint:

{
    "data": {
        "success": true,
        "action": "Create",
        "processedAt": "2017-05-24T14:24:20.844Z",
        "integrationId": "c9cec2cb-e782-4ebb-bc1d-1b2fa703cf03",
        "isSuccess": true,
        "status": "Created alert",
        "alertId": "8743a1b2-11da-480e-8493-744660987bef",
        "alias": "8743a1b2-11da-480e-8493-744660987bef"
    },
    "took": 0.022,
    "requestId": "ec7e1d8e-1c75-442e-a271-731070a7fa4d"
}

4. Responders Field

responders field is introduced to Create Alerts instead of recipients and teams fields. Teams, users, escalations and schedules that you want to route the alert can be identified with IDs or names of them, and type key is mandatory for each.

The following is an example responders field from the request payload:

{
    "responders": [
        {
            "id":"4513b7ea-3b91-438f-b7e4-e3e54af9147c",
            "type":"team"
        },
        {
            "name":"NOC",
            "type":"team"
        },
        {
            "id":"bb4d9938-c3c2-455d-aaab-727aa701c0d8",
            "type":"user"
        },
        {
            "username":"[email protected]",
            "type":"user"
        },
        {
            "id":"aee8a0de-c80f-4515-a232-501c0bc9d715",
            "type":"escalation"
        },
        {
            "name":"Nightwatch Escalation",
            "type":"escalation"
        },
        {
            "id":"80564037-1984-4f38-b98e-8a1f662df552",
            "type":"schedule"
        },
        {
            "name":"First Responders Schedule",
            "type":"schedule"
        }
    ]
}

📘

Create Alert Request of the Alert Rest API is compatible with the Alert API v1 in terms of remaining payload fields that are alias , message, description, priority, actions , source , tags , details , entity , user and note.