Kubiya REST API

Welcome to the Kubiya REST API documentation. This API allows you to programmatically interact with the Kubiya Agentic Platform, enabling you to automate workflows, integrate with your existing tools, and build custom experiences on top of the platform.

Authentication

All API requests require authentication using API keys. You can generate an API key from the Kubiya Web App under Settings → API Keys or using the CLI:

# Login and view your API key
kubiya auth login
kubiya config view

Include your API key in the Authorization header:

Authorization: UserKey YOUR_API_KEY

Note that Kubiya uses the UserKey prefix for API keys, rather than the more common Bearer token prefix.

Base URL

https://api.kubiya.ai/v1

For specialized endpoints, different API versions may be used (like /api/v3 for runners).

Core Endpoints

Infrastructure as Code (IaC) Capabilities

Kubiya provides robust Infrastructure as Code (IaC) capabilities through the Projects and Tasks APIs:

These endpoints enable:

• GitOps Workflows: Automate your infrastructure deployments from Git repositories
• State Management: Manage your Terraform state securely in the Kubiya platform
• Agentic Operations: Combine AI agents with your infrastructure for intelligent management

Response Format

API responses are returned in JSON format. Successful responses typically include a status code of 200 (OK) or 201 (Created).

Error responses include appropriate HTTP status codes (4xx for client errors, 5xx for server errors) and a JSON body with error details:

{
  "error": "Error title",
  "details": "More detailed error message",
  "errorCode": "ERROR_CODE"
}

Rate Limiting

API requests are subject to rate limiting. The current limits are:

• 100 requests per minute per API key
• 5,000 requests per day per API key

If you exceed the rate limit, you'll receive a 429 Too Many Requests response.

Pagination

List endpoints support pagination through limit and offset query parameters:

GET /agents?limit=10&offset=20

The response includes pagination metadata:

{
  "data": [...],
  "pagination": {
    "total": 45,
    "limit": 10,
    "offset": 20
  }
}

SDK Libraries

We provide official SDK libraries for several programming languages:

• JavaScript/TypeScript
• Python
• Go

Example JavaScript SDK usage:

const { KubiyaClient } = require('@kubiya/sdk');
 
// Initialize with your API key
const kubiya = new KubiyaClient({ 
  apiKey: 'YOUR_API_KEY',
  baseUrl: 'https://api.kubiya.ai/v1' // Optional
});
 
// Get all teammates
kubiya.getTeammates()
  .then(teammates => console.log(teammates))
  .catch(error => console.error(error));

API Playground

Try the Kubiya API directly in your browser with our interactive API playground. Test endpoints, see request and response examples, and understand how to integrate with the Kubiya platform.

API Versioning

The Kubiya API is versioned to ensure backward compatibility. The primary version is v1, included in the URL path:

https://api.kubiya.ai/v1/...

Some specialized services use different version paths (e.g., /api/v3/runners). When new features or breaking changes are introduced, a new version will be created with reasonable deprecation periods for older versions.