Kubiya LogoKubiya Developer Docs

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.

This playground makes API calls to Kubiya API through a secure server-side proxy. Your requests never expose your API token directly to the browser.

Endpoints

MethodPathDescription
GET/api/v3/runnersList all runners
GET/api/v3/runners/{runner}/describeGet runner details
GET/api/v3/runners/{runner}/healthGet 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}/opsPerform operations on a runner

List Runners

Retrieve all runners in your organization.

GET /api/v3/runners

Headers

NameRequiredDescription
AuthorizationYesUserKey YOUR_API_KEY

Response

[
  {
    "name": "runner-prod",
    "wss_url": "",
    "task_id": "",
    "managed_by": "",
    "description": "",
    "authentication_type": "",
    "version": 0,
    "runner_type": "kubiya_operator_v2",
    "gateway_url": null,
    "gateway_password": null,
    "namespace": "kubiya",
    "subject": "kubiya-ai.runnervunner-prod.incoming",
    "user_key_id": "*****",
    "runner_health": {
      "status": "",
      "health": "",
      "error": "",
      "version": ""
    },
    "tool_manager_health": {
      "status": "",
      "health": "",
      "error": "",
      "version": ""
    },
    "agent_manager_health": {
      "status": "",
      "health": "",
      "error": "",
      "version": ""
    },
    "kubernetes_namespace": ""
  }
]

Get Runner Health

Check the health status of a runner and its components.

GET /api/v3/runners/{runnerName}/health

Path Parameters

NameTypeRequiredDescription
runnerNamestringYesName of the runner

Headers

NameRequiredDescription
AuthorizationYesUserKey YOUR_API_KEY

Response

{
  "health": "ok",
  "status": "healthy",
  "time": "2023-10-15T14:30:00Z",
  "version": "2.0.0",
  "checks": [
    {
      "name": "tool-manager",
      "status": "healthy",
      "version": "2.0.0",
      "metadata": {
        "git_sha": "abcdef123456",
        "release": "v2.0.0"
      }
    },
    {
      "name": "agent-manager",
      "status": "healthy",
      "version": "2.0.0",
      "metadata": {
        "git_sha": "abcdef123456",
        "release": "v2.0.0"
      }
    }
  ]
}

Create Runner

Create a new runner instance.

POST /api/v3/runners

Headers

NameRequiredDescription
AuthorizationYesUserKey YOUR_API_KEY
Content-TypeYesapplication/json

Request Body

{
  "name": "runner-prod",
  "description": "Production runner for critical operations",
  "type": "local"
}

Response

{
  "id": "runner-12345",
  "name": "runner-prod",
  "description": "Production runner for critical operations",
  "type": "local",
  "status": "creating",
  "created_at": "2023-10-15T14:30:00Z"
}

Example Usage

# List all runners
curl -X GET "https://api.kubiya.ai/api/v3/runners" \
  -H "Authorization: UserKey YOUR_API_KEY"
 
# Get runner health
curl -X GET "https://api.kubiya.ai/api/v3/runners/runner-prod/health" \
  -H "Authorization: UserKey YOUR_API_KEY"
 
# Create a new runner
curl -X POST "https://api.kubiya.ai/api/v3/runners" \
  -H "Authorization: UserKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "runner-prod",
    "description": "Production runner for critical operations",
    "type": "local"
  }'

Runners are essential components of the Kubiya platform. Make sure to monitor their health and ensure they have the necessary permissions to execute tools.

Common Errors

HTTP StatusDescription
400Bad Request - Invalid request body or missing required fields
401Unauthorized - API key is missing or invalid
403Forbidden - The API key doesn't have permission to perform this action
404Not Found - The specified runner was not found
500Internal Server Error - An unexpected error occurred on the server

Next Steps

After setting up runners, you can:

Endpoint Descriptions

  • GET /api/v3/runners: Retrieve a list of all runners in your organization.
  • GET /api/v3/runners/{runner}/describe: Get detailed information about a specific runner.
  • GET /api/v3/runners/{runner}/health: Check the health status of a runner and its components.
  • DELETE /api/v3/runners/{runner}: Delete a specific runner from your organization.
  • PUT /api/v3/runners/description/{runner}: Update the description of a runner.
  • POST /api/v3/runners/{runner}: Create a new runner with a specific name and configuration.
  • GET /api/v3/runners/helmchart/{runner}: Retrieve the Helm chart for deploying a runner.
  • GET /api/v3/runners/helm/{runner}: Retrieve the Helm YAML manifest for a runner.
  • POST /api/v3/runners/{runner}/ops: Perform operations (such as restart) on a runner.

On this page