AI Connections

AI Provider Connections

Description

An AI Connection (shown in the UI as an AI Provider Connection) is a Connection record that includes an aiProvider and the authentication details required to call that provider through Contextual’s AI Gateway. AI Connections are used by:

• AI Routes

• AI Generate

Creating an AI Connection

1. In your tenant workspace, go to Components → Connections

2. Click Create Connection

3. Choose AI Provider Connection

4. Provide a Connection ID, Connection Name, choose an AI Provider, and complete the provider-specific configuration

5. Save

Required Information

All AI Connections require:

• Connection ID (apiId) - Lower case letters, numbers, and dashes (^[a-z0-9-]+$)

• Connection Name (name)

• AI Provider (aiProvider)

Provider-specific requirements:

OpenAI

• API Key (bearerToken)

• Endpoint (default: https://api.openai.com/v1)

• Underlying Connection type: bearer

OpenAI Connections use the OpenAI Responses API. To use a provider not offered directly that implements the OpenAI Chat Completions API, use an OpenAI Compatible Connection.

OpenAI Compatible

Use an OpenAI Compatible Connection for a provider that AI Gateway does not offer directly and that accepts OpenAI-style Chat Completions requests.

• API Key (bearerToken) - Required; sent using bearer authentication

• Base URL (endpoint) - Required; enter the provider's complete API base URL, including /v1 or the provider's equivalent path prefix

• Underlying Connection type: bearer

Base URL appears alongside API Key in the form. AI Gateway preserves the URL path prefix and appends /chat/completions, so omit that suffix from Base URL. It does not add /v1 for you.

For example, a Base URL of https://inference.example.com/team/deployment/v1 sends generation requests to https://inference.example.com/team/deployment/v1/chat/completions. This is an illustrative URL; use the base URL supplied by your provider.

After saving the Connection, add it to an AI Route. In the route's Details section, under Model Providers, select the Connection in AI Provider Connection and enter the provider's exact model ID in Model. Supported inputs and features depend on the provider and model.

Anthropic

• API Key (stored in headers as x-api-key)

• Endpoint (default: https://api.anthropic.com/v1)

• Underlying Connection type: public

Azure OpenAI

• Resource Name (aiProviderData.resourceName)

• API Key (stored in headers as api-key)

• Endpoint is generated from the Resource Name (default: https://{resourceName}.openai.azure.com/openai) and can be overridden

• Underlying Connection type: public

Google AI (Gemini)

• API Key (stored in headers as x-goog-api-key)

• Endpoint (default: https://generativelanguage.googleapis.com/v1beta)

• Underlying Connection type: public

Vertex AI

• Project ID (aiProviderData.projectId)

• Location (aiProviderData.location, for example us-central1 or global)

• Service Account Key (JSON) (key)

• Endpoint is generated from Project ID + Location and can be overridden

• Underlying Connection type: google-service-account (uses scope https://www.googleapis.com/auth/cloud-platform)

Vertex AI Anthropic

Same requirements as Vertex AI, but routes to Anthropic models through Vertex AI’s Anthropic publisher endpoint. Anthropic models need to be explicitly enabled for each Vertex AI account, so make sure you are opted in to the particular Anthropic model you want to access through Vertex.

Headers Note

Additional headers you add to a Connection are included in requests made by HTTP Nodes, but are not used in requests made through AI Routes / the AI Gateway.

Usage

• AI Routes only allow selecting Connections that have an aiProvider configured (AI Connections).

• Use the Connection’s Endpoint as the base URL when making manual provider calls from HTTP nodes (if needed).

• AI Connections are standard Contextual Connections, so they can be used anywhere a Connection is accepted (for example, selecting the AI Connection in an HTTP Request/HTTP node to call the provider API directly without using an AI Route or the AI Generate node).