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 and auth for each environment you'll use. At least one environment is required; the others are optional.

Per-environment configuration​

Each Custom API integration has three environment slots: Development, Staging, and Production. Each slot has its own base URL and its own auth connector. 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; changes save when you click Save.

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 fields are shared — every agent linking the action sees the same values. The parameters schema (what the AI collects) and the request body template (how those values map into the HTTP request) are set per agent — open the agent's Actions tab and click the action to configure them. Conversation phases, max successful calls, and allowed states are also per agent.

See API call actions for the full 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​

  • MCP servers — the other kind of API integration
  • API call actions — full configuration reference for shared API actions
  • Restore behavior — how linked shared actions behave when restoring an older agent version