SDK Server Overview

Production-ready REST API server for Kubiya Workflow SDK

SDK Server Overview

The Kubiya Workflow SDK includes a production-ready REST API server that provides HTTP endpoints for workflow management, AI-powered generation, and real-time execution streaming.

Features

REST API

Complete RESTful API for all SDK operations

SSE Streaming

Real-time execution updates via Server-Sent Events

AI Integration

Built-in support for AI providers

Authentication

Secure API key authentication

Quick Start

Starting the Server

# Using the CLI
kubiya-server

# With custom settings
kubiya-server --host 0.0.0.0 --port 8000

# Using Python module
python -m kubiya_workflow_sdk.server

# Using Docker
docker run -p 8000:8000 kubiya-sdk-server

Configuration

The server can be configured via environment variables:

export HOST=0.0.0.0
export PORT=8000
export LOG_LEVEL=INFO
export CORS_ORIGINS='["*"]'

API Endpoints

Core Endpoints

Method	Endpoint	Description
GET	/health	Health check
GET	/docs	OpenAPI documentation
GET	/api/v1/providers	List AI providers
POST	/api/v1/compose	Generate/execute workflows
POST	/api/v1/workflows/execute	Execute workflow directly

Authentication

All API endpoints (except /health) require authentication:

curl -H "Authorization: Bearer $KUBIYA_API_KEY" \
  http://localhost:8000/api/v1/providers

Server Architecture

Key Components

1. FastAPI Application

Built on FastAPI for:

• High performance async handling
• Automatic OpenAPI documentation
• Type validation
• CORS support

2. Streaming Support

Real-time updates using SSE:

• Workflow generation progress
• Execution status updates
• Step outputs and logs
• Error notifications

3. Provider Integration

Seamless integration with AI providers:

• Dynamic provider loading
• Unified API interface
• Streaming format support

Usage Examples

Generate Workflow (cURL)

curl -X POST http://localhost:8000/api/v1/compose \
  -H "Authorization: Bearer $KUBIYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "adk",
    "task": "Create backup workflow",
    "mode": "plan"
  }'

Python Client

import requests

response = requests.post(
    "http://localhost:8000/api/v1/compose",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "provider": "adk",
        "task": "Deploy application",
        "mode": "act",
        "stream": True
    },
    stream=True
)

for line in response.iter_lines():
    if line:
        print(line.decode('utf-8'))

JavaScript/TypeScript

const eventSource = new EventSource(
  'http://localhost:8000/api/v1/compose?' + 
  new URLSearchParams({
    provider: 'adk',
    task: 'Check system health',
    mode: 'act'
  }),
  {
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  }
);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Event:', data);
};

Deployment Options

Local Development

# Install SDK with server
pip install kubiya-workflow-sdk[server]

# Start server
kubiya-server --reload

# Install SDK with server
pip install kubiya-workflow-sdk[server]

# Start server
kubiya-server --reload

# Using pre-built image
docker run -p 8000:8000 \
  -e KUBIYA_API_KEY=$KUBIYA_API_KEY \
  kubiya-sdk-server

apiVersion: apps/v1
kind: Deployment
metadata:
  name: kubiya-server
spec:
  replicas: 3
  template:
    spec:
      containers:
      - name: server
        image: kubiya-sdk-server
        ports:
        - containerPort: 8000

Monitoring & Observability

Health Checks

# Liveness probe
curl http://localhost:8000/health

# Response
{
  "status": "healthy",
  "version": "2.0.0",
  "timestamp": "2024-01-20T10:30:00Z"
}

Logging

Structured JSON logging with levels:

{
  "timestamp": "2024-01-20T10:30:00Z",
  "level": "INFO",
  "message": "Workflow executed successfully",
  "workflow_id": "backup-123",
  "duration": 45.2
}

Metrics

Prometheus-compatible metrics endpoint (coming soon):

• Request count and latency
• Workflow execution metrics
• Provider usage statistics

Security Considerations

1. API Key Management: Store keys securely, rotate regularly
2. CORS Configuration: Restrict origins in production
3. Rate Limiting: Implement rate limits for API endpoints
4. TLS/SSL: Always use HTTPS in production

Next Steps

API Endpoints

Detailed endpoint documentation

Authentication

Security and authentication guide

SSE Streaming

Real-time streaming details

Deployment

Production deployment guide