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)
Feature-level access control (disable specific features per space)
URL-based space selection (/s/space-id/app/…)
Default space always exists and cannot be deleted

Common use cases:

Multi-tenant SaaS applications
Department or team isolation
Development/staging/production environments
Customer-specific dashboards and visualizations

Example

>>> from kibana import Kibana
>>> client = Kibana("http://localhost:5601", api_key="...")
>>>
>>> # Create a space for marketing team
>>> space = client.spaces.create(
...     id="marketing",
...     name="Marketing Team",
...     description="Space for marketing analytics",
...     color="#FF6B6B",
...     initials="MK"
... )
>>>
>>> # 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, disabled_features=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, no special characters except hyphens and underscores).

Parameters:

id (str) – Unique identifier for the space. Must be URL-friendly (lowercase, alphanumeric, hyphens, underscores). Cannot be changed after creation. Examples: “marketing”, “team-a”, “prod_env”
name (str) – Display name for the space. This is 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 hex color code for the space avatar (e.g., “#FF0000”, “#00FF00”). Used in the Kibana UI for visual identification.
initials (str | None) – Optional initials to display in the space avatar (max 2 characters). If not provided, Kibana generates them from the name.
disabled_features (list[str] | None) – Optional list of Kibana feature IDs to disable in this space. Common features include: - “discover”: Discover app - “dashboard”: Dashboards - “canvas”: Canvas - “maps”: Maps - “ml”: Machine Learning - “apm”: APM - “infrastructure”: Infrastructure monitoring - “logs”: Logs - “uptime”: Uptime monitoring

Returns:

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

Raises:

ValueError – If required parameters (id, name) are missing.
BadRequestError – If the space ID format 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:

ObjectApiResponse[dict[str, Any]]

Example

>>> # Create a basic space
>>> space = client.spaces.create(
...     id="engineering",
...     name="Engineering Team"
... )
>>>
>>> # Create a space with full configuration
>>> space = client.spaces.create(
...     id="marketing",
...     name="Marketing Analytics",
...     description="Marketing team's analytics workspace",
...     color="#FF6B6B",
...     initials="MA",
...     disabled_features=["ml", "apm"]
... )
>>> print(space.body["id"])
marketing

get(*, id)[source]¶

Get a space by ID.

Retrieves detailed information about a specific space including its configuration, enabled features, and metadata.

Parameters:

id (str) – The space ID to retrieve (e.g., “default”, “marketing”).

Returns:

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

Raises:

ValueError – If the id parameter is missing.
NotFoundError – If the space does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges to view the space.

Return type:

ObjectApiResponse[dict[str, Any]]

Example

>>> space = client.spaces.get(id="marketing")
>>> print(space.body["name"])
Marketing Team
>>> print(space.body["color"])
#FF6B6B
>>> print(space.body.get("disabledFeatures", []))
['ml', 'apm']

get_all()[source]¶

Get all spaces.

Retrieves a list of all spaces in the Kibana instance that the authenticated user has access to view.

Returns:

ObjectApiResponse containing a list of all spaces. Each space includes id, name, description, color, initials, disabledFeatures, and other metadata.

Raises:

AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges to list spaces.

Return type:

ObjectApiResponse[list[dict[str, Any]]]

Example

>>> spaces = client.spaces.get_all()
>>> for space in spaces.body:
...     print(f"{space['name']} ({space['id']})")
...     if space.get('description'):
...         print(f"  Description: {space['description']}")
Default (default)
Marketing Team (marketing)
  Description: Marketing team's analytics workspace
Engineering (engineering)

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

Update a space.

Updates the configuration of an existing space. Only the provided parameters will be updated; omitted parameters remain unchanged. Note that the space ID cannot be changed after creation.

Parameters:

id (str) – The space ID to update (cannot be changed).
name (str | None) – Optional new display name for the space.
description (str | None) – Optional new description. Pass empty string to clear.
color (str | None) – Optional new hex color code (e.g., “#00FF00”).
initials (str | None) – Optional new initials (max 2 characters).
disabled_features (list[str] | None) – Optional new list of disabled feature IDs. This replaces the entire list, not appends to it.

Returns:

ObjectApiResponse containing the updated space details.

Raises:

ValueError – If the id parameter is missing.
NotFoundError – If the space does not exist.
BadRequestError – If the update parameters are invalid.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges to update the space.

Return type:

ObjectApiResponse[dict[str, Any]]

Example

>>> # Update space name and color
>>> space = client.spaces.update(
...     id="marketing",
...     name="Marketing & Sales",
...     color="#00FF00"
... )
>>>
>>> # Disable additional features
>>> space = client.spaces.update(
...     id="marketing",
...     disabled_features=["ml", "apm", "canvas"]
... )
>>>
>>> # Clear description
>>> space = client.spaces.update(
...     id="marketing",
...     description=""
... )

delete(*, id)[source]¶

Delete a space.

Permanently deletes a space and all its associated saved objects (dashboards, visualizations, index patterns, etc.). This operation cannot be undone.

Warning

Deleting a space will permanently delete all saved objects within that space. This includes dashboards, visualizations, saved searches, and other Kibana objects. The default space cannot be deleted.

Parameters:

id (str) – The space ID to delete. Cannot be “default”.

Returns:

ObjectApiResponse, typically empty for successful deletion.

Raises:

ValueError – If the id parameter is missing.
NotFoundError – If the space does not exist.
BadRequestError – If attempting to delete the default space.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges to delete the space.

Return type:

ObjectApiResponse[dict[str, Any]]

Example

>>> # Delete a space
>>> client.spaces.delete(id="old-project")
>>>
>>> # Verify deletion
>>> try:
...     client.spaces.get(id="old-project")
... except NotFoundError:
...     print("Space successfully deleted")
Space successfully deleted

__init__(client, default_space_id=None, validate_spaces=True)¶

Initialize NamespaceClient with optional space support.

Parameters:

client (BaseClient) – Parent BaseClient 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)

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]

AsyncSpacesClient¶

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

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

Bases: AsyncNamespaceClient

Async client for Kibana Spaces API.

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

Usage

The AsyncSpacesClient provides the same methods as SpacesClient 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 space (async)
        space = await client.spaces.create(
            id="async-space",
            name="Async Space",
            description="Created with async client"
        )

        # Get all spaces (async)
        spaces = await client.spaces.get_all()

        # Update space (async)
        updated = await client.spaces.update(
            id="async-space",
            name="Updated Async Space"
        )

        # Delete space (async)
        await client.spaces.delete(id="async-space")

asyncio.run(main())

Concurrent Space Operations

Perform multiple space operations concurrently:

import asyncio

async def main():
    async with AsyncKibana("http://localhost:5601") as client:
        # Create multiple spaces concurrently
        spaces = await asyncio.gather(
            client.spaces.create(
                id="team-a",
                name="Team A",
                description="Team A workspace"
            ),
            client.spaces.create(
                id="team-b",
                name="Team B",
                description="Team B workspace"
            ),
            client.spaces.create(
                id="team-c",
                name="Team C",
                description="Team C workspace"
            )
        )

        print(f"Created {len(spaces)} spaces")

        # Get all spaces concurrently with their details
        space_details = await asyncio.gather(
            client.spaces.get(id="team-a"),
            client.spaces.get(id="team-b"),
            client.spaces.get(id="team-c")
        )

asyncio.run(main())

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

Create a new space.

Parameters:

id (str) – Unique identifier for the space (URL-friendly)
name (str) – Display name for the space
description (str | None) – Optional description of the space
color (str | None) – Optional hex color code for the space (e.g., “#FF0000”)
initials (str | None) – Optional initials to display for the space (max 2 characters)
disabled_features (list[str] | None) – Optional list of feature IDs to disable in this space

Returns:

ObjectApiResponse containing the created space details

Return type:

ObjectApiResponse[dict[str, Any]]

async get(*, id)[source]¶

Get a space by ID.

Parameters:: id (str) – The space ID to retrieve
Returns:: ObjectApiResponse containing the space details
Return type:: ObjectApiResponse[dict[str, Any]]

async get_all()[source]¶

Get all spaces.

Returns:: ObjectApiResponse containing a list of all spaces
Return type:: ObjectApiResponse[list[dict[str, Any]]]

async update(*, id, name=None, description=None, color=None, initials=None, disabled_features=None)[source]¶

Update a space.

Parameters:

id (str) – The space ID to update
name (str | None) – Optional new display name for the space
description (str | None) – Optional new description
color (str | None) – Optional new hex color code
initials (str | None) – Optional new initials
disabled_features (list[str] | None) – Optional new list of disabled features

Returns:

ObjectApiResponse containing the updated space details

Return type:

ObjectApiResponse[dict[str, Any]]

async delete(*, id)[source]¶

Delete a space.

Parameters:: id (str) – The space ID to delete
Returns:: ObjectApiResponse (typically empty for successful deletion)
Return type:: ObjectApiResponse[dict[str, Any]]

__init__(client, default_space_id=None, validate_spaces=True)¶

Initialize AsyncNamespaceClient with optional space support.

Parameters:

client (AsyncBaseClient) – 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 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]