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

JSON Body Fields

FieldsMandatoryDescription
descriptionfalseDescription for the maintenance
timetrueTime 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
rulestrueRules 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

In-Line Parameters

Referred NameDescription
maintenanceIdId 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

In-Line Parameters

Referred NameDescription
maintenanceIdId of the maintenance

JSON Body Fields

FieldsMandatoryDescription
descriptionfalseDescription for the maintenance
timetrueTime 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
rulestrueRules 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

In-Line Parameters

Referred NameDescription
maintenanceIdId 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

Query Parameters

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

In-Line Parameters

Referred NameDescription
maintenanceIdId 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"
}

Fields of Time Object

FieldMandatoryDescription
typetrueThis 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
startDatetrue*This parameter takes a date format as (yyyy-MM-dd'T'HH:mm:ssZ) (e.g. 2017-01-15T08:00:00+02:00).
endDatetrue*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

FieldMandatoryDescription
entitytrueThis 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
statetrue*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