Skip to main content
POST
Create endpoint connection

Authorizations

​
Authorization
string
header
required

API key authorization. Pass your API key in the Authorization header as a Bearer token. Both new (gsk_*) and legacy (gsk-) API keys are accepted, e.g. Authorization: Bearer gsk_... or Authorization: Bearer gsk-....

Body

application/json
​
productId
string
required
Example:

"prod_123"

​
name
string
required
Example:

"My API Connection"

​
url
string
required
Example:

"https://api.example.com/v1/chat/completions"

​
httpMethod
enum<string>
required
Available options:
GET,
POST,
PUT,
PATCH,
DELETE
Example:

"POST"

​
authType
enum<string>
required
Available options:
NONE,
BEARER,
API_KEY,
BASIC
Example:

"BEARER"

​
inputTemplate
string | null
required

Jinja2/Nunjucks template for request body. Must contain {{ input.user_message }} placeholder.

Example:

"{\"prompt\": \"{{ input.user_message }}\"}"

​
outputMapping
object | null
required

JSONPath expressions to extract values from API response. Must include "output" key. Special keys: "retrieval_context", "session_id" (initialization), "traces", and "output_files". "output_files" matches one file or a list of files the endpoint answers with, each a data: URI, an http(s) URL, the storage URI of a Galtea file, or an object with "base64", "url" or "uri" plus optional "mime_type" and "filename". Each file is stored as a Galtea file on the turn output: at most 20 files and 20 MB per output, a type a judge can read (the file extension decides it), and a URL is downloaded once without the connection headers or credentials, over plain http only when the connection acknowledged it. A Galtea file is linked rather than copied, and must be an uploaded file of the product organization. A file that cannot be stored fails the turn. Every other key is stored on the session metadata.

Example:
​
id
string
Example:

"ec_123"

​
userId
string | null
Example:

"user_123"

​
hasAuthToken
boolean

Whether an auth token is configured (token value is not exposed)

​
username
string | null

Username for Basic auth

​
hasPassword
boolean

Whether a password is configured (password value is not exposed)

​
headers
object | null

Custom headers as key-value pairs. A secret value is encrypted at rest once its headers are saved, and every read returns it as "••••••••". A value is secret unless its name is Content-Type, Accept, Accept-Language, Accept-Encoding, Cache-Control, User-Agent, traceparent or tracestate, or it holds only placeholders (for example "Bearer {{ bearer_token }}"). On update, send "••••••••" to keep the stored value of that header name; any other value replaces it. Sending "••••••••" for a header with no stored value is a 400, and so is a value in the stored ciphertext shape or with a character a header cannot carry.

Example:
​
inputSchema
object | null

Optional JSON Schema (draft 2020-12) defining the structure of input fields, their types, and valid values. Must have type "object" with a "properties" key.

Example:
​
type
enum<string>
Available options:
INITIALIZATION,
CONVERSATION,
FINALIZATION
Example:

"CONVERSATION"

​
timeout
integer | null
default:15

Per-attempt request timeout in seconds. Unset applies the default (15). Capped server-side at 120 seconds.

Required range: 1 <= x <= 120
Example:

15

​
rateLimit
integer | null

Maximum requests per minute. Unset (null) means no rate limit.

Required range: x >= 1
Example:

60

​
retryEnabled
boolean
default:true

Whether automatic retry is enabled for failed requests

​
retryMaxAttempts
integer | null
default:1

Maximum number of retry attempts (applied when retryEnabled is true). 0 is only valid when retryEnabled is false; with retry enabled the minimum is 1.

Required range: 0 <= x <= 10
​
retryInitialDelayMs
integer | null
default:1000

Initial delay in milliseconds before first retry

Required range: x >= 0
​
retryBackoffStrategy
enum<string> | null
default:EXPONENTIAL

Strategy for increasing delay between retries

Available options:
FIXED,
EXPONENTIAL,
LINEAR
​
retryMaxDelayMs
integer | null
default:3000

Maximum delay between retry attempts, in milliseconds. Capped server-side at 60000 (60 seconds) to bound retry blast radius.

Required range: 0 <= x <= 60000
​
retryableStatusCodes
integer[]

HTTP status codes that should trigger a retry

Required range: 100 <= x <= 599
​
acknowledgedInsecureHttp
boolean
default:false

Required true to use an http:// URL. It records that the creator accepted that traffic to this endpoint is not encrypted, so anyone on the network path can read prompts, responses and credentials. The acceptance covers the connection, not one host: a redirect may send an acknowledged request to any public http:// host, carrying the connection credentials with it. Without it every hop the platform makes to the endpoint must stay on https. It is stored as false for an https:// URL, whatever the request sends.

​
conversationEndRules
object[]

Responses that mean the agent closed the conversation on its own. Only a CONVERSATION connection accepts rules. A rule matches a response with its status code and, when bodyMatch is set, a response body whose first JSONPath match equals the expected value as text. The rules are checked before the retry policy, and a matching response is never retried, even when its status code is in retryableStatusCodes. A matching 2xx response with an agent output keeps its turn as the last one, on any turn and in a single-turn test. A matching response with no agent output (a non-2xx response, or a 2xx response with no output) removes the rejected turn on a later turn of a scenario test. In both cases the session completes with the turns so far and is evaluated, with the stopping reason "The agent ended the conversation (HTTP )". A match with no agent output on the first turn, or on a single-turn test, still fails the session. An empty list keeps the default behaviour.

Maximum array length: 20
​
createdAt
string<date-time>
​
deletedAt
string<date-time> | null

Response

Endpoint connection created successfully

​
productId
string
required
Example:

"prod_123"

​
name
string
required
Example:

"My API Connection"

​
url
string
required
Example:

"https://api.example.com/v1/chat/completions"

​
httpMethod
enum<string>
required
Available options:
GET,
POST,
PUT,
PATCH,
DELETE
Example:

"POST"

​
authType
enum<string>
required
Available options:
NONE,
BEARER,
API_KEY,
BASIC
Example:

"BEARER"

​
inputTemplate
string | null
required

Jinja2/Nunjucks template for request body. Must contain {{ input.user_message }} placeholder.

Example:

"{\"prompt\": \"{{ input.user_message }}\"}"

​
outputMapping
object | null
required

JSONPath expressions to extract values from API response. Must include "output" key. Special keys: "retrieval_context", "session_id" (initialization), "traces", and "output_files". "output_files" matches one file or a list of files the endpoint answers with, each a data: URI, an http(s) URL, the storage URI of a Galtea file, or an object with "base64", "url" or "uri" plus optional "mime_type" and "filename". Each file is stored as a Galtea file on the turn output: at most 20 files and 20 MB per output, a type a judge can read (the file extension decides it), and a URL is downloaded once without the connection headers or credentials, over plain http only when the connection acknowledged it. A Galtea file is linked rather than copied, and must be an uploaded file of the product organization. A file that cannot be stored fails the turn. Every other key is stored on the session metadata.

Example:
​
id
string
Example:

"ec_123"

​
userId
string | null
Example:

"user_123"

​
hasAuthToken
boolean

Whether an auth token is configured (token value is not exposed)

​
username
string | null

Username for Basic auth

​
hasPassword
boolean

Whether a password is configured (password value is not exposed)

​
headers
object | null

Custom headers as key-value pairs. A secret value is encrypted at rest once its headers are saved, and every read returns it as "••••••••". A value is secret unless its name is Content-Type, Accept, Accept-Language, Accept-Encoding, Cache-Control, User-Agent, traceparent or tracestate, or it holds only placeholders (for example "Bearer {{ bearer_token }}"). On update, send "••••••••" to keep the stored value of that header name; any other value replaces it. Sending "••••••••" for a header with no stored value is a 400, and so is a value in the stored ciphertext shape or with a character a header cannot carry.

Example:
​
inputSchema
object | null

Optional JSON Schema (draft 2020-12) defining the structure of input fields, their types, and valid values. Must have type "object" with a "properties" key.

Example:
​
type
enum<string>
Available options:
INITIALIZATION,
CONVERSATION,
FINALIZATION
Example:

"CONVERSATION"

​
timeout
integer | null
default:15

Per-attempt request timeout in seconds. Unset applies the default (15). Capped server-side at 120 seconds.

Required range: 1 <= x <= 120
Example:

15

​
rateLimit
integer | null

Maximum requests per minute. Unset (null) means no rate limit.

Required range: x >= 1
Example:

60

​
retryEnabled
boolean
default:true

Whether automatic retry is enabled for failed requests

​
retryMaxAttempts
integer | null
default:1

Maximum number of retry attempts (applied when retryEnabled is true). 0 is only valid when retryEnabled is false; with retry enabled the minimum is 1.

Required range: 0 <= x <= 10
​
retryInitialDelayMs
integer | null
default:1000

Initial delay in milliseconds before first retry

Required range: x >= 0
​
retryBackoffStrategy
enum<string> | null
default:EXPONENTIAL

Strategy for increasing delay between retries

Available options:
FIXED,
EXPONENTIAL,
LINEAR
​
retryMaxDelayMs
integer | null
default:3000

Maximum delay between retry attempts, in milliseconds. Capped server-side at 60000 (60 seconds) to bound retry blast radius.

Required range: 0 <= x <= 60000
​
retryableStatusCodes
integer[]

HTTP status codes that should trigger a retry

Required range: 100 <= x <= 599
​
acknowledgedInsecureHttp
boolean
default:false

Required true to use an http:// URL. It records that the creator accepted that traffic to this endpoint is not encrypted, so anyone on the network path can read prompts, responses and credentials. The acceptance covers the connection, not one host: a redirect may send an acknowledged request to any public http:// host, carrying the connection credentials with it. Without it every hop the platform makes to the endpoint must stay on https. It is stored as false for an https:// URL, whatever the request sends.

​
conversationEndRules
object[]

Responses that mean the agent closed the conversation on its own. Only a CONVERSATION connection accepts rules. A rule matches a response with its status code and, when bodyMatch is set, a response body whose first JSONPath match equals the expected value as text. The rules are checked before the retry policy, and a matching response is never retried, even when its status code is in retryableStatusCodes. A matching 2xx response with an agent output keeps its turn as the last one, on any turn and in a single-turn test. A matching response with no agent output (a non-2xx response, or a 2xx response with no output) removes the rejected turn on a later turn of a scenario test. In both cases the session completes with the turns so far and is evaluated, with the stopping reason "The agent ended the conversation (HTTP )". A match with no agent output on the first turn, or on a single-turn test, still fails the session. An empty list keeps the default behaviour.

Maximum array length: 20
​
createdAt
string<date-time>
​
deletedAt
string<date-time> | null