API Tools

API tools let agents make HTTP requests to external services, enabling real-time data retrieval and actions beyond the knowledge base.

Plan required: Pro

Use Cases

• Check inventory in your warehouse management system

• Look up customer information in your CRM

• Verify appointment availability in your scheduling system

• Retrieve pricing from an external service

• Submit form data to your backend

• Trigger workflows in automation platforms

Adding an API Tool

Navigate to Integrations > Custom Extensions > API integrations and click Create new.

Step 1: Integration Information

Field	Description
Name	A descriptive name for the tool (e.g., "Order Status")
Description	Explains what the tool does and when to use it. This helps the agent decide when to call this tool.
Assign to Agent	Which agent should have access to this tool

Write clear, specific descriptions. Instead of "Gets data from the API", write "Retrieves the status of an order given the order number. Use when customers ask about their order status."

Step 2: Define Variables

Variables are the parameters your API needs. You must define at least one variable. There are two sources for variables:

Asked by AI

Variables that the AI will ask the user for during the conversation.

Field	Description
Name	Variable name (e.g., order_id) - used in placeholders
Parameter description	Describes what this variable is (helps the AI ask for it correctly)
Type	Data type: Text, Number, Integer, Boolean, Array, or Object
Mandatory	Whether this variable is required
Test value	Sample value for testing the API call

Click Add variable after filling in the fields.

From SDK

Variables passed from your website via the SDK's userMetadata. Use this when you already have customer information available on your site (like a logged-in user's ID).

Field	Description
Name	Variable name - must match the key in userMetadata
Test value	Sample value for testing the API call

To pass variables from your website, use the Custom Data feature:

document.gleenConfig = {
    company: 'your-company-key',
    userMetadata: {
        customer_id: '12345',
        plan_type: 'premium'
    }
};

Step 3: Configure API Call

Use your defined variables in the API configuration with double curly braces: {{variable_name}}

Field	Description
API Endpoint URL	The full URL, can include variables (e.g., https://api.example.com/orders/{{order_id}})
API Method	GET, POST, PUT, PATCH, or DELETE
Body	Request body for POST/PUT/PATCH methods (JSON format)
Headers	Authentication and other headers

Example endpoint with variable:

https://api.example.com/v1/orders/{{order_id}}/status

Example body with variables:

{
  "customer_id": "{{customer_id}}",
  "action": "lookup"
}

Example header with variable:

Authorization: Bearer {{api_token}}

Store API keys securely. For static API keys, add them directly to headers. For dynamic tokens passed from the SDK, use variables.

Step 4: Validate Your API Call

Click Run Test to verify your configuration works. The test uses the test values you provided for each variable.

Check that:

• The API returns a successful response

• The response contains the expected data

• Error cases are handled appropriately

Step 5: Filter Response (Optional)

Use JMESPath expressions to filter the API response before sending it to the AI. This helps:

• Reduce unnecessary data sent to the language model

• Speed up response times

• Focus the agent on relevant information

Add filters using Output Key and JMESPath Expression pairs:

Output Key	JMESPath Expression	Result
status	order.status	Extracts the status field
items	order.items[*].name	Gets all item names
total	order.total_amount	Extracts the total

Click Update Preview to see the filtered result before saving.

Step 6: Save

Click Save Changes to save your API tool. The tool will be enabled and assigned to your selected agent.

Managing API Tools

View all tools

Navigate to Integrations > Custom Extensions > API integrations to see all your API tools.

Enable or disable a tool

On the edit page, toggle Integration Status to enable or disable the tool.

Delete a tool

On the edit page, click Delete Integration to remove the tool.

Best Practices

Write descriptive tool descriptions

The description is how the agent knows when to use your tool. Be specific about:

• What information the tool provides

• What user questions should trigger this tool

• What the agent should do with the response

Use SDK variables for known data

If you already have customer information on your website (from login, cookies, etc.), pass it via SDK userMetadata instead of having the AI ask for it. This creates a smoother experience.

Handle authentication securely

• Use API keys or tokens rather than username/password

• Rotate credentials periodically

• Use the minimum required permissions

Keep responses focused

Return only the data the agent needs. Use JMESPath filters to extract relevant fields. Large responses with unnecessary data can confuse the agent and slow down responses.

Troubleshooting

Issue	Solution
Tool never gets called	Check that the description clearly indicates when to use it
Wrong parameters sent	Verify variable names match between definition and placeholders
Authentication errors	Test the endpoint directly to verify credentials work
Variables not populated	For SDK variables, verify userMetadata is set before SDK loads
Unexpected responses	Use JMESPath filters to extract the specific data needed

Related

• MCP Servers - For more complex integrations

• Sheet Search - For spreadsheet data access

• Custom Data - Passing data from your website

• Custom Agents - Assign tools to specific agents