The Kestrel Python SDK

Workflows-as-code is how platform teams keep automation reviewable, versioned, and reproducible. Today we're shipping the Kestrel Python SDK — a typed, fluent library for building and operating Kestrel Workflows from your application code, scripts, and CI/CD, with full IDE autocompletion the whole way.

pip install kestrel-workflows

Build workflows with typed classes

The builder pattern mirrors the visual canvas: a Workflow with a Trigger, chained Action steps, plus Condition branches and Approval gates. Every integration has typed factory methods, so your editor autocompletes triggers, actions, and their parameters.

from kestrel import KestrelClient
from kestrel.workflows import Workflow, Trigger, Action

wf = (
    Workflow("Pod Crash RCA + Jira")
    .description("Run RCA on pod crash, create a Jira ticket")
    .trigger(
        Trigger.k8s_pod_status()
        .reasons("CrashLoopBackOff")
        .namespace("production")
    )
    .cooldown(hours=24)
    .then(Action.kestrel_trigger_rca().label("Run RCA"))
    .then(Action.jira_create_ticket()
        .project("KAN")
        .title("{{incident.title}}")
        .priority("High")
    )
    .alert_on_failure(channel="alerts-channel-id")
)

client = KestrelClient(api_key="kestrel_sk_...")
created = client.workflows.deploy(wf, activate=True)
print(f"Deployed: {created.id} ({created.status})")

Triggers and actions support fluent filter chaining — scope a trigger to specific clusters, namespaces, or workloads; template action parameters with {{incident.title}}-style variables that resolve from earlier steps. The same workflow you build here is the one you see on the canvas; the canvas and the SDK are two views of one definition.

Branch, gate, and generate

Add conditional branching with Condition.equals(...) and .on_true(...) / .on_false(...), and human-in-the-loop gates with Approval.slack("#approvals"), Approval.manual(), Approval.pr_approval(), or Approval.pr_merge(). Prefer to start from words? client.workflows.generate("...") turns a plain-English description into a workflow you can refine in code.

Operate, not just author

The SDK covers the whole lifecycle, so you can wire Kestrel into your own tooling:

• Manage — list, get, activate, pause, and delete workflows.
• Test & wait — kick off a test execution and block on the result with client.executions.wait(...).
• Executions — page through execution history and inspect step results.
• Approvals — list pending gates and approve or reject with a justification.
• Versioning — list version history and roll back to any previous version.
• Replay — re-run a failed execution from the beginning or from the failed step.

Sync or async

Use KestrelClient for straightforward scripts, or AsyncKestrelClient for the same API surface with async/await. Authenticate with an API key, or reuse your CLI session with KestrelClient.from_config(). Typed errors like NotFoundError and AuthError make failures easy to handle.

Scoped, auditable access

SDK access uses API keys you create and manage on the API Keys page — the same keys that power the CLI and MCP server. Name a key, pick its scopes, and set an expiration (No expiration, 30 days, 90 days, or 1 year). Scopes are granular — workflows:read, workflows:write, workflows:activate, workflows:delete, executions:read, executions:cancel, approvals:read, approvals:manage, requests:read, requests:manage, and catalog:read — or grant Full Access. So an automation that only needs to read executions doesn't have permission to delete a workflow — and you can scope permissions across teams, giving each one exactly the access its automations require.

The page tracks every key's scopes, status, last-used time, expiration, and creation date, and lets you revoke or delete a key at any time — so the access your code holds stays visible and revocable as your automations evolve.

Getting Started

Run pip install kestrel-workflows, create a scoped API key under Workflows → API Keys, and deploy your first workflow in a few lines. The full reference — every trigger, action, condition, and approval — is in the Python SDK docs.