API Tool
An API Tool lets you connect an agent to any REST API endpoint — without writing code. You define the URL, method, headers, and parameters, and the agent can call it during conversations. Use it for internal APIs, third-party services that don't have a pre-built integration, or any HTTP-based tool.
When to use API Tool
Use an API Tool when:
- The service you need isn't in the integration catalogue
- You have an internal REST API you want the agent to call
- You want full control over the request shape
Use a pre-built integration (like Jira, Shopify, Slack) when one exists — they handle auth and error cases for you.
Creating an API Tool
- Open your project and go to Tools → Add tool.
- Under Or start from a blank type, choose API Call (REST).
- Give the tool a descriptive name (for example "Check Account Balance").
- Work through the configuration steps.
Configuring the request
URL
Enter the full endpoint URL. Use {{double_braces}} for dynamic values the agent will fill in:
https://api.example.com/v1/customers/{{customer_id}}
Method
Choose GET, POST, PUT, PATCH, or DELETE.
Headers
Add static headers as key-value pairs. Use {{param_name}} for values that should be injected at runtime:
| Key | Value |
|---|---|
Authorization | Bearer {{api_key}} |
Content-Type | application/json |
Body (POST / PUT / PATCH)
Enter the JSON body template. Use {{param_name}} placeholders for dynamic values:
{
"email": "{{customer_email}}",
"subject": "{{subject}}",
"message": "{{message_body}}"
}
Defining parameters
Parameters are the inputs the agent will provide when calling the tool. For each {{param_name}} placeholder in the URL, headers, or body, add a parameter definition:
| Field | Description |
|---|---|
| Name | Must match the placeholder exactly (e.g. customer_id) |
| Type | string, number, boolean |
| Required | Whether the agent must provide this value |
| Description | What this value is — the agent uses this to decide what to pass |
Authentication options
For APIs that require authentication:
- API Key in header — add an
Authorizationheader withBearer {{api_key}}and defineapi_keyas a parameter with a fixed default value - Basic auth — add an
Authorization: Basic {{base64_credentials}}header - No auth — leave headers blank for public APIs
Do not put API keys or tokens in your agent's system prompt or ask the agent to supply them. Set them as fixed values in the tool configuration so the model never sees them.
Viewing the response
The API response is returned as JSON and passed to the agent. The agent can then extract and present the relevant fields in its reply.
Example: look up a shipping status
URL: https://api.shipping.example.com/shipments/{{tracking_number}}
Method: GET
Headers: Authorization: Bearer {{api_key}}
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
tracking_number | string | Yes | The shipment tracking number provided by the customer |
api_key | string | Yes | Shipping API key (set a default value) |
System prompt fragment:
When a customer asks about their shipment, ask for their tracking number.
Then use the shipping status tool to look up the current location and estimated delivery.
Present the status in plain language: "Your package is currently in [location] and is estimated to arrive by [date]."
Troubleshooting
Agent doesn't call the tool
Make sure the parameter descriptions are clear enough for the model to understand what to collect from the user. Vague descriptions like "ID" are less effective than "The customer account ID from their welcome email".
Connection error or timeout
VoisX could not reach the API endpoint. Make sure it is reachable from the public internet. If your firewall only allows known IP addresses, contact us for the addresses to allowlist for your region.
Unexpected response format
If the API returns something other than JSON (HTML, plain text), the agent may have trouble parsing it. APIs that return HTML error pages on failures are a common cause — add error handling in your system prompt to handle empty or unexpected responses gracefully.