ActionsClient¶

Client for managing Kibana action connectors through the Actions API.

Actions (also known as connectors) enable integration with external systems for alerting, notifications, and automation workflows in Kibana.

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

Bases: NamespaceClient

Client for managing Kibana Actions (connectors).

Actions in Kibana are connectors that enable integration with external systems for alerting, notifications, and automation workflows. This client provides comprehensive methods to create, read, update, delete, and execute action connectors with full support for Kibana Spaces.

Connectors can be scoped to specific spaces, enabling multi-tenancy where different teams or projects can have isolated sets of connectors.

Common connector types:

.webhook: HTTP webhooks for custom integrations
.slack: Slack messages and notifications
.email: Email notifications
.index: Write to Elasticsearch indices
.server-log: Server log entries
.pagerduty: PagerDuty incident management
.servicenow: ServiceNow ticket creation
.teams: Microsoft Teams messages
.jira: Jira issue creation

_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 webhook connector
>>> connector = client.actions.create(
...     name="Alert Webhook",
...     connector_type_id=".webhook",
...     config={"url": "https://example.com/webhook"},
...     secrets={"user": "admin", "password": "secret"}
... )
>>>
>>> # Execute the connector
>>> result = client.actions.execute(
...     id=connector.body["id"],
...     params={"message": "Alert triggered!"}
... )
>>>
>>> # Work with space-scoped connectors
>>> marketing_client = client.space("marketing")
>>> connector = marketing_client.actions.create(
...     name="Marketing Webhook",
...     connector_type_id=".webhook",
...     config={"url": "https://marketing.example.com/webhook"}
... )

Overview

The ActionsClient provides methods to create, retrieve, update, delete, and execute action connectors. Connectors can be scoped to specific Kibana Spaces for multi-tenancy.

Creating Connectors

Create a new connector with the create() method:

from kibana import Kibana

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

# Create an index connector
connector = client.actions.create(
    name="My Index Connector",
    connector_type_id=".index",
    config={
        "index": "my-index",
        "executionTimeField": "@timestamp"
    }
)

connector_id = connector.body["id"]
print(f"Created connector: {connector_id}")

Space-Scoped Connectors

Connectors can be created and managed within specific Kibana Spaces:

# Create connector in a specific space
connector = client.actions.create(
    name="Marketing Webhook",
    connector_type_id=".webhook",
    config={"url": "https://marketing.example.com/webhook"},
    space_id="marketing"
)

# Or use a space-scoped client
marketing_client = client.space("marketing")
connector = marketing_client.actions.create(
    name="Marketing Webhook",
    connector_type_id=".webhook",
    config={"url": "https://marketing.example.com/webhook"}
)

Listing Connectors

Retrieve all connectors or list available connector types:

# Get all connectors
connectors = client.actions.get_all()
for connector in connectors.body:
    print(f"{connector['name']}: {connector['connector_type_id']}")

# List available connector types
types = client.actions.list_types()
for connector_type in types.body:
    print(f"{connector_type['id']}: {connector_type['name']}")

Executing Connectors

Execute a connector with specific parameters:

# Execute a webhook connector
result = client.actions.execute(
    id=connector_id,
    params={
        "body": '{"message": "Alert triggered!"}'
    }
)

print(f"Execution status: {result.body['status']}")

Updating and Deleting

Update connector configuration or delete connectors:

# Update connector
updated = client.actions.update(
    id=connector_id,
    name="Updated Connector Name",
    config={"url": "https://new-url.example.com/webhook"}
)

# Delete connector
client.actions.delete(id=connector_id)

Error Handling

Handle common errors when working with connectors:

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

try:
    connector = client.actions.create(
        name="Test Connector",
        connector_type_id=".webhook",
        config={"url": "https://example.com/webhook"},
        space_id="marketing"
    )
except SpaceNotFoundError as e:
    print(f"Space not found: {e.space_id}")
except BadRequestError as e:
    print(f"Invalid configuration: {e.message}")
except ConflictError as e:
    print(f"Connector already exists: {e.message}")

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

Initialize ActionsClient 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
>>> actions = ActionsClient(base_client)
>>>
>>> # Client with default space
>>> marketing_actions = ActionsClient(
...     base_client,
...     default_space_id="marketing",
...     validate_spaces=True
... )

create(*, name, connector_type_id, config, secrets=None, space_id=None, validate_space=None)[source]¶

Create a new action connector.

Parameters:

name (str) – Display name for the connector
connector_type_id (str) – Type of connector (e.g., ‘.email’, ‘.slack’, ‘.webhook’)
config (dict[str, Any]) – Connector configuration (non-sensitive data)
secrets (dict[str, Any] | None) – Connector secrets (sensitive data like API keys, passwords)
space_id (str | None) – Optional space ID to create the connector in
validate_space (bool | None) – Override space validation setting for this operation

Returns:

Created connector details

Raises:

ValueError – If required parameters are missing
BadRequestError – If the connector configuration is invalid
ConflictError – If a connector with the same name already exists
AuthenticationException – If authentication fails
AuthorizationException – If insufficient privileges

Return type:

ObjectApiResponse[dict[str, Any]]

Example

>>> # Create a webhook connector
>>> connector = client.actions.create(
...     name="Alert Webhook",
...     connector_type_id=".webhook",
...     config={"url": "https://example.com/webhook"},
...     secrets={"user": "admin", "password": "secret"}
... )
>>> print(connector["id"])

>>> # Create a Slack connector in a specific space
>>> slack_connector = client.actions.create(
...     name="Slack Alerts",
...     connector_type_id=".slack",
...     config={},
...     secrets={"webhookUrl": "https://hooks.slack.com/services/..."},
...     space_id="marketing"
... )

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

Get an action connector by ID.

Parameters:

id (str) – Connector ID to retrieve
space_id (str | None) – Optional space ID to get the connector from
validate_space (bool | None) – Override space validation setting for this operation

Returns:

Connector details

Raises:

ValueError – If id parameter is missing
NotFoundError – If the connector is not found
AuthenticationException – If authentication fails
AuthorizationException – If insufficient privileges

Return type:

ObjectApiResponse[dict[str, Any]]

Example

>>> connector = client.actions.get(id="my-webhook-connector")
>>> print(connector["name"])
>>> print(connector["connector_type_id"])

>>> # Get connector from specific space
>>> connector = client.actions.get(id="my-connector", space_id="marketing")

get_all(*, space_id=None, validate_space=None)[source]¶

Get all action connectors.

Parameters:

space_id (str | None) – Optional space ID to get connectors from
validate_space (bool | None) – Override space validation setting for this operation

Returns:

List of all connectors

Raises:

AuthenticationException – If authentication fails
AuthorizationException – If insufficient privileges

Return type:

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

Example

>>> connectors = client.actions.get_all()
>>> for connector in connectors:
...     print(f"{connector['name']}: {connector['connector_type_id']}")

>>> # Get connectors from specific space
>>> connectors = client.actions.get_all(space_id="marketing")

list_types()[source]¶

Get all available action connector types.

Returns:

List of available connector types with their capabilities

Raises:

AuthenticationException – If authentication fails
AuthorizationException – If insufficient privileges

Return type:

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

Example

>>> types = client.actions.list_types()
>>> for connector_type in types:
...     print(f"{connector_type['id']}: {connector_type['name']}")
...     if connector_type.get('enabled'):
...         print("  Status: Enabled")

update(*, id, name=None, config=None, secrets=None, space_id=None, validate_space=None)[source]¶

Update an existing action connector.

Parameters:

id (str) – Connector ID to update
name (str | None) – New display name for the connector (optional)
config (dict[str, Any] | None) – New connector configuration (optional)
secrets (dict[str, Any] | None) – New connector secrets (optional)
space_id (str | None) – Optional space ID where the connector exists
validate_space (bool | None) – Override space validation setting for this operation

Returns:

Updated connector details

Raises:

ValueError – If id parameter is missing
NotFoundError – If the connector is not found
AuthenticationException – If authentication fails
AuthorizationException – If insufficient privileges

Return type:

ObjectApiResponse[dict[str, Any]]

Example

>>> # Update connector name and config
>>> updated = client.actions.update(
...     id="my-webhook-connector",
...     name="Updated Webhook",
...     config={"url": "https://new-endpoint.com/webhook"}
... )

>>> # Update connector in specific space
>>> updated = client.actions.update(
...     id="my-slack-connector",
...     secrets={"webhookUrl": "https://hooks.slack.com/services/new..."},
...     space_id="marketing"
... )

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

Delete an action connector.

Parameters:

id (str) – Connector ID to delete
space_id (str | None) – Optional space ID where the connector exists
validate_space (bool | None) – Override space validation setting for this operation

Returns:

Deletion confirmation

Raises:

ValueError – If id parameter is missing
NotFoundError – If the connector is not found
AuthenticationException – If authentication fails
AuthorizationException – If insufficient privileges

Return type:

ObjectApiResponse[dict[str, Any]]

Example

>>> client.actions.delete(id="my-old-connector")

>>> # Delete connector from specific space
>>> client.actions.delete(id="my-connector", space_id="marketing")

execute(*, id, params, space_id=None, validate_space=None)[source]¶

Execute an action connector with the provided parameters.

Parameters:

id (str) – Connector ID to execute
params (dict[str, Any]) – Execution parameters specific to the connector type
space_id (str | None) – Optional space ID where the connector exists
validate_space (bool | None) – Override space validation setting for this operation

Returns:

Execution results

Raises:

ValueError – If required parameters are missing
BadRequestError – If the execution parameters are invalid
NotFoundError – If the connector is not found
AuthenticationException – If authentication fails
AuthorizationException – If insufficient privileges

Return type:

ObjectApiResponse[dict[str, Any]]

Example

>>> # Execute a webhook connector
>>> result = client.actions.execute(
...     id="my-webhook-connector",
...     params={
...         "message": "Alert triggered!",
...         "severity": "high",
...         "timestamp": "2024-01-01T12:00:00Z"
...     }
... )
>>> print(result["status"])

>>> # Execute a Slack connector in specific space
>>> result = client.actions.execute(
...     id="my-slack-connector",
...     params={
...         "message": "System alert: High CPU usage detected"
...     },
...     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]

AsyncActionsClient¶

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

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

Bases: AsyncNamespaceClient

Async client for managing Kibana Actions (connectors).

Actions in Kibana are connectors that enable integration with external systems for alerting, notifications, and automation. This client provides async methods to create, read, update, delete, and execute action connectors.

Common connector types: - .webhook: HTTP webhooks - .slack: Slack messages - .email: Email notifications - .index: Elasticsearch index - .server-log: Server log entries - .pagerduty: PagerDuty incidents - .servicenow: ServiceNow tickets

Usage

The AsyncActionsClient provides the same methods as ActionsClient 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 connector (async)
        connector = await client.actions.create(
            name="Async Webhook",
            connector_type_id=".webhook",
            config={"url": "https://example.com/webhook"}
        )

        # Get all connectors (async)
        connectors = await client.actions.get_all()

        # Execute connector (async)
        result = await client.actions.execute(
            id=connector.body["id"],
            params={"body": '{"message": "Test"}'}
        )

asyncio.run(main())

Concurrent Operations

Perform multiple connector operations concurrently:

import asyncio

async def main():
    async with AsyncKibana("http://localhost:5601") as client:
        # Create multiple connectors concurrently
        connectors = await asyncio.gather(
            client.actions.create(
                name="Webhook 1",
                connector_type_id=".webhook",
                config={"url": "https://example1.com/webhook"}
            ),
            client.actions.create(
                name="Webhook 2",
                connector_type_id=".webhook",
                config={"url": "https://example2.com/webhook"}
            ),
            client.actions.create(
                name="Index Connector",
                connector_type_id=".index",
                config={"index": "logs"}
            )
        )

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

asyncio.run(main())

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

Initialize AsyncActionsClient 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(*, name, connector_type_id, config, secrets=None, space_id=None, validate_space=None)[source]¶

Create a new action connector.

Parameters:

name (str) – Display name for the connector
connector_type_id (str) – Type of connector (e.g., ‘.email’, ‘.slack’, ‘.webhook’)
config (dict[str, Any]) – Connector configuration (non-sensitive data)
secrets (dict[str, Any] | None) – Connector secrets (sensitive data like API keys, passwords)
space_id (str | None) – Optional space ID to create the connector in
validate_space (bool | None) – Override space validation setting for this operation

Returns:

Created connector details

Raises:

ValueError – If required parameters are missing
BadRequestError – If the connector configuration is invalid
ConflictError – If a connector with the same name already exists
SpaceNotFoundError – If space doesn’t exist and validation is enabled
InvalidSpaceIdError – If space ID format is invalid
AuthenticationException – If authentication fails
AuthorizationException – If insufficient privileges

Return type:

ObjectApiResponse[dict[str, Any]]

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

Get an action connector by ID.

Parameters:

id (str) – Connector ID to retrieve
space_id (str | None) – Optional space ID to get the connector from
validate_space (bool | None) – Override space validation setting for this operation

Returns:

Connector details

Raises:

ValueError – If id parameter is missing
NotFoundError – If the connector is not found
SpaceNotFoundError – If space doesn’t exist and validation is enabled
InvalidSpaceIdError – If space ID format is invalid
AuthenticationException – If authentication fails
AuthorizationException – If insufficient privileges

Return type:

ObjectApiResponse[dict[str, Any]]

async get_all(*, space_id=None, validate_space=None)[source]¶

Get all action connectors.

Parameters:

space_id (str | None) – Optional space ID to get connectors from
validate_space (bool | None) – Override space validation setting for this operation

Returns:

List of all connectors

Raises:

SpaceNotFoundError – If space doesn’t exist and validation is enabled
InvalidSpaceIdError – If space ID format is invalid
AuthenticationException – If authentication fails
AuthorizationException – If insufficient privileges

Return type:

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

async list_types()[source]¶

Get all available action connector types.

Returns:

List of available connector types with their capabilities

Raises:

AuthenticationException – If authentication fails
AuthorizationException – If insufficient privileges

Return type:

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

async update(*, id, name=None, config=None, secrets=None, space_id=None, validate_space=None)[source]¶

Update an existing action connector.

Parameters:

id (str) – Connector ID to update
name (str | None) – New display name for the connector (optional)
config (dict[str, Any] | None) – New connector configuration (optional)
secrets (dict[str, Any] | None) – New connector secrets (optional)
space_id (str | None) – Optional space ID to update the connector in
validate_space (bool | None) – Override space validation setting for this operation

Returns:

Updated connector details

Raises:

ValueError – If id parameter is missing
NotFoundError – If the connector is not found
SpaceNotFoundError – If space doesn’t exist and validation is enabled
InvalidSpaceIdError – If space ID format is invalid
AuthenticationException – If authentication fails
AuthorizationException – If insufficient privileges

Return type:

ObjectApiResponse[dict[str, Any]]

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

Delete an action connector.

Parameters:

id (str) – Connector ID to delete
space_id (str | None) – Optional space ID to delete the connector from
validate_space (bool | None) – Override space validation setting for this operation

Returns:

Deletion confirmation

Raises:

ValueError – If id parameter is missing
NotFoundError – If the connector is not found
SpaceNotFoundError – If space doesn’t exist and validation is enabled
InvalidSpaceIdError – If space ID format is invalid
AuthenticationException – If authentication fails
AuthorizationException – If insufficient privileges

Return type:

ObjectApiResponse[dict[str, Any]]

async execute(*, id, params, space_id=None, validate_space=None)[source]¶

Execute an action connector with the provided parameters.

Parameters:

id (str) – Connector ID to execute
params (dict[str, Any]) – Execution parameters specific to the connector type
space_id (str | None) – Optional space ID to execute the connector in
validate_space (bool | None) – Override space validation setting for this operation

Returns:

Execution results

Raises:

ValueError – If required parameters are missing
BadRequestError – If the execution parameters are invalid
NotFoundError – If the connector is not found
SpaceNotFoundError – If space doesn’t exist and validation is enabled
InvalidSpaceIdError – If space ID format is invalid
AuthenticationException – If authentication fails
AuthorizationException – If insufficient privileges

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]