Runners API
API endpoints for managing Kubiya runners that execute tools
Runners API
Runners in Kubiya are the execution environments that run tools and provide capabilities to teammates. The Runners API allows you to create, manage, and monitor runner instances in your environment.
Endpoints
Method | Path | Description |
---|---|---|
GET | /api/v3/runners | List all runners |
GET | /api/v3/runners/{runner}/describe | Get runner details |
GET | /api/v3/runners/{runner}/health | Get runner health |
DELETE | /api/v3/runners/{runner} | Delete a runner |
PUT | /api/v3/runners/description/{runner} | Update runner description |
POST | /api/v3/runners/{runner} | Create a new runner with a specific name |
GET | /api/v3/runners/helmchart/{runner} | Get Helm chart for a runner |
GET | /api/v3/runners/helm/{runner} | Get Helm YAML for a runner |
POST | /api/v3/runners/{runner}/ops | Perform operations on a runner |
Common Response Status Codes
Status Code | Description |
---|---|
200 | Success |
400 | Bad Request - Invalid parameters or request body |
401 | Unauthorized - Invalid or missing API key |
403 | Forbidden - Insufficient permissions |
404 | Not Found - Resource doesn't exist |
500 | Internal Server Error |
Error Response Format
List Runners
Retrieve all runners in your organization.
Headers
Name | Required | Description |
---|---|---|
Authorization | Yes | UserKey YOUR_API_KEY |
Response
Get Runner Details
Retrieve detailed information about a specific runner.
Path Parameters
Name | Type | Required | Description |
---|---|---|---|
runner | string | Yes | Name of the runner |
Headers
Name | Required | Description |
---|---|---|
Authorization | Yes | UserKey YOUR_API_KEY |
Response
Get Runner Health
Check the health status of a runner and its components.
Path Parameters
Name | Type | Required | Description |
---|---|---|---|
runner | string | Yes | Name of the runner |
Headers
Name | Required | Description |
---|---|---|
Authorization | Yes | UserKey YOUR_API_KEY |
Response
Create Runner
Create a new runner instance.
Path Parameters
Name | Type | Required | Description |
---|---|---|---|
runner | string | Yes | Name for the new runner |
Headers
Name | Required | Description |
---|---|---|
Authorization | Yes | UserKey YOUR_API_KEY |
Content-Type | Yes | application/json |
Request Body
Response
Update Runner Description
Update the description of an existing runner.
Path Parameters
Name | Type | Required | Description |
---|---|---|---|
runner | string | Yes | Name of the runner to update |
Headers
Name | Required | Description |
---|---|---|
Authorization | Yes | UserKey YOUR_API_KEY |
Content-Type | Yes | application/json |
Request Body
Response
Delete Runner
Delete a runner instance.
Path Parameters
Name | Type | Required | Description |
---|---|---|---|
runner | string | Yes | Name of the runner to delete |
Headers
Name | Required | Description |
---|---|---|
Authorization | Yes | UserKey YOUR_API_KEY |
Response
A successful delete operation returns an HTTP 200 status with no response body.
Get Runner Helm Chart
Retrieve the Helm chart for deploying a runner.
Path Parameters
Name | Type | Required | Description |
---|---|---|---|
runner | string | Yes | Name of the runner |
Headers
Name | Required | Description |
---|---|---|
Authorization | Yes | UserKey YOUR_API_KEY |
Response
The response is a Helm chart archive file.
Get Runner Helm YAML
Retrieve the Helm YAML manifest for a runner.
Path Parameters
Name | Type | Required | Description |
---|---|---|---|
runner | string | Yes | Name of the runner |
Headers
Name | Required | Description |
---|---|---|
Authorization | Yes | UserKey YOUR_API_KEY |
Response
The response is a YAML file containing the Helm manifest.
Perform Runner Operations
Execute operations on a runner.
Path Parameters
Name | Type | Required | Description |
---|---|---|---|
runner | string | Yes | Name of the runner |
Headers
Name | Required | Description |
---|---|---|
Authorization | Yes | UserKey YOUR_API_KEY |
Content-Type | Yes | application/json |
Request Body
Response
Runners are essential components of the Kubiya platform. Make sure to monitor their health and ensure they have the necessary permissions to execute tools.
Example Usage
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 specified runner was not found |
500 | Internal Server Error - An unexpected error occurred on the server |
Next Steps
After setting up runners, you can:
- Use them to load sources with specific tools
- Configure teammates to use tools that the runners execute
- Manage runners using Terraform