> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kubiya.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Control Plane API

> Multi-tenant agent orchestration platform with comprehensive REST APIs

## 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:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

You can obtain an API key from the [Kubiya Dashboard](https://compose.kubiya.ai).

## 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

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

### Example: Create an Agent

```bash theme={null}
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

```bash theme={null}
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:

```json theme={null}
{
  "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:

```bash theme={null}
?limit=50&offset=0
```

Response includes pagination metadata:

```json theme={null}
{
  "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](https://docs.kubiya.ai)
* **Dashboard**: [compose.kubiya.ai](https://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.