Skip to main content
POST
/
v1
/
maintenance_windows
Create
curl --request POST \
  --url https://api.incident.io/v1/maintenance_windows \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "alert_condition_groups": [
    {
      "conditions": [
        {
          "operation": "one_of",
          "param_bindings": [
            {
              "array_value": [
                {
                  "literal": "SEV123",
                  "reference": "incident.severity"
                }
              ],
              "value": {
                "literal": "SEV123",
                "reference": "incident.severity"
              }
            }
          ],
          "subject": "incident.severity"
        }
      ]
    }
  ],
  "end_at": "2021-08-17T14:28:57.801578Z",
  "escalation_targets": [
    {
      "escalation_paths": {
        "array_value": [
          {
            "literal": "SEV123",
            "reference": "incident.severity"
          }
        ],
        "value": {
          "literal": "SEV123",
          "reference": "incident.severity"
        }
      },
      "users": {
        "array_value": [
          {
            "literal": "SEV123",
            "reference": "incident.severity"
          }
        ],
        "value": {
          "literal": "SEV123",
          "reference": "incident.severity"
        }
      }
    }
  ],
  "incident_id": "01FCNDV6P870EA6S7TK1DSYDG0",
  "lead": {
    "email": "bob@example.com",
    "id": "01G0J1EXE7AXZ2C93K61WBPYEH",
    "slack_user_id": "USER123"
  },
  "name": "Planned database migration",
  "notification_message": "Scheduled downtime for database migration",
  "notify_channels": [
    {
      "channel_id": "C0ACTHQMHS8",
      "channel_name": "general",
      "channel_type": "public"
    }
  ],
  "notify_end_minutes_before": 5,
  "notify_start_minutes_before": 15,
  "reroute_on_end": false,
  "resolve_on_end": false,
  "show_in_sidebar": true,
  "start_at": "2021-08-17T13:28:57.801578Z"
}
'
{
  "maintenance_window": {
    "alert_condition_groups": [
      {
        "conditions": [
          {
            "operation": {
              "label": "Lawrence Jones",
              "value": "01FCQSP07Z74QMMYPDDGQB9FTG"
            },
            "param_bindings": [
              {
                "array_value": [
                  {
                    "label": "Lawrence Jones",
                    "literal": "SEV123",
                    "reference": "incident.severity"
                  }
                ],
                "value": {
                  "label": "Lawrence Jones",
                  "literal": "SEV123",
                  "reference": "incident.severity"
                }
              }
            ],
            "subject": {
              "label": "Incident Severity",
              "reference": "incident.severity"
            }
          }
        ]
      }
    ],
    "archived_at": "2021-08-17T13:28:57.801578Z",
    "created_at": "2021-08-17T13:28:57.801578Z",
    "end_at": "2021-08-17T14:28:57.801578Z",
    "escalation_targets": [
      {
        "escalation_paths": {
          "array_value": [
            {
              "label": "Lawrence Jones",
              "literal": "SEV123",
              "reference": "incident.severity"
            }
          ],
          "value": {
            "label": "Lawrence Jones",
            "literal": "SEV123",
            "reference": "incident.severity"
          }
        },
        "users": {
          "array_value": [
            {
              "label": "Lawrence Jones",
              "literal": "SEV123",
              "reference": "incident.severity"
            }
          ],
          "value": {
            "label": "Lawrence Jones",
            "literal": "SEV123",
            "reference": "incident.severity"
          }
        }
      }
    ],
    "id": "01FCNDV6P870EA6S7TK1DSYDG0",
    "incident_id": "01FCNDV6P870EA6S7TK1DSYDG0",
    "lead": {
      "alert": {
        "id": "01GW2G3V0S59R238FAHPDS1R66",
        "title": "*errors.withMessage: PG::Error failed to connect"
      },
      "api_key": {
        "id": "01FCNDV6P870EA6S7TK1DSYDG0",
        "name": "My test API key"
      },
      "user": {
        "email": "lisa@incident.io",
        "id": "01FCNDV6P870EA6S7TK1DSYDG0",
        "name": "Lisa Karlin Curtis",
        "role": "viewer",
        "slack_user_id": "U02AYNF2XJM"
      },
      "workflow": {
        "id": "01FCNDV6P870EA6S7TK1DSYDG0",
        "name": "My little workflow"
      }
    },
    "name": "Planned database migration",
    "notification_message": "Scheduled downtime for database migration",
    "notify_channels": [
      {
        "channel_id": "C0ACTHQMHS8",
        "channel_name": "general",
        "channel_type": "public",
        "is_private": false
      }
    ],
    "notify_end_minutes_before": 5,
    "notify_start_minutes_before": 15,
    "reroute_on_end": false,
    "resolve_on_end": false,
    "show_in_sidebar": true,
    "start_at": "2021-08-17T13:28:57.801578Z",
    "updated_at": "2021-08-17T13:28:57.801578Z"
  }
}

Authorizations

​
Authorization
string
header
required

API key from your incident.io dashboard (Settings → API keys)

Body

application/json
​
alert_condition_groups
object[]
required

Condition groups that determine which alerts this maintenance window applies to

Example:
[
  {
    "conditions": [
      {
        "operation": "one_of",
        "param_bindings": [
          {
            "array_value": [
              {
                "literal": "SEV123",
                "reference": "incident.severity"
              }
            ],
            "value": {
              "literal": "SEV123",
              "reference": "incident.severity"
            }
          }
        ],
        "subject": "incident.severity"
      }
    ]
  }
]
​
end_at
string<date-time>
required

When the maintenance window should end

Example:

"2021-08-17T14:28:57.801578Z"

​
lead
object
required
Example:
{
  "email": "bob@example.com",
  "id": "01G0J1EXE7AXZ2C93K61WBPYEH",
  "slack_user_id": "USER123"
}
​
name
string
required

Human readable name for the maintenance window

Example:

"Planned database migration"

​
show_in_sidebar
boolean
required

Whether to show this maintenance window in the dashboard sidebar when active

Example:

true

​
start_at
string<date-time>
required

When the maintenance window should start

Example:

"2021-08-17T13:28:57.801578Z"

​
escalation_targets
object[]

If set, alerts matching this window will be escalated to these targets

Example:
[
  {
    "escalation_paths": {
      "array_value": [
        {
          "literal": "SEV123",
          "reference": "incident.severity"
        }
      ],
      "value": {
        "literal": "SEV123",
        "reference": "incident.severity"
      }
    },
    "users": {
      "array_value": [
        {
          "literal": "SEV123",
          "reference": "incident.severity"
        }
      ],
      "value": {
        "literal": "SEV123",
        "reference": "incident.severity"
      }
    }
  }
]
​
incident_id
string

If set, alerts matching this window will be automatically attached to this incident

Example:

"01FCNDV6P870EA6S7TK1DSYDG0"

​
notification_message
string

Custom message included in notifications about this maintenance window

Example:

"Scheduled downtime for database migration"

​
notify_channels
object[]

Channels to notify about the maintenance window starting and ending

Example:
[
  {
    "channel_id": "C0ACTHQMHS8",
    "channel_name": "general",
    "channel_type": "public"
  }
]
​
notify_end_minutes_before
integer<int64>

Minutes before the end to send a notification to the configured channels

Example:

5

​
notify_start_minutes_before
integer<int64>

Minutes before the start to send a notification to the configured channels

Example:

15

​
reroute_on_end
boolean

Whether to retrigger firing alerts through alert routing when the window ends

Example:

false

​
resolve_on_end
boolean

Whether to automatically resolve all firing alerts that matched this window when it ends

Example:

false

Response

201 - application/json

Created response.

​
maintenance_window
object
required
Example:
{
  "alert_condition_groups": [
    {
      "conditions": [
        {
          "operation": {
            "label": "Lawrence Jones",
            "value": "01FCQSP07Z74QMMYPDDGQB9FTG"
          },
          "param_bindings": [
            {
              "array_value": [
                {
                  "label": "Lawrence Jones",
                  "literal": "SEV123",
                  "reference": "incident.severity"
                }
              ],
              "value": {
                "label": "Lawrence Jones",
                "literal": "SEV123",
                "reference": "incident.severity"
              }
            }
          ],
          "subject": {
            "label": "Incident Severity",
            "reference": "incident.severity"
          }
        }
      ]
    }
  ],
  "archived_at": "2021-08-17T13:28:57.801578Z",
  "created_at": "2021-08-17T13:28:57.801578Z",
  "end_at": "2021-08-17T14:28:57.801578Z",
  "escalation_targets": [
    {
      "escalation_paths": {
        "array_value": [
          {
            "label": "Lawrence Jones",
            "literal": "SEV123",
            "reference": "incident.severity"
          }
        ],
        "value": {
          "label": "Lawrence Jones",
          "literal": "SEV123",
          "reference": "incident.severity"
        }
      },
      "users": {
        "array_value": [
          {
            "label": "Lawrence Jones",
            "literal": "SEV123",
            "reference": "incident.severity"
          }
        ],
        "value": {
          "label": "Lawrence Jones",
          "literal": "SEV123",
          "reference": "incident.severity"
        }
      }
    }
  ],
  "id": "01FCNDV6P870EA6S7TK1DSYDG0",
  "incident_id": "01FCNDV6P870EA6S7TK1DSYDG0",
  "lead": {
    "alert": {
      "id": "01GW2G3V0S59R238FAHPDS1R66",
      "title": "*errors.withMessage: PG::Error failed to connect"
    },
    "api_key": {
      "id": "01FCNDV6P870EA6S7TK1DSYDG0",
      "name": "My test API key"
    },
    "user": {
      "email": "lisa@incident.io",
      "id": "01FCNDV6P870EA6S7TK1DSYDG0",
      "name": "Lisa Karlin Curtis",
      "role": "viewer",
      "slack_user_id": "U02AYNF2XJM"
    },
    "workflow": {
      "id": "01FCNDV6P870EA6S7TK1DSYDG0",
      "name": "My little workflow"
    }
  },
  "name": "Planned database migration",
  "notification_message": "Scheduled downtime for database migration",
  "notify_channels": [
    {
      "channel_id": "C0ACTHQMHS8",
      "channel_name": "general",
      "channel_type": "public",
      "is_private": false
    }
  ],
  "notify_end_minutes_before": 5,
  "notify_start_minutes_before": 15,
  "reroute_on_end": false,
  "resolve_on_end": false,
  "show_in_sidebar": true,
  "start_at": "2021-08-17T13:28:57.801578Z",
  "updated_at": "2021-08-17T13:28:57.801578Z"
}