Skip to main content

Custom API integrations

Connect any HTTP API as a Custom API integration. Once connected, you define shared actions under the integration (like lookup_invoice or create_ticket), and any agent in your workspace can link those actions.

Connect an API​

Open Integrations, click + Add integration → API/MCP server, and pick Custom API.

Give the integration a name (used in lists and when linking actions to agents) and an optional description. Then configure the base URL, auth, and any shared headers for each environment you'll use. At least one environment is required; the others are optional.

Start from a template​

If you're connecting a common service (Salesforce, HubSpot, Genesys Cloud, Zendesk, Microsoft Dynamics 365, or Microsoft Exchange / Outlook 365), pick it from the Templates row on the same screen instead of filling everything in by hand. The template prefills the integration name, base URL, expected auth type, and a starter set of shared actions (e.g. create_lead, get_contact_by_email), so the only thing you still need to provide is your tenant-specific details (such as your instance or subdomain, where the service uses one) plus the credentials for the auth connector.

Once you've picked a template, the wizard header shows a Setup steps link with the third-party prerequisites (for example, where to create an External Client App in Salesforce or a Private App in HubSpot) and a link to the vendor's own reference.

Per-environment configuration​

Each Custom API integration has three environment slots: Development, Staging, and Production. Each slot has its own base URL, its own auth connector, and its own HTTP headers. When a conversation runs in a given environment, Stellar resolves the matching slot, so a playground session running in Development hits your sandbox URL with sandbox credentials, while a real production call hits the live API.

You don't have to fill in all three. If a slot is empty, the agent won't be able to use this integration in that environment.

After creating the integration, the Settings tab on its detail page shows the same per-environment configuration. Edit any slot inline, then click Save.

Shared headers​

Use per-environment headers for values you'd otherwise repeat on every action, like a shared API version header or an environment-specific auth header. Each header is either a static value or a reference to a secret, so credentials stay in your secret store and never appear in the action configuration. These headers are sent on every action request that runs in that environment. If a shared action sets a header with the same name, the action's value takes precedence for that action.

Authentication​

Auth connectors handle credential management: Bearer tokens, API keys, Basic auth, and OAuth2. Pick an existing auth connector from the picker, or create a new one from there.

Auth connectors carry their own per-environment credentials. If your production OAuth2 client differs from your staging client, configure both on the same auth connector.

For simple credentials (a single API key, for example), secrets are pulled from your org's secret store. You can also create a new secret directly from any secret picker.

Shared actions​

Open the Actions tab on the integration's detail page to add and edit shared actions. Each shared action defines what the agent can call:

  • Name and description: what the agent sees when deciding to call the action
  • URL and method: the endpoint, relative to the integration's base URL
  • Headers: extra HTTP headers for this specific endpoint
  • Output variables: fields to extract from the response so the agent can use them in later turns

These are the parts every agent shares. What each agent collects and how it maps into the request is set per agent on the binding, from the agent's own Actions tab. See shared actions for the full split of what's shared versus per agent, and API call actions for the field reference.

From an agent's Actions tab, click + Add action and pick the integration as the source. Choose the shared action you want and confirm. The agent is now linked.

The action will use the integration's base URL and auth automatically. Edit phases, allowed states, and other per-agent fields from the agent's binding page.

See Agent-specific actions for when an API call is better left agent-local instead of shared under an integration.

Delete an integration​

From the integration's detail page, open the menu in the header and choose Delete. You can't delete an integration that has actions linked to active agents. Unlink those bindings first, or remove the actions from the agent versions that still reference them.

Next steps​