Create AI Connection

Headers

• CONFIDENT_API_KEYstringRequired

  The API key of your Confident AI project.

Request body

• namestringRequired

  The name of the AI connection, unique within the project.

• typeenum

  How Confident AI reaches your LLM application: ENDPOINT calls the endpoint you registered, RELAY_ENDPOINT calls it through the Confident AI relay so it never leaves your network boundary, and AGENT_HANDLER expects your own runner to pull work rather than being called, so it needs no endpoint. Defaults to ENDPOINT.

  Show 3 enum valuesHide 3 enum values

  • ENDPOINT
  • RELAY_ENDPOINT
  • AGENT_HANDLER

• endpointstring | null

  The https:// URL Confident AI calls to reach your LLM application, or a wss:// URL when responseMode is WEBSOCKET. An AGENT_HANDLER connection needs none. Send null to clear it.

• responseModeenum | null

  How your application replies. HTTP_RESPONSE returns one completed body. SSE_STREAMING, HTTP_STREAMING and WEBSOCKET stream the answer, so the values are read from named events as they arrive rather than out of a finished body, and WEBSOCKET requires a wss:// endpoint. PHONE and SIP are voice connections placed over a telephony provider.

  Show 7 enum valuesHide 7 enum values

  • HTTP_RESPONSE
  • SSE_STREAMING
  • HTTP_STREAMING
  • WEBSOCKET
  • PHONE
  • SIP
  • WEBRTC

• asyncResponseboolean

  Whether your application acknowledges the request and posts the result back later instead of answering inline. Only a non-streaming responseMode supports this.

• timeoutinteger | null

  How many seconds to wait for your application to answer before giving up on a request. Defaults to 60 when the connection is created. Send null to clear it.

• maxConcurrencyinteger | null

  The most requests Confident AI sends to your application at the same time. Send null to leave it unbounded.

• maxRetriesinteger | null

  How many times a failed request is retried before the test case is recorded as errored. Send null to clear it.

• defaultNumGenerationsinteger

  How many times your application is called per test case, so one unlucky output does not decide the result. At most 50.

• headersarray | null

  The headers sent with every request. The list replaces the stored headers rather than merging into them, so include every header the connection should keep. Send null to clear them.

  Show 2 propertiesHide 2 properties

  • keystringRequired

    The header or query parameter name.

  • valuestringRequired

    The value sent under this name on every request. It is stored as sent and read back as stored.

• queryParamsarray | null

  The query parameters appended to every request. The list replaces the stored parameters rather than merging into them. Send null to clear them.

  Show 2 propertiesHide 2 properties

  • keystringRequired

    The header or query parameter name.

  • valuestringRequired

    The value sent under this name on every request. It is stored as sent and read back as stored.

• payloadobject | null

  The request body template Confident AI sends. Placeholders such as {{input}} are filled from the test case, and any key in prompts is filled with that prompt's text. Send null to clear it.

• hyperparametersobject | null

  Free-form settings recorded against every test run made through this connection, so results can be compared across configurations. They are not sent to your application. Send null to clear them.

• authenticationobject | null

  The authentication configuration Confident AI applies when calling your application. Set authType to AUTH0, HMAC, AZURE_AD, OAUTH2_CLIENT_CREDENTIALS or LIVEKIT and put that scheme's settings in the matching object: auth0Config, hmacConfig, azureAdConfig, oauth2Config or livekitConfig. A value that does not match that shape is rejected. Send null to clear it.

• cloudProviderobject | null

  The cloud vault configuration Confident AI uses to pull credentials at call time instead of holding them itself. Set enabled, provider to AZURE_KEY_VAULT, vaultUrl to your vault, and azureCredentials with the tenantId, clientId and clientSecret used to read from it. A value that does not match that shape is rejected. Send null to clear it.

• actualOutputKeyPatharray | null

  Where your application's answer sits in its response. Each element is an object key or an array index, walked in order, so ["choices", 0, "message", "content"] reads choices[0].message.content. A connection needs this or actualOutputTransformerId before it can be used. Send null or an empty list to clear it.

  Show 2 variantsHide 2 variants

  • string

  • OR

  • integer

• retrievalContextKeyPatharray | null

  Where the retrieved context sits in your application's response, walked the same way as actualOutputKeyPath. Set it for RAG applications so retrieval metrics have something to score. Send null or an empty list to clear it.

  Show 2 variantsHide 2 variants

  • string

  • OR

  • integer

• toolsCalledKeyPatharray | null

  Where the list of tools your application called sits in its response, walked the same way as actualOutputKeyPath. Set it for agents so tool-use metrics have something to score. Send null or an empty list to clear it.

  Show 2 variantsHide 2 variants

  • string

  • OR

  • integer

• stateKeyPatharray | null

  Where the conversation state sits in your application's response, walked the same way as actualOutputKeyPath. Confident AI reads it after each simulated turn and sends it back on the next one. Send null or an empty list to clear it.

  Show 2 variantsHide 2 variants

  • string

  • OR

  • integer

• inputTokenCountKeyPatharray | null

  Where the prompt token count sits in your application's response, walked the same way as actualOutputKeyPath. Send null or an empty list to clear it.

  Show 2 variantsHide 2 variants

  • string

  • OR

  • integer

• outputTokenCountKeyPatharray | null

  Where the completion token count sits in your application's response, walked the same way as actualOutputKeyPath. Send null or an empty list to clear it.

  Show 2 variantsHide 2 variants

  • string

  • OR

  • integer

• tokenCostKeyPatharray | null

  Where the cost of the call sits in your application's response, walked the same way as actualOutputKeyPath. Send null or an empty list to clear it.

  Show 2 variantsHide 2 variants

  • string

  • OR

  • integer

• actualOutputEventstring | null

  For a streaming responseMode, the name of the event carrying your application's answer. Confident AI reads the value out of the events with this name instead of out of a completed body, applying actualOutputKeyPath to each one. Send null to clear it.

• retrievalContextEventstring | null

  For a streaming responseMode, the name of the event carrying the retrieved context, read the same way as actualOutputEvent. Send null to clear it.

• toolsCalledEventstring | null

  For a streaming responseMode, the name of the event carrying the tools called, read the same way as actualOutputEvent. Send null to clear it.

• stateEventstring | null

  For a streaming responseMode, the name of the event carrying the conversation state, read the same way as actualOutputEvent. Send null to clear it.

• actualOutputAccumulateboolean

  For a streaming responseMode, whether the chunks arriving on actualOutputEvent are joined into one answer. Set it to false when each event already carries the whole answer and only the last one counts.

• actualOutputTransformerIdstring | null

  The id of a transformer that extracts the answer by running your code over the response, for shapes a key path cannot reach. Send this or actualOutputKeyPath, never both. The transformer must belong to this project. Send null to clear it.

• retrievalContextTransformerIdstring | null

  The id of a transformer that extracts the retrieved context. Send this or retrievalContextKeyPath, never both. Send null to clear it.

• toolsCalledTransformerIdstring | null

  The id of a transformer that extracts the tools called. Send this or toolsCalledKeyPath, never both. Send null to clear it.

• stateTransformerIdstring | null

  The id of a transformer that extracts the conversation state. Send this or stateKeyPath, never both. Send null to clear it.

• inputTokenCountTransformerIdstring | null

  The id of a transformer that extracts the prompt token count. Send this or inputTokenCountKeyPath, never both. Send null to clear it.

• outputTokenCountTransformerIdstring | null

  The id of a transformer that extracts the completion token count. Send this or outputTokenCountKeyPath, never both. Send null to clear it.

• tokenCostTransformerIdstring | null

  The id of a transformer that extracts the cost of the call. Send this or tokenCostKeyPath, never both. Send null to clear it.

• promptsobject | null

  The prompts to substitute into the request body, keyed by the placeholder they fill in payload. The map replaces the connection's current prompts rather than merging into them.

Response

Create AI Connection succeeded.

• successboolean

  Indicates if the request was successful.

• dataobject

  A reference to an AI connection by its id.

  Show 1 propertyHide 1 property

  • idstring

    The id of the AI connection, generated by Confident AI.

• linkstring

  This is the URL of the resource on the Confident AI platform.

• deprecatedboolean

  Indicates if this endpoint is deprecated.