Kibana maintenance-window API
You can schedule single or recurring maintenance windows to temporarily reduce rule notifications. For example, a maintenance window prevents false alarms during planned outages.
OpenAPI Specification
openapi: 3.0.3
info:
contact:
name: Kibana Team
description: 'The Kibana REST APIs enable you to manage resources such as connectors, data views, and saved objects.
The API calls are stateless.
Each request that you make happens in isolation from other calls and must include all of the necessary information for Kibana to fulfill the
request.
API requests return JSON output, which is a format that is machine-readable and works well for automation.
To interact with Kibana APIs, use the following operations:
- GET: Fetches the information.
- PATCH: Applies partial modifications to the existing information.
- POST: Adds new information.
- PUT: Updates the existing information.
- DELETE: Removes the information.
You can prepend any Kibana API endpoint with `kbn:` and run the request in **Dev Tools → Console**.
For example:
```
GET kbn:/api/data_views
```
For more information about the console, refer to [Run API requests](https://www.elastic.co/docs/explore-analyze/query-filter/tools/console).
NOTE: Access to internal Kibana API endpoints will be restricted in Kibana version 9.0. Please move any integrations to publicly documented APIs.
## Documentation source and versions
This documentation is derived from the `main` branch of the [kibana](https://github.com/elastic/kibana) repository.
It is provided under license [Attribution-NonCommercial-NoDerivatives 4.0 International](https://creativecommons.org/licenses/by-nc-nd/4.0/).
This documentation contains work-in-progress information for future Elastic Stack releases.
'
title: Kibana APIs Actions maintenance-window API
version: ''
x-doc-license:
name: Attribution-NonCommercial-NoDerivatives 4.0 International
url: https://creativecommons.org/licenses/by-nc-nd/4.0/
x-feedbackLink:
label: Feedback
url: https://github.com/elastic/docs-content/issues/new?assignees=&labels=feedback%2Ccommunity&projects=&template=api-feedback.yaml&title=%5BFeedback%5D%3A+
servers:
- url: https://{kibana_url}
variables:
kibana_url:
default: localhost:5601
security:
- apiKeyAuth: []
- basicAuth: []
tags:
- name: maintenance-window
description: 'You can schedule single or recurring maintenance windows to temporarily reduce rule notifications. For example, a maintenance window prevents false alarms during planned outages.
'
externalDocs:
description: Maintenance window documentation
url: https://www.elastic.co/docs/explore-analyze/alerts-cases/alerts/maintenance-windows
x-displayName: Maintenance windows
paths:
/api/maintenance_window:
post:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb post">post</span> <span class="operation-path">/s/{space_id}/api/maintenance_window</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
[Required authorization] Route required privileges: write-maintenance-window.'
operationId: post-maintenance-window
parameters:
- description: A required header to protect against CSRF attacks
in: header
name: kbn-xsrf
required: true
schema:
example: 'true'
type: string
requestBody:
content:
application/json:
examples:
createMaintenanceWindowRequest:
description: 'Create a maintenance window that recurs every week on Monday and Wednesday for two hours, with a scope that filters specific alerts using a KQL query.
'
summary: Create a maintenance window
value:
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: "infra"'
title: Weekly Maintenance Window
schema:
additionalProperties: false
type: object
properties:
enabled:
description: Whether the current maintenance window is enabled. Disabled maintenance windows do not suppress notifications.
type: boolean
schedule:
additionalProperties: false
type: object
properties:
custom:
additionalProperties: false
type: object
properties:
duration:
description: '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`.'
type: string
recurring:
additionalProperties: false
type: object
properties:
end:
description: '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`.'
type: string
every:
description: '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`.'
type: string
occurrences:
description: The total number of recurrences of the schedule.
minimum: 1
type: number
onMonth:
description: The specific months for a recurring schedule. Valid values are 1-12.
items:
maximum: 12
minimum: 1
type: number
minItems: 1
type: array
onMonthDay:
description: The specific days of the month for a recurring schedule. Valid values are 1-31.
items:
maximum: 31
minimum: 1
type: number
minItems: 1
type: array
onWeekDay:
description: 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.
items:
type: string
minItems: 1
type: array
start:
description: '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`.'
type: string
timezone:
description: The timezone of the schedule. The default timezone is UTC.
type: string
required:
- start
- duration
required:
- custom
scope:
additionalProperties: false
type: object
properties:
alerting:
additionalProperties: false
type: object
properties:
query:
additionalProperties: false
type: object
properties:
kql:
description: A filter written in Kibana Query Language (KQL). Only alerts matching this query will be supressed by the maintenance window.
type: string
required:
- kql
required:
- query
required:
- alerting
title:
description: 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.
type: string
required:
- title
- schedule
responses:
'200':
content:
application/json:
examples:
createMaintenanceWindowResponse:
description: 'The response returned when a maintenance window is successfully created.
'
summary: Create a maintenance window response
value:
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: "infra"'
status: upcoming
title: Weekly Maintenance Window
updated_at: '2025-02-25T10:00:00.000Z'
updated_by: elastic
schema:
additionalProperties: false
type: object
properties:
created_at:
description: The date and time when the maintenance window was created.
type: string
created_by:
description: The identifier for the user that created the maintenance window.
nullable: true
type: string
enabled:
description: Whether the current maintenance window is enabled. Disabled maintenance windows do not suppress notifications.
type: boolean
id:
description: The identifier for the maintenance window.
type: string
schedule:
additionalProperties: false
type: object
properties:
custom:
additionalProperties: false
type: object
properties:
duration:
description: '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`.'
type: string
recurring:
additionalProperties: false
type: object
properties:
end:
description: '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`.'
type: string
every:
description: '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`.'
type: string
occurrences:
description: The total number of recurrences of the schedule.
type: number
onMonth:
description: The specific months for a recurring schedule. Valid values are 1-12.
items:
type: number
type: array
onMonthDay:
description: The specific days of the month for a recurring schedule. Valid values are 1-31.
items:
type: number
type: array
onWeekDay:
description: 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.
items:
type: string
type: array
start:
description: '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`.'
type: string
timezone:
description: The timezone of the schedule. The default timezone is UTC.
type: string
required:
- start
- duration
required:
- custom
scope:
additionalProperties: false
type: object
properties:
alerting:
additionalProperties: false
type: object
properties:
query:
additionalProperties: false
type: object
properties:
kql:
description: A filter written in Kibana Query Language (KQL).
type: string
required:
- kql
required:
- query
required:
- alerting
status:
description: The current status of the maintenance window.
enum:
- running
- upcoming
- finished
- archived
- disabled
type: string
title:
description: The name of the maintenance window.
type: string
updated_at:
description: The date and time when the maintenance window was last updated.
type: string
updated_by:
description: The identifier for the user that last updated this maintenance window.
nullable: true
type: string
required:
- id
- title
- enabled
- created_by
- updated_by
- created_at
- updated_at
- status
- schedule
description: Indicates a successful call.
'400':
description: Indicates an invalid schema or parameters.
'403':
description: Indicates that this call is forbidden.
summary: Create a maintenance window.
tags:
- maintenance-window
x-state: Generally available; added in 9.1.0
x-metaTags:
- content: Kibana
name: product_name
/api/maintenance_window/_find:
get:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb get">get</span> <span class="operation-path">/s/{space_id}/api/maintenance_window/_find</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
[Required authorization] Route required privileges: read-maintenance-window.'
operationId: get-maintenance-window-find
parameters:
- description: The title of the maintenance window.
in: query
name: title
required: false
schema:
type: string
- description: The user who created the maintenance window.
in: query
name: created_by
required: false
schema:
type: string
- description: The status of the maintenance window. It can be "running", "upcoming", "finished", "archived", or "disabled".
in: query
name: status
required: false
schema:
items:
enum:
- running
- finished
- upcoming
- archived
- disabled
type: string
type: array
- description: The page number to return.
in: query
name: page
required: false
schema:
default: 1
maximum: 100
minimum: 1
type: number
- description: The number of maintenance windows to return per page.
in: query
name: per_page
required: false
schema:
default: 10
maximum: 100
minimum: 1
type: number
responses:
'200':
content:
application/json:
examples:
findMaintenanceWindowsResponse:
description: 'The response returned when maintenance windows are successfully found.
'
summary: Find maintenance windows response
value:
maintenanceWindows:
- 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: "infra"'
status: upcoming
title: Weekly Maintenance Window
updated_at: '2025-02-25T10:00:00.000Z'
updated_by: elastic
- created_at: '2025-03-10T09:00:00.000Z'
created_by: elastic
enabled: true
id: a1c94560-6e3b-4ea1-9065-8e3f1b8c5f29
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: Database Upgrade Window
updated_at: '2025-03-15T14:30:00.000Z'
updated_by: elastic
page: 1
per_page: 10
total: 2
schema:
additionalProperties: false
type: object
properties:
maintenanceWindows:
description: The list of maintenance windows.
items:
additionalProperties: false
type: object
properties:
created_at:
description: The date and time when the maintenance window was created.
type: string
created_by:
description: The identifier for the user that created the maintenance window.
nullable: true
type: string
enabled:
description: Whether the current maintenance window is enabled. Disabled maintenance windows do not suppress notifications.
type: boolean
id:
description: The identifier for the maintenance window.
type: string
schedule:
additionalProperties: false
type: object
properties:
custom:
additionalProperties: false
type: object
properties:
duration:
description: '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`.'
type: string
recurring:
additionalProperties: false
type: object
properties:
end:
description: '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`.'
type: string
every:
description: '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`.'
type: string
occurrences:
description: The total number of recurrences of the schedule.
type: number
onMonth:
description: The specific months for a recurring schedule. Valid values are 1-12.
items:
type: number
type: array
onMonthDay:
description: The specific days of the month for a recurring schedule. Valid values are 1-31.
items:
type: number
type: array
onWeekDay:
description: 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.
items:
type: string
type: array
start:
description: '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`.'
type: string
timezone:
description: The timezone of the schedule. The default timezone is UTC.
type: string
required:
- start
- duration
required:
- custom
scope:
additionalProperties: false
type: object
properties:
alerting:
additionalProperties: false
type: object
properties:
query:
additionalProperties: false
type: object
properties:
kql:
description: A filter written in Kibana Query Language (KQL).
type: string
required:
- kql
required:
- query
required:
- alerting
status:
description: The current status of the maintenance window.
enum:
- running
- upcoming
- finished
- archived
- disabled
type: string
title:
description: The name of the maintenance window.
type: string
updated_at:
description: The date and time when the maintenance window was last updated.
type: string
updated_by:
description: The identifier for the user that last updated this maintenance window.
nullable: true
type: string
required:
- id
- title
- enabled
- created_by
- updated_by
- created_at
- updated_at
- status
- schedule
type: array
page:
description: The current page number.
type: number
per_page:
description: The number of maintenance windows returned per page.
type: number
total:
description: The total number of maintenance windows that match the query.
type: number
required:
- page
- per_page
- total
- maintenanceWindows
description: Indicates a successful call.
'400':
description: Indicates an invalid schema or parameters.
'403':
description: Indicates that this call is forbidden.
summary: Search for a maintenance window.
tags:
- maintenance-window
x-state: Generally available; added in 9.2.0
x-metaTags:
- content: Kibana
name: product_name
/api/maintenance_window/{id}:
delete:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb delete">delete</span> <span class="operation-path">/s/{space_id}/api/maintenance_window/{id}</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
[Required authorization] Route required privileges: write-maintenance-window.'
operationId: delete-maintenance-window-id
parameters:
- description: A required header to protect against CSRF attacks
in: header
name: kbn-xsrf
required: true
schema:
example: 'true'
type: string
- description: The identifier for the maintenance window to be deleted.
in: path
name: id
required: true
schema:
type: string
responses:
'204':
description: Indicates a successful call.
'400':
description: Indicates an invalid schema or parameters.
'403':
description: Indicates that this call is forbidden.
'404':
description: Indicates a maintenance window with the given ID does not exist.
summary: Delete a maintenance window.
tags:
- maintenance-window
x-state: Generally available; added in 9.1.0
x-metaTags:
- content: Kibana
name: product_name
get:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb get">get</span> <span class="operation-path">/s/{space_id}/api/maintenance_window/{id}</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
[Required authorization] Route required privileges: read-maintenance-window.'
operationId: get-maintenance-window-id
parameters:
- description: The identifier for the maintenance window.
in: path
name: id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
examples:
getMaintenanceWindowResponse:
description: 'The response returned when a maintenance window is successfully retrieved.
'
summary: Get a maintenance window response
value:
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: "infra"'
status: upcoming
title: Weekly Maintenance Window
updated_at: '2025-02-25T10:00:00.000Z'
updated_by: elastic
schema:
additionalProperties: false
type: object
properties:
created_at:
description: The date and time when the maintenance window was created.
type: string
created_by:
description: The identifier for the user that created the maintenance window.
nullable: true
type: string
enabled:
description: Whether the current maintenance window is enabled. Disabled maintenance windows do not suppress notifications.
type: boolean
# --- truncated at 32 KB (69 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kibana/refs/heads/main/openapi/kibana-maintenance-window-api-openapi.yml