SDK API Reference
Complete reference for all SDK classes, methods, and functions.Client
The main entry point for interacting with Kubiya API.Class: Client
Parameters
Parameter | Type | Default | Description |
---|---|---|---|
api_key | str | None | Kubiya API key. If not provided, reads from KUBIYA_API_KEY env var |
api_url | str | "https://api.kubiya.ai" | API endpoint URL |
org_name | str | None | Organization name for multi-org accounts |
timeout | int | 30 | Request timeout in seconds |
retry_count | int | 3 | Number of retries for failed requests |
verify_ssl | bool | True | Whether to verify SSL certificates |
proxy | str | None | HTTP/SOCKS proxy URL |
Methods
execute_workflow(workflow, params=None, stream=False, runner=None)
Execute a workflow.
workflow
: Workflow object or dictparams
: Dict of parameters to pass to workflowstream
: Boolean to enable streaming responserunner
: String name of the runner (created via Kubiya platform). Defaults to “kubiya-hosted”
ExecutionResult
or generator of StreamEvent
Runners must be created through the Kubiya platform (web interface or API). The platform will provide a Kubernetes manifest or Helm chart to deploy the runner in your infrastructure.
list_workflows()
List all workflows in the organization.
get_workflow(name)
Get a specific workflow by name.
test_connection()
Test API connectivity and authentication.
Workflow
Class: Workflow
Methods
add_step(step)
Add a step to the workflow.
to_dict()
Convert workflow to dictionary representation.
to_yaml()
Convert workflow to YAML string.
validate()
Validate workflow structure and dependencies.
execute(client=None, **kwargs)
Execute the workflow.
Step
Class: Step
Properties
Property | Type | Description |
---|---|---|
name | str | Unique step identifier |
image | str | Docker image to use |
command | str | Command to execute |
script | str | Script content to run |
env | Dict[str, str] | Environment variables |
volumes | Dict[str, str] | Volume mounts |
resources | Dict[str, Any] | Resource limits/requests |
depends | List[str] | Step dependencies |
retry | RetryPolicy | Retry configuration |
timeout | str | Execution timeout |
when | str | Conditional execution |
outputs | Dict[str, str] | Output mappings |
DSL Functions
workflow
Decorator
step
Functions
step.shell(command, **kwargs)
Execute a shell command.
step.python(script, **kwargs)
Execute Python code.
step.container(image, **kwargs)
Run a container with advanced options.
step.inline_agent(message, **kwargs)
Execute an inline AI agent.
Providers
Function: get_provider(name, **kwargs)
Get a workflow provider instance.
Class: BaseProvider
Base class for custom providers.
Streaming
Class: StreamEvent
Stream Event Types
Type | Description | Data Fields |
---|---|---|
workflow.started | Workflow execution started | workflow_id , name |
step.started | Step execution started | step_name , image |
log | Log output | message , level |
step.completed | Step finished | step_name , exit_code , duration |
workflow.completed | Workflow finished | workflow_id , status |
error | Error occurred | message , step_name |
Errors
Exception Classes
KubiyaError
Base exception for all SDK errors.
AuthenticationError
Raised for authentication failures.
ValidationError
Raised for workflow validation failures.
ExecutionError
Raised for workflow execution failures.
Utilities
Function: load_workflow(path)
Load workflow from YAML file.
Function: save_workflow(workflow, path)
Save workflow to YAML file.
Function: merge_workflows(*workflows)
Merge multiple workflows into one.
Type Definitions
RetryPolicy
ResourceSpec
Parameter
Examples
Basic Workflow
Streaming Execution
Error Handling
Version Compatibility
SDK Version | API Version | Python Version |
---|---|---|
2.0.x | v2 | 3.8+ |
1.5.x | v1 | 3.7+ |
1.0.x | v1 | 3.6+ |