Kestra SDK

Interact with Kestra’s API with multiple language SDKs.

Java, Python, JavaScript, and Go SDKs

There are official Kestra SDKs for Java, Python, JavaScript, and Go. These SDKs provide a convenient way to interact with Kestra’s API and build custom applications on top of it.

To demonstrate how to use the SDKs, let’s create a simple flow that logs a message. This example assumes you have a Kestra instance running and accessible via the KESTRA_HOST environment variable, along with your username and password set in .env file such as:

KESTRA_HOST=http://localhost:8080
KESTRA_USERNAME=admin@kestra.io
KESTRA_PASSWORD=Admin1234

First, create a virtual environment and install the Python SDK:

uv venv
source .venv/bin/activate
uv pip install kestrapy
uv pip install python-dotenv # For loading auth environment variables from .env file

Now, use the following Python script to create or update a flow that logs a message:

import kestra_api_client
from dotenv import load_dotenv
import os
import json
load_dotenv()
configuration = kestra_api_client.Configuration(
    host = os.environ.get("KESTRA_HOST"),
    username = os.environ.get("KESTRA_USERNAME"),
    password = os.environ.get("KESTRA_PASSWORD")
)
api_client = kestra_api_client.ApiClient(configuration)
api_instance = kestra_api_client.FlowsApi(api_client)
tenant = 'main'
flow_id = 'sdk'
namespace = 'demo'
body = f"""id: {flow_id}
namespace: {namespace}
tasks:
  - id: hello
    type: io.kestra.plugin.core.log.Log
    message: Hello from the SDK! 👋
"""
try:
    api_response = api_instance.create_flow(tenant, body)
    print(api_response)
except kestra_api_client.rest.ApiException as e:
    if e.status == 422 and "Flow id already exists" in json.loads(e.body).get("message", ""):
        try:
            api_response = api_instance.update_flow(flow_id, namespace, tenant, body)
            print(api_response)
        except ValueError:
            print("Flow updated successfully")
    else:
        print(e)

In the Kestra UI, there will now be a flow with the ID sdk that logs the hello message.

Refer to the Client SDK repository on GitHub for more information and check out the Java, JavaScript, and Go READMEs for more details getting started with them.

Kestra plugin

The dedicated Kestra plugin is developed with the Java SDK. The plugin enables you to interact with flows, executions, and namespaces via tasks and provides tasks to interact with Kestra’s own metadata, such as listing all flows in a namespace or exporting flow definitions. To see it in action check out the video below.

Example flow

To test the Kestra Plugin, use the following example flow that lists all namespaces and their flows, then logs the output.

id: kestra_plugin
namespace: demo
tasks:
  - id: list_namespaces
    type: io.kestra.plugin.kestra.namespaces.List
  - id: loop
    type: io.kestra.plugin.core.flow.ForEach
    values: "{{ outputs.list_namespaces.namespaces }}"
    tasks:
      - id: list_flows
        type: io.kestra.plugin.kestra.flows.List
        namespace: "{{ taskrun.value }}"
  - id: log_output
    type: io.kestra.plugin.core.log.Log
    message: "{{ outputs.list_flows | jq('[.[] .flows[] | {namespace: .namespace, id: .id}]') | first }}"
pluginDefaults:
  - type: io.kestra.plugin.kestra
    values:
      kestraUrl: http://host.docker.internal:8080
      auth:
        username: admin@kestra.io # pass your Kestra username as secret or KV pair
        password: Admin1234 # pass your Kestra password as secret or KV pair