Kubiya LogoKubiya Developer Docs

API Reference

API reference for the Agent Composer UI - proxies and integrations with Kubiya platform

API Reference

The Agent Composer UI provides several API endpoints that primarily serve as proxies to the Kubiya platform APIs and manage local UI state. This reference covers the actual implemented endpoints.

Base URL & Authentication

# Local UI API Base
http://localhost:3000/api
 
# Authentication (required for most endpoints)
Authorization: Bearer <id_token>
Cookie: auth0-session=<session_cookie>

Authentication Required: Most endpoints require Auth0 authentication. The UI uses ID tokens from Auth0 sessions to authenticate with the underlying Kubiya API.

Core Endpoints

Agent Management

GET /api/agents

Proxy to Kubiya API for listing all available agents.

// Response Schema (from Kubiya API)
[
  {
    "uuid": "string",
    "name": "string", 
    "description": "string",
    "metadata": {},
    "avatar_url": "string",
    "created_at": "string",
    "last_updated": "string",
    "tools": [],
    "workflows": [],
    "inline_tools": [],
    "inline_workflows": []
  }
]

POST /api/agents

Create new agent or revalidate cache.

// Cache revalidation
{
  "action": "revalidate"
}
 
// Agent creation (proxied to Kubiya API)
{
  "name": "string",
  "description": "string",
  "sources": [],
  "inline_tools": [],
  "inline_workflows": []
}

Task Management (UI State)

GET /api/tasks?userId={userId}

Retrieve tasks from Redis storage (UI task state only).

// Response Schema
{
  "tasks": [
    {
      "id": "string",
      "userId": "string", 
      "title": "string",
      "description": "string",
      "status": "pending" | "running" | "completed" | "failed" | "cancelled",
      "createdAt": "string",
      "updatedAt": "string",
      "steps": [
        {
          "id": "string",
          "type": "string",
          "title": "string", 
          "content": "string",
          "status": "string",
          "timestamp": "number"
        }
      ]
    }
  ]
}

POST /api/tasks

Save task to Redis storage or save entire task state.

// Save individual task
{
  "task": {
    "id": "string",
    "userId": "string",
    "title": "string",
    "description": "string",
    // ... other task properties
  }
}
 
// Save complete task state
{
  "userId": "string",
  "threads": [],
  "backgroundTasks": [],
  "activeThreadId": "string",
  "globalSettings": {}
}

DELETE /api/tasks?userId={userId}&taskId={taskId}

Delete specific task or all user tasks from Redis.

POST /api/tasks/cancel

Cancel a running task.

// Request Schema
{
  "taskId": "string"
}
 
// Response Schema  
{
  "success": true,
  "message": "Task cancelled successfully",
  "taskId": "string",
  "status": "cancelled"
}

Real-Time Streaming

POST /api/direct-stream

Stream task execution through ADK Orchestrator backend.

// Request Schema
{
  "userID": "string",
  "userEmail": "string", 
  "orgId": "string",
  "conversationId": "string",
  "model": "string",
  "messages": [],
  "agentId": "string",
  "prompt": "string",
  "authToken": "string",
  "mode": "direct" | "plan",
  "no_infra": true,
  "auto_approve": false,
  "approval_level": "critical" | "all" | "none"
}

The response is a Server-Sent Events (SSE) stream with Vercel AI SDK format:

// SSE Event Types
data: 0:{"type":"task_start","task_id":"12345"}
data: 1:{"type":"step_start","step":"build_application"}  
data: 2:{"type":"step_output","content":"Building React app..."}
data: 3:{"type":"step_complete","step":"build_application","status":"success"}
data: d:{"finishReason":"stop"}

GET /api/direct-stream?taskId={taskId}

Stream task updates from Redis storage.

// SSE Events
data: {"type":"initial","task":{},"steps":[],"timestamp":1234567890}
data: {"type":"update","task":{},"steps":[],"timestamp":1234567890}
data: {"type":"status_update","status":"completed","timestamp":1234567890}
data: {"finishReason":"stop"}

GET /api/tasks/stream?taskId={taskId}

Alternative streaming endpoint for task updates.

Runner Information

GET /api/runners

Proxy to Kubiya API for available execution runners.

// Response Schema (from Kubiya API)
[
  {
    "id": "string",
    "name": "string",
    "type": "kubernetes" | "docker" | "serverless",
    "region": "string",
    "capabilities": [],
    "resource_limits": {},
    "health_status": "healthy" | "degraded" | "unhealthy",
    "current_load": 0.65
  }
]

POST /api/runners/{runnerName}

Generate runner manifest (proxy to Kubiya API).

Authentication & User Info

GET /api/auth/token

Get authentication token from current session.

// Response Schema
{
  "token": "string",
  "expires_in": 3600,
  "token_type": "Bearer", 
  "source": "auth0-id-token",
  "auth_source_used": "string",
  "org_id": "string"
}

GET /api/user

Get current user information.

// Response Schema
{
  "sub": "string",
  "email": "string",
  "name": "string", 
  "nickname": "string",
  "picture": "string",
  "org_name": "string",
  "org_id": "string",
  "organization": "string",
  "email_verified": true,
  "updated_at": "string"
}

Secrets Management

GET /api/v2/secrets/get_value/{secretName}

Retrieve secret value (proxy to Kubiya API).

GET /api/v2/secrets/{...path}

General secrets API proxy to Kubiya API.

Health & Utility

GET /api/health

Health check endpoint.

// Response Schema
{
  "status": "ok",
  "timestamp": "2024-12-25T09:00:00Z",
  "environment": "development",
  "vercel": false
}

External Webhook Integration

External Webhooks: The Agent Composer generates webhook URLs that point to compose.kubiya.ai, not this local UI. These are handled by the Kubiya platform directly.

Webhook URL Format

# Generated webhook URLs (external to this UI)
POST https://compose.kubiya.ai/api/webhooks/tasks/{task-id}/{secret}
Content-Type: application/json
 
{
  "event": "deployment_completed",
  "data": {
    "status": "success",
    "version": "1.2.3"
  }
}

Data Flow Architecture

graph TB
    A[Frontend UI] --> B[Next.js API Routes]
    
    B --> C[Redis Storage]
    B --> D[Kubiya API]
    B --> E[ADK Orchestrator]
    
    C --> F[Task State]
    C --> G[User Sessions] 
    C --> H[MCP Integrations]
    
    D --> I[Agents API]
    D --> J[Runners API]
    D --> K[Secrets API]
    
    E --> L[Task Execution]
    E --> M[Workflow Streaming]
    
    N[External Systems] --> O[compose.kubiya.ai]
    O --> P[Webhook Processing]

Authentication Flow

  1. Login: Auth0 handles user authentication
  2. Session: ID token stored in Auth0 session cookie
  3. API Calls: ID token extracted and forwarded to Kubiya API
  4. Proxy: Most endpoints proxy requests to api.kubiya.ai

Error Handling

All endpoints use consistent error response format:

// Error Response Schema
{
  "error": "string",
  "code": "string", 
  "status": 400,
  "details": "string"
}

Common error codes:

  • AUTHENTICATION_ERROR: Missing or invalid authentication
  • TOKEN_EXPIRED: Auth token has expired
  • KUBIYA_API_ERROR: Error from underlying Kubiya API
  • REDIS_CONNECTION_ERROR: Redis storage unavailable

Implementation Notes

Proxy Architecture: This UI primarily serves as a frontend proxy to the Kubiya platform APIs. Task execution, agent management, and workflow processing happen on the Kubiya backend, not locally.

  • Task Storage: Redis stores UI task state, not actual execution state
  • Real Execution: Handled by ADK Orchestrator backend via /api/direct-stream
  • Agent Management: All agent operations proxy to api.kubiya.ai
  • Webhooks: Generated URLs point to external Kubiya infrastructure
  • MCP Integration: Configuration stored in Redis, execution handled by backend

This API reference covers the actual endpoints implemented in the codebase. For the full Kubiya platform API documentation, refer to the official Kubiya API docs.