Tools API

The Tools API allows you to manage executable functions 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.

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 Tools

Retrieve all available tools in your organization.

GET /v1/tools

Headers

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

Query Parameters

Name	Type	Required	Description
`source_id`	string	No	Filter tools by source ID

Response

[
  {
    "id": "tool-id-123",
    "name": "create_ec2_instance",
    "description": "Create a new EC2 instance in AWS",
    "source_id": "source-id-456"
  },
  {
    "id": "tool-id-456",
    "name": "list_s3_buckets",
    "description": "List all S3 buckets in AWS account",
    "source_id": "source-id-456"
  }
]

Get Tool Details

Retrieve detailed information about a specific tool.

GET /v1/tools/{tool_id}

Path Parameters

Name	Type	Required	Description
`tool_id`	string	Yes	ID of the tool

Headers

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

Response

{
  "id": "tool-id-123",
  "name": "create_ec2_instance",
  "description": "Create a new EC2 instance in AWS",
  "source_id": "source-id-456",
  "parameters": {
    "instance_type": {
      "type": "string",
      "description": "EC2 instance type (e.g., t2.micro)",
      "required": true
    },
    "ami_id": {
      "type": "string",
      "description": "Amazon Machine Image ID",
      "required": true
    },
    "region": {
      "type": "string",
      "description": "AWS region",
      "required": false,
      "default": "us-east-1"
    }
  },
  "execution": {
    "type": "python",
    "source": "def create_ec2_instance(instance_type, ami_id, region='us-east-1'):\n    # Implementation..."
  }
}

Create Tool

Create a new tool for your teammates to use.

POST /v1/tools

Headers

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

Request Body

{
  "name": "create_ec2_instance",
  "description": "Create a new EC2 instance in AWS",
  "source_id": "source-id-456",
  "parameters": {
    "instance_type": {
      "type": "string",
      "description": "EC2 instance type (e.g., t2.micro)",
      "required": true
    },
    "ami_id": {
      "type": "string",
      "description": "Amazon Machine Image ID",
      "required": true
    },
    "region": {
      "type": "string",
      "description": "AWS region",
      "required": false,
      "default": "us-east-1"
    }
  },
  "execution": {
    "type": "python",
    "source": "def create_ec2_instance(instance_type, ami_id, region='us-east-1'):\n    # Implementation..."
  }
}

Response

{
  "id": "tool-id-123",
  "name": "create_ec2_instance",
  "description": "Create a new EC2 instance in AWS",
  "source_id": "source-id-456"
}

The response will contain the newly created tool's ID which you'll need to reference it in future API calls.

Update Tool

Update an existing tool.

PUT /v1/tools/{tool_id}

Path Parameters

Name	Type	Required	Description
`tool_id`	string	Yes	ID of the tool to update

Headers

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

Request Body

{
  "name": "create_ec2_instance",
  "description": "Updated description for creating EC2 instances",
  "parameters": {
    "instance_type": {
      "type": "string",
      "description": "EC2 instance type (e.g., t2.micro, t3.small)",
      "required": true
    },
    "ami_id": {
      "type": "string",
      "description": "Amazon Machine Image ID",
      "required": true
    },
    "region": {
      "type": "string",
      "description": "AWS region",
      "required": false,
      "default": "us-west-2"
    },
    "tags": {
      "type": "object",
      "description": "Tags to apply to the instance",
      "required": false
    }
  },
  "execution": {
    "type": "python",
    "source": "def create_ec2_instance(instance_type, ami_id, region='us-west-2', tags=None):\n    # Updated implementation..."
  }
}

Response

{
  "id": "tool-id-123",
  "name": "create_ec2_instance",
  "description": "Updated description for creating EC2 instances",
  "source_id": "source-id-456"
}

Delete Tool

Delete a tool.

DELETE /v1/tools/{tool_id}

Path Parameters

Name	Type	Required	Description
`tool_id`	string	Yes	ID of the tool 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 Source Tools

Retrieve all tools belonging to a specific source.

GET /v1/sources/{source_id}/tools

Path Parameters

Name	Type	Required	Description
`source_id`	string	Yes	ID of the source

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY

Response

[
  {
    "id": "tool-id-123",
    "name": "create_ec2_instance",
    "description": "Create a new EC2 instance in AWS",
    "source_id": "source-id-456"
  },
  {
    "id": "tool-id-789",
    "name": "list_s3_buckets",
    "description": "List all S3 buckets in AWS account",
    "source_id": "source-id-456"
  }
]

Example Usage

Create a Tool

curl -X POST "https://api.kubiya.ai/v1/tools" \
  -H "Authorization: UserKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "create_ec2_instance",
    "description": "Create a new EC2 instance in AWS",
    "source_id": "source-id-456",
    "parameters": {
      "instance_type": {
        "type": "string",
        "description": "EC2 instance type (e.g., t2.micro)",
        "required": true
      },
      "ami_id": {
        "type": "string",
        "description": "Amazon Machine Image ID",
        "required": true
      }
    },
    "execution": {
      "type": "python",
      "source": "def create_ec2_instance(instance_type, ami_id):\n    # Implementation..."
    }
  }'

Update a Tool

curl -X PUT "https://api.kubiya.ai/v1/tools/tool-id-123" \
  -H "Authorization: UserKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "create_ec2_instance",
    "description": "Updated description for creating EC2 instances",
    "parameters": {
      "instance_type": {
        "type": "string",
        "description": "EC2 instance type (e.g., t2.micro, t3.small)",
        "required": true
      },
      "ami_id": {
        "type": "string",
        "description": "Amazon Machine Image ID",
        "required": true
      },
      "region": {
        "type": "string",
        "description": "AWS region",
        "required": false,
        "default": "us-west-2"
      }
    },
    "execution": {
      "type": "python",
      "source": "def create_ec2_instance(instance_type, ami_id, region='\''us-west-2'\''):\n    # Updated implementation..."
    }
  }'

Delete a Tool

curl -X DELETE "https://api.kubiya.ai/v1/tools/tool-id-123" \
  -H "Authorization: UserKey YOUR_API_KEY"

Common Errors

HTTP Status	Description
400	Bad Request - The request was invalid, often due to 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 tool was not found
409	Conflict - A tool with the same name already exists in the source
500	Internal Server Error - An unexpected error occurred on the server

Next Steps

After creating tools, you can:

Assign them to AI Teammates to use in conversations
Monitor Tool Executions to track usage and performance
Set up Webhooks to handle events from tool executions

Tools API

On this page