curl --request POST \
--url https://app.egma.ai/v1/agents/{agentId}/connections \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"agentPlatform": "retell",
"connectionType": "retell_text_mode",
"accessVariant": "retell_text_mode.api_key",
"modality": "chat",
"platformAgentId": "agent_receptionist",
"credentials": {
"apiKey": "YOUR_RETELL_API_KEY"
}
}
'{
"connection": {
"id": "<string>",
"agentId": "<string>",
"projectId": "<string>",
"name": "<string>",
"agentPlatform": "retell",
"connectionType": "retell_chat_api",
"accessVariant": "retell_chat_api.api_key",
"modality": "voice",
"productLabel": "<string>",
"topology": "agent-dials-out",
"environment": "<string>",
"config": {},
"credentialPresent": true,
"credentialsHint": "<string>",
"archived": true,
"archivedAt": "2023-11-07T05:31:56Z",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}
}{
"error": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"message": "<string>",
"details": {}
}Add an agent connection
Add a simulation connection to an agent. Use the connection catalog for required fields, Retell discovery for platformAgentId, or your LiveKit worker’s dispatch name for config.agentName.
curl --request POST \
--url https://app.egma.ai/v1/agents/{agentId}/connections \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"agentPlatform": "retell",
"connectionType": "retell_text_mode",
"accessVariant": "retell_text_mode.api_key",
"modality": "chat",
"platformAgentId": "agent_receptionist",
"credentials": {
"apiKey": "YOUR_RETELL_API_KEY"
}
}
'{
"connection": {
"id": "<string>",
"agentId": "<string>",
"projectId": "<string>",
"name": "<string>",
"agentPlatform": "retell",
"connectionType": "retell_chat_api",
"accessVariant": "retell_chat_api.api_key",
"modality": "voice",
"productLabel": "<string>",
"topology": "agent-dials-out",
"environment": "<string>",
"config": {},
"credentialPresent": true,
"credentialsHint": "<string>",
"archived": true,
"archivedAt": "2023-11-07T05:31:56Z",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z"
}
}{
"error": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"message": "<string>",
"details": {}
}{
"error": "<string>",
"message": "<string>",
"details": {}
}Authorizations
An Egma API key.
Path Parameters
The Egma agent ID returned by Register an agent or List agents.
1"agt_01M0E4J0BBE1FVDVTZ1BSS5C97"
Query Parameters
Project to act in. A project-scoped API key already identifies its project.
1Body
Choose one supported agentPlatform, connectionType, accessVariant, and modality from List supported connection options. Its fields describe config and its credentialFields describe credentials. Egma validates the complete combination before saving it.
The platform that runs the agent. It must be compatible with the selected connection type and agent.
retell, livekit Connection type from the options catalog. Retell text mode tests a voice agent through chat; a Retell web call uses voice. LiveKit room connections can use voice or chat.
retell_text_mode, retell_web_call, phone_number, livekit_room Credential method for the connection type, copied from the same catalog entry.
retell_text_mode.api_key, retell_web_call.api_key, phone_number.public_e164, livekit_room.project_credentials, livekit_room.customer_token_endpoint How simulations communicate with the agent. Use a modality offered by the selected catalog entry.
voice, chat Optional connection display name. If omitted, Egma chooses the next available numbered name.
"Staging voice"
Optional label identifying the environment this connection reaches.
"staging"
Non-secret settings for the selected access variant. Use only its catalog fields. Retell API variants use retellAgentId; a Retell phone connection uses phoneNumber. LiveKit project credentials use url and agentName. LiveKit token endpoints use tokenEndpoint and agentName; tokenEndpoint must be a public HTTPS URL. agentName must match the name registered by your LiveKit worker. When platformAgentId is supplied for a Retell API variant, Egma derives and confirms retellAgentId from that selection.
{ "retellAgentId": "agent_receptionist" }
{
"url": "wss://example.livekit.cloud",
"agentName": "receptionist"
}
{
"tokenEndpoint": "https://voice.example.com/egma/token",
"agentName": "receptionist"
}
Secret fields for the selected access variant. Retell uses apiKey. LiveKit project credentials use apiKey and apiSecret. A LiveKit token endpoint requires headers: a JSON-encoded string containing a non-empty object of header names to string values. For an additional Retell connection, platformAgentId can reuse the agent's saved Retell key when credentials are omitted. For a Retell phone connection, the key confirms provider identity and is held on the agent; the phone connection itself stores no key. Responses return credential presence and hints, never the secret values.
{ "apiKey": "YOUR_RETELL_API_KEY" }
{
"apiKey": "YOUR_LIVEKIT_API_KEY",
"apiSecret": "YOUR_LIVEKIT_API_SECRET"
}
{
"headers": "{\"Authorization\":\"Bearer YOUR_ENDPOINT_TOKEN\"}"
}
Retell's agent ID from Discover agents, not an Egma agent ID. Supply it with the selected candidate to confirm the provider agent and save its identity on the Egma agent. Required for Retell phone connections. Egma uses credentials.apiKey or the key already saved on that agent. A different Retell identity on the same Egma agent is refused. Do not send this together with agentPlatformSelection.
"agent_receptionist"
Start pulling this agent's production calls with the same save. Off unless the request says otherwise; the first switch-on imports the fixed 30-day history.
Superseded by platformAgentId beside credentials, and still accepted. Egma revalidates the selected provider agent and route during creation, then discards this object.
Show child attributes
Show child attributes
Response
The new connection.
Show child attributes
Show child attributes