> ## Documentation Index
> Fetch the complete documentation index at: https://docs.galtea.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Endpoint Connection
> A reusable connection to an external endpoint that defines how to connect to your AI system's API.
## What is an Endpoint Connection?
An Endpoint Connection tells Galtea how to call your AI system's API. You configure the URL, authentication, request format, and response mapping once, and Galtea uses it to run evaluations against your endpoint automatically.
## Use Cases
* **Automate evaluations** — Galtea calls your endpoint directly for each test case, no manual inference needed
* **Standardize API calls** — Define reusable configurations with consistent auth and request formatting
* **Manage multiple environments** — Create separate connections for development, staging, and production
## Creating an Endpoint Connection
To create an Endpoint Connection:
1. Navigate to your product in the [Galtea Dashboard](https://platform.galtea.ai/)
2. Go to the "Endpoint Connections" section
3. Click "New Endpoint Connection" and choose how to start:
* **From cURL** — paste a cURL command and Galtea pre-fills the form (URL, method, headers, authentication, request body, and a suggested connection name) for you. Deterministic fields show an "Auto-filled" badge. For **Conversation** endpoints, when the request body is valid JSON, Galtea also uses AI to produce a richer input template (with conversation history, context fields, and the correct placeholder vocabulary) and to suggest a more descriptive connection name — both of those fields show an "AI Generated" badge instead. For **Initialization** and **Finalization** endpoints, the request body is used verbatim as the input template and the name is derived from the host URL (no AI enrichment for either field). Anything Galtea cannot parse is left for you to complete. You can also open this importer from the **Import from cURL** button inside the form.
* **Blank** — start from an empty form.
4. Configure the connection properties as described below
## Quick Start: Single Conversation Endpoint
Most integrations only need **one Conversation endpoint**. At its simplest, you just need to configure:
* **Input Template** — How to format the request body (using `{{ input.user_message }}` for the simulated user message)
* **Output Mapping** — How to extract your product's AI response (using a JSONPath expression for the `output` key)
```json Input Template theme={"system"}
{
"message": "{{ input.user_message }}"
}
```
```json Output Mapping theme={"system"}
{
"output": "$.response"
}
```
This is all you need to start running evaluations against your endpoint. For advanced template syntax, conversation history loops, state management, and output mapping options, see [Templates & Mapping](/concepts/product/endpoint-connection-configuration).
## Multi-Step Session Lifecycle (Advanced)
Some AI products expose separate endpoints for session setup and cleanup. In those cases, you can configure up to three endpoint connections:
* **Initialization** (optional): runs before conversation
* **Conversation** (required): runs for each turn
* **Finalization** (optional): runs after conversation
### Session Lifecycle Flow
When a version has initialization and/or finalization endpoints configured, the evaluation follows this lifecycle:
```mermaid theme={"system"}
%%{init: {"theme": "neutral"}}%%
sequenceDiagram
participant Galtea
participant Init as Initialization Endpoint
participant Conv as Conversation Endpoint
participant Final as Finalization Endpoint
Galtea->>Galtea: Create Session
opt If Initialization Configured
Galtea->>Init: Initialize Session
Init-->>Galtea: Return session_id
Galtea->>Galtea: Store session_id for future requests
end
loop For Each Turn
Galtea->>Conv: Send Message (with session_id + metadata)
Conv-->>Galtea: Return Response
Galtea->>Galtea: Store Inference Result
end
opt If Finalization Configured
Galtea->>Final: Finalize Session (always runs)
end
```
### Example Use Case: Multi-Step Chatbot
Some chatbot APIs require multiple steps:
* **Initialization**: create a session and return a `session_id`
* **Conversation**: send messages using that `session_id`
* **Finalization**: clean up the session
In this setup:
* Your **Initialization** connection extracts `session_id` via `outputMapping`.
* Your **Conversation** connection can reuse it in the URL/body using `{{ session_id }}`.
* Any additional fields extracted via `outputMapping` are stored in **session metadata** and can also be reused in later turns.
## Endpoint Connection Properties
A unique name for the endpoint connection within the product. **Example**: "Production Chat API" or "Staging Summarizer"
The purpose of the endpoint connection:
* `INITIALIZATION` - Runs before the conversation
* `CONVERSATION` - Runs for each turn
* `FINALIZATION` - Runs after the conversation
The full URL of the endpoint. Must be a valid HTTP or HTTPS URL. **Example**: "[https://api.company.com/v1/chat](https://api.company.com/v1/chat)"
The HTTP method: `GET`, `POST`, `PUT`, `PATCH`, or `DELETE`.
Authentication method: `NONE`, `BEARER`, `API_KEY`, or `BASIC`.
The authentication token or credentials. This value is securely stored.
Optional custom headers to include with each request.
Optional JSON Schema defining the structure of test case inputs (field types, constraints, enums). When set, Galtea generates structured multi-field test data matching this schema. See [Input Schema](/concepts/product/endpoint-connection-input-schema) for details and examples.
A Jinja2 template defining the request body. See [Templates & Mapping](/concepts/product/endpoint-connection-configuration#input-template) for the full placeholder reference and examples.
A JSON object defining how to extract values from the response using JSONPath. See [Templates & Mapping](/concepts/product/endpoint-connection-configuration#output-mapping) for special keys and examples.
Request timeout in seconds (1–300). Default: 30 seconds.
Optional rate limit for requests per minute.
## 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. See [Retry Configuration](/concepts/product/endpoint-connection-configuration#retry-configuration).
Never share your auth tokens. Galtea securely stores and encrypts all authentication credentials.
## Related
How Galtea's concepts connect — diagram + per-entity quick reference.
Define structured, multi-field inputs for test case generation.
Full reference for Input Templates, Output Mapping, state management, and retry configuration.
Deep dive into `{{ input.field_name }}` and `{{ context.field_name }}` placeholder syntax, JSON escaping, and missing field behavior.
Manage endpoint connections programmatically using the Python SDK.
Attach endpoint connections to a version for evaluation.
Run evaluations from the dashboard using your endpoint connection.