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.

Base URL

https://api.kubiya.ai/api/v3/runners

All endpoints require authentication with a valid API key.

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

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  }
}

Runner Object

{
  "name": "runner-prod",
  "description": "Production runner for critical operations",
  "type": "local",
  "status": "active",
  "created_at": "2023-10-15T14:30:00Z",
  "updated_at": "2023-10-15T14:30:00Z",
  "version": "2.0.0",
  "health": {
    "status": "healthy",
    "last_check": "2023-10-15T14:30:00Z",
    "components": {
      "tool_manager": {
        "status": "healthy",
        "version": "2.0.0"
      },
      "agent_manager": {
        "status": "healthy",
        "version": "2.0.0"
      }
    }
  },
  "metadata": {
    "namespace": "kubiya",
    "gateway_url": "https://gateway.kubiya.ai",
    "subject": "kubiya-ai.runnervrunner-prod.incoming"
  }
}

List Runners

Retrieve all runners in your organization.

GET /api/v3/runners

Headers

Authorization

string

required

UserKey YOUR_API_KEY

Example Requests

curl -X GET "https://api.kubiya.ai/api/v3/runners" \
  -H "Authorization: UserKey $KUBIYA_API_KEY"

Response

[
  {
    "name": "runner-prod",
    "description": "Production runner for critical operations",
    "type": "local",
    "status": "active",
    "created_at": "2023-10-15T14:30:00Z",
    "updated_at": "2023-10-15T14:30:00Z",
    "version": "2.0.0",
    "health": {
      "status": "healthy",
      "last_check": "2023-10-15T14:30:00Z",
      "components": {
        "tool_manager": {
          "status": "healthy",
          "version": "2.0.0"
        },
        "agent_manager": {
          "status": "healthy",
          "version": "2.0.0"
        }
      }
    },
    "metadata": {
      "namespace": "kubiya",
      "gateway_url": "https://gateway.kubiya.ai",
      "subject": "kubiya-ai.runnervrunner-prod.incoming"
    }
  }
]

Get Runner Details

Retrieve detailed information about a specific runner.

GET /api/v3/runners/{runner}/describe

Path Parameters

runner

string

required

Name of the runner

Headers

Authorization

string

required

UserKey YOUR_API_KEY

Example Requests

curl -X GET "https://api.kubiya.ai/api/v3/runners/runner-prod/describe" \
  -H "Authorization: UserKey $KUBIYA_API_KEY"

Response

{
  "name": "runner-prod",
  "description": "Production runner for critical operations",
  "type": "local",
  "status": "active",
  "created_at": "2023-10-15T14:30:00Z",
  "updated_at": "2023-10-15T14:30:00Z",
  "version": "2.0.0",
  "health": {
    "status": "healthy",
    "last_check": "2023-10-15T14:30:00Z",
    "components": {
      "tool_manager": {
        "status": "healthy",
        "version": "2.0.0"
      },
      "agent_manager": {
        "status": "healthy",
        "version": "2.0.0"
      }
    }
  },
  "metadata": {
    "namespace": "kubiya",
    "gateway_url": "https://gateway.kubiya.ai",
    "subject": "kubiya-ai.runnervrunner-prod.incoming"
  }
}

Get Runner Health

Check the health status of a runner and its components.

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

Path Parameters

runner

string

required

Name of the runner

Headers

Authorization

string

required

UserKey YOUR_API_KEY

Example Requests

curl -X GET "https://api.kubiya.ai/api/v3/runners/runner-prod/health" \
  -H "Authorization: UserKey $KUBIYA_API_KEY"

Response

{
  "status": "healthy",
  "last_check": "2023-10-15T14:30:00Z",
  "components": {
    "tool_manager": {
      "status": "healthy",
      "version": "2.0.0",
      "metadata": {
        "git_sha": "abcdef123456",
        "release": "v2.0.0"
      }
    },
    "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/{runner}

Path Parameters

runner

string

required

Name for the new runner

Headers

Authorization

string

required

UserKey YOUR_API_KEY

Content-Type

string

required

application/json

Request Body

description

string

Description of the runner

type

string

default:"local"

Type of runner

metadata

object

Runner metadata including namespace and gateway configuration

Example Requests

curl -X POST "https://api.kubiya.ai/api/v3/runners/runner-prod" \
  -H "Authorization: UserKey $KUBIYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Production runner for critical operations",
    "type": "local",
    "metadata": {
      "namespace": "kubiya",
      "gateway_url": "https://gateway.kubiya.ai"
    }
  }'

Response

{
  "name": "runner-prod",
  "description": "Production runner for critical operations",
  "type": "local",
  "status": "creating",
  "created_at": "2023-10-15T14:30:00Z",
  "updated_at": "2023-10-15T14:30:00Z",
  "version": "2.0.0",
  "metadata": {
    "namespace": "kubiya",
    "gateway_url": "https://gateway.kubiya.ai",
    "subject": "kubiya-ai.runnervrunner-prod.incoming"
  }
}

Update Runner Description

Update the description of an existing runner.

PUT /api/v3/runners/description/{runner}

Path Parameters

runner

string

required

Name of the runner to update

Headers

Authorization

string

required

UserKey YOUR_API_KEY

Content-Type

string

required

application/json

Request Body

description

string

required

New description for the runner

Example Requests

curl -X PUT "https://api.kubiya.ai/api/v3/runners/description/runner-prod" \
  -H "Authorization: UserKey $KUBIYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated production runner with enhanced monitoring"
  }'

Response

{
  "name": "runner-prod",
  "description": "Updated production runner with enhanced monitoring",
  "type": "local",
  "status": "active",
  "created_at": "2023-10-15T14:30:00Z",
  "updated_at": "2023-10-15T15:00:00Z",
  "version": "2.0.0",
  "metadata": {
    "namespace": "kubiya",
    "gateway_url": "https://gateway.kubiya.ai",
    "subject": "kubiya-ai.runnervrunner-prod.incoming"
  }
}

Delete Runner

Delete a runner instance.

DELETE /api/v3/runners/{runner}

Path Parameters

runner

string

required

Name of the runner to delete

Headers

Authorization

string

required

UserKey YOUR_API_KEY

Example Requests

curl -X DELETE "https://api.kubiya.ai/api/v3/runners/runner-prod" \
  -H "Authorization: UserKey $KUBIYA_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.

GET /api/v3/runners/helmchart/{runner}

Path Parameters

runner

string

required

Name of the runner

Headers

Authorization

string

required

UserKey YOUR_API_KEY

Example Request

curl -X GET "https://api.kubiya.ai/api/v3/runners/helmchart/runner-prod" \
  -H "Authorization: UserKey $KUBIYA_API_KEY" \
  -o runner-prod-chart.tgz

Response

The response is a Helm chart archive file.

Get Runner Helm YAML

Retrieve the Helm YAML manifest for a runner.

GET /api/v3/runners/helm/{runner}

Path Parameters

runner

string

required

Name of the runner

Headers

Authorization

string

required

UserKey YOUR_API_KEY

Example Requests

curl -X GET "https://api.kubiya.ai/api/v3/runners/helm/runner-prod" \
  -H "Authorization: UserKey $KUBIYA_API_KEY"

Response

The response is a YAML file containing the Helm manifest.

Perform Runner Operations

Execute operations on a runner.

POST /api/v3/runners/{runner}/ops

Path Parameters

runner

string

required

Name of the runner

Headers

Authorization

string

required

UserKey YOUR_API_KEY

Content-Type

string

required

application/json

Request Body

operation

string

required

Operation to perform (e.g., “restart”, “stop”, “start”)

parameters

object

Operation-specific parameters

Example Requests

curl -X POST "https://api.kubiya.ai/api/v3/runners/runner-prod/ops" \
  -H "Authorization: UserKey $KUBIYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "restart",
    "parameters": {
      "component": "tool_manager"
    }
  }'

Response

{
  "operation": "restart",
  "status": "success",
  "message": "Runner component restarted successfully",
  "timestamp": "2023-10-15T15:30:00Z"
}

Common Errors

{
  "error": {
    "code": "not_found",
    "message": "Runner not found",
    "details": {
      "runner": "runner-invalid"
    }
  }
}

Error Status Codes

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

Tasks API

Execute tasks on your runners

Agents API

Configure agents to use runners

Sources API

Load tool sources onto runners

Webhooks API

Monitor runner events and health

Kubiya Platform APIs

MCP Server APIs

​Runners API

​Base URL

​Endpoints

​Common Response Status Codes

​Error Response Format

​Runner Object

​List Runners

​Headers

​Example Requests

​Response

​Get Runner Details

​Path Parameters

​Headers

​Example Requests

​Response

​Get Runner Health

​Path Parameters

​Headers

​Example Requests

​Response

​Create Runner

​Path Parameters

​Headers

​Request Body

​Example Requests

​Response

​Update Runner Description

​Path Parameters

​Headers

​Request Body

​Example Requests

​Response

​Delete Runner

​Path Parameters

​Headers

​Example Requests

​Response

​Get Runner Helm Chart

​Path Parameters

​Headers

​Example Request

​Response

​Get Runner Helm YAML

​Path Parameters

​Headers

​Example Requests

​Response

​Perform Runner Operations

​Path Parameters

​Headers

​Request Body

​Example Requests

​Response

​Common Errors

​Error Status Codes

​Next Steps

Tasks API

Agents API

Sources API

Webhooks API

Runners API

Base URL

Endpoints

Common Response Status Codes

Error Response Format

Runner Object

List Runners

Headers

Example Requests

Response

Get Runner Details

Path Parameters

Headers

Example Requests

Response

Get Runner Health

Path Parameters

Headers

Example Requests

Response

Create Runner

Path Parameters

Headers

Request Body

Example Requests

Response

Update Runner Description

Path Parameters

Headers

Request Body

Example Requests

Response

Delete Runner

Path Parameters

Headers

Example Requests

Response

Get Runner Helm Chart

Path Parameters

Headers

Example Request

Response

Get Runner Helm YAML

Path Parameters

Headers

Example Requests

Response

Perform Runner Operations

Path Parameters

Headers

Request Body

Example Requests

Response

Common Errors

Error Status Codes

Next Steps