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

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

Query Parameters

Name	Type	Required	Description
`runner`	string	Yes	The 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 Status	Description
400	Bad Request - Missing runner parameter or invalid request body
401	Unauthorized - API key is missing or invalid
403	Forbidden - The API key doesn't have permission to execute tools
500	Internal 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

Tools API

On this page