Skip to main content

​
Returns

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

​
Example

​
Parameters

​
string
required
Name of the endpoint connection. Must be unique per product.
​
string
required
ID of the product this connection belongs to.
​
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.
​
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.
​
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.
​
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.
​
string
Authentication token. Required for BEARER and API_KEY auth types.
​
string
Username for BASIC authentication.
​
string
Password for BASIC authentication.
​
dict[string, string]
Custom headers as key-value pairs. Supports credential placeholders (e.g., {{ bearer_token }}, {{ api_key }}). See Custom Headers.
​
string
Input template with Jinja2 placeholders. Required for CONVERSATION type. Must name at least one input field, such as {{ input.user_message }}. Add {{ input_files[0].url }} or {{ input_files[0].base64 }} to send an attached file to your endpoint. A test case that attaches files is refused without one of them. See Templates & Mapping.
​
dict[string, string]
Output mapping configuration using JSONPath expressions. Required for INITIALIZATION (needs session_id) and CONVERSATION (needs output) types. See Templates & Mapping.
​
int
Per-attempt request timeout in seconds. Defaults to 15. Maximum 120 (values above this are rejected by the API).
​
int
Maximum requests per minute. Leave empty for no limit (no throttling).
​
bool
Whether automatic retry is enabled. Defaults to true. See Retry Configuration.
​
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.
​
int
Initial delay in milliseconds before first retry. Defaults to 1000.
​
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.
​
int
Maximum delay between retry attempts, in milliseconds. Defaults to 3000. Capped at 60000; values above this are rejected.
​
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).
​
bool
Set to true to accept an http:// URL. Required when url is not HTTPS, unless the deployment allows plain HTTP for every connection. See HTTP Endpoints.
​
list[ConversationEndRule]
Replies that mean your agent ended the conversation. On a match, the session completes and is evaluated instead of failing, and the match is never retried. Each ConversationEndRule has a status_code (100–599) and an optional body_match, a ConversationEndBodyMatch with a JSONPath path and the expected value equals. A 2xx rule needs a body_match. At most 20 rules, and only for CONVERSATION type. Defaults to no rules. For example, ConversationEndRule(status_code=409, body_match=ConversationEndBodyMatch(path="$.error.code", equals="conversation_ended")). See Conversation End Rules.