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

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

List Runners

Retrieve all runners in your organization.

GET /api/v3/runners

Headers

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

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

Headers

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

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

Headers

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

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

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

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

{
  "description": "Updated description for the runner"
}

Response

{
  "name": "runner-prod",
  "description": "Updated description for the runner",
  "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

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.

GET /api/v3/runners/helmchart/{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.

GET /api/v3/runners/helm/{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.

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

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

{
  "operation": "restart",
  "parameters": {
    "component": "tool_manager"
  }
}

Response

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

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

# List all runners
curl -X GET "https://api.kubiya.ai/api/v3/runners" \
  -H "Authorization: UserKey YOUR_API_KEY"
 
# Get runner details
curl -X GET "https://api.kubiya.ai/api/v3/runners/runner-prod/describe" \
  -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/runner-prod" \
  -H "Authorization: UserKey YOUR_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"
    }
  }'
 
# Update runner description
curl -X PUT "https://api.kubiya.ai/api/v3/runners/description/runner-prod" \
  -H "Authorization: UserKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description for the runner"
  }'
 
# Delete a runner
curl -X DELETE "https://api.kubiya.ai/api/v3/runners/runner-prod" \
  -H "Authorization: UserKey YOUR_API_KEY"
 
# Perform runner operation
curl -X POST "https://api.kubiya.ai/api/v3/runners/runner-prod/ops" \
  -H "Authorization: UserKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "restart",
    "parameters": {
      "component": "tool_manager"
    }
  }'

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

Runners API

On this page