# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://alhena.gitbook.io/docs/integrations/custom-extensions/api-tools.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.