> For the complete documentation index, see [llms.txt](https://alhena.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://alhena.gitbook.io/docs/integrations/custom-extensions/api-tools.md).

# 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                                                         |

{% hint style="info" %}
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."
{% endhint %}

### 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](/docs/developer-reference/website-sdk/custom-data.md) feature:

```javascript
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:**

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

**Example header with variable:**

```
Authorization: Bearer {{api_token}}
```

{% hint style="warning" %}
Store API keys securely. For static API keys, add them directly to headers. For dynamic tokens passed from the SDK, use variables.
{% endhint %}

### 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](https://jmespath.org/tutorial.html) 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](/docs/integrations/custom-extensions/mcp-servers.md) - For more complex integrations
* [Sheet Search](/docs/integrations/custom-extensions/sheet-search.md) - For spreadsheet data access
* [Custom Data](/docs/developer-reference/website-sdk/custom-data.md) - Passing data from your website
* [Custom Agents](/docs/ai-configuration/agents/custom-agents.md) - Assign tools to specific agents