Kubiya LogoKubiya Developer Docs

Tools API

API endpoints for executing agentic tools in the Kubiya platform

Tools API

The Tools API allows you to execute tools that can be used by AI Teammates (agents) in the Kubiya platform. Tools enable your AI agents to perform specific actions or retrieve information from external systems.

No endpoints found for the specified API type: Tools

Execute Tool

Execute a tool on a specific runner.

POST /api/v1/tools/exec

Headers

NameRequiredDescription
AuthorizationYesUserKey YOUR_API_KEY
Content-TypeYesapplication/json

Query Parameters

NameTypeRequiredDescription
runnerstringYesThe runner to execute the tool on

Request Body

{
  "tool_name": "create_ec2_instance",
  "parameters": {
    "instance_type": "t2.micro",
    "ami_id": "ami-123456",
    "region": "us-east-1"
  }
}

Response

The response is streamed as Server-Sent Events (SSE) with the following format:

data: {"status": "running", "message": "Starting tool execution..."}

data: {"status": "running", "message": "Creating EC2 instance..."}

data: {"status": "completed", "result": {"instance_id": "i-1234567890abcdef0"}}

Example Usage

# Execute a tool on a specific runner
curl -X POST "https://api.kubiya.ai/api/v1/tools/exec?runner=runner-prod" \
  -H "Authorization: UserKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "create_ec2_instance",
    "parameters": {
      "instance_type": "t2.micro",
      "ami_id": "ami-123456",
      "region": "us-east-1"
    }
  }'

Common Errors

HTTP StatusDescription
400Bad Request - Missing runner parameter or invalid request body
401Unauthorized - API key is missing or invalid
403Forbidden - The API key doesn't have permission to execute tools
500Internal Server Error - An unexpected error occurred on the server

Tool execution is streamed back to the client in real-time, allowing you to monitor the progress of long-running operations.

Next Steps

After executing tools, you can:

  • Monitor tool execution status and results
  • Configure Runners for tool execution
  • Set up Webhooks to handle tool execution events

On this page