API connections

Save an API base URL, authentication, and headers once, then reuse them in Custom API actions and widget functions for the same agent.

An API connection saves a base URL and the credentials and headers sent with requests to that API. Use it in one or more Custom API actions and widget Call API functions.

Connections belong to one agent. They are not shared with other agents or teams.

Create a connection

In your agent, go to Build > API connections and select Create connection. Enter a name and the API’s base URL, then set authentication or add headers if the API requires them.

The base URL must use HTTPS and point to a public address. You can include a path such as https://api.example.com/v1, but not a query, fragment, or variable. Add the endpoint path in the action or widget function that uses the connection.

Authentication

Choose the method your API expects:

Use Headers to add other HTTP headers that every request needs. Chatvox encrypts saved secrets and masks them in the editor. Select Replace to enter a new secret. Saving without replacing it keeps the saved value.

Test the connection

In the connection’s Test card, choose a method and enter a Path and query, such as /orders?limit=1. Leave the path empty to request the base URL. Select Send test request to see the HTTP status and response body.

The test uses unsaved connection settings and sends a real request. A test with POST, PUT, PATCH, or DELETE can change data in your API.

Use a connection

In a Custom API action or widget’s Call API function, select the connection, method, and Path and query. Add a JSON request body or choose Query params for the action’s or function’s fields when needed. The connection supplies the base URL, authentication, and headers.

You can edit a connection without changing its users. Its Used by list shows actions and widgets that use it. Remove the connection from each caller before deleting it.

For a complete setup, see Custom API or the widget Call API guide.