​
Platform APIs Overview

The Kubiya Platform APIs are cloud-based REST APIs that allow you to programmatically manage your Kubiya resources including agents (teammates), sources (tool collections), knowledge entries, tasks, and runners.
These APIs are different from the Agent Server APIs which are exposed by orchestration servers for direct agent interactions.

​
Base URL

All Platform APIs use the following base URL: 
https://api.kubiya.ai

​
Authentication

All Platform API endpoints require authentication using a UserKey: 
Authorization: UserKey YOUR_API_KEY

curl -X GET "https://api.kubiya.ai/api/v1/agents" \
  -H "Authorization: UserKey $KUBIYA_API_KEY"

​
Available APIs

Tasks API

Execute and manage workflow tasks across your organizationKey endpoints:
  • GET /api/v1/tasks - List all tasks
  • POST /api/v1/tasks - Create a new task
  • PUT /api/v1/tasks/{taskId}/cancel - Cancel running tasks
  • GET /api/v1/tasks/{taskId}/logs - View task execution logs

Runners API

Deploy and manage Kubernetes operators that execute workflowsKey endpoints:
  • GET /api/v3/runners - List all runners
  • POST /api/v3/runners/{runner} - Restart a runner
  • GET /api/v3/runners/{runner}/health - Check runner health
  • POST /api/v3/runners/{runner}/helm - Manage Helm integrations

Agents API

Create and manage AI teammates with custom tools and knowledgeKey endpoints:
  • GET /api/v1/agents - List all agents
  • POST /api/v1/agents - Create a new agent
  • PUT /api/v1/agents/{agentId} - Update agent configuration
  • GET /api/v1/agents/{agentId}/integrations - Manage integrations

Sources API

Manage tool sources and repositories attached to agentsKey endpoints:
  • GET /api/v1/sources - List all sources
  • POST /api/v1/sources - Create a new source
  • PUT /api/v1/sources/{sourceId} - Sync source with repository
  • GET /api/v1/sources/load - Discover and load external sources

Knowledge API

Store and retrieve contextual information for enhanced agent performanceKey endpoints:
  • GET /api/v1/knowledge - List all knowledge entries
  • POST /api/v1/knowledge - Create knowledge entry
  • GET /api/v1/knowledge/search - Search knowledge base
  • GET /api/v1/knowledge/{id}/versions - View version history

​
Common Response Patterns

​
Success Responses

All successful API responses return appropriate HTTP status codes:
  • 200 - Successful GET, PUT, DELETE operations
  • 201 - Successful POST operations (resource created)

​
Error Responses

All APIs follow a consistent error response format: 
{
  "error": {
    "code": "string",
    "message": "string", 
    "details": {}
  }
}
Common HTTP error codes:
  • 400 - Bad Request (invalid parameters)
  • 401 - Unauthorized (invalid API key)
  • 403 - Forbidden (insufficient permissions)
  • 404 - Not Found (resource doesn’t exist)
  • 500 - Internal Server Error

​
Pagination

List endpoints that return large datasets use consistent pagination: 
{
  "results": [...],
  "total": 100,
  "page": 1,
  "limit": 50
}

​
Quick Start Example

Here’s a complete example of creating and executing a task: 
# 1. List available agents
curl -X GET "https://api.kubiya.ai/api/v1/agents" \
  -H "Authorization: UserKey $KUBIYA_API_KEY"

# 2. Create a task
TASK_ID=$(curl -X POST "https://api.kubiya.ai/api/v1/tasks" \
  -H "Authorization: UserKey $KUBIYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "List all running pods in the default namespace",
    "agent": "devops-agent",
    "runner": "prod-runner"
  }' | jq -r '.id')

# 3. Monitor task status
curl -X GET "https://api.kubiya.ai/api/v1/tasks/$TASK_ID" \
  -H "Authorization: UserKey $KUBIYA_API_KEY"

# 4. Get task logs
curl -X GET "https://api.kubiya.ai/api/v1/tasks/$TASK_ID/logs" \
  -H "Authorization: UserKey $KUBIYA_API_KEY"

​
Rate Limits

The Platform APIs have the following rate limits:
Operation TypeLimit
Read operations (GET)1000 requests/minute
Write operations (POST/PUT)200 requests/minute
Delete operations50 requests/minute
Task creation100 tasks/minute
Search operations300 requests/minute

​
API Versioning

The Platform APIs use path-based versioning:
  • /api/v1/ - Current stable version for most resources
  • /api/v2/ - Enhanced version for specific resources (agents)
  • /api/v3/ - Latest version for runners
When breaking changes are introduced, a new version path is created while maintaining backward compatibility for existing versions.

​
Best Practices

Error Handling

Always implement proper error handling:
try:
    response = requests.get(url, headers=headers)
    response.raise_for_status()
    data = response.json()
except requests.exceptions.HTTPError as e:
    print(f"HTTP error: {e.response.status_code}")
except requests.exceptions.RequestException as e:
    print(f"Request failed: {e}")

Rate Limiting

Implement exponential backoff for rate-limited requests:
import time
from random import uniform

def api_call_with_backoff(func, max_retries=3):
    for attempt in range(max_retries):
        try:
            return func()
        except RateLimitError:
            wait = (2 ** attempt) + uniform(0, 1)
            time.sleep(wait)
    raise Exception("Max retries exceeded")

Pagination

Handle paginated responses properly:
def get_all_resources(endpoint):
    all_items = []
    page = 1
    
    while True:
        response = requests.get(
            f"{endpoint}?page={page}&limit=100",
            headers=headers
        )
        data = response.json()
        all_items.extend(data.get('results', []))
        
        if not data.get('has_more', False):
            break
        page += 1
    
    return all_items

Security

Keep API keys secure:
  • Store in environment variables
  • Use secrets management systems
  • Rotate keys regularly
  • Monitor API usage logs
export KUBIYA_API_KEY="your_secret_key"
# Never commit keys to version control

​
Need Help?

Agent Server APIs

Direct orchestration server interactions

SDK Documentation

Official SDKs for Python, TypeScript, and Go

Examples

Real-world usage examples and tutorials

​
What’s Next?

  1. Set up authentication - Get your API key from the Kubiya dashboard
  2. Create your first agent - Use the Agents API to create a teammate
  3. Add knowledge - Enhance your agent with the Knowledge API
  4. Execute tasks - Run workflows using the Tasks API
  5. Monitor execution - Track performance with the Runners API