> ## 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.

# Register an agent

> Register an agent in your project, with an optional first connection. An existing provider identity can be reused. Check result to see whether Egma created an agent, added a connection, or reused one.



## OpenAPI

````yaml openapi.json POST /v1/agents
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:
    post:
      tags:
        - Agents
      summary: Register an agent
      description: >-
        Register an agent in your project, with an optional first connection. An
        existing provider identity can be reused. Check result to see whether
        Egma created an agent, added a connection, or reused one.
      operationId: registerAgent
      parameters:
        - 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
              properties:
                name:
                  type: string
                  description: Display name for the agent in Egma.
                  examples:
                    - Receptionist
                agentPlatform:
                  type: string
                  enum:
                    - retell
                    - livekit
                  description: The product or framework that runs your agent.
                connection:
                  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"}'
              required:
                - name
                - agentPlatform
              additionalProperties: false
              examples:
                - name: Receptionist
                  agentPlatform: retell
                - name: Receptionist
                  agentPlatform: livekit
                  connection:
                    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
      responses:
        '200':
          description: An existing agent reused by the registration.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    enum:
                      - reused
                  agent:
                    type: object
                    properties:
                      id:
                        type: string
                        minLength: 1
                      projectId:
                        type: string
                        minLength: 1
                      name:
                        type: string
                      agentPlatform:
                        type: string
                        enum:
                          - retell
                          - livekit
                      platformAgentId:
                        anyOf:
                          - type: string
                          - type: 'null'
                      retellModality:
                        anyOf:
                          - type: string
                            enum:
                              - voice
                              - chat
                          - type: 'null'
                      monitoringKeyPresent:
                        type: boolean
                      monitoringApiKeyHint:
                        anyOf:
                          - type: string
                          - type: 'null'
                      pullProductionCalls:
                        type: boolean
                      monitoringConfigured:
                        type: boolean
                      lastReceivedAt:
                        anyOf:
                          - type: string
                            format: date-time
                          - 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
                      - projectId
                      - name
                      - agentPlatform
                      - platformAgentId
                      - retellModality
                      - monitoringKeyPresent
                      - monitoringApiKeyHint
                      - pullProductionCalls
                      - monitoringConfigured
                      - lastReceivedAt
                      - archived
                      - archivedAt
                      - createdAt
                      - updatedAt
                    additionalProperties: false
                  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:
                  - result
                  - agent
                  - connection
                additionalProperties: false
        '201':
          description: An agent or connection created by the registration.
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: string
                    enum:
                      - created
                      - connection_added
                  agent:
                    type: object
                    properties:
                      id:
                        type: string
                        minLength: 1
                      projectId:
                        type: string
                        minLength: 1
                      name:
                        type: string
                      agentPlatform:
                        type: string
                        enum:
                          - retell
                          - livekit
                      platformAgentId:
                        anyOf:
                          - type: string
                          - type: 'null'
                      retellModality:
                        anyOf:
                          - type: string
                            enum:
                              - voice
                              - chat
                          - type: 'null'
                      monitoringKeyPresent:
                        type: boolean
                      monitoringApiKeyHint:
                        anyOf:
                          - type: string
                          - type: 'null'
                      pullProductionCalls:
                        type: boolean
                      monitoringConfigured:
                        type: boolean
                      lastReceivedAt:
                        anyOf:
                          - type: string
                            format: date-time
                          - 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
                      - projectId
                      - name
                      - agentPlatform
                      - platformAgentId
                      - retellModality
                      - monitoringKeyPresent
                      - monitoringApiKeyHint
                      - pullProductionCalls
                      - monitoringConfigured
                      - lastReceivedAt
                      - archived
                      - archivedAt
                      - createdAt
                      - updatedAt
                    additionalProperties: false
                  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:
                  - result
                  - agent
                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.

````