MaintenanceWindowsClient¶

Client for the Kibana Maintenance Windows API.

A maintenance window suppresses rule notifications for a scheduled period of time: alerts continue to be created, but their actions (notifications) are not run while a maintenance window is active. Maintenance windows require a Platinum or higher license.

Maintenance windows are space-scoped: a maintenance window created in one space only affects rules in that space. Every method accepts an optional space_id to target a specific space.

class kibana._sync.client.maintenance_windows.MaintenanceWindowsClient(client, default_space_id=None, validate_spaces=True)[source]¶

Bases: NamespaceClient

Client for the Kibana Maintenance Windows API.

The Maintenance Windows API is generally available in Kibana 9.4 (create, get, update, delete, archive and unarchive were added in 9.1.0; find was added in 9.2.0).

Maintenance windows are space-scoped: a maintenance window created in one space only affects rules in that space. Every method accepts an optional space_id to target a specific space (None targets the default space or the space the client is scoped to).

Example

>>> from kibana import Kibana
>>> client = Kibana("http://localhost:5601", api_key="...")
>>>
>>> # Create a one-hour maintenance window
>>> created = client.maintenance_windows.create(
...     title="Weekend maintenance",
...     schedule={
...         "custom": {
...             "start": "2030-01-05T00:00:00.000Z",
...             "duration": "1h",
...         }
...     },
... )
>>> mw_id = created.body["id"]
>>>
>>> # Archive it once it is no longer needed, then delete it
>>> client.maintenance_windows.archive(id=mw_id)
>>> client.maintenance_windows.delete(id=mw_id)

Creating Maintenance Windows

from kibana import Kibana

client = Kibana("http://localhost:5601", api_key="your_api_key")

# Create a one-hour maintenance window
created = client.maintenance_windows.create(
    title="Weekend maintenance",
    schedule={
        "custom": {
            "start": "2030-01-05T00:00:00.000Z",
            "duration": "1h",
        }
    },
)
mw_id = created.body["id"]

Finding and Retrieving

# Find maintenance windows
results = client.maintenance_windows.find(status="upcoming")
for mw in results.body["maintenanceWindows"]:
    print(mw["id"], mw["title"], mw["status"])

# Get a single maintenance window
mw = client.maintenance_windows.get(id=mw_id)

Updating, Archiving, and Deleting

# Update the schedule
client.maintenance_windows.update(
    id=mw_id,
    title="Weekend maintenance (extended)",
    schedule={
        "custom": {
            "start": "2030-01-05T00:00:00.000Z",
            "duration": "2h",
        }
    },
)

# Archive it once it is no longer needed
client.maintenance_windows.archive(id=mw_id)

# Or bring it back
client.maintenance_windows.unarchive(id=mw_id)

# Delete it
client.maintenance_windows.delete(id=mw_id)

__init__(client, default_space_id=None, validate_spaces=True)[source]¶

Initialize the MaintenanceWindowsClient.

Parameters:

client (Kibana) – The parent Kibana client instance to delegate requests to.
default_space_id (str | None) – Optional default space ID for all operations.
validate_spaces (bool) – Whether to validate space existence before space-scoped operations (default: True).

Example

>>> maintenance_windows_client = MaintenanceWindowsClient(kibana_client)

create(*, title, schedule, enabled=None, scope=None, space_id=None, validate_spaces=None)[source]¶

Create a maintenance window.

Generally available; added in 9.1.0. You must have read privileges for the Maintenance Windows feature in the Management section of the Kibana feature privileges.

Parameters:

title (str) – The name of the maintenance window. While this name does not have to be unique, a distinctive name helps you identify a specific maintenance window.

schedule (dict[str, Any]) –

The schedule of the maintenance window. An object with a required custom key, for example:

{
    "custom": {
        "start": "2030-01-05T00:00:00.000Z",  # required
        "duration": "2h",                     # required
        "timezone": "UTC",
        "recurring": {
            "every": "1w",
            "onWeekDay": ["MO", "FR"],
            "onMonthDay": [1, 15],
            "onMonth": [1, 6],
            "occurrences": 10,
            "end": "2031-01-01T00:00:00.000Z",
        },
    }
}

duration accepts <integer><unit> values where unit is one of d, h, m or s; recurring.every accepts d, w, M or y units.

enabled (bool | None) – Whether the maintenance window is enabled. Disabled maintenance windows do not suppress notifications.
scope (dict[str, Any] | None) – An object narrowing the affected rules with a KQL query, for example {"alerting": {"query": {"kql": "..."}}}. When omitted, the maintenance window affects all rules in the space.
space_id (str | None) – Optional space ID to create the maintenance window in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

id: The identifier for the maintenance window
title / enabled / schedule / scope: as configured
status: “running”, “upcoming”, “finished”, “archived” or “disabled”
created_at / created_by / updated_at / updated_by: metadata

Return type:

ObjectApiResponse containing the created maintenance window

Raises:

BadRequestError – If the request body is invalid.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges or license.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Example

>>> created = client.maintenance_windows.create(
...     title="Monthly patch window",
...     schedule={
...         "custom": {
...             "start": "2030-01-01T00:00:00.000Z",
...             "duration": "4h",
...             "recurring": {"every": "1M", "onMonthDay": [1]},
...         }
...     },
...     scope={"alerting": {"query": {"kql": 'tags: "maintenance"'}}},
... )
>>> print(created.body["title"])
Monthly patch window

get(*, id, space_id=None, validate_spaces=None)[source]¶

Get maintenance window details.

Generally available; added in 9.1.0. You must have read privileges for the Maintenance Windows feature in the Management section of the Kibana feature privileges.

Parameters:

id (str) – The identifier for the maintenance window.
space_id (str | None) – Optional space ID to get the maintenance window from.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the maintenance window (id, title, enabled, schedule, scope, status and created/updated metadata).

Raises:

NotFoundError – If the maintenance window does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges or license.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> window = client.maintenance_windows.get(id="da4c2f57-...")
>>> print(window.body["title"])
Weekend maintenance

find(*, title=None, created_by=None, status=None, page=None, per_page=None, space_id=None, validate_spaces=None)[source]¶

Search for maintenance windows.

Generally available; added in 9.2.0. Retrieves a paginated list of maintenance windows, optionally filtered by title, creator or status. You must have read privileges for the Maintenance Windows feature in the Management section of the Kibana feature privileges.

Parameters:

title (str | None) – The title of the maintenance window.
created_by (str | None) – The user who created the maintenance window.
status (str | list[str] | None) – The status of the maintenance window. One (or a list) of "running", "upcoming", "finished", "archived" or "disabled".
page (int | None) – The page number to return (1-100, default 1).
per_page (int | None) – The number of maintenance windows to return per page (1-100, default 10).
space_id (str | None) – Optional space ID to search in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

maintenanceWindows: The list of matching maintenance windows
total: The total number of matching maintenance windows
page / per_page: The pagination values used

Return type:

ObjectApiResponse containing

Raises:

BadRequestError – If a query parameter is invalid.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges or license.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Example

>>> found = client.maintenance_windows.find(
...     status=["running", "upcoming"], per_page=50
... )
>>> for window in found.body["maintenanceWindows"]:
...     print(window["id"], window["title"])

update(*, id, title=None, enabled=None, schedule=None, scope=None, space_id=None, validate_spaces=None)[source]¶

Update a maintenance window.

Generally available; added in 9.1.0. Performs a partial update: only the provided fields are changed. You must have all privileges for the Maintenance Windows feature in the Management section of the Kibana feature privileges.

Parameters:

id (str) – The identifier for the maintenance window.
title (str | None) – The new name of the maintenance window.
enabled (bool | None) – Whether the maintenance window is enabled. Disabled maintenance windows do not suppress notifications.
schedule (dict[str, Any] | None) – The new schedule of the maintenance window; an object with a required custom key (see MaintenanceWindowsClient.create()).
scope (dict[str, Any] | None) – An object narrowing the affected rules with a KQL query, for example {"alerting": {"query": {"kql": "..."}}}.
space_id (str | None) – Optional space ID the maintenance window lives in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the updated maintenance window.

Raises:

NotFoundError – If the maintenance window does not exist.
BadRequestError – If the request body is invalid.
ConflictError – If the maintenance window was concurrently updated.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges or license.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> updated = client.maintenance_windows.update(
...     id="da4c2f57-...", enabled=False
... )
>>> print(updated.body["status"])
disabled

delete(*, id, space_id=None, validate_spaces=None)[source]¶

Delete a maintenance window.

Generally available; added in 9.1.0. You must have all privileges for the Maintenance Windows feature in the Management section of the Kibana feature privileges.

Parameters:

id (str) – The identifier for the maintenance window.
space_id (str | None) – Optional space ID the maintenance window lives in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with an empty body (HTTP 204) on success.

Raises:

NotFoundError – If the maintenance window does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges or license.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> client.maintenance_windows.delete(id="da4c2f57-...")

archive(*, id, space_id=None, validate_spaces=None)[source]¶

Archive a maintenance window.

Generally available; added in 9.1.0. An archived maintenance window no longer suppresses notifications and is hidden from the active lists in the UI. You must have all privileges for the Maintenance Windows feature in the Management section of the Kibana feature privileges.

Parameters:

id (str) – The identifier for the maintenance window.
space_id (str | None) – Optional space ID the maintenance window lives in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the archived maintenance window (its status becomes "archived" unless it is disabled).

Raises:

NotFoundError – If the maintenance window does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges or license.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> archived = client.maintenance_windows.archive(id="da4c2f57-...")
>>> print(archived.body["status"])
archived

unarchive(*, id, space_id=None, validate_spaces=None)[source]¶

Unarchive a maintenance window.

Generally available; added in 9.1.0. Restores an archived maintenance window; its status is recomputed from its schedule. You must have all privileges for the Maintenance Windows feature in the Management section of the Kibana feature privileges.

Parameters:

id (str) – The identifier for the maintenance window.
space_id (str | None) – Optional space ID the maintenance window lives in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the unarchived maintenance window. Note: in Kibana 9.4.3 the recomputed status is derived from the events Kibana materializes within a limited look-ahead horizon, so a window whose schedule lies in the far future is reported as "finished" rather than "upcoming".

Raises:

NotFoundError – If the maintenance window does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges or license.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> restored = client.maintenance_windows.unarchive(id="da4c2f57-...")
>>> print(restored.body["status"] != "archived")
True

perform_request(method, path, *, params=None, headers=None, body=None)¶

Perform an HTTP request via the parent client with space context enhancement.

Parameters:

method (str) – HTTP method (GET, POST, PUT, DELETE, etc.)
path (str) – API endpoint path
params (dict[str, Any] | None) – Query parameters
headers (dict[str, str] | None) – Request headers
body (dict[str, Any] | None) – Request body

Returns:

API response

Raises:

ApiError – If the API returns an error response (enhanced with space context)

Return type:

ObjectApiResponse[Any]

AsyncMaintenanceWindowsClient¶

Asynchronous version of the MaintenanceWindowsClient for use with async/await syntax.

class kibana._async.client.maintenance_windows.AsyncMaintenanceWindowsClient(client, default_space_id=None, validate_spaces=True)[source]¶

Bases: AsyncNamespaceClient

Async client for the Kibana Maintenance Windows API.

The Maintenance Windows API is generally available in Kibana 9.4 (create, get, update, delete, archive and unarchive were added in 9.1.0; find was added in 9.2.0).

Example

>>> from kibana import AsyncKibana
>>> client = AsyncKibana("http://localhost:5601", api_key="...")
>>>
>>> # Create a one-hour maintenance window
>>> created = await client.maintenance_windows.create(
...     title="Weekend maintenance",
...     schedule={
...         "custom": {
...             "start": "2030-01-05T00:00:00.000Z",
...             "duration": "1h",
...         }
...     },
... )
>>> mw_id = created.body["id"]
>>>
>>> # Archive it once it is no longer needed, then delete it
>>> await client.maintenance_windows.archive(id=mw_id)
>>> await client.maintenance_windows.delete(id=mw_id)

Usage

The AsyncMaintenanceWindowsClient provides the same methods as MaintenanceWindowsClient but all methods are async and must be awaited:

from kibana import AsyncKibana
import asyncio

async def main():
    async with AsyncKibana("http://localhost:5601") as client:
        # Create a maintenance window (async)
        created = await client.maintenance_windows.create(
            title="Async maintenance",
            schedule={
                "custom": {
                    "start": "2030-01-05T00:00:00.000Z",
                    "duration": "1h",
                }
            },
        )

        # Archive and delete (async)
        await client.maintenance_windows.archive(
            id=created.body["id"]
        )
        await client.maintenance_windows.delete(id=created.body["id"])

asyncio.run(main())

__init__(client, default_space_id=None, validate_spaces=True)[source]¶

Initialize the AsyncMaintenanceWindowsClient.

Parameters:

client (AsyncKibana) – The parent AsyncKibana client instance to delegate requests to.
default_space_id (str | None) – Optional default space ID for all operations.
validate_spaces (bool) – Whether to validate space existence before space-scoped operations (default: True).

Example

>>> maintenance_windows_client = AsyncMaintenanceWindowsClient(kibana_client)

async create(*, title, schedule, enabled=None, scope=None, space_id=None, validate_spaces=None)[source]¶

Create a maintenance window.

Generally available; added in 9.1.0. You must have read privileges for the Maintenance Windows feature in the Management section of the Kibana feature privileges.

Parameters:

title (str) – The name of the maintenance window. While this name does not have to be unique, a distinctive name helps you identify a specific maintenance window.

schedule (dict[str, Any]) –

The schedule of the maintenance window. An object with a required custom key, for example:

{
    "custom": {
        "start": "2030-01-05T00:00:00.000Z",  # required
        "duration": "2h",                     # required
        "timezone": "UTC",
        "recurring": {
            "every": "1w",
            "onWeekDay": ["MO", "FR"],
            "onMonthDay": [1, 15],
            "onMonth": [1, 6],
            "occurrences": 10,
            "end": "2031-01-01T00:00:00.000Z",
        },
    }
}

duration accepts <integer><unit> values where unit is one of d, h, m or s; recurring.every accepts d, w, M or y units.

enabled (bool | None) – Whether the maintenance window is enabled. Disabled maintenance windows do not suppress notifications.
scope (dict[str, Any] | None) – An object narrowing the affected rules with a KQL query, for example {"alerting": {"query": {"kql": "..."}}}. When omitted, the maintenance window affects all rules in the space.
space_id (str | None) – Optional space ID to create the maintenance window in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

id: The identifier for the maintenance window
title / enabled / schedule / scope: as configured
status: “running”, “upcoming”, “finished”, “archived” or “disabled”
created_at / created_by / updated_at / updated_by: metadata

Return type:

ObjectApiResponse containing the created maintenance window

Raises:

BadRequestError – If the request body is invalid.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges or license.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Example

>>> created = await client.maintenance_windows.create(
...     title="Monthly patch window",
...     schedule={
...         "custom": {
...             "start": "2030-01-01T00:00:00.000Z",
...             "duration": "4h",
...             "recurring": {"every": "1M", "onMonthDay": [1]},
...         }
...     },
...     scope={"alerting": {"query": {"kql": 'tags: "maintenance"'}}},
... )
>>> print(created.body["title"])
Monthly patch window

async get(*, id, space_id=None, validate_spaces=None)[source]¶

Get maintenance window details.

Generally available; added in 9.1.0. You must have read privileges for the Maintenance Windows feature in the Management section of the Kibana feature privileges.

Parameters:

id (str) – The identifier for the maintenance window.
space_id (str | None) – Optional space ID to get the maintenance window from.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the maintenance window (id, title, enabled, schedule, scope, status and created/updated metadata).

Raises:

NotFoundError – If the maintenance window does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges or license.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> window = await client.maintenance_windows.get(id="da4c2f57-...")
>>> print(window.body["title"])
Weekend maintenance

async find(*, title=None, created_by=None, status=None, page=None, per_page=None, space_id=None, validate_spaces=None)[source]¶

Search for maintenance windows.

Parameters:

title (str | None) – The title of the maintenance window.
created_by (str | None) – The user who created the maintenance window.
status (str | list[str] | None) – The status of the maintenance window. One (or a list) of "running", "upcoming", "finished", "archived" or "disabled".
page (int | None) – The page number to return (1-100, default 1).
per_page (int | None) – The number of maintenance windows to return per page (1-100, default 10).
space_id (str | None) – Optional space ID to search in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

maintenanceWindows: The list of matching maintenance windows
total: The total number of matching maintenance windows
page / per_page: The pagination values used

Return type:

ObjectApiResponse containing

Raises:

BadRequestError – If a query parameter is invalid.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges or license.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Example

>>> found = await client.maintenance_windows.find(
...     status=["running", "upcoming"], per_page=50
... )
>>> for window in found.body["maintenanceWindows"]:
...     print(window["id"], window["title"])

async update(*, id, title=None, enabled=None, schedule=None, scope=None, space_id=None, validate_spaces=None)[source]¶

Update a maintenance window.

Parameters:

id (str) – The identifier for the maintenance window.
title (str | None) – The new name of the maintenance window.
enabled (bool | None) – Whether the maintenance window is enabled. Disabled maintenance windows do not suppress notifications.
schedule (dict[str, Any] | None) – The new schedule of the maintenance window; an object with a required custom key (see AsyncMaintenanceWindowsClient.create()).
scope (dict[str, Any] | None) – An object narrowing the affected rules with a KQL query, for example {"alerting": {"query": {"kql": "..."}}}.
space_id (str | None) – Optional space ID the maintenance window lives in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the updated maintenance window.

Raises:

NotFoundError – If the maintenance window does not exist.
BadRequestError – If the request body is invalid.
ConflictError – If the maintenance window was concurrently updated.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges or license.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> updated = await client.maintenance_windows.update(
...     id="da4c2f57-...", enabled=False
... )
>>> print(updated.body["status"])
disabled

async delete(*, id, space_id=None, validate_spaces=None)[source]¶

Delete a maintenance window.

Generally available; added in 9.1.0. You must have all privileges for the Maintenance Windows feature in the Management section of the Kibana feature privileges.

Parameters:

id (str) – The identifier for the maintenance window.
space_id (str | None) – Optional space ID the maintenance window lives in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with an empty body (HTTP 204) on success.

Raises:

NotFoundError – If the maintenance window does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges or license.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> await client.maintenance_windows.delete(id="da4c2f57-...")

async archive(*, id, space_id=None, validate_spaces=None)[source]¶

Archive a maintenance window.

Parameters:

id (str) – The identifier for the maintenance window.
space_id (str | None) – Optional space ID the maintenance window lives in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the archived maintenance window (its status becomes "archived" unless it is disabled).

Raises:

NotFoundError – If the maintenance window does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges or license.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> archived = await client.maintenance_windows.archive(id="da4c2f57-...")
>>> print(archived.body["status"])
archived

async unarchive(*, id, space_id=None, validate_spaces=None)[source]¶

Unarchive a maintenance window.

Parameters:

id (str) – The identifier for the maintenance window.
space_id (str | None) – Optional space ID the maintenance window lives in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

Raises:

NotFoundError – If the maintenance window does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges or license.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> restored = await client.maintenance_windows.unarchive(id="da4c2f57-...")
>>> print(restored.body["status"] != "archived")
True

async perform_request(method, path, *, params=None, headers=None, body=None)¶

Perform an async HTTP request via the parent client with space context enhancement.

Parameters:

method (str) – HTTP method (GET, POST, PUT, DELETE, etc.)
path (str) – API endpoint path
params (dict[str, Any] | None) – Query parameters
headers (dict[str, str] | None) – Request headers
body (dict[str, Any] | None) – Request body

Returns:

API response

Raises:

ApiError – If the API returns an error response (enhanced with space context)

Return type:

ObjectApiResponse[Any]