Create an API tool

Create an API tool that calls your own web endpoint during a call, attach it to a voice or WhatsApp agent, and test it before going live.

What you will achieve

You will create a tool such as "look up the status of an order", attach it to an agent, and see it work.

A web endpoint reachable from the internet (not a private or localhost address), returning JSON or text.
The owner or admin role.

Open Tools in the sidebar and choose Add tool.
In New tool, fill in:
- Name: what the model sees, so name it after the action, for example lookup_order. Spaces become underscores and letters are lower-cased.
- Description: how the model decides when to call it, for example "Look up the delivery status of an order".
- Method: GET, POST, PUT, PATCH or DELETE.
- API endpoint: for example https://api.yoursite.com/orders/{order_id}. Wrap a name in braces to put it in the path.
Choose Create tool. The tool's own page opens for the details: parameters, authentication and limits.
Add each Parameter the model must supply (see the next guide), set Authentication if the endpoint needs it, and choose Save changes.
Attach it to an agent: open the agent, Tools tab, Your tools, Add tool, Existing tool, tick it and choose Add tool. Or choose New tool there to create and attach in one step (Create and add).
Press Save on the agent if it shows unsaved changes.

Section	What it holds
What it does	Description: "Tells the model when to call this tool."
When it runs	Run in the background: whether the agent waits for the tool or carries on talking.
Endpoint	Method and URL. Put `{param}` in the path, like `/orders/{order_id}`.
Body template	Optional JSON for POST, PUT and PATCH. Empty means the parameters are sent as JSON.
Read this from the response	A dotted path such as `data.status`. Empty returns everything.
Parameters	What the model must supply, validated before each request.
Authentication	Type, Sent as, Name and the secret.
Limits	Timeout and Attempts.
Test	Try the tool with sample values.

Path. {order_id} in the URL is replaced with the value, URL-encoded.
GET and DELETE. Parameters not used in the path are sent as the query string.
POST, PUT, PATCH. Parameters are sent as a JSON body, or fill your Body template.
Redirects are not followed, responses are capped at 1 MB, and private or internal addresses are refused.

Use Test on the tool page (see Test and troubleshoot tools), then Talk to the agent and ask for what the tool does.

The agent answers using the tool's result, and the tool's row on the Tools page shows a request counted as successful.

A tool named '…' already exists. Names are unique in a workspace.
The agent never calls it. Improve the Description, and mention the tool in the system prompt.
See Tool failures.

Something here does not match what you see in the dashboard? Let us know.