Skip to content

About

Kestra Client SDK

Resources

Stars

0 stars

Watchers

0 watching

Forks

 
 

Repository files navigation

Kestra workflow orchestrator

Event-Driven Declarative Orchestrator

Last Version License Github star
Kestra infinitely scalable orchestration and scheduling platform Slack

twitter   linkedin   youtube  


Get started in 4 minutes with Kestra

Get started with Kestra in 4 minutes.

Kestra client SDK

Kestra client SDK in various language to interact with a running Kestra instance.

Documention is avaible on https://kestra.io/docs/api-reference/kestra-sdk

SDK usage by language

The repository currently ships SDKs for Python, Java, JavaScript, and Go. The snippets below show how to install each package, authenticate with either Basic credentials or a service account API key, and perform a basic flow lifecycle: create a flow, update it, then trigger a new execution.

Python (kestrapy)

  • Install with pip install kestrapy (Python 3.9+).
  • Configure Configuration.host with the URL of your Kestra instance.
  • For Basic authentication set configuration.username and configuration.password. For service accounts pass the API key as KestraClient(host=..., token=...) (KestraClient does not read configuration.access_token).
from kestrapy import KestraClient, Configuration
from kestrapy.exceptions import ApiException

tenant = "main"
namespace = "demo"
flow_id = "hello_from_sdk"

flow_yaml = """id: hello_from_sdk
namespace: demo

tasks:
  - id: log
    type: io.kestra.plugin.core.log.Log
    message: Hello from the SDK
"""

configuration = Configuration()
configuration.host = "https://<kestra-host>"
configuration.username = "user@kestra.io"
configuration.password = "password"  # replace with your Basic auth secrets

client = KestraClient(configuration)
# Service account alternative:
# client = KestraClient(host="https://<kestra-host>", token="<service-account-api-key>")

try:
    client.flows.create_flow(tenant, flow_yaml)

    updated_flow_yaml = """id: hello_from_sdk
namespace: demo

tasks:
  - id: log
    type: io.kestra.plugin.core.log.Log
    message: Hello after update
"""

    client.flows.update_flow(
        id=flow_id,
        namespace=namespace,
        tenant=tenant,
        body=updated_flow_yaml,
    )

    execution = client.executions.create_execution(
        tenant=tenant,
        namespace=namespace,
        id=flow_id,
        wait=True,
    )
    print("Execution ID:", execution.id)
except ApiException as err:
    print("Kestra API error:", err)

Java (io.kestra:kestra-api-client)

  • Add the dependency to your build: io.kestra:kestra-api-client:2.0.1 (Java 25+).
  • Basic authentication uses the builder method .basicAuth(username, password). Service accounts call .tokenAuth("<service-account-api-key>") instead.
Maven
<dependency>
  <groupId>io.kestra</groupId>
  <artifactId>kestra-api-client</artifactId>
  <version>2.0.1</version>
</dependency>
Gradle (Kotlin DSL)
implementation("io.kestra:kestra-api-client:2.0.1")

Build a client, then perform a basic flow lifecycle:

import io.kestra.sdk.KestraClient;

KestraClient client = KestraClient.builder()
    .url("https://<kestra-host>")
    .basicAuth("user@kestra.io", "password")
    .build();
// Service account alternative:
// KestraClient client = KestraClient.builder()
//     .url("https://<kestra-host>")
//     .tokenAuth("<service-account-api-key>")
//     .build();

String tenant = "main";

The block below is injected from the CI-tested example java/java-sdk/java-sdk-test/src/main/java/io/kestra/example/BasicSDKUsageExample.java (issue #144). Do not edit it by hand — change the example and re-run java test-utils/EmbedSnippets.java --write README.md.

String namespace = "company.team";
String flowId = "hello_from_sdk";

// List the first page of flows in the tenant.
PagedResultsFlow flows = client.flows().searchFlows(tenant, 1, 10, null, List.of());
System.out.println("Found " + flows.getResults().size() + " flows");

// Create a flow from its YAML source.
String flowYaml = """
    id: hello_from_sdk
    namespace: company.team

    tasks:
      - id: hello
        type: io.kestra.plugin.core.log.Log
        message: Hello from the Kestra Java SDK!
    """;
FlowWithSource created = client.flows().createFlow(tenant, flowYaml);
System.out.println("Created flow " + created.getNamespace() + "." + created.getId()
    + " (revision " + created.getRevision() + ")");

// Update the flow — updateFlow takes (namespace, id, tenant, body).
String updatedYaml = """
    id: hello_from_sdk
    namespace: company.team

    tasks:
      - id: hello
        type: io.kestra.plugin.core.log.Log
        message: Hello after update!
    """;
client.flows().updateFlow(namespace, flowId, tenant, updatedYaml);

// Trigger an execution and wait for it to complete.
ExecutionControllerExecutionResponse execution = client.executions()
    .createExecution(tenant, namespace, flowId, null, true, null, null, null, null);
System.out.println("Execution " + execution.getId()
    + " finished in state " + execution.getState().getCurrent());

JavaScript (@kestra-io/kestra-sdk)

  • Install with npm install @kestra-io/kestra-sdk or yarn add @kestra-io/kestra-sdk.
  • Configure the shared client once with configureClient({ baseUrl, auth }), then import the operations of each domain from its module (@kestra-io/kestra-sdk/flows, /executions, ...).
  • For Basic authentication return "<username>:<password>" from auth. For service accounts return the API key for the bearer scheme only — see README_JAVASCRIPT_SDK.md.
import { configureClient } from "@kestra-io/kestra-sdk";
import * as FlowsAPI from "@kestra-io/kestra-sdk/flows";
import * as ExecutionsAPI from "@kestra-io/kestra-sdk/executions";

configureClient({
  baseUrl: "https://<kestra-host>",
  auth: () => "user@kestra.io:password",
  // Service account alternative:
  // auth: (auth) => (auth.scheme === "bearer" ? "<service-account-api-key>" : undefined),
});

const tenant = "main";
const namespace = "demo";
const flowId = "hello_from_sdk";

await FlowsAPI.createFlow({
  tenant,
  body: `id: hello_from_sdk
namespace: demo

tasks:
  - id: log
    type: io.kestra.plugin.core.log.Log
    message: Hello from the SDK
`,
});

await FlowsAPI.updateFlow({
  tenant,
  namespace,
  id: flowId,
  body: `id: hello_from_sdk
namespace: demo

tasks:
  - id: log
    type: io.kestra.plugin.core.log.Log
    message: Hello after update
`,
});

const execution = await ExecutionsAPI.createExecution({ tenant, namespace, id: flowId, wait: true });
console.log("Execution ID:", execution.id);

Go (github.com/kestra-io/client-sdk/go-sdk/v2)

  • Pull the module into your project with go get github.com/kestra-io/client-sdk/go-sdk/v2@latest.
  • Build a KestraClient with NewClient, pointing it at your Kestra host.
  • Authenticate with Basic credentials via WithBasicAuth, or with a service-account token via WithTokenAuth.

Build a client, then perform a basic flow lifecycle:

package main

import (
	"context"
	"fmt"
	"log"

	kestra "github.com/kestra-io/client-sdk/go-sdk/v2/kestra_api_client"
)

func main() {
	client := kestra.NewClient(
		"https://<kestra-host>",
		kestra.WithBasicAuth("user@kestra.io", "password"),
	)
	// Service account alternative:
	// client := kestra.NewClient(
	// 	"https://<kestra-host>",
	// 	kestra.WithTokenAuth("<service-account-api-key>"),
	// )

	if _, err := flowLifecycle(context.Background(), client, "main"); err != nil {
		log.Fatal(err)
	}
}

The flowLifecycle function below is injected from the CI-tested example go-sdk/test/basic_sdk_usage_example.go (issue #144). Do not edit it by hand — change the example and re-run java test-utils/EmbedSnippets.java --write README.md.

// flowLifecycle lists the tenant's flows, creates one from YAML, updates it,
// then triggers an execution and waits for it to finish, returning its id.
func flowLifecycle(ctx context.Context, client *kestra.KestraClient, tenant string) (string, error) {
	namespace := "company.team"
	flowID := "hello_from_sdk"

	// List the first page of flows in the tenant.
	flows, err := client.Flows().SearchFlows(ctx, tenant, kestra.PtrInt(1), kestra.PtrInt(10), nil, nil)
	if err != nil {
		return "", err
	}
	fmt.Printf("Found %d flows\n", flows.GetTotal())

	// Create a flow from its YAML source.
	flowYAML := `id: hello_from_sdk
namespace: company.team

tasks:
  - id: hello
    type: io.kestra.plugin.core.log.Log
    message: Hello from the Kestra Go SDK!
`
	created, err := client.Flows().CreateFlow(ctx, tenant, flowYAML)
	if err != nil {
		return "", err
	}
	fmt.Printf("Created flow %s.%s (revision %d)\n", created.GetNamespace(), created.GetId(), created.GetRevision())

	// Update the flow — UpdateFlow takes (namespace, id, tenant, body).
	updatedYAML := `id: hello_from_sdk
namespace: company.team

tasks:
  - id: hello
    type: io.kestra.plugin.core.log.Log
    message: Hello after update!
`
	if _, err := client.Flows().UpdateFlow(ctx, namespace, flowID, tenant, updatedYAML); err != nil {
		return "", err
	}

	// Trigger an execution and wait for it to complete.
	execution, err := client.Executions().CreateExecution(ctx, tenant, namespace, flowID, nil, kestra.PtrBool(true), nil, nil, nil, nil)
	if err != nil {
		return "", err
	}
	state := execution.GetState()
	fmt.Printf("Execution %s finished in state %s\n", execution.GetId(), state.GetCurrent())

	return execution.GetId(), nil
}

Complex queries (AND / OR filters)

Every *ByQuery / search endpoint accepts grouped filters (Kestra #16197). Each SDK ships a small query DSL so you build AND / OR groups (one level of nesting) without hand-encoding filters[...] strings — and a plain flat filter list keeps producing the exact same wire format as before.

// Java
List<QueryFilter> filters = where(and(
    eq(QueryFilterField.NAMESPACE, "company.team"),
    or(eq(QueryFilterField.STATE, "SUCCESS"), eq(QueryFilterField.STATE, "WARNING"))));
# Python
filters = where(and_(
    eq(F.NAMESPACE, "company.team"),
    or_(eq(F.STATE, "SUCCESS"), eq(F.STATE, "WARNING"))))
// Go
filters := kestra.Where(kestra.And(
    kestra.Eq(kestra.FilterNamespace, "company.team"),
    kestra.Or(kestra.Eq(kestra.FilterState, "SUCCESS"), kestra.Eq(kestra.FilterState, "WARNING"))))

See README_JAVA_SDK.md, README_PYTHON_SDK.md and README_GO_SDK.md for the full helper list. The shared serialization contract is pinned by golden vectors in test-utils/query-filter-golden.json, asserted by every SDK's offline test. (JavaScript support is tracked separately — it lives in the @kestra-io/hey-api-plugin package.)

How to update the SDK

  • Generate openapi from Kestra-EE: ./gradlew clean build updateOpenapiVersion -xtest
  • Move kestra-ee.yml from webserver-ee/build/classes/java/main/META-INF/swagger to the root of the SDK repository
  • Generate the JavaScript SDK using ./generate-sdks.sh javascript 1.0.12 (change the version to SDK-current-version + 1). JavaScript is the only generated SDK — Java (#222), Go (#230) and Python (#237) are hand-written, and generate-sdks.sh refuses to run for them because generating would delete and overwrite hand-written code. Add the equivalent code to those three by hand.
  • Tags can be excluded from every SDK via tagsToSkip in configurations/kestra-openapi-sdk-customizer.json
  • Create the tests for the added functionality in each SDK tests folder
  • Run tests of all SDKs: TMP=~/IdeaProjects/client-sdk && cd $TMP/java/java-sdk && chmod 755 gradlew && ./run-tests.sh develop && cd $TMP/go-sdk && bash ./run-tests.sh develop && cd $TMP/javascript && bash ./run-tests.sh develop && cd $TMP/python/python-sdk && bash ./run-tests.sh develop
  • ⚠ If an existing test fails, you're probably introducing a breaking change (or someone's prior commit did). If that's the case, make sure it's safe to introduce that before merging
  • Commit and make a PR

CI: daily SDK freshness check

The per-PR pipelines test each SDK against the Kestra version resolved for the branch and only run when that SDK's files change. To catch upstream API breaking changes early, .github/workflows/sdk-freshness-check.yml runs every day (05:00 UTC) — and on manual workflow_dispatch — exercising all four SDK test suites against a Kestra server built from the latest line (develop).

The job is non-blocking: it only runs on a schedule / manual trigger, never on PRs, and must not be added to branch-protection required checks. A red run is an early-warning signal, not a merge gate. On failure it posts to Slack (#_int_alert-plugins-build, via the SLACK_WEBHOOK_URL secret) naming the SDK that broke, the Kestra version under test, and a link to the run.

Triaging an alert — when a leg goes red, decide which case applies:

  • The committed spec is stale — develop added/changed an endpoint the SDK doesn't know about yet. Regenerate from the latest spec (see How to update the SDK above) and update tests.
  • A real upstream breaking change — develop removed or altered behaviour the SDK relies on. Surface it to the plugin squad / upstream; the SDK (and downstream consumers like kestractl) will need to absorb it before the next major.

License

Apache 2.0 © Kestra Technologies

Stay up to date

We release new versions every month. Give the main repository a star to stay up to date with the latest releases and get notified about future updates.

Star the repo

About

Kestra Client SDK

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages