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.

Deprecated since version Kibana: 8.7 The single-object and bulk CRUD endpoints (create, get, update, delete, find, resolve and the bulk_* methods) are deprecated in Kibana 9.4.3. Prefer the type-specific APIs (e.g. client.dashboards, client.data_views) or the spec-current export/import_objects APIs, which remain fully supported.

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 (deprecated endpoints)
Bulk create/get/update/delete/resolve operations
NDJSON export and multipart import (spec-current)
Space-scoped operations for multi-tenancy
Reference management between objects
Version control with optimistic concurrency

_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"
...     }
... )
>>>
>>> # Export objects as NDJSON and re-import them
>>> exported = client.saved_objects.export(
...     objects=[{"type": "dashboard", "id": dashboard["id"]}]
... )
>>> result = client.saved_objects.import_objects(
...     file=list(exported), overwrite=True
... )
>>>
>>> # 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, initial_namespaces=None, core_migration_version=None, type_migration_version=None, space_id=None, validate_space=None)[source]¶

Create a new saved object.

POST /api/saved_objects/{type} or POST /api/saved_objects/{type}/{id}

Deprecated since version Kibana: 8.7 Deprecated in Kibana 9.4.3. Use the type-specific APIs (e.g. client.dashboards.create, client.data_views.create) or import_objects() instead.

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
initial_namespaces (list[str] | None) – Identifiers of the spaces the object is shared into when it is created (for shareable object types)
core_migration_version (str | None) – The Kibana version that last migrated this document (preserve when creating objects outside of Kibana)
type_migration_version (str | None) – The type version that last migrated this document (preserve when creating objects outside of Kibana)
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:

ValueError – If required parameters are missing
BadRequestError – If the saved object data is invalid
ConflictError – If a saved object with the same ID already exists
AuthenticationException – If authentication fails
AuthorizationException – If insufficient privileges

Return type:

SavedObjectsClient¶

AsyncSavedObjectsClient¶