Skip to main content

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​

  1. Open your project and go to Tools → Add tool.
  2. Under Or start from a blank type, choose API Call (REST).
  3. Give the tool a descriptive name (for example "Check Account Balance").
  4. 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:

KeyValue
AuthorizationBearer {{api_key}}
Content-Typeapplication/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:

FieldDescription
NameMust match the placeholder exactly (e.g. customer_id)
Typestring, number, boolean
RequiredWhether the agent must provide this value
DescriptionWhat 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 Authorization header with Bearer {{api_key}} and define api_key as a parameter with a fixed default value
  • Basic auth — add an Authorization: Basic {{base64_credentials}} header
  • No auth — leave headers blank for public APIs
warning

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:

NameTypeRequiredDescription
tracking_numberstringYesThe shipment tracking number provided by the customer
api_keystringYesShipping 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.

Was this page helpful?