Guides
Log InStart Free Trial
Start typing to search…

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

Updated 8 days ago