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

Login: Auth0 handles user authentication
Session: ID token stored in Auth0 session cookie
API Calls: ID token extracted and forwarded to Kubiya API
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.

API Reference

On this page