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
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.
POST /api/agents
Create new agent or revalidate cache.
Task Management (UI State)
GET /api/tasks?userId={userId}
Retrieve tasks from Redis storage (UI task state only).
POST /api/tasks
Save task to Redis storage or save entire task state.
DELETE /api/tasks?userId={userId}&taskId={taskId}
Delete specific task or all user tasks from Redis.
POST /api/tasks/cancel
Cancel a running task.
Real-Time Streaming
POST /api/direct-stream
Stream task execution through ADK Orchestrator backend.
The response is a Server-Sent Events (SSE) stream with Vercel AI SDK format:
GET /api/direct-stream?taskId={taskId}
Stream task updates from Redis storage.
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.
POST /api/runners/{runnerName}
Generate runner manifest (proxy to Kubiya API).
Authentication & User Info
GET /api/auth/token
Get authentication token from current session.
GET /api/user
Get current user information.
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.
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
Data Flow Architecture
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:
Common error codes:
AUTHENTICATION_ERROR
: Missing or invalid authenticationTOKEN_EXPIRED
: Auth token has expiredKUBIYA_API_ERROR
: Error from underlying Kubiya APIREDIS_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.