Skip to main content

​
Returns

Returns an Endpoint Connection object for the given parameters, or None if an error occurs.

​
Example

​
Parameters

​
name
string
required
Name of the endpoint connection. Must be unique per product.
​
product_id
string
required
ID of the product this connection belongs to.
​
url
string
required
The endpoint URL (HTTPS only). For multi-step session lifecycles, the URL supports a {{ session_id }} placeholder for dynamic session IDs (e.g., https://api.example.com/v1/threads/{{ session_id }}/messages). Only available when an INITIALIZATION endpoint connection returns a session_id.
​
type
string
required
Type of endpoint connection. Valid values: INITIALIZATION, CONVERSATION, FINALIZATION. CONVERSATION is required for all products. INITIALIZATION and FINALIZATION are only needed for complex session management (e.g., when your API requires a separate setup call that returns a session ID, or a cleanup call after the conversation ends). Other string values are sent to the API unchanged, so values added in newer API versions can be used; the API rejects invalid ones.
​
http_method
string
default:"POST"
HTTP method. Valid values: GET, POST, PUT, PATCH, DELETE. Defaults to POST. Other string values are sent to the API unchanged, so values added in newer API versions can be used; the API rejects invalid ones.
​
auth_type
string
default:"BEARER"
Authentication type. Valid values: NONE, BEARER, API_KEY, BASIC. Defaults to BEARER. Other string values are sent to the API unchanged, so values added in newer API versions can be used; the API rejects invalid ones.
​
auth_token
string
Authentication token. Required for BEARER and API_KEY auth types.
​
username
string
Username for BASIC authentication.
​
password
string
Password for BASIC authentication.
​
headers
dict[string, string]
Custom headers as key-value pairs. Supports credential placeholders (e.g., {{ bearer_token }}, {{ api_key }}). See Custom Headers.
​
input_template
string
Input template with Jinja2 placeholders. Required for CONVERSATION type. Must contain {{ input.user_message }}. See Templates & Mapping.
​
output_mapping
dict[string, string]
Output mapping configuration using JSONPath expressions. Required for INITIALIZATION (needs session_id) and CONVERSATION (needs output) types. See Templates & Mapping.
​
timeout
int
Per-attempt request timeout in seconds. Defaults to 15. Maximum 120 (values above this are rejected by the API).
​
rate_limit
int
Maximum requests per minute. Leave empty for no limit (no throttling).
​
retry_enabled
bool
Whether automatic retry is enabled. Defaults to true. See Retry Configuration.
​
retry_max_attempts
int
Maximum retry attempts (0–10). Defaults to 1. These are retries after the first call, so N attempts means up to N+1 calls to your endpoint, and each call uses credits. 0 is only valid when retry is disabled; with retry enabled the minimum is 1.
​
retry_initial_delay_ms
int
Initial delay in milliseconds before first retry. Defaults to 1000.
​
retry_backoff_strategy
string
Backoff strategy. Valid values: FIXED, EXPONENTIAL, LINEAR. Defaults to EXPONENTIAL. Other string values are sent to the API unchanged, so values added in newer API versions can be used; the API rejects invalid ones.
​
retry_max_delay_ms
int
Maximum delay between retry attempts, in milliseconds. Defaults to 3000. Capped at 60000; values above this are rejected.
​
retryable_status_codes
list[int]
HTTP status codes that trigger retry. Defaults to [429, 500, 502, 503, 504]. Each value must be a valid HTTP status code (100–599).