Skip to main content

​
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

​
Next Steps

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