Create AI Connection

POSThttps://api.confident-ai.com/v1/ai-connections

Registers your LLM application's endpoint as an AI connection and returns its id. The endpoint is called once to determine whether the connection is active, which you read back from the single-connection route. Requires the Starter plan or above.

POST/v1/ai-connections

curl -X POST "https://api.confident-ai.com/v1/ai-connections" \
  -H "CONFIDENT_API_KEY: <PROJECT-API-KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Production Chatbot",
  "endpoint": "https://api.example.com/chat",
  "payload": {
    "query": "{{input}}"
  },
  "headers": [
    {
      "key": "Authorization",
      "value": "Bearer YOUR-TOKEN"
    },
    {
      "key": "Content-Type",
      "value": "application/json"
    }
  ],
  "actualOutputKeyPath": [
    "choices",
    0,
    "message",
    "content"
  ]
}'

200

{
  "success": true,
  "data": {
    "id": "AI-CONNECTION-ID"
  },
  "deprecated": false
}

Headers

CONFIDENT_API_KEYstringRequired
The API key of your Confident AI project.

Request body

namestringRequired
Unique within the project.
typeenum
How Confident AI reaches your application. AGENT_HANDLER needs no endpoint.
Show 3 enum valuesHide 3 enum values
- ENDPOINT
- RELAY_ENDPOINT
- AGENT_HANDLER
endpointstring
The https:// URL Confident AI calls — wss:// when responseMode is WEBSOCKET.
responseModeenum
How your endpoint replies. Streaming modes read the answer from an event stream rather than a completed body.
Show 4 enum valuesHide 4 enum values
- HTTP_RESPONSE
- SSE_STREAMING
- HTTP_STREAMING
- WEBSOCKET
asyncResponseboolean
Your endpoint acknowledges the request and posts results back later. Requires a responseMode of HTTP_RESPONSE.
timeoutinteger
Seconds to wait for a response. Defaults to 60.
maxConcurrencyinteger
Most simultaneous requests Confident AI will make.
maxRetriesinteger
Retries per failed request.
defaultNumGenerationsinteger
How many times to call the endpoint per test case, so one unlucky output doesn't skew results.
headerslist of objects
Full replacement of the header list — include every header the connection should keep.
Show 2 propertiesHide 2 properties
- keystringRequired
  The header or parameter name.
- valuestringRequired
  The value. Read back masked unless the key is a common protocol header such as Content-Type.
queryParamslist of objects
Full replacement of the query-parameter list.
Show 2 propertiesHide 2 properties
- keystringRequired
  The header or parameter name.
- valuestringRequired
  The value. Read back masked unless the key is a common protocol header such as Content-Type.
payloadobject
The request body template sent to your endpoint.
hyperparametersobject
Recorded against every test run that uses this connection.
authenticationobject
Auth configuration (Auth0, HMAC, or Azure AD). Secret values are read back masked.
cloudProviderobject
Vault configuration for pulling credentials at call time.
actualOutputKeyPathlist of string | integer
Where your application's answer lives in the response. A connection needs this (or a transformer) to be usable.
Show 2 variantsHide 2 variants
- string
- OR
- integer
retrievalContextKeyPathlist of string | integer
Where the retrieved context lives, for RAG applications.
Show 2 variantsHide 2 variants
- string
- OR
- integer
toolsCalledKeyPathlist of string | integer
Where the list of called tools lives, for agents.
Show 2 variantsHide 2 variants
- string
- OR
- integer
stateKeyPathlist of string | integer
Where multi-turn state lives, carried between simulated turns.
Show 2 variantsHide 2 variants
- string
- OR
- integer
actualOutputTransformerIdstring
Extract the output by running a transformer instead of walking a key path. Send this or actualOutputKeyPath, never both.
retrievalContextTransformerIdstring
As above, for the retrieved context.
toolsCalledTransformerIdstring
As above, for the called tools.
stateTransformerIdstring
As above, for multi-turn state.
actualOutputEventstring
Streaming modes only — which event carries the output.
retrievalContextEventstring
Streaming modes only — which event carries the retrieved context.
toolsCalledEventstring
Streaming modes only — which event carries the called tools.
stateEventstring
Streaming modes only — which event carries the state.
actualOutputAccumulateboolean
Streaming modes only — concatenate the streamed chunks rather than taking the last one.

Response

The id of the created AI connection.

successboolean
Indicates if the request was successful.
dataobject
The id of the affected AI connection.
Show 1 propertyHide 1 property
- idstring
  The id of the affected AI connection.
deprecatedboolean
Indicates if this endpoint is deprecated.

Built byConfident AI