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. Go to your project → Integrations
2. Click Add Integration → Browse → API Tool
3. Fill in the form:
   • Name — descriptive name (e.g. "Check Account Balance")
   • Node type — API Tool (pre-selected)
4. Proceed 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 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

For sensitive credentials (API keys, tokens), consider storing them as vault secrets and referencing them in the node config rather than as agent parameters. Contact your administrator to set this up.

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

The API endpoint is unreachable from Vois AI's backend. Verify it's publicly accessible or that your firewall allows connections from Vois AI IP ranges.

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.