Introduction
Agents
Knowledge Base
Organizations
Analytics
Preview & Voice Selection
Integrations
{
"config": {
"tool_name": "GetOrderStatus",
"tool_description": "Retrieves the status of a customer order using their order ID",
"webhook_url": "https://api.shop.com/orders/status",
"http_method": "POST",
"headers": {
"Authorization": "Bearer token123"
},
"parameters": [
{
"parameter_name": "order_id",
"parameter_type": "string",
"parameter_description": "The unique order identifier",
"parameter_required": true
}
],
"timeout_seconds": 30
}
}
{
"success": true,
"message": "Tool created successfully",
"data": {
"tool_id": "tool_a1b2c3d4e5f6",
"tool_name": "GetOrderStatus",
"tool_description": "Retrieves the status of a customer order using their order ID",
"webhook_url": "https://api.shop.com/orders/status",
"http_method": "POST",
"headers": {
"Authorization": "Bearer token123"
},
"parameters": [
{
"parameter_name": "order_id",
"parameter_type": "string",
"parameter_description": "The unique order identifier",
"parameter_required": true
}
],
"timeout_seconds": 30,
"client_id": "org_abc123",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
}
Tools
Create Tool
POST
/
api
/
tools
{
"config": {
"tool_name": "GetOrderStatus",
"tool_description": "Retrieves the status of a customer order using their order ID",
"webhook_url": "https://api.shop.com/orders/status",
"http_method": "POST",
"headers": {
"Authorization": "Bearer token123"
},
"parameters": [
{
"parameter_name": "order_id",
"parameter_type": "string",
"parameter_description": "The unique order identifier",
"parameter_required": true
}
],
"timeout_seconds": 30
}
}
{
"success": true,
"message": "Tool created successfully",
"data": {
"tool_id": "tool_a1b2c3d4e5f6",
"tool_name": "GetOrderStatus",
"tool_description": "Retrieves the status of a customer order using their order ID",
"webhook_url": "https://api.shop.com/orders/status",
"http_method": "POST",
"headers": {
"Authorization": "Bearer token123"
},
"parameters": [
{
"parameter_name": "order_id",
"parameter_type": "string",
"parameter_description": "The unique order identifier",
"parameter_required": true
}
],
"timeout_seconds": 30,
"client_id": "org_abc123",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
}
Create a new custom tool that agents can use during calls.
Headers
Your API key for authentication.
The organization ID.
Must be
application/json.Permissions
tools:create(admin, agent_manager)
Request Body
Tool configuration object.
Show config properties
Show config properties
Name of the tool. Must be unique within your organization. Pattern:
^[a-zA-Z0-9_]+$ (1-50 characters).Natural language description of what the tool does. The LLM uses this to decide when to call the tool (1-500 characters).
The API endpoint URL that Butter AI will call (1-500 characters).
HTTP method:
GET, POST, PUT, PATCH, or DELETE.Key-value pairs of HTTP headers to include in the request (e.g.,
{"Authorization": "Bearer ..."}).List of parameters the tool accepts.
Show ToolParameter properties
Show ToolParameter properties
The name of the parameter. Pattern:
^[a-zA-Z0-9_]+$ (1-50 characters).The data type:
string, integer, number, boolean, null, object, or array.Description used by the LLM to extract this value from the conversation (1-200 characters).
Whether this parameter is mandatory for the tool call.
Maximum time to wait for your API to respond (1-60 seconds).
Response
Indicates if the request was successful.
Human-readable success message.
The created tool object.
{
"config": {
"tool_name": "GetOrderStatus",
"tool_description": "Retrieves the status of a customer order using their order ID",
"webhook_url": "https://api.shop.com/orders/status",
"http_method": "POST",
"headers": {
"Authorization": "Bearer token123"
},
"parameters": [
{
"parameter_name": "order_id",
"parameter_type": "string",
"parameter_description": "The unique order identifier",
"parameter_required": true
}
],
"timeout_seconds": 30
}
}
{
"success": true,
"message": "Tool created successfully",
"data": {
"tool_id": "tool_a1b2c3d4e5f6",
"tool_name": "GetOrderStatus",
"tool_description": "Retrieves the status of a customer order using their order ID",
"webhook_url": "https://api.shop.com/orders/status",
"http_method": "POST",
"headers": {
"Authorization": "Bearer token123"
},
"parameters": [
{
"parameter_name": "order_id",
"parameter_type": "string",
"parameter_description": "The unique order identifier",
"parameter_required": true
}
],
"timeout_seconds": 30,
"client_id": "org_abc123",
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
}
⌘I