Complete reference documentation for the Kubiya Platform REST API, allowing you to integrate and extend the platform programmatically.

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:

# Set environment variable with your API key
export KUBIYA_API_KEY=YOUR_API_KEY

Include your API key in the Authorization header:

Authorization: UserKey YOUR_API_KEY

Keep your API keys secure and never share them publicly. Rotate your keys regularly and use different keys for different environments.

Base URL

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

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

Core Endpoints

Resource	Description
Agents	Create, update, and manage AI Teammates
Sources	Discover and manage tool sources
Agentic Tools	Create and manage tools that extend capabilities
Runners	Deploy and manage execution environments
Knowledge	Add, retrieve, and manage knowledge entries
Webhooks	Configure and manage webhooks for event handling

Infrastructure as Code (IaC) Capabilities

Kubiya provides Infrastructure as Code (IaC) capabilities through the Tasks API:

Resource	Description
Tasks	Execute operations and workflows

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

Common Errors

HTTP Status	Description
400	Bad Request - Invalid request body or missing required fields
401	Unauthorized - API key is missing or invalid
403	Forbidden - The API key doesn't have permission to perform this action
404	Not Found - The requested resource was not found
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - An unexpected error occurred on the server

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 /api/v1/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:

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/api/v1' // Optional
});
 
// Get all agents
kubiya.getAgents()
  .then(agents => console.log(agents))
  .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.

No endpoints found for the specified API type:

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/api/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.

Kubiya REST API Reference