--- type: api title: Create a maintenance window. description: **Spaces method and path for this operation:** url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana/operation/operation-post-maintenance-window resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana/operation/operation-post-maintenance-window products: - Kibana --- # Create a maintenance window. Availability: 9.1+ - Server: `https://{kibana_url}` ## Paths - `POST` `/api/maintenance_window` - `POST` `/s/{space_id}/api/maintenance_window` - [Api key auth](/elastic/docs-builder/docs/4371/api/doc/kibana/authentication#apikeyauth) - [Basic auth](/elastic/docs-builder/docs/4371/api/doc/kibana/authentication#basicauth) ## Description Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information. [Required authorization] Route required privileges: write-maintenance-window. ## Request Body `application/json` - `enabled` (boolean) — optional Whether the current maintenance window is enabled. Disabled maintenance windows do not suppress notifications. - `schedule` (object) — required - `custom` ({}) — required - `duration` (string · max: 100) — required The duration of the schedule. It allows values in `` format. `` is one of `d`, `h`, `m`, or `s` for hours, minutes, seconds. For example: `1d`, `5h`, `30m`, `5000s`. - `recurring` ({}) — optional - `end` (string · max: 100) — optional 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 · max: 100) — optional The interval and frequency of a recurring schedule. It allows values in `` format. `` is one of `d`, `w`, `M`, or `y` for days, weeks, months, years. For example: `15d`, `2w`, `3m`, `1y`. - `occurrences` (number · min: 1) — optional The total number of recurrences of the schedule. - `onMonth` ([] number · min: 1 · max: 12) — optional The specific months for a recurring schedule. Valid values are 1-12. - `onMonthDay` ([] number · min: 1 · max: 31) — optional 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. - `onWeekDay` ([] string · min: 1 · max: 77) — optional 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. - `start` (string · max: 100) — 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 · max: 64) — optional The timezone of the schedule. The default timezone is UTC. - `scope` ({}) — optional - `alerting` (object) — optional 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. - `enabled` (boolean) — optional Whether this maintenance window applies to Alerting V1 alerts. If omitted, is treated as `true`. - `query` (object) — optional - `kql` (string · max: 10000) — 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. - `alerting_v2` (object) — optional Settings that control how this maintenance window affects Alerting V2 alerts, including an optional KQL filter. If you omit `alerting_v2`, the maintenance window doesn't affect Alerting V2 alerts. - `enabled` (boolean) — optional Whether this maintenance window affects Alerting V2 alerts. Defaults to `true`. - `query` (object) — optional - `kql` (string · max: 4096) — required A KQL filter that limits which Alerting V2 alerts this maintenance window affects. You can filter on `alert_id`, `alert_status`, `group_hash`, `last_event_timestamp`, `severity`, and `data.*`. Matching alerts don't send notifications while the window is active. If you omit query, the window affects all Alerting V2 alerts. - `title` (string) — required 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` Indicates a successful call. `application/json` - `created_at` (string) The date and time when the maintenance window was created. - `created_by` (string · default: null) — nullable The identifier for the user that created the maintenance window. - `enabled` (boolean) Whether the current maintenance window is enabled. Disabled maintenance windows do not suppress notifications. - `id` (string) The identifier for the maintenance window. - `schedule` (object) - `custom` ({}) - `duration` (string) The duration of the schedule. It allows values in `` format. `` is one of `d`, `h`, `m`, or `s` for hours, minutes, seconds. For example: `1d`, `5h`, `30m`, `5000s`. - `recurring` ({}) - `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 `` format. `` 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` ([] number · max: 12) The specific months for a recurring schedule. Valid values are 1-12. - `onMonthDay` ([] number · max: 31) 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. - `onWeekDay` ([] string · max: 77) 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. - `start` (string) 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` ({}) - `alerting` (object) 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. - `enabled` (boolean) Whether this maintenance window applies to Alerting V1 alerts. If omitted, is treated as `true`. - `query` (object) - `kql` (string) 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 alerts, including an optional KQL filter. If you omit `alerting_v2`, the maintenance window doesn't affect Alerting V2 alerts. - `enabled` (boolean) Whether the maintenance window applies to Alerting V2 alerts. If omitted, is treated as `true`. - `query` (object) - `kql` (string · max: 4096) A KQL filter that limits which Alerting V2 alerts this maintenance window affects. It can filter on `alert_id`, `alert_status`, `group_hash`, `last_event_timestamp`, `severity`, and `data.*`. Matching alerts don't send notifications while the window is active. If query isn't returned, the window affects all Alerting V2 alerts. - `status` (enum) The current status of the maintenance window. Values: `running`, `upcoming`, `finished`, `archived`, `disabled` - `title` (string) The name of the maintenance window. - `updated_at` (string) The date and time when the maintenance window was last updated. - `updated_by` (string · default: null) — nullable 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. ## Code Examples #### Console ```console POST /api/maintenance_window { "enabled": true, "schedule": { "custom": { "duration": "2h", "recurring": { "every": "1w", "occurrences": 10, "onWeekDay": [ "MO", "WE" ] }, "start": "2025-03-01T08:00:00.000Z", "timezone": "Europe/Amsterdam" } }, "scope": { "alerting": { "query": { "kql": "kibana.alert.tags: \u0022infra\u0022" } } }, "title": "Weekly Maintenance Window" } ``` #### curl ```curl curl -X POST "https://{kibana_url}/api/maintenance_window" \ -H "kbn-xsrf: true" \ -H "Content-Type: application/json" \ -d '{ "enabled": true, "schedule": { "custom": { "duration": "2h", "recurring": { "every": "1w", "occurrences": 10, "onWeekDay": [ "MO", "WE" ] }, "start": "2025-03-01T08:00:00.000Z", "timezone": "Europe/Amsterdam" } }, "scope": { "alerting": { "query": { "kql": "kibana.alert.tags: \u0022infra\u0022" } } }, "title": "Weekly Maintenance Window" }' ``` ## Response Examples #### Create a maintenance window response The response returned when a maintenance window is successfully created. ```json { "created_at": "2025-02-25T10:00:00.000Z", "created_by": "elastic", "enabled": true, "id": "f0cb1780-537a-4e34-8adf-3b4336862858", "schedule": { "custom": { "duration": "2h", "recurring": { "every": "1w", "occurrences": 10, "onWeekDay": [ "MO", "WE" ] }, "start": "2025-03-01T08:00:00.000Z", "timezone": "Europe/Amsterdam" } }, "scope": { "alerting": { "query": { "kql": "kibana.alert.tags: \u0022infra\u0022" } } }, "status": "upcoming", "title": "Weekly Maintenance Window", "updated_at": "2025-02-25T10:00:00.000Z", "updated_by": "elastic" } ```