Tools API

Tools give your agents the ability to perform actions during conversations, like looking up customer data, checking weather, or triggering webhooks. Each tool can have one or more webhook actions that execute when the tool is invoked.

Base URL: https://kalem.me/api/v1/agents/{agent_id}/tools

The Tool Object

{
  "id": 1,
  "name": "get_weather",
  "description": "Get current weather for a location",
  "is_active": true,
  "parameters": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "City name"
      }
    },
    "required": ["location"]
  },
  "webhook_actions": [
    {
      "id": 10,
      "name": "Weather API Call",
      "url": "https://api.weather.com/v1/current",
      "method": "GET",
      "payload": null,
      "headers": null,
      "query_params": null,
      "wait_response": true
    }
  ],
  "created_at": "2025-01-15T10:30:00+00:00",
  "updated_at": "2025-01-15T10:30:00+00:00"
}

List Tools

GET /api/v1/agents/{agent_id}/tools

Query Parameters

Parameter	Type	Description
`status`	string	Filter: `active` or `inactive`
`search`	string	Search by tool name
`per_page`	integer	Results per page (default: 15, max: 100)

Example Request

curl -X GET "https://kalem.me/api/v1/agents/1/tools" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

const response = await fetch(
  'https://kalem.me/api/v1/agents/1/tools',
  { headers: { 'Authorization': 'Bearer YOUR_API_TOKEN' } }
);
const data = await response.json();

import requests

response = requests.get(
    'https://kalem.me/api/v1/agents/1/tools',
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'}
)
data = response.json()

$response = Http::withToken('YOUR_API_TOKEN')
    ->get('https://kalem.me/api/v1/agents/1/tools');
$data = $response->json();

Create Tool

POST /api/v1/agents/{agent_id}/tools

Request Body Parameters

Parameter	Type	Required	Description
`name`	string	Required	Tool name in snake_case (e.g., `get_weather`, `lookup_customer`)
`description`	string	Required	Description the AI uses to decide when to call this tool
`parameters`	object	Optional	JSON Schema defining the tool's input parameters
`is_active`	boolean	Optional	Whether the tool is enabled (default: true)
Webhook Actions (optional)
`webhook_actions`	array	Optional	Array of webhook action objects to execute when the tool is called
`webhook_actions.*.name`	string	Required	Name of the webhook action
`webhook_actions.*.url`	string	Required	Target URL (max 2048 characters)
`webhook_actions.*.method`	string	Optional	`GET`, `POST`, `PUT`, `PATCH`, `DELETE` (default: POST)
`webhook_actions.*.payload`	object	Optional	Request body for the webhook
`webhook_actions.*.headers`	object	Optional	Custom headers for the webhook
`webhook_actions.*.query_params`	object	Optional	Query parameters appended to the URL
`webhook_actions.*.wait_response`	boolean	Optional	Whether to wait for the response (default: true)

Example: Create Tool with Webhook

curl -X POST https://kalem.me/api/v1/agents/1/tools \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "get_weather",
    "description": "Get current weather for a location",
    "parameters": {
      "type": "object",
      "properties": {
        "location": {"type": "string", "description": "City name"}
      },
      "required": ["location"]
    },
    "webhook_actions": [
      {
        "name": "Weather API",
        "url": "https://api.weather.com/v1/current",
        "method": "GET",
        "query_params": {"key": "YOUR_WEATHER_KEY"},
        "wait_response": true
      }
    ]
  }'

const response = await fetch('https://kalem.me/api/v1/agents/1/tools', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'get_weather',
    description: 'Get current weather for a location',
    parameters: {
      type: 'object',
      properties: { location: { type: 'string', description: 'City name' } },
      required: ['location'],
    },
    webhook_actions: [{
      name: 'Weather API',
      url: 'https://api.weather.com/v1/current',
      method: 'GET',
      wait_response: true,
    }],
  }),
});
const data = await response.json();

import requests

response = requests.post(
    'https://kalem.me/api/v1/agents/1/tools',
    json={
        'name': 'get_weather',
        'description': 'Get current weather for a location',
        'parameters': {
            'type': 'object',
            'properties': {'location': {'type': 'string', 'description': 'City name'}},
            'required': ['location'],
        },
        'webhook_actions': [{
            'name': 'Weather API',
            'url': 'https://api.weather.com/v1/current',
            'method': 'GET',
            'wait_response': True,
        }],
    },
    headers={'Authorization': 'Bearer YOUR_API_TOKEN'}
)
data = response.json()

$response = Http::withToken('YOUR_API_TOKEN')
    ->post('https://kalem.me/api/v1/agents/1/tools', [
        'name' => 'get_weather',
        'description' => 'Get current weather for a location',
        'parameters' => [
            'type' => 'object',
            'properties' => ['location' => ['type' => 'string', 'description' => 'City name']],
            'required' => ['location'],
        ],
        'webhook_actions' => [[
            'name' => 'Weather API',
            'url' => 'https://api.weather.com/v1/current',
            'method' => 'GET',
            'wait_response' => true,
        ]],
    ]);
$data = $response->json();

Get Tool

GET /api/v1/agents/{agent_id}/tools/{id}

Retrieve a tool with its webhook actions.

curl -X GET https://kalem.me/api/v1/agents/1/tools/3 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Update Tool

PUT /api/v1/agents/{agent_id}/tools/{id}

Update a tool's properties. If webhook_actions is included, the existing webhook actions will be replaced entirely with the new set.

curl -X PUT https://kalem.me/api/v1/agents/1/tools/3 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description",
    "webhook_actions": [
      {
        "name": "New Action",
        "url": "https://api.example.com/v2/data",
        "method": "POST"
      }
    ]
  }'

Important: When updating webhook_actions, provide the complete list. All existing webhook actions will be detached and replaced with the new set.

Delete Tool

DELETE /api/v1/agents/{agent_id}/tools/{id}

curl -X DELETE https://kalem.me/api/v1/agents/1/tools/3 \
  -H "Authorization: Bearer YOUR_API_TOKEN"