Skip to main content

API connections

API connections are reusable configurations for external API integrations. They centralize the base URL, authentication, and headers for an API so that multiple actions can share the same connection settings without duplicating configuration.

Why use API connections​

Without API connections, each action needs its own full URL, auth connector, and headers configured independently. API connections solve this by providing a single, named configuration that actions reference:

  • Reuse: Define the base URL, auth, and headers once — use across multiple actions.
  • Per-environment config: Each API connection supports different settings per environment (Development, Staging, Production), so your actions automatically point at the right API.
  • Easier maintenance: Update the base URL or credentials in one place instead of editing every action.

Creating an API connection​

  1. Navigate to Manage > API connections in Studio
  2. Click Add API connection
  3. Enter a Name (e.g., CRM API, Payment Gateway)
  4. Configure each environment:

Per-environment settings​

For each environment (Development, Staging, Production), you can configure:

Base URL (required) — The root URL for the API in this environment.

EnvironmentExample base URL
Developmenthttps://sandbox.api.example.com/v2
Staginghttps://staging.api.example.com/v2
Productionhttps://api.example.com/v2

Auth connector (optional) — Select an auth connector to handle authentication for requests through this connection. The auth connector's own per-environment credentials are used automatically.

Headers (optional) — Add custom HTTP headers. Each header can be:

  • Static value: A fixed string (e.g., Content-Type: application/json).
  • Secret reference: A reference to an org secret, so sensitive values like API keys are never exposed. The secret's per-environment value is resolved automatically.

You don't need to configure all three environments. Only configure the environments you plan to use.

Using API connections in actions​

When creating or editing an API call action, you can select an API connection:

  1. In the action editor, select an API connection from the dropdown
  2. The URL field changes to a Path field — enter just the path portion (e.g., /orders or /customers/search)

Example:

With an API connection CRM API configured with base URL https://api.example.com/v2 for Production:

  • Action path: /orders
  • Resulting URL: https://api.example.com/v2/orders

The action inherits the API connection's auth connector and headers. You can still add action-specific headers on top — they are merged with the connection's headers at request time.

When to use API connections

Use an API connection when you have multiple actions that call the same API (e.g., get_order, create_order, update_order all hitting the same CRM). For one-off API calls, configuring the action directly may be simpler.

Managing API connections​

Editing​

  1. Find the API connection in the list
  2. Click Edit
  3. Update the name, base URLs, auth connector, or headers
  4. Click Save

Deleting​

  1. Find the API connection in the list
  2. Click Delete
  3. Confirm deletion
Before Deleting

You cannot delete an API connection that is referenced by any agent action. Remove the reference from all actions first, or switch those actions to a different API connection.