​

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.

​

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

​

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:

​

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

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}")

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")

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

export KUBIYA_API_KEY="your_secret_key"
# Never commit keys to version control

​

Need Help?

​

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