Maintenance API

This document is designed for describing the OpsGenie Maintenance API which is a new RESTful API implementation designed around RESTful principles.


General Information

API Requests

Authentication & Authorization

Authentication is required for calling any Maintenance API.

There are two ways for authentication:

  1. Authorization Header
  2. Header Key: Authorization
    Header Value: GenieKey $apiKey

    OR

    Header Key: Authorization
    Header Value: basic $apiKey(base64 encoded)
  3. Query Parameter “apiKey”
  4. Example:
    https://api.opsgenie.com/v1/maintenance?apiKey=$apiKey

Response Codes

In the table below you can find the response codes and their descriptions.

Status Code Internal Code Description
200 - OK Successful
201 - Created A new entity is created
202 - Accepted Request is valid and will be processed asynchronously
400 - Bad Request (Syntax Error only) Invalid JSON body
401 - Unauthenticated (Not Unauthorized) apiKey is invalid or integration is disabled
402 - Payment Required apiKey is valid but the account cannot do this action because of subscription plan
403 - Forbidden (Unauthorized) 40301 apiKey is valid but the apiKey cannot do this operation because of permissions
403 - Forbidden 40302 apiKey is valid and authorized but we do not support the request
404 - Not Found Resource or handler not found
405 - Method Not Allowed URL is valid but HTTP method not supported
406 - Not Acceptable Requested format is not supported (Accept header)
409 - Conflict ID or name conflicts with another entity. E.g. integration name already exists
410 - Gone Feature is deprecated
415 - Unsupported Media Type Request body format is not supported (Content-Type header)
416 - Requested Range Not Satisfiable The given range is not supported.
422 - Unprocessable Entity Semantic errors in request body
428 - Pre Condition Required Entity is used by another entity (schedule,escalation,team,etc)
429 - Too Many Request* Throttling
500 - Internal Server Error
501 - Not Implemented
503 - Service Unavailable* Back-end servers are at capacity.

Create Maintenance

Available Methods

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

Mandatory Parameters

Parameter
time Time configuration of maintenance. This field takes a time object which has 'type', 'startDate' and 'endDate' fields. You can refer here for more about the parameter definition.
rules Rules of maintenance. This field takes a list of rule objects which define the maintenance rules over integrations and policies. You can refer here for more about the parameter definition.

Optional Parameters

Parameter
description This is the description for the maintenance.
Sample Request
curl -H "Content-Type: application/json" -XPOST 'https://api.opsgenie.com/v1/maintenance?apiKey=66495a09-2870-417c-99e9-b61812dc8d42' -d '
{
  "time" : {
    "type" : "schedule",
    "startDate": "2017-03-25T08:45:00+0000",
    "endDate":"2017-03-25T21:45:00+0000"
  },
  "rules" : [
    {
      "entity" : {
        "id" : "00746f59-a826-4a83-91ff-f00caeec5073",
        "type" : "policy"
      },
      "state" : "enabled"
    }
  ]
}'
Response:
{
  "data": {
    "id": "5cf81459-ca34-4173-baf9-783dcc4e8472",
    "status": "planned",
    "time": {
      "type": "schedule",
      "startDate": "2017-03-25T08:45:00+0000",
      "endDate": "2017-03-25T21:45:00+0000"
    },
    "description": "sample maintenance"
  },
  "took": 0.194,
  "requestId": "0fed7f5e-528f-4486-927e-f4e7ab75d45e"
}

Get Maintenance

Available Methods

HTTP Method URL
GET https://api.opsgenie.com/v1/maintenance/$maintenanceId
Sample Request
curl -XGET 'https://api.opsgenie.com/v1/maintenance/32fff5fe-ae03-4ce8-b9e7-a2a4e5bda65d?apiKey=66495a09-2870-417c-99e9-b61812dc8d42'
Response:
"data": {
    "id": "32fff5fe-ae03-4ce8-b9e7-a2a4e5bda65d",
    "status": "active",
    "rules": [
      {
        "entity" : {
            "id": "00746f59-a826-4a83-91ff-f00caeec5073",
            "type": "policy",
        },
        "state": "enabled"
      }
    ],
    "time": {
      "type": "for-1-hour"
    },
    "description": "sample maintenance"
  },
  "took": 0.022,
  "requestId": "4992f8b4-dbae-494d-a564-2163542bfc4f"
}

Update Maintenance

Available Methods

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

Mandatory Parameters

Parameter
time Time configuration of maintenance. This field takes a time object which has 'type', 'startDate' and 'endDate' fields. You can refer here for more about the parameter definition.
rules Rules of maintenance. This field takes a list of rule objects which define the maintenance rules over integrations and policies. You can refer here for more about the parameter definition.

Optional Parameters

Parameter
description This is the description for the maintenance.
Sample Request
curl -H "Content-Type: application/json" -X PUT 'https://api.opsgenie.com/v1/maintenance?apiKey=66495a09-2870-417c-99e9-b61812dc8d42' -d '
{
  "time" : {
    "type" : "schedule",
    "startDate": "2017-03-30T11:41:00+0000",
    "endDate":"2017-03-30T12:15:00+0000"
  },
  "rules" : [
    {
      "entity" : {
        "id" : "00746f59-a826-4a83-91ff-f00caeec5073",
        "type" : "policy"
      },
      "state" : "enabled"
    }
  ]
}'
Response:
{
  "data": {
    "id": "5cf81459-ca34-4173-baf9-783dcc4e8472",
    "status": "planned",
    "time": {
      "type": "schedule",
      "startDate": "2017-03-30T11:41:00+0000",
      "endDate": "2017-03-30T12:15:00+0000"
    },
    "description": "sample maintenance"
  },
  "took": 0.064,
  "requestId": "291f1ab1-6090-4c53-aea0-361a0074739f"
}

Delete Maintenance

Available Methods

HTTP Method URL
DELETE https://api.opsgenie.com/v1/maintenance/$maintenanceId
Sample Request
curl -X DELETE 'https://api.opsgenie.com/v1/maintenance/32fff5fe-ae03-4ce8-b9e7-a2a4e5bda65d?apiKey=66495a09-2870-417c-99e9-b61812dc8d42'
Response:
{
  "result": "Maintenance deleted.",
  "took": 0.067,
  "requestId": "43d7c4f5-0c95-491a-8168-0bfbcd01f8b7"
}

List Maintenance

Available Methods

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

Optional Parameters

Parameter
type This parameter defines which maintenance will be listed according to maintenance status. This parameter is 'all' by default, and can take 'all', 'non-expired' or 'past'.
Sample Request For Non-Expired Maintenance
curl -XGET 'https://api.opsgenie.com/v1/maintenance?apiKey=66495a09-2870-417c-99e9-b61812dc8d42'
Response:
{
  "data": [
    {
      "id": "20b78362-9d1e-43e0-8b86-3026b7071109",
      "status": "planned",
      "time": {
        "type": "schedule",
        "startDate": "2017-03-20T11:41:00+0000",
        "endDate": "2017-03-20T12:15:00+0000"
      },
      "description": "sample maintenance"
    },
    {
      "id": "32fff5fe-ae03-4ce8-b9e7-a2a4e5bda65d",
      "status": "active",
      "time": {
        "type": "indefinitely"
      },
      "description": "sample maintenance"
    }
  ],
  "took": 0.115,
  "requestId": "ecbe0030-21b7-4aa3-8e54-1970cc934490"
}
Sample Request For Past Maintenance
curl -XGET 'https://api.opsgenie.com/v1/maintenance?type=non-expired&apiKey=66495a09-2870-417c-99e9-b61812dc8d42'
Response:
{
  "data": [
    {
      "id": "42fbff83-0883-4f24-930a-9195bf10a888",
      "status": "past",
      "time": {
        "type": "for-1-hour"
      },
      "description": "sample past maintenance"
    },
    {
      "id": "5e735d18-26b8-47f3-ae27-c03868e11da3",
      "status": "past",
      "time": {
        "type": "for-5-minutes"
      },
      "description": ""
    },
    {
      "id": "93dca1a9-0cfc-4162-9b5f-d0318afd93f5",
      "status": "past",
      "time": {
        "type": "for-30-minutes"
      },
      "description": "sample past maintenance description"
    }
  ],
  "took": 0.014,
  "requestId": "78796f58-cc3f-4a02-ab2d-983a1c94c6a4"
}

Cancel Maintenance

Available Methods

HTTP Method URL
POST, PUT, PATCH https://api.opsgenie.com/v1/maintenance/$maintenanceId/cancel
Sample Request
curl -X POST 'https://api.opsgenie.com/v1/maintenance/32fff5fe-ae03-4ce8-b9e7-a2a4e5bda65d/cancel?apiKey=66495a09-2870-417c-99e9-b61812dc8d42'
curl -X PUT 'https://api.opsgenie.com/v1/maintenance/32fff5fe-ae03-4ce8-b9e7-a2a4e5bda65d/cancel?apiKey=66495a09-2870-417c-99e9-b61812dc8d42'
curl -X PATCH 'https://api.opsgenie.com/v1/maintenance/32fff5fe-ae03-4ce8-b9e7-a2a4e5bda65d/cancel?apiKey=66495a09-2870-417c-99e9-b61812dc8d42'
Response:
{
  "result": "Maintenance cancelled.",
  "took": 0.061,
  "requestId": "9c62b255-a0fa-4390-97a6-317dc7cb577a"
}

Parameters of time

time field should contain a time object. Time object should have the following format:
Parameter
type This parameter defines when the maintenance will be active. 'type' field can take one of 'for-5-minutes', 'for-30-minutes', 'for-1-hour', 'indefinitely' or 'schedule'.
startDate startDate parameter is mandatory for 'schedule' type maintenance. This takes a date format as (yyyy-MM-dd'T'HH:mm:ssZ). (e.g. 2017-01-15T08:00:00+02:00)
endDate endDate parameter is mandatory for 'schedule' type maintenance. This takes a date format as (yyyy-MM-dd'T'HH:mm:ssZ).(e.g. 2017-01-15T08:00:00+02:00)

Parameters of rules

rules field should contain a list of rule objects. Rule object should have the following format:
Parameter
entity 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. entityType can be either 'integration' or 'policy'.
state This field is the 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.