> ## Documentation Index > Fetch the complete documentation index at: https://docs.egma.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml openapi.json POST /v1/agents/{agentId}/connections openapi: 3.1.0 info: title: Egma Platform API version: 1.0.0 description: >- The customer-facing HTTP interface used by Egma's web app, CLI, and outside clients. servers: - url: https://app.egma.ai security: [] paths: /v1/agents/{agentId}/connections: post: tags: - Connections summary: Add an agent connection description: >- 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. operationId: addConnection parameters: - name: agentId in: path required: true schema: type: string minLength: 1 description: The Egma agent ID returned by Register an agent or List agents. examples: - agt_01M0E4J0BBE1FVDVTZ1BSS5C97 - name: projectId in: query required: false schema: type: string minLength: 1 description: >- Project to act in. A project-scoped API key already identifies its project. requestBody: required: true content: application/json: schema: type: object description: >- 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. properties: name: type: string description: >- Optional connection display name. If omitted, Egma chooses the next available numbered name. examples: - Staging voice agentPlatform: anyOf: - type: string enum: - retell - livekit description: >- The platform that runs the agent. It must be compatible with the selected connection type and agent. - type: 'null' connectionType: type: string description: >- 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. enum: - retell_text_mode - retell_web_call - phone_number - livekit_room accessVariant: type: string description: >- Credential method for the connection type, copied from the same catalog entry. enum: - retell_text_mode.api_key - retell_web_call.api_key - phone_number.public_e164 - livekit_room.project_credentials - livekit_room.customer_token_endpoint modality: type: string enum: - voice - chat description: >- How simulations communicate with the agent. Use a modality offered by the selected catalog entry. environment: type: string description: >- Optional label identifying the environment this connection reaches. examples: - staging config: type: object additionalProperties: true description: >- 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. examples: - retellAgentId: agent_receptionist - url: wss://example.livekit.cloud agentName: receptionist - tokenEndpoint: https://voice.example.com/egma/token agentName: receptionist credentials: type: object additionalProperties: true description: >- 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. examples: - apiKey: YOUR_RETELL_API_KEY - apiKey: YOUR_LIVEKIT_API_KEY apiSecret: YOUR_LIVEKIT_API_SECRET - headers: '{"Authorization":"Bearer YOUR_ENDPOINT_TOKEN"}' platformAgentId: type: string description: >- 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. examples: - agent_receptionist pullProductionCalls: type: boolean description: >- 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. agentPlatformSelection: type: object description: >- Superseded by platformAgentId beside credentials, and still accepted. Egma revalidates the selected provider agent and route during creation, then discards this object. properties: platformAgentId: type: string credentials: type: object properties: apiKey: type: string required: - apiKey additionalProperties: false required: - platformAgentId - credentials additionalProperties: false required: - agentPlatform - connectionType - accessVariant - modality additionalProperties: false examples: - name: Retell chat agentPlatform: retell connectionType: retell_text_mode accessVariant: retell_text_mode.api_key modality: chat platformAgentId: agent_receptionist config: retellAgentId: agent_receptionist credentials: apiKey: YOUR_RETELL_API_KEY - name: LiveKit voice agentPlatform: livekit connectionType: livekit_room accessVariant: livekit_room.project_credentials modality: voice config: url: wss://example.livekit.cloud agentName: receptionist credentials: apiKey: YOUR_LIVEKIT_API_KEY apiSecret: YOUR_LIVEKIT_API_SECRET - name: LiveKit token endpoint agentPlatform: livekit connectionType: livekit_room accessVariant: livekit_room.customer_token_endpoint modality: voice config: tokenEndpoint: https://voice.example.com/egma/token agentName: receptionist credentials: headers: '{"Authorization":"Bearer YOUR_ENDPOINT_TOKEN"}' responses: '201': description: The new connection. content: application/json: schema: type: object properties: connection: type: object properties: id: type: string minLength: 1 agentId: type: string minLength: 1 projectId: type: string minLength: 1 name: type: string agentPlatform: type: string enum: - retell - livekit connectionType: type: string enum: - retell_chat_api - retell_text_mode - retell_web_call - phone_number - livekit_room accessVariant: type: string enum: - retell_chat_api.api_key - retell_text_mode.api_key - retell_web_call.api_key - phone_number.public_e164 - livekit_room.project_credentials - livekit_room.customer_token_endpoint modality: type: string enum: - voice - chat productLabel: type: string topology: type: string enum: - agent-dials-out - hosted-broker - egma-dials-in environment: anyOf: - type: string - type: 'null' config: type: object additionalProperties: type: string credentialPresent: type: boolean credentialsHint: anyOf: - type: string - type: 'null' archived: type: boolean archivedAt: anyOf: - type: string format: date-time - type: 'null' createdAt: type: string format: date-time updatedAt: type: string format: date-time required: - id - agentId - projectId - name - agentPlatform - connectionType - accessVariant - modality - productLabel - topology - environment - config - credentialPresent - credentialsHint - archived - archivedAt - createdAt - updatedAt additionalProperties: false required: - connection additionalProperties: false '400': description: The request was refused. content: application/json: schema: $ref: '#/components/schemas/Refusal' '401': description: The request was refused. content: application/json: schema: $ref: '#/components/schemas/Refusal' '403': description: The request was refused. content: application/json: schema: $ref: '#/components/schemas/Refusal' '404': description: The request was refused. content: application/json: schema: $ref: '#/components/schemas/Refusal' '409': description: The request was refused. content: application/json: schema: $ref: '#/components/schemas/Refusal' '422': description: The request was refused. content: application/json: schema: $ref: '#/components/schemas/Refusal' '429': description: The request rate limit was reached. headers: Retry-After: description: Seconds to wait before trying again. schema: type: integer minimum: 1 content: application/json: schema: $ref: '#/components/schemas/Refusal' '503': description: The request was refused. content: application/json: schema: $ref: '#/components/schemas/Refusal' security: - bearerAuth: [] - sessionCookie: [] components: schemas: Refusal: type: object properties: error: type: string message: type: string details: type: object additionalProperties: true required: - error - message additionalProperties: false securitySchemes: bearerAuth: type: http scheme: bearer description: An Egma API key. sessionCookie: type: apiKey in: cookie name: egma.session_token description: >- The browser session cookie issued by Egma. HTTPS deployments add the standard __Secure- prefix. ````