SavedObjectsClient

Client for managing Kibana saved objects through the Saved Objects API.

Saved Objects in Kibana are entities like dashboards, visualizations, index patterns, and other configuration items. This API provides methods to create, read, update, and delete saved objects, as well as bulk operations and import/export functionality.

class kibana.SavedObjectsClient(client, default_space_id=None, validate_spaces=True)[source]

Bases: NamespaceClient

Client for managing Kibana Saved Objects.

Saved Objects in Kibana are persistent entities that store configuration, user-created content, and application state. This includes dashboards, visualizations, index patterns, saved searches, and other Kibana objects. This client provides comprehensive CRUD operations with full support for Kibana Spaces.

Saved objects are scoped to spaces, enabling multi-tenancy where different teams or projects can maintain isolated sets of dashboards and visualizations.

Common saved object types:

  • dashboard: Kibana dashboards with visualizations

  • visualization: Individual visualizations (charts, graphs, etc.)

  • index-pattern: Index patterns for data access

  • search: Saved searches and queries

  • config: Kibana configuration settings

  • lens: Lens visualizations

  • map: Maps visualizations

  • canvas-workpad: Canvas workpads

  • tag: Tags for organizing objects

Key features:

  • CRUD operations for all saved object types

  • Space-scoped operations for multi-tenancy

  • Reference management between objects

  • Version control with optimistic concurrency

  • Bulk operations for efficiency

_default_space_id

Default space ID for operations if not specified per-request.

_validate_spaces

Whether to validate space existence before operations.

Example

>>> from kibana import Kibana
>>> client = Kibana("http://localhost:5601", api_key="...")
>>>
>>> # Create a dashboard
>>> dashboard = client.saved_objects.create(
...     type="dashboard",
...     attributes={
...         "title": "My Dashboard",
...         "description": "Sales analytics dashboard"
...     }
... )
>>>
>>> # Get a saved object
>>> obj = client.saved_objects.get(
...     type="dashboard",
...     id="my-dashboard-id"
... )
>>> print(obj.body["attributes"]["title"])
>>>
>>> # Work with space-scoped saved objects
>>> marketing_client = client.space("marketing")
>>> dashboards = marketing_client.saved_objects.find(
...     type="dashboard"
... )

Overview

The SavedObjectsClient provides comprehensive methods for managing Kibana saved objects. Saved objects can be scoped to specific Kibana Spaces for multi-tenancy.

Creating Saved Objects

Create a new saved object with the create() method:

from kibana import Kibana

client = Kibana("http://localhost:5601")

# Create a dashboard
dashboard = client.saved_objects.create(
    type="dashboard",
    attributes={
        "title": "My Dashboard",
        "description": "A sample dashboard"
    }
)

dashboard_id = dashboard.body["id"]
print(f"Created dashboard: {dashboard_id}")

# Create with a specific ID
visualization = client.saved_objects.create(
    type="visualization",
    id="my-viz-id",
    attributes={
        "title": "My Visualization",
        "visState": "{}"
    }
)

Saved Object Types

Common saved object types include:

  • dashboard - Kibana dashboards

  • visualization - Visualizations

  • index-pattern - Index patterns

  • search - Saved searches

  • lens - Lens visualizations

  • map - Maps

  • canvas-workpad - Canvas workpads

# Create an index pattern
index_pattern = client.saved_objects.create(
    type="index-pattern",
    attributes={
        "title": "logs-*",
        "timeFieldName": "@timestamp"
    }
)

# Create a saved search
search = client.saved_objects.create(
    type="search",
    attributes={
        "title": "Error Logs",
        "columns": ["message", "level"],
        "sort": [["@timestamp", "desc"]]
    }
)

Retrieving Saved Objects

Get saved objects by type and ID:

# Get a specific saved object
obj = client.saved_objects.get(
    type="dashboard",
    id=dashboard_id
)

print(f"Title: {obj.body['attributes']['title']}")

# Get multiple saved objects at once
objects = client.saved_objects.bulk_get(
    objects=[
        {"type": "dashboard", "id": "dashboard-1"},
        {"type": "visualization", "id": "viz-1"},
        {"type": "index-pattern", "id": "pattern-1"}
    ]
)

Updating Saved Objects

Update saved object attributes:

# Update a dashboard
updated = client.saved_objects.update(
    type="dashboard",
    id=dashboard_id,
    attributes={
        "title": "Updated Dashboard Title",
        "description": "Updated description"
    }
)

# Partial update (only specified attributes are updated)
updated = client.saved_objects.update(
    type="dashboard",
    id=dashboard_id,
    attributes={
        "description": "New description only"
    }
)

Deleting Saved Objects

Delete saved objects:

# Delete a single saved object
client.saved_objects.delete(
    type="dashboard",
    id=dashboard_id
)

# Bulk delete multiple saved objects
result = client.saved_objects.bulk_delete(
    objects=[
        {"type": "dashboard", "id": "dashboard-1"},
        {"type": "visualization", "id": "viz-1"}
    ]
)

Finding Saved Objects

Search for saved objects with filters:

# Find all dashboards
dashboards = client.saved_objects.find(
    type="dashboard"
)

for dashboard in dashboards.body["saved_objects"]:
    print(f"{dashboard['id']}: {dashboard['attributes']['title']}")

# Find with search query
results = client.saved_objects.find(
    type="dashboard",
    search="error",
    search_fields=["title", "description"]
)

# Find with pagination
results = client.saved_objects.find(
    type="visualization",
    page=1,
    per_page=20
)

Bulk Operations

Perform bulk create and update operations:

# Bulk create multiple saved objects
result = client.saved_objects.bulk_create(
    objects=[
        {
            "type": "dashboard",
            "attributes": {"title": "Dashboard 1"}
        },
        {
            "type": "dashboard",
            "attributes": {"title": "Dashboard 2"}
        },
        {
            "type": "visualization",
            "attributes": {"title": "Viz 1"}
        }
    ]
)

# Bulk update
result = client.saved_objects.bulk_update(
    objects=[
        {
            "type": "dashboard",
            "id": "dashboard-1",
            "attributes": {"title": "Updated Dashboard 1"}
        },
        {
            "type": "dashboard",
            "id": "dashboard-2",
            "attributes": {"title": "Updated Dashboard 2"}
        }
    ]
)

Export and Import

Export and import saved objects:

# Export saved objects
export_data = client.saved_objects.export(
    objects=[
        {"type": "dashboard", "id": "dashboard-1"},
        {"type": "visualization", "id": "viz-1"}
    ]
)

# Export all objects of a type
export_data = client.saved_objects.export(
    type="dashboard"
)

# Import saved objects
result = client.saved_objects.import_objects(
    file=export_data,
    overwrite=True
)

Space-Scoped Operations

Work with saved objects in specific spaces:

# Create saved object in a specific space
dashboard = client.saved_objects.create(
    type="dashboard",
    attributes={"title": "Marketing Dashboard"},
    space_id="marketing"
)

# Or use a space-scoped client
marketing_client = client.space("marketing")
dashboard = marketing_client.saved_objects.create(
    type="dashboard",
    attributes={"title": "Marketing Dashboard"}
)

# Find saved objects in a specific space
results = client.saved_objects.find(
    type="dashboard",
    space_id="marketing"
)

Error Handling

Handle common errors when working with saved objects:

from kibana.exceptions import (
    NotFoundError,
    ConflictError,
    BadRequestError,
    SpaceNotFoundError
)

try:
    obj = client.saved_objects.create(
        type="dashboard",
        id="my-dashboard",
        attributes={"title": "My Dashboard"},
        space_id="marketing"
    )
except SpaceNotFoundError as e:
    print(f"Space not found: {e.space_id}")
except ConflictError as e:
    print(f"Object already exists: {e.message}")
except BadRequestError as e:
    print(f"Invalid attributes: {e.message}")

try:
    obj = client.saved_objects.get(
        type="dashboard",
        id="nonexistent"
    )
except NotFoundError as e:
    print(f"Object not found: {e.message}")
__init__(client, default_space_id=None, validate_spaces=True)[source]

Initialize SavedObjectsClient with optional space context.

Parameters:

  • client – Parent BaseClient instance to delegate HTTP requests to.

  • default_space_id (str | None) – Optional default space ID for all operations. If provided, all operations will be scoped to this space unless overridden with the space_id parameter.

  • validate_spaces (bool) – Whether to validate space existence before operations. When True (default), the client will verify that spaces exist before making API calls. Set to False for better performance if you’re certain spaces exist.

Example

>>> # Client without default space
>>> saved_objects = SavedObjectsClient(base_client)
>>>
>>> # Client with default space
>>> marketing_objects = SavedObjectsClient(
...     base_client,
...     default_space_id="marketing",
...     validate_spaces=True
... )
create(*, type, attributes, id=None, overwrite=False, references=None, space_id=None, validate_space=None)[source]

Create a new saved object.

Parameters:

  • type (str) – Type of saved object (e.g., ‘dashboard’, ‘visualization’, ‘index-pattern’)

  • attributes (dict[str, Any]) – Attributes of the saved object

  • id (str | None) – Optional ID for the saved object (auto-generated if not provided)

  • overwrite (bool) – If true, overwrite existing object with the same ID

  • references (list[dict[str, Any]] | None) – Optional list of references to other saved objects

  • space_id (str | None) – Optional space ID for space-scoped operations

  • validate_space (bool | None) – Override space validation setting for this operation

Returns:

Created saved object details

Raises:
Return type:

ObjectApiResponse[dict[str, Any]]

Example

>>> # Create a dashboard
>>> dashboard = client.saved_objects.create(
...     type="dashboard",
...     attributes={
...         "title": "My Dashboard",
...         "description": "Dashboard description"
...     }
... )
>>> print(dashboard["id"])

>>> # Create with explicit ID
>>> dashboard = client.saved_objects.create(
...     type="dashboard",
...     id="my-dashboard-id",
...     attributes={"title": "My Dashboard"}
... )

>>> # Create in a specific space
>>> dashboard = client.saved_objects.create(
...     type="dashboard",
...     attributes={"title": "Marketing Dashboard"},
...     space_id="marketing"
... )
get(*, type, id, space_id=None, validate_space=None)[source]

Get a saved object by type and ID.

Parameters:

  • type (str) – Type of saved object

  • id (str) – ID of the saved object

  • space_id (str | None) – Optional space ID for space-scoped operations

  • validate_space (bool | None) – Override space validation setting for this operation

Returns:

Saved object details

Raises:
Return type:

ObjectApiResponse[dict[str, Any]]

Example

>>> # Get a dashboard
>>> dashboard = client.saved_objects.get(
...     type="dashboard",
...     id="my-dashboard-id"
... )
>>> print(dashboard["attributes"]["title"])

>>> # Get from a specific space
>>> dashboard = client.saved_objects.get(
...     type="dashboard",
...     id="my-dashboard-id",
...     space_id="marketing"
... )
find(*, type, search=None, search_fields=None, page=None, per_page=None, sort_field=None, has_reference=None, fields=None, space_id=None)[source]

Find saved objects.

Parameters:

  • type (str | list[str]) – Type(s) of saved objects to find

  • search (str | None) – Search string

  • search_fields (list[str] | None) – Fields to search in

  • page (int | None) – Page number

  • per_page (int | None) – Items per page

  • sort_field (str | None) – Field to sort by

  • has_reference (dict[str, str] | None) – Filter by reference

  • fields (list[str] | None) – Fields to include in response

  • space_id (str | None) – Optional space ID for space-scoped operations

Returns:

ObjectApiResponse containing search results

Return type:

ObjectApiResponse[dict[str, Any]]

update(*, type, id, attributes, version=None, references=None, space_id=None, validate_space=None)[source]

Update an existing saved object.

Parameters:

  • type (str) – Type of saved object

  • id (str) – ID of the saved object

  • attributes (dict[str, Any]) – Updated attributes (partial or full)

  • version (str | None) – Optional version for optimistic concurrency control

  • references (list[dict[str, Any]] | None) – Optional updated list of references

  • space_id (str | None) – Optional space ID for space-scoped operations

  • validate_space (bool | None) – Override space validation setting for this operation

Returns:

Updated saved object details

Raises:
Return type:

ObjectApiResponse[dict[str, Any]]

Example

>>> # Update a dashboard
>>> updated = client.saved_objects.update(
...     type="dashboard",
...     id="my-dashboard-id",
...     attributes={"title": "Updated Dashboard Title"}
... )

>>> # Update with version for optimistic concurrency
>>> updated = client.saved_objects.update(
...     type="dashboard",
...     id="my-dashboard-id",
...     attributes={"title": "Updated Title"},
...     version="WzEsMV0="
... )

>>> # Update in a specific space
>>> updated = client.saved_objects.update(
...     type="dashboard",
...     id="my-dashboard-id",
...     attributes={"title": "Updated Title"},
...     space_id="marketing"
... )
delete(*, type, id, force=False, space_id=None, validate_space=None)[source]

Delete a saved object.

Parameters:

  • type (str) – Type of saved object

  • id (str) – ID of the saved object

  • force (bool) – If true, force delete even if object has references

  • space_id (str | None) – Optional space ID for space-scoped operations

  • validate_space (bool | None) – Override space validation setting for this operation

Returns:

Deletion confirmation

Raises:
Return type:

ObjectApiResponse[dict[str, Any]]

Example

>>> # Delete a dashboard
>>> client.saved_objects.delete(
...     type="dashboard",
...     id="my-dashboard-id"
... )

>>> # Force delete
>>> client.saved_objects.delete(
...     type="dashboard",
...     id="my-dashboard-id",
...     force=True
... )

>>> # Delete from a specific space
>>> client.saved_objects.delete(
...     type="dashboard",
...     id="my-dashboard-id",
...     space_id="marketing"
... )
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]

AsyncSavedObjectsClient

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

class kibana._async.client.saved_objects.AsyncSavedObjectsClient(client, default_space_id=None, validate_spaces=True)[source]

Bases: AsyncNamespaceClient

Async client for managing Kibana Saved Objects.

Saved Objects in Kibana are entities like dashboards, visualizations, index patterns, and other configuration items. This client provides async methods to create, read, update, and delete saved objects.

Common saved object types: - dashboard: Kibana dashboards - visualization: Visualizations - index-pattern: Index patterns - search: Saved searches - config: Kibana configuration

Usage

The AsyncSavedObjectsClient provides the same methods as SavedObjectsClient 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 saved object (async)
        dashboard = await client.saved_objects.create(
            type="dashboard",
            attributes={"title": "Async Dashboard"}
        )

        # Get saved object (async)
        obj = await client.saved_objects.get(
            type="dashboard",
            id=dashboard.body["id"]
        )

        # Find saved objects (async)
        results = await client.saved_objects.find(
            type="dashboard"
        )

        # Delete saved object (async)
        await client.saved_objects.delete(
            type="dashboard",
            id=dashboard.body["id"]
        )

asyncio.run(main())

Concurrent Operations

Perform multiple saved object operations concurrently:

import asyncio

async def main():
    async with AsyncKibana("http://localhost:5601") as client:
        # Create multiple saved objects concurrently
        objects = await asyncio.gather(
            client.saved_objects.create(
                type="dashboard",
                attributes={"title": "Dashboard 1"}
            ),
            client.saved_objects.create(
                type="dashboard",
                attributes={"title": "Dashboard 2"}
            ),
            client.saved_objects.create(
                type="visualization",
                attributes={"title": "Viz 1"}
            )
        )

        print(f"Created {len(objects)} saved objects")

        # Retrieve multiple objects concurrently
        retrieved = await asyncio.gather(
            client.saved_objects.get(
                type="dashboard",
                id=objects[0].body["id"]
            ),
            client.saved_objects.get(
                type="dashboard",
                id=objects[1].body["id"]
            ),
            client.saved_objects.get(
                type="visualization",
                id=objects[2].body["id"]
            )
        )

asyncio.run(main())
__init__(client, default_space_id=None, validate_spaces=True)[source]

Initialize AsyncSavedObjectsClient with optional space context.

Parameters:

  • client – Parent AsyncBaseClient 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 (default: True)

async create(*, type, attributes, id=None, overwrite=False, references=None, space_id=None, validate_space=None)[source]

Create a new saved object.

Parameters:

  • type (str) – Type of saved object (e.g., ‘dashboard’, ‘visualization’, ‘index-pattern’)

  • attributes (dict[str, Any]) – Attributes of the saved object

  • id (str | None) – Optional ID for the saved object (auto-generated if not provided)

  • overwrite (bool) – If true, overwrite existing object with the same ID

  • references (list[dict[str, Any]] | None) – Optional list of references to other saved objects

  • space_id (str | None) – Optional space ID for space-scoped operations

  • validate_space (bool | None) – Override space validation setting for this operation

Returns:

Created saved object details

Raises:
Return type:

ObjectApiResponse[dict[str, Any]]

async get(*, type, id, space_id=None, validate_space=None)[source]

Get a saved object by type and ID.

Parameters:

  • type (str) – Type of saved object

  • id (str) – ID of the saved object

  • space_id (str | None) – Optional space ID for space-scoped operations

  • validate_space (bool | None) – Override space validation setting for this operation

Returns:

Saved object details

Raises:
Return type:

ObjectApiResponse[dict[str, Any]]

async find(*, type, search=None, search_fields=None, page=None, per_page=None, sort_field=None, has_reference=None, fields=None, space_id=None)[source]

Find saved objects asynchronously.

Parameters:

  • type (str | list[str]) – Type(s) of saved objects to find

  • search (str | None) – Search string

  • search_fields (list[str] | None) – Fields to search in

  • page (int | None) – Page number

  • per_page (int | None) – Items per page

  • sort_field (str | None) – Field to sort by

  • has_reference (dict[str, str] | None) – Filter by reference

  • fields (list[str] | None) – Fields to include in response

  • space_id (str | None) – Optional space ID for space-scoped operations

Returns:

ObjectApiResponse containing search results

Return type:

ObjectApiResponse[dict[str, Any]]

async update(*, type, id, attributes, version=None, references=None, space_id=None, validate_space=None)[source]

Update an existing saved object.

Parameters:

  • type (str) – Type of saved object

  • id (str) – ID of the saved object

  • attributes (dict[str, Any]) – Updated attributes (partial or full)

  • version (str | None) – Optional version for optimistic concurrency control

  • references (list[dict[str, Any]] | None) – Optional updated list of references

  • space_id (str | None) – Optional space ID for space-scoped operations

  • validate_space (bool | None) – Override space validation setting for this operation

Returns:

Updated saved object details

Raises:
Return type:

ObjectApiResponse[dict[str, Any]]

async delete(*, type, id, force=False, space_id=None, validate_space=None)[source]

Delete a saved object.

Parameters:

  • type (str) – Type of saved object

  • id (str) – ID of the saved object

  • force (bool) – If true, force delete even if object has references

  • space_id (str | None) – Optional space ID for space-scoped operations

  • validate_space (bool | None) – Override space validation setting for this operation

Returns:

Deletion confirmation

Raises:
Return type:

ObjectApiResponse[dict[str, Any]]

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]