SpacesClient¶

Client for managing Kibana Spaces through the Spaces API.

Spaces allow you to organize your Kibana objects (dashboards, visualizations, saved objects) into separate, isolated areas. Each space can have its own set of saved objects and can be used to implement multi-tenancy in Kibana.

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

Bases: NamespaceClient

Client for Kibana Spaces API.

Spaces allow you to organize your Kibana objects (dashboards, visualizations, index patterns, etc.) into separate, isolated areas. Each space has its own set of saved objects and can be used to implement multi-tenancy, enabling different teams or projects to work independently within the same Kibana instance.

Key features of Spaces:

Isolated saved objects per space
Customizable appearance (color, initials, custom avatar image)
Solution views (“es”, “oblt”, “security”, “classic”) introduced in 9.x
Feature-level access control (disable specific features per space)
URL-based space selection (/s/space-id/app/…)
Copying and sharing saved objects between spaces
Default space always exists and cannot be deleted

Example

>>> from kibana import Kibana
>>> client = Kibana("http://localhost:5601", api_key="...")
>>>
>>> # Create a space for the marketing team
>>> space = client.spaces.create(
...     id="marketing",
...     name="Marketing Team",
...     description="Space for marketing analytics",
...     color="#FF6B6B",
...     initials="MK",
...     solution="classic",
... )
>>>
>>> # List all spaces
>>> spaces = client.spaces.get_all()
>>> for space in spaces.body:
...     print(f"{space['name']} ({space['id']})")
>>>
>>> # Work within a specific space
>>> marketing_client = client.space("marketing")
>>> connectors = marketing_client.actions.get_all()

Overview

The SpacesClient provides methods to create, retrieve, update, and delete Kibana Spaces. Spaces enable multi-tenancy by isolating saved objects and providing separate workspaces for different teams or use cases.

Creating Spaces

Create a new space with the create() method:

from kibana import Kibana

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

# Create a space
space = client.spaces.create(
    id="marketing",
    name="Marketing Team",
    description="Space for the marketing team",
    color="#FF6B6B",
    initials="MK"
)

print(f"Created space: {space.body['id']}")

Space Configuration Options

Spaces can be configured with various options:

# Create space with disabled features
space = client.spaces.create(
    id="sales",
    name="Sales Team",
    description="Sales team workspace",
    color="#4ECDC4",
    initials="ST",
    disabled_features=["dev_tools", "advancedSettings"]
)

# Create space with custom image URL
space = client.spaces.create(
    id="engineering",
    name="Engineering",
    description="Engineering team space",
    image_url="https://example.com/logo.png"
)

Listing and Retrieving Spaces

Get all spaces or retrieve a specific space:

# Get all spaces
spaces = client.spaces.get_all()
for space in spaces.body:
    print(f"{space['id']}: {space['name']}")

# Get a specific space
space = client.spaces.get(id="marketing")
print(f"Space name: {space.body['name']}")
print(f"Description: {space.body['description']}")

Updating Spaces

Update space configuration:

# Update space name and description
updated = client.spaces.update(
    id="marketing",
    name="Marketing Department",
    description="Updated description for marketing team"
)

# Update disabled features
updated = client.spaces.update(
    id="marketing",
    disabled_features=["dev_tools", "advancedSettings", "indexPatterns"]
)

Deleting Spaces

Delete a space and all its saved objects:

# Delete a space
client.spaces.delete(id="marketing")

Warning

Deleting a space permanently removes all saved objects within that space. This operation cannot be undone.

Space-Scoped Operations

Use spaces with other API clients for multi-tenancy:

# Create a space
space = client.spaces.create(
    id="team-a",
    name="Team A",
    description="Team A workspace"
)

# Create a space-scoped client
team_a_client = client.space("team-a")

# Create connector in Team A's space
connector = team_a_client.actions.create(
    name="Team A Webhook",
    connector_type_id=".webhook",
    config={"url": "https://team-a.example.com/webhook"}
)

# Create dashboard in Team A's space
dashboard = team_a_client.saved_objects.create(
    type="dashboard",
    attributes={"title": "Team A Dashboard"}
)

Error Handling

Handle common errors when working with spaces:

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

try:
    space = client.spaces.create(
        id="my-space",
        name="My Space"
    )
except ConflictError as e:
    print(f"Space already exists: {e.message}")
except InvalidSpaceIdError as e:
    print(f"Invalid space ID: {e.space_id}")
except BadRequestError as e:
    print(f"Invalid configuration: {e.message}")

try:
    space = client.spaces.get(id="nonexistent")
except NotFoundError as e:
    print(f"Space not found: {e.message}")

create(*, id, name, description=None, color=None, initials=None, image_url=None, disabled_features=None, solution=None)[source]¶

Create a new space.

Creates a new Kibana space with the specified configuration. The space ID must be unique and URL-friendly (lowercase alphanumeric, hyphens and underscores only) and cannot be changed after creation.

Parameters:

id (str) – Unique identifier for the space. Limited to lowercase alphanumeric, underscore, and hyphen characters (a-z, 0-9, _, -). Examples: “marketing”, “team-a”, “prod_env”.
name (str) – Display name for the space. Shown in the Kibana UI and can contain any characters.
description (str | None) – Optional description explaining the purpose of the space. Displayed in the space selector.
color (str | None) – Optional hexadecimal color code for the space avatar (e.g., “#FF0000”). By default, the color is generated from the name.
initials (str | None) – Optional one or two characters shown in the space avatar. If not provided, Kibana generates them from the name.
image_url (str | None) – Optional data-URL encoded image to display in the space avatar instead of initials. For best results use a 64x64 image. Sent as the imageUrl body field.
disabled_features (list[str] | None) – Optional list of Kibana feature IDs to turn off in this space (e.g., “discover”, “dashboard”, “canvas”, “maps”, “ml”, “apm”, “slo”, “uptime”).
solution (str | None) – Optional solution view for the space. One of "es" (Elasticsearch), "oblt" (Observability), "security" (Security), or "classic". Controls which navigation and features the space presents.

Returns:

ObjectApiResponse containing the created space details including id, name, description, color, initials, disabledFeatures, and solution.

Raises:

ValueError – If required parameters (id, name) are empty.
BadRequestError – If the space ID format or solution value is invalid.
ConflictError – If a space with the same ID already exists.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges to create spaces.

Return type:

SpacesClient¶

AsyncSpacesClient¶