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

Create maintenance 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/v1/maintenance

JSON Body Fields

Fields	Mandatory	Description
description	false	Description for the maintenance
time	true	Time configuration of maintenance. It takes a time object which has `type`, `startDate` and `endDate` fields. You can refer here for more information about the field definition
rules	true	Rules of maintenance, which takes a list of rule objects and defines the maintenance rules over integrations and policies. You can refer here for more information about the field definition

Sample Request:

curl -X POST 'https://api.opsgenie.com/v1/maintenance'
    --header 'Authorization: GenieKey eb24alp-faa2-4ba2-a551q-1alpf565c889'
    --header 'Content-Type: application/json'
    --data
'{
    "description": "Maintenance Description",
    "time": {
        "type" : "schedule",
        "startDate": "2018-03-25T08:45:00Z",
        "endDate": "2018-03-25T21:45:00Z"
    },
    "rules": [
        {
            "state": "enabled",
            "entity": {
                "id": "00746f59-a826-4a83-91ff-f00calpc5073",
                "type": "policy"
            }
        }
    ]
}'

Response:

{
    "data": {
        "id": "b0ee8414-1d29-45c3-850f-11dbf0f1402f",
        "status": "planned",
        "time": {
            "type": "schedule",
            "startDate": "2018-03-25T08:45:00Z",
            "endDate": "2018-03-25T21:45:00Z"
        },
        "description": "Maintenance Description"
    },
    "took": 0.149,
    "requestId": "6d48d850-feb2-4871-bc0c-8f2f1715b751"
}

Get Maintenance

HTTP Method	URL
GET	https://api.opsgenie.com/v1/maintenance/:maintenanceId

In-Line Parameters

Referred Name	Description
maintenanceId	Id of the maintenance

Sample Request:

curl -X GET 'https://api.opsgenie.com/v1/maintenance/32fff5fe-ae03-4ce8-b9e7-a2a4e5alp65d'
    --header 'Authorization: GenieKey eb24alp-faa2-4ba2-a551q-1alpf565c889'

Response:

{
    "data": {
        "id": "b0ee8414-1d29-45c3-850f-11dbf0f1402f",
        "status": "planned",
        "rules": [
            {
                "state": "enabled",
                "entity": {
                    "id": "1d9530bb-a079-43d9-8535-bbfd2fb6f8af",
                    "type": "policy"
                }
            }
        ],
        "time": {
            "type": "schedule",
            "startDate": "2018-03-25T08:45:00Z",
            "endDate": "2018-03-25T21:45:00Z"
        },
        "description": "Maintenance Description"
    },
    "took": 1.165,
    "requestId": "f9ab08f1-484f-44b3-a8e7-9f894a6e84fe"
}

Update Maintenance

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

HTTP Method	URL
PUT	https://api.opsgenie.com/v1/maintenance/:maintenanceId

In-Line Parameters

Referred Name	Description
maintenanceId	Id of the maintenance

JSON Body Fields

Fields	Mandatory	Description
description	false	Description for the maintenance
time	true	Time configuration of maintenance. It takes a time object which has `type`, `startDate` and `endDate` fields. You can refer here for more information about the field definition
rules	true	Rules of maintenance, which takes a list of rule objects and defines the maintenance rules over integrations and policies. You can refer here for more information about the field definition

Sample Request:

curl -X PUT 'https://api.opsgenie.com/v1/maintenance/32fff5fe-ae03-4ce8-b9e7-a2a4e5alp65d'
    --header 'Authorization: GenieKey eb24alp-faa2-4ba2-a551q-1alpf565c889'
    --header 'Content-Type: application/json'
    --data
'{
    "time" : {
        "type" : "schedule",
        "startDate": "2017-03-30T11:41:00Z",
        "endDate":"2017-03-30T12:15:00Z"
    },
    "rules" : [
        {
            "entity" : {
                "type" : "integration",
                "id" : "00746f59-a826-4a83-91ff-f00caeec5073"
            },
            "state" : "enabled"
        }
    ]
}'

Response:

{
    "data": {
        "id": "32fff5fe-ae03-4ce8-b9e7-a2a4e5alp65d",
        "status": "planned",
        "time": {
            "type": "schedule",
            "startDate": "2018-03-30T11:41:00Z",
            "endDate": "2018-03-30T12:15:00Z"
        },
        "description": "Maintenance Description"
    },
    "took": 0.064,
    "requestId": "291f1ab1-6090-4c53-aea0-361a0074739f"
}

🚧
If maintenance status is active or cancelled, it cannot be updated

Delete Maintenance

Delete maintenance 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/v1/maintenance/:maintenanceId

In-Line Parameters

Referred Name	Description
maintenanceId	Id of the maintenance

Sample Request

curl -X DELETE 'https://api.opsgenie.com/v1/maintenance/32fff5fe-ae03-4ce8-b9e7-a2a4e5bda65d'
    --header 'Authorization: GenieKey eb24alp-faa2-4ba2-a551q-1alpf565c889'

Response:

{
    "result": "Deleted",
    "took": 0.067,
    "requestId": "43d7c4f5-0c95-491a-8168-0bfbcd01f8b7"
}

List Maintenance

HTTP Method	URL
GET	https://api.opsgenie.com/v1/maintenance

Query Parameters

Parameter	Mandatory	Description
type	false	Defines which maintenance will be listed according to maintenance status. This parameter is all by default, and should be one of all, non-expired or past

Sample Request For Non-Expired Maintenance:

curl -X GET 'https://api.opsgenie.com/v1/maintenance?type=non-expired'
    --header 'Authorization: GenieKey eb24alp-faa2-4ba2-a551q-1alpf565c889'

Response

{
    "data": [
        {
            "id": "20b78362-9d1e-43e0-8b86-3026b7071109",
            "status": "planned",
            "time": {
                "type": "schedule",
                "startDate": "2017-03-20T11:41:00Z",
                "endDate": "2017-03-20T12:15:00Z"
            },
            "description": "Maintenance1"
        },
        {
            "id": "32fff5fe-ae03-4ce8-b9e7-a2a4e5bda65d",
            "status": "active",
            "time": {
                "type": "indefinitely"
            },
            "description": "Maintenance2"
        }
    ],
    "took": 0.115,
    "requestId": "ecbe0030-21b7-4aa3-8e54-1970cc934490"
}

Sample Request For Past Maintenance:

curl -X GET 'https://api.opsgenie.com/v1/maintenance?type=past'
    --header 'Authorization: GenieKey eb24alp-faa2-4ba2-a551q-1alpf565c889'

Response:

{
    "data": [
        {
            "id": "9aa71390-fe1c-425a-ad52-f1cfbdf56091",
            "status": "past",
            "time": {
                "type": "for-1-hour"
            },
            "description": "Maintenance Description"
        }
    ],
    "took": 1.166,
    "requestId": "df1e7f69-a0e8-4081-875d-56b5fdba094a"
}

Cancel Maintenance

Cancel maintenance 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/v1/maintenance/:maintenanceId/cancel

In-Line Parameters

Referred Name	Description
maintenanceId	Id of the maintenance

Sample Request:

curl -X POST 'https://api.opsgenie.com/v1/maintenance/32fff5fe-ae03-4ce8-b9e7-a2a4e5bda65d/cancel'
    --header 'Authorization: GenieKey eb24alp-faa2-4ba2-a551q-1alpf565c889'

Response:

{
    "result": "Cancelled",
    "took": 0.061,
    "requestId": "9c62b255-a0fa-4390-97a6-317dc7cb577a"
}

Change Maintenance End Date

Change maintenance end date 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/v1/maintenance/:maintenanceId/change-end-date

In-Line Parameters

Referred Name	Description
maintenanceId	Id of the maintenance

Sample Request:

curl -X POST 'https://api.opsgenie.com/v1/maintenance/32fffalp-ae03-4ce8-b9e7-a2a4e5bda65d/change-end-date'
    --header 'Authorization: GenieKey eb24alp-faa2-4ba2-a551q-1alpf565c889'
    --header 'Content-Type: application/json'
    --data
'{
    "endDate":"2017-03-30T12:15:00Z"
 }'

Response:

{
    "data": [
        {
            "id": "9aa71390-fe1c-425a-ad52-f1cfbdf56091",
            "status": "past",
            "time": {
                "type": "for-1-hour"
            },
            "description": "Maintenance Description"
        }
    ],
    "took": 1.166,
    "requestId": "df1e7f69-a0e8-4081-875d-56b5fdba094a"
}

Fields of Time Object

Field	Mandatory	Description
type	true	This parameter defines when the maintenance will be active. It can take one of for-5-minutes, for-30-minutes, for-1-hour, indefinitely or schedule
startDate	true*	This parameter takes a date format as (yyyy-MM-dd'T'HH:mm:ssZ) (e.g. 2017-01-15T08:00:00+02:00).
endDate	true*	This parameter takes a date format as (yyyy-MM-dd'T'HH:mm:ssZ) (e.g. 2017-01-15T08:00:00+02:00).

🚧
startDate and endDate fields are mandatory for only schedule type maintenance

Fields of Rules Object

Field	Mandatory	Description
entity	true	This field represents the entity that maintenance will be applied. Entity field takes two mandatory fields as `id` and `type` id:The id of the entity that maintenance will be applied. type: The type of the entity that maintenance will be applied. It can be either integration or policy
state	true*	State of rule that will be defined in maintenance and can take either enabled or disabled for policy type rules. This field has to be disabled for integration type entity rules

🚧
state field is not mandatory for integration type maintenance, it is disabled by default