Control Plane API

Overview

The Kubiya Control Plane API is a RESTful API that provides comprehensive control over your AI agent infrastructure. It enables you to programmatically manage agents, teams, workflows, integrations, and execution environments.

Base URL

https://control-plane.kubiya.ai/api

For local development:

http://localhost:8001

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

You can obtain an API key from the Kubiya Dashboard.

API Version

Current version: v0.3.0

Core Capabilities

The Control Plane API is organized into several functional areas:

Agent Management

Agents - Create, update, and execute individual AI agents
Teams - Coordinate multi-agent teams for complex tasks
Runtimes - Configure agent runtime environments and capabilities

Workflow & Execution

Workflows - Define and orchestrate multi-step task sequences
Task Planning - AI-powered task analysis and planning
Worker Queues - Manage worker orchestration and deployment
Runners - Control execution infrastructure

Configuration & Resources

Projects - Organize resources into logical projects
Environments - Manage execution environments and variables
Skills/Tool Sets - Define agent capabilities and tools
Models - Configure LLM models for agents

Security & Integration

Secrets - Secure credential storage and retrieval
Integrations - Connect to third-party services
Policies - OPA-based authorization and enforcement
Context Management - Manage knowledge and configuration inheritance

Monitoring & Health

Health Checks - Verify service readiness and health
Workers - Monitor Temporal worker registration and heartbeats

Getting Started

Example: List Available Models

curl -X GET "https://control-plane.kubiya.ai/api/v1/models?enabled_only=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example: Create an Agent

curl -X POST https://control-plane.kubiya.ai/api/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "DevOps Assistant",
    "description": "Helps with infrastructure and deployment tasks",
    "runtime": "claude_code",
    "model_id": "anthropic/claude-sonnet-4-5",
    "system_prompt": "You are a helpful DevOps assistant"
  }'

Example: Execute an Agent Task

curl -X POST https://control-plane.kubiya.ai/api/v1/agents/{agent_id}/execute \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Check the status of pods in the production namespace",
    "worker_queue_id": "your-worker-queue-id",
    "stream": true
  }'

Note: The worker_queue_id is required and must be a valid UUID of an existing worker queue.

Rate Limits

The API implements rate limiting to ensure fair usage:

Standard tier: 100 requests per minute
Enterprise tier: Custom limits available

Rate limit information is included in response headers:

X-RateLimit-Limit - Maximum requests per window
X-RateLimit-Remaining - Remaining requests in current window
X-RateLimit-Reset - Time when the rate limit resets

Error Handling

The API uses standard HTTP status codes and returns detailed error messages:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid agent configuration",
    "details": {
      "field": "runtime",
      "issue": "Unsupported runtime type"
    }
  }
}

Common status codes:

200 - Success
201 - Created
400 - Bad Request
401 - Unauthorized
403 - Forbidden
404 - Not Found
422 - Validation Error
429 - Rate Limit Exceeded
500 - Internal Server Error

Pagination

List endpoints support pagination using query parameters:

?limit=50&offset=0

Response includes pagination metadata:

{
  "items": [...],
  "total": 150,
  "limit": 50,
  "offset": 0
}

Webhooks

Configure webhooks to receive real-time notifications for:

Agent execution completion
Workflow state changes
Error events
Worker status updates

Support

Documentation: docs.kubiya.ai
Dashboard: compose.kubiya.ai
Issues: Contact support through the dashboard

Next Steps

Explore the API endpoints in the sections below to learn about specific operations and capabilities.

​Overview

​Base URL

​Authentication

​API Version

​Core Capabilities

​Agent Management

​Workflow & Execution

​Configuration & Resources

​Security & Integration

​Monitoring & Health

​Getting Started

​Example: List Available Models

​Example: Create an Agent

​Example: Execute an Agent Task

​Rate Limits

​Error Handling

​Pagination

​Webhooks

​Support

​Next Steps