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.

List Runners

Retrieve all runners in your organization.

GET /api/v3/runners

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY
`Content-Type`	No	application/json

Response

[
  {
    "name": "runner-prod",
    "version": "v2",
    "namespace": "kubiya-system",
    "kubernetes_namespace": "kubiya-system",
    "runner_health": {
      "status": "healthy",
      "health": "ok",
      "version": "2.0.0"
    },
    "tool_manager_health": {
      "status": "healthy",
      "health": "ok",
      "version": "2.0.0"
    },
    "agent_manager_health": {
      "status": "healthy",
      "health": "ok",
      "version": "2.0.0"
    }
  },
  {
    "name": "runner-dev",
    "version": "v2",
    "namespace": "kubiya-dev"
  }
]

The runner list includes health information for each component of the runner, which is fetched concurrently to provide a complete status overview.

Get Runner Details

Retrieve detailed information about a specific runner.

GET /v1/runners/{runner_name}/describe

Path Parameters

Name	Type	Required	Description
`runner_name`	string	Yes	Name of the runner

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY

Response

{
  "name": "runner-prod",
  "version": "v2",
  "namespace": "kubiya-system",
  "kubernetes_namespace": "kubiya-system"
}

Get Runner Health

Check the health status of a runner and its components.

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

Path Parameters

Name	Type	Required	Description
`runner_name`	string	Yes	Name of the runner

Headers

Name	Required	Description
`Authorization`	Yes	UserKey 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 Manifest

Create a new runner manifest that can be used to deploy a runner instance.

POST /api/v3/runners/{runner_name}

Path Parameters

Name	Type	Required	Description
`runner_name`	string	Yes	Name for the new runner

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY
`Content-Type`	Yes	application/json

Response

{
  "name": "runner-prod",
  "manifest_url": "https://api.kubiya.ai/manifests/runner-prod-123456.yaml"
}

The manifest URL provides a Kubernetes YAML file that can be applied to your cluster to deploy the runner.

Get Runner Manifest

Retrieve the deployment manifest for an existing runner.

GET /v1/runners/{runner_name}/manifest

Path Parameters

Name	Type	Required	Description
`runner_name`	string	Yes	Name of the runner

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY

Response

{
  "name": "runner-prod",
  "manifest_url": "https://api.kubiya.ai/manifests/runner-prod-123456.yaml",
  "manifest_content": "apiVersion: v1\nkind: Namespace\nmetadata:\n  name: kubiya-system\n---\napiVersion: apps/v1\nkind: Deployment\n..."
}

Download Manifest

Download a runner manifest file for deployment.

GET {manifest_url}

Response

The response is a raw YAML file containing the Kubernetes manifests for deploying the runner.

apiVersion: v1
kind: Namespace
metadata:
  name: kubiya-system
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: kubiya-runner
  namespace: kubiya-system
spec:
  replicas: 1
  selector:
    matchLabels:
      app: kubiya-runner
...

Example Usage

List Runners

# Get all runners
curl -X GET "https://api.kubiya.ai/api/v3/runners" \
  -H "Authorization: UserKey YOUR_API_KEY" \
  -H "Content-Type: application/json"

Create Runner Manifest

# Create a new runner manifest
curl -X POST "https://api.kubiya.ai/api/v3/runners/new-runner" \
  -H "Authorization: UserKey YOUR_API_KEY" \
  -H "Content-Type: application/json"

Check Runner Health

# Check health of a specific runner
curl -X GET "https://api.kubiya.ai/api/v3/runners/runner-prod/health" \
  -H "Authorization: UserKey YOUR_API_KEY" \
  -H "Content-Type: application/json"

Get Runner Manifest

# Get manifest for a runner
curl -X GET "https://api.kubiya.ai/v1/runners/runner-prod/manifest" \
  -H "Authorization: UserKey YOUR_API_KEY"

Deployment Process

The typical process for deploying a new runner involves:

Create a runner manifest using the API
Download the manifest file
Apply the manifest to your Kubernetes cluster:
kubectl apply -f runner-manifest.yaml
Verify the runner is healthy using the health endpoint
Use the runner name when executing tools or loading sources

Runners require appropriate permissions in your Kubernetes cluster to function properly. Make sure to review the manifest before applying it and ensure it has the necessary RBAC roles.

Common Errors

HTTP Status	Description
400	Bad Request - The request was invalid or malformed
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

Runners API

On this page