API Tools

API Tools let your AI agent call external APIs during conversations. This enables real-time data lookups like order tracking, appointment availability, service status, and more.

How it works

1. You configure an API endpoint with parameters
2. When a customer asks a relevant question (e.g., "where is my order?"), the agent recognizes it needs data
3. The agent asks the customer for required information (e.g., order number)
4. The agent calls the API with the collected parameters
5. The agent formats the response and replies to the customer

Setting up a tool

Go to your agent's API Tools tab and click Add Tool.

Basic info

Field	Description
Tool Name	A unique identifier (e.g., lookupOrder). The agent uses this internally.
Description	Tells the agent when to use this tool. Be specific — e.g., "Look up order status by order number."

API configuration

Field	Description
Method	HTTP method — GET, POST, PUT, PATCH, DELETE
Endpoint URL	The API URL. Use {{param}} for dynamic values — e.g., https://api.example.com/orders/{{order_id}}

Authentication

Type	Description
No Auth	Public API, no credentials needed
Bearer Token	Sends Authorization: Bearer <token> header
API Key (Header)	Sends the key in a custom header (e.g., X-API-Key)
API Key (Query)	Appends the key as a URL query parameter
Basic Auth	Sends base64-encoded user:password in the Authorization header

Credentials are encrypted at rest and never exposed in API responses.

Parameters

Parameters define what information the agent needs to collect from the customer before calling the API.

Example: For an order lookup tool, you'd add:

Name	Type	Required	Description
order_number	string	Yes	The order number (e.g., ORD-12345)

The agent will ask the customer for their order number before making the API call.

Response mapping

Response Path — If the API returns nested JSON, specify the dot-path to extract the useful data.

Example: If the API returns:

{
  "data": {
    "order": {
      "id": "ORD-123",
      "status": "shipped",
      "eta": "May 20"
    }
  }
}

Set the response path to data.order to extract just the order object.

Response Template — Format the extracted data into a readable sentence using {{field}} placeholders.

Example template:

Order {{id}} is {{status}}, expected delivery: {{eta}}

Result: "Order ORD-123 is shipped, expected delivery: May 20"

Leave both fields empty to let the agent interpret the raw API response.

Example: Order tracking tool

Setting	Value
Name	trackOrder
Description	Check the delivery status of a customer order using their order number
Method	GET
Endpoint URL	https://api.mystore.com/v1/orders/{{order_number}}
Auth	Bearer Token
Parameter	order_number (string, required) — "The customer's order number"
Response Path	data
Response Template	Order {{order_number}} is {{status}}. {{tracking_url}}

Credits

API tool calls cost 2x AI credits compared to regular responses. This covers the additional API processing and multi-step reasoning.

Limits

• Max 3 tool call rounds per message (prevents infinite loops)
• Tool timeout: configurable, default 10 seconds, max 30 seconds
• Rate limit: configurable per tool, default 60 calls/hour