Update a maintenance window. | Kibana API documentation

Update a maintenance window. Generally available; added in 9.1.0

PATCH /api/maintenance_window/{id}

Api key auth Basic auth

Spaces method and path for this operation:

patch /s/{space_id}/api/maintenance_window/{id}

Refer to Spaces for more information.

[Required authorization] Route required privileges: write-maintenance-window.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

Path parameters

id string Required

The identifier for the maintenance window.

application/json

Body

enabled boolean

Whether the current maintenance window is enabled. Disabled maintenance windows do not suppress notifications.
schedule object

Additional properties are NOT allowed.
Hide schedule attribute Show schedule attribute object
- custom object Required
  
  Additional properties are NOT allowed.
  Hide custom attributes Show custom attributes object
  
  duration string Required
  
  The duration of the schedule. It allows values in <integer><unit> format. <unit> is one of d, h, m, or s for hours, minutes, seconds. For example: 1d, 5h, 30m, 5000s.
  
  Maximum length is 100.
  
  recurring object
  
  Additional properties are NOT allowed.
  
  Hide recurring attributes Show recurring attributes object
  
  end string
  
  The end date of a recurring schedule, provided in ISO 8601 format and set to the UTC timezone. For example: 2025-04-01T00:00:00.000Z.
  
  Maximum length is 100.
  
  every string
  
  The interval and frequency of a recurring schedule. It allows values in <integer><unit> format. <unit> is one of d, w, M, or y for days, weeks, months, years. For example: 15d, 2w, 3m, 1y.
  
  Maximum length is 100.
  
  occurrences number
  
  The total number of recurrences of the schedule.
  
  Minimum value is 1.
  
  onMonth array[number]
  
  The specific months for a recurring schedule. Valid values are 1-12.
  
  At least 1 but not more than 12 elements. Minimum value of each is 1, maximum value of each is 12.
  
  onMonthDay array[number]
  
  The specific days of the month for a recurring schedule. Valid values are 1 to 31, or -1 for the last day of the month.
  
  At least 1 but not more than 31 elements. Minimum value of each is -1, maximum value of each is 31.
  
  onWeekDay array[string]
  
  The specific days of the week ([MO,TU,WE,TH,FR,SA,SU]) or nth day of month ([+1MO, -3FR, +2WE, -4SA, -5SU]) for a recurring schedule.
  
  At least 1 but not more than 77 elements. Maximum length of each is 10.
  
  start string Required
  
  The start date and time of the schedule, provided in ISO 8601 format and set to the UTC timezone. For example: 2025-03-12T12:00:00.000Z.
  
  Maximum length is 100.
  
  timezone string
  
  The timezone of the schedule. The default timezone is UTC.
  
  Maximum length is 64.
scope object

Additional properties are NOT allowed.
Hide scope attributes Show scope attributes object
- alerting object
  
  Settings that control how this maintenance window affects Alerting V1 alerts, including an optional KQL filter. If you include scope but omit alerting, the maintenance window doesn't affect these alerts.
  
  Additional properties are NOT allowed.
  Hide alerting attributes Show alerting attributes object
  
  enabled boolean
  
  Whether this maintenance window applies to Alerting V1 alerts. If omitted, is treated as true.
  
  query object
  
  Additional properties are NOT allowed.
  
  Hide query attribute Show query attribute object
  
  kql string Required
  
  A KQL filter that limits which Alerting V1 alerts this maintenance window affects. Matching alerts don't run rule actions while the window is active. If you omit query, the window affects all alerts.
  
  Maximum length is 10000.
- alerting_v2 object
  
  Settings that control how this maintenance window affects Alerting V2 alerting episodes, including an optional KQL filter. If you omit alerting_v2, the maintenance window doesn't affect Alerting V2 alert episodes.
  
  Additional properties are NOT allowed.
  Hide alerting_v2 attributes Show alerting_v2 attributes object
  
  enabled boolean
  
  Whether this maintenance window affects Alerting V2 alert episodes. Defaults to true.
  
  query object
  
  Additional properties are NOT allowed.
  
  Hide query attribute Show query attribute object
  
  kql string Required
  
  A KQL filter that limits which Alerting V2 alert episodes this maintenance window affects. You can filter on episode_id, episode_status, group_hash, last_event_timestamp, severity, and data.*. Matching episodes don't send notifications while the window is active. If you omit query, the window affects all Alerting V2 alert episodes.
  
  Maximum length is 4096.
title string

The name of the maintenance window. While this name does not have to be unique, a distinctive name can help you identify a specific maintenance window.

Responses

200 application/json

Indicates a successful call.
Hide response attributes Show response attributes object
- created_at string Required
  
  The date and time when the maintenance window was created.
- created_by string | null
  
  The identifier for the user that created the maintenance window.
- enabled boolean Required
  
  Whether the current maintenance window is enabled. Disabled maintenance windows do not suppress notifications.
- id string Required
  
  The identifier for the maintenance window.
- schedule object Required
  
  Additional properties are NOT allowed.
  
  Hide schedule attribute Show schedule attribute object
  
  custom object Required
  
  Additional properties are NOT allowed.
  
  Hide custom attributes Show custom attributes object
  
  duration string Required
  
  The duration of the schedule. It allows values in <integer><unit> format. <unit> is one of d, h, m, or s for hours, minutes, seconds. For example: 1d, 5h, 30m, 5000s.
  
  recurring object
  
  Additional properties are NOT allowed.
  
  Hide recurring attributes Show recurring attributes object
  
  end string
  
  The end date of a recurring schedule, provided in ISO 8601 format and set to the UTC timezone. For example: 2025-04-01T00:00:00.000Z.
  
  every string
  
  The interval and frequency of a recurring schedule. It allows values in <integer><unit> format. <unit> is one of d, w, M, or y for days, weeks, months, years. For example: 15d, 2w, 3m, 1y.
  
  occurrences number
  
  The total number of recurrences of the schedule.
  
  onMonth array[number]
  
  The specific months for a recurring schedule. Valid values are 1-12.
  
  Not more than 12 elements.
  
  onMonthDay array[number]
  
  The specific days of the month for a recurring schedule. Valid values are 1 to 31, or -1 for the last day of the month.
  
  Not more than 31 elements.
  
  onWeekDay array[string]
  
  The specific days of the week ([MO,TU,WE,TH,FR,SA,SU]) or nth day of month ([+1MO, -3FR, +2WE, -4SA, -5SU]) for a recurring schedule.
  
  Not more than 77 elements. Maximum length of each is 10.
  
  start string Required
  
  The start date and time of the schedule, provided in ISO 8601 format and set to the UTC timezone. For example: 2025-03-12T12:00:00.000Z.
  
  timezone string
  
  The timezone of the schedule. The default timezone is UTC.
- scope object
  
  Additional properties are NOT allowed.
  
  Hide scope attributes Show scope attributes object
  
  alerting object Required
  
  Settings that control how this maintenance window affects Alerting V1 alerts, including an optional KQL filter. Always returned when scope is returned. Check enabled to see whether the maintenance window affects these alerts.
  
  Additional properties are NOT allowed.
  
  Hide alerting attributes Show alerting attributes object
  
  enabled boolean
  
  Whether this maintenance window applies to Alerting V1 alerts. If omitted, is treated as true.
  
  query object Required
  
  Additional properties are NOT allowed.
  
  Hide query attribute Show query attribute object
  
  kql string Required
  
  A filter written in Kibana Query Language (KQL). Only alerts matching this query will be suppressed by the maintenance window.
  
  alerting_v2 object
  
  Settings that control how this maintenance window affects Alerting V2 alerting episodes, including an optional KQL filter. If you omit alerting_v2, the maintenance window doesn't affect Alerting V2 alert episodes.
  
  Additional properties are NOT allowed.
  
  Hide alerting_v2 attributes Show alerting_v2 attributes object
  
  enabled boolean
  
  Whether the maintenance window applies to Alerting V2 alert episodes. If omitted, is treated as true.
  
  query object
  
  Additional properties are NOT allowed.
  
  Hide query attribute Show query attribute object
  
  kql string Required
  
  A KQL filter that limits which Alerting V2 alert episodes this maintenance window affects. Matching alert episodes don't send notifications while the window is active. If query isn't returned, the window affects all Alerting V2 alert episodes.
  
  Maximum length is 4096.
- status string Required
  
  The current status of the maintenance window.
  
  Values are running, upcoming, finished, archived, or disabled.
- title string Required
  
  The name of the maintenance window.
- updated_at string Required
  
  The date and time when the maintenance window was last updated.
- updated_by string | null
  
  The identifier for the user that last updated this maintenance window.
400

Indicates an invalid schema or parameters.
403

Indicates that this call is forbidden.
404

Indicates a maintenance window with the given ID does not exist.
409

Indicates that the maintenance window has already been updated by another user.

PATCH /api/maintenance_window/{id}

curl \
 --request PATCH 'https://localhost:5601/api/maintenance_window/{id}' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --header "kbn-xsrf: true" \
 --data '{
  "enabled": true,
  "schedule": {
    "custom": {
      "duration": "1h",
      "recurring": {
        "end": "2025-12-31T00:00:00.000Z",
        "every": "2w",
        "onWeekDay": [
          "FR"
        ]
      },
      "start": "2025-04-01T10:00:00.000Z",
      "timezone": "US/Eastern"
    }
  },
  "scope": {
    "alerting": {
      "query": {
        "kql": "kibana.alert.tags: \"database\""
      }
    }
  },
  "title": "Updated maintenance window"
}'

Request example

Update a maintenance window to change its title, schedule, and scope.

{
  "enabled": true,
  "schedule": {
    "custom": {
      "duration": "1h",
      "recurring": {
        "end": "2025-12-31T00:00:00.000Z",
        "every": "2w",
        "onWeekDay": [
          "FR"
        ]
      },
      "start": "2025-04-01T10:00:00.000Z",
      "timezone": "US/Eastern"
    }
  },
  "scope": {
    "alerting": {
      "query": {
        "kql": "kibana.alert.tags: \"database\""
      }
    }
  },
  "title": "Updated maintenance window"
}

Response examples (200)

The response returned when a maintenance window is successfully updated.

{
  "created_at": "2025-02-25T10:00:00.000Z",
  "created_by": "elastic",
  "enabled": true,
  "id": "f0cb1780-537a-4e34-8adf-3b4336862858",
  "schedule": {
    "custom": {
      "duration": "1h",
      "recurring": {
        "end": "2025-12-31T00:00:00.000Z",
        "every": "2w",
        "onWeekDay": [
          "FR"
        ]
      },
      "start": "2025-04-01T10:00:00.000Z",
      "timezone": "US/Eastern"
    }
  },
  "scope": {
    "alerting": {
      "query": {
        "kql": "kibana.alert.tags: \"database\""
      }
    }
  },
  "status": "upcoming",
  "title": "Updated maintenance window",
  "updated_at": "2025-03-15T14:30:00.000Z",
  "updated_by": "elastic"
}