Skip to main content

​
What is an Endpoint Connection?

An Endpoint Connection in Galtea represents a reusable configuration for connecting to external API endpoints. Endpoint Connections are associated with a product and allow you to define how Galtea should communicate with your AI system during evaluations.
Endpoint Connections are only available through the Galtea Dashboard. They are not currently accessible via the SDK.

​
Use Cases

Endpoint Connections are useful when you want to:
  • Automate evaluations - Configure how Galtea calls your AI endpoint for automated testing
  • Standardize API calls - Define reusable endpoint configurations with consistent authentication and request formatting
  • Manage multiple environments - Create separate connections for development, staging, and production endpoints

​
Creating an Endpoint Connection

To create an Endpoint Connection:
  1. Navigate to your product in the Galtea Dashboard
  2. Go to the “Endpoint Connections” section
  3. Click “New Endpoint Connection”
  4. Configure the connection properties as described below

​
Endpoint Connection Properties

​
Name
Text
required
A unique name for the endpoint connection within the product. Example: “Production Chat API” or “Staging Summarizer”
​
Type
Enum
required
A type that defines the purpose of the endpoint connection. Supported values:
  • INITIALIZATION - Connection used for initializing a session
  • CONVERSATION - Connection used for conversational interactions
  • FINALIZATION - Connection used for finalizing a session
This is done for complex session lifecycles where a single endpoint connection is not enough.
​
URL
Text
required
The full URL of the endpoint to connect to. Must be a valid HTTP or HTTPS URL. Example: “https://api.company.com/v1/chat”
​
HTTP Method
Enum
required
The HTTP method to use when calling the endpoint. Supported values:
  • GET
  • POST
  • PUT
  • PATCH
  • DELETE
​
Auth Type
Enum
required
The authentication method to use. Supported values:
  • NONE - No authentication
  • BEARER - Bearer token authentication
  • API_KEY - API key authentication
  • BASIC - Basic HTTP authentication
​
Auth Token
Text
The authentication token or credentials, depending on the selected auth type. This value is securely stored.
​
Headers
JSON
Optional custom headers to include with each request. Example:
{
  "Content-Type": "application/json",
  "X-Custom-Header": "value"
}
​
Input Template
String (Jinja2)
required
A Jinja2 template string defining how to format the request body. This template is rendered before sending the request to your endpoint.Available placeholders:
  • {{ input }} - The test case input (required)
  • {{ context }} - The test case context
  • {{ session_id }} - The external session ID (if available)
  • {{ test_case_id }} - The test case ID
  • {{ test_id }} - The test ID
  • {{ galtea_session_id }} - The Galtea session ID
  • Any field stored in session metadata (for example {{ sessionId }}, {{ tenant }}, {{ conversation_token }})
  • {% for turn in past_turns %}...{% endfor %} - Loop through conversation history
    • {{ turn.input }} - Previous user input
    • {{ turn.output }} - Previous assistant response
Example (OpenAI-compatible format):
{
  "model": "gpt-4",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {% for turn in past_turns %}
    {"role": "user", "content": "{{ turn.input }}"},
    {"role": "assistant", "content": "{{ turn.output }}"},
    {% endfor %}
    {"role": "user", "content": "{{ input }}"}
  ]
}
Example (Previous queries array):
{
  "model": "gpt-4",
  "previous_queries": [
    {% for turn in past_turns %}
    "{{ turn.input }}"{% if not loop.last %},{% endif %}
    {% endfor %}
  ],
  "current_query": "{{ input }}"
}
When a loop is the last item in a JSON array, use {% if not loop.last %},{% endif %} after each iteration to prevent a trailing comma. When there’s content after the loop (like in the OpenAI example above), trailing commas are valid and this pattern is not required.
Example (Custom format):
{
  "data": {
    "names": ["query", "contexto"],
    "ndarray": [
      [
        "{{ input }}",
        [
          {% for turn in past_turns %}
          "{{ turn.input }}",
          "{{ turn.output }}"{% if not loop.last %},{% endif %}
          {% endfor %}
        ]
      ]
    ]
  }
}
​
Output Mapping
JSON
required
A JSON object defining how to extract values from the API response using JSONPath expressions.Required keys:
  • output - JSONPath expression to extract the main response (required)
Optional keys:
  • retrieval_context - JSONPath expression to extract retrieval context
  • Any additional keys for extra properties to store in session metadata
JSONPath Syntax Reference:
ExpressionDescription
$Root object
.Child operator
[]Array index or child operator
[*]Wildcard (all elements)
[0]First array element
[-1]Last array element
Example:
{
  "output": "$.choices[0].message.content",
  "retrieval_context": "$.choices[0].retrieval_context",
  "session_id": "$.metadata.session_id"
}
​
Timeout
Number
Request timeout in seconds. Must be between 1 and 300 seconds. Default: 30 seconds.
​
Rate Limit
Number
Optional rate limit for requests per minute. Use this to avoid exceeding your API’s rate limits.

​
Retry Configuration

Configure automatic retry behavior for failed requests. When enabled, Galtea will automatically retry requests that fail with specific HTTP status codes.
​
Retry Enabled
Boolean
Whether automatic retry is enabled. Default: false
​
Max Retry Attempts
Number
Maximum number of retry attempts. Default: 3
​
Initial Delay
Number
Initial delay in milliseconds before the first retry. Default: 1000 (1 second)
​
Backoff Strategy
Enum
Strategy for increasing delay between retry attempts:
  • exponential - Delay doubles with each attempt (recommended)
  • linear - Delay increases linearly
  • fixed - Constant delay between attempts
Default: exponential
​
Max Delay
Number
Maximum delay cap in milliseconds. Default: 30000 (30 seconds)
​
Retryable Status Codes
Array of Numbers
HTTP status codes that should trigger a retry. Default: [429, 500, 502, 503, 504]

​
Best Practices

Choose names that clearly identify the endpoint’s purpose and environment, such as “Production Chat API” or “Staging Document Analyzer”.
Set timeouts based on your endpoint’s expected response time. For complex AI operations, you may need longer timeouts (60-120 seconds).
Configure retries for endpoints that may experience transient failures. Start with 2-3 retries with exponential backoff.
Never share your auth tokens. Galtea securely stores and encrypts all authentication credentials.