Register and Manage Voice Agents with the Egma API

Agents are the voice-agent identities Egma tests and monitors. Each agent you register maps to one agent in your provider — Retell or LiveKit — and carries one or more connections that tell Egma how to reach it. Registering is retry-safe: if you send the same agent name and provider id twice, Egma reuses the existing agent and tells you so in the result field rather than minting a second identity. Credentials you supply are sealed before storage; only the last four characters come back in credentials_hint, so a serializer can never accidentally leak a key.

Register an agent

POST /api/agents Register a new agent and, optionally, attach the first connection to it in the same request. Both the agent row and the connection row are written in one transaction, so a connection payload the registry rejects leaves no partial agent behind. The result field in the response tells you exactly what happened:

Value	Meaning
`created`	A new agent and a new connection were written.
`reused`	An agent with this provider id already existed; nothing was written.
`connection_added`	The agent already existed; a new connection was attached to it.

201 Created is returned for created and connection_added. 200 OK is returned for reused.

Request body

string

Display name for the agent. Required unless you want Egma to pick a numbered default. Must be unique within the project.

string

Optional free-text description.

string

Project id or name to write this agent into. Defaults to the project your API key belongs to. In a single-project organization you never need this field.

object

The first connection to attach. Leave this out to register a bare agent and add connections later with POST /api/agents/:agentId/connections.

Show connection fields

string

required

Connection type. One of retell or livekit.

string

required

Always voice for the currently supported modalities.

string

Display name for this connection. Defaults to a numbered name if omitted.

string

Optional environment label, e.g. staging or production.

object

required

Provider-specific configuration.Retell — { "agentId": "<retell_agent_id>" }LiveKit — { "url": "<livekit_server_url>", "agentName": "<optional>", "metadata": "<optional>" }

object

Provider credentials. Sealed before storage; never returned in full.Retell — { "apiKey": "<retell_api_key>" }LiveKit — { "apiKey": "<livekit_api_key>", "apiSecret": "<livekit_api_secret>" }

Response fields

string

One of created, reused, or connection_added.

object

The agent record.

Show agent fields

string

Unique agent identifier (agt_…).

string

The project this agent belongs to.

string

Display name.

string | null

Free-text description, or null.

string

ISO 8601 timestamp.

string

ISO 8601 timestamp.

object

The connection that was created or reused. Absent when result is reused and no new connection was written.

Show connection fields

string

Unique connection identifier.

string

The agent this connection belongs to.

string

The project this connection belongs to.

string

Display name.

string

Provider type: retell or livekit.

string

Always voice.

string

Derived from the type; indicates who initiates the call.

string | null

Environment label, or null.

object

Provider-specific configuration (opaque keys vary by type).

string

Last four characters of the sealed credential. Use this to confirm a rotation landed.

object

Provider capabilities detected at registration time.

string

ISO 8601 timestamp.

string

ISO 8601 timestamp.

Example — register a Retell agent

curl -X POST https://your-egma-host/api/agents \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "front-desk",
    "connection": {
      "type": "retell",
      "modality": "voice",
      "config": { "agentId": "retell_agent_abc123" },
      "credentials": { "apiKey": "retell_sk_…" }
    }
  }'

Example — register a LiveKit agent

curl -X POST https://your-egma-host/api/agents \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support-bot",
    "connection": {
      "type": "livekit",
      "modality": "voice",
      "config": {
        "url": "wss://my-livekit.example.com",
        "agentName": "support-agent"
      },
      "credentials": {
        "apiKey": "livekit_api_key",
        "apiSecret": "livekit_api_secret"
      }
    }
  }'

List agents

GET /api/agents Return a paginated list of agents your credential can reach, ordered newest first. Filter by project with ?project. Paginate using the next_cursor value from the previous page.

Query parameters

string

Filter to a specific project by id or name. Omit to list agents across all projects your key can read.

string

The next_cursor value from the previous page. Omit to start from the newest agent.

Response fields

array

Array of agent objects. Each has the same shape as the agent field in the registration response.

string | null

Pass this as ?cursor to fetch the next page. null means you are on the last page.

Example

curl "https://your-egma-host/api/agents?project=my-project&cursor=agt_prev" \
  -H "Authorization: Bearer <api-key>"

Get an agent

GET /api/agents/:agentId Retrieve a single agent and all of its connections. An agent you cannot see answers the same not_found sentence as an id that was never minted.

Path parameters

string

required

The agt_… identifier of the agent.

Response fields

object

The agent record (same shape as in registration).

array

All connections currently attached to this agent. Each entry has the same shape as the connection field in the registration response.

Example

curl "https://your-egma-host/api/agents/agt_01abc" \
  -H "Authorization: Bearer <api-key>"

Add a connection

POST /api/agents/:agentId/connections Attach another provider connection to an existing agent. The request body is identical in shape to the connection object on registration. Returns 201 Created with the new connection.

Path parameters

string

required

The agt_… identifier of the agent to attach the connection to.

Request body

Same fields as the connection object on POST /api/agents. All fields (type, modality, config, credentials, etc.) apply identically.

Response fields

object

The newly created connection record (same shape as the connection field in the registration response).

Example

curl -X POST "https://your-egma-host/api/agents/agt_01abc/connections" \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "retell",
    "modality": "voice",
    "environment": "staging",
    "config": { "agentId": "retell_agent_staging_xyz" },
    "credentials": { "apiKey": "retell_sk_staging_…" }
  }'

Overview

Agents & Tests

Graders

Telemetry

Account

Register and Manage Voice Agents with the Egma API

Register an agent

Request body

Response fields

Example — register a Retell agent

Example — register a LiveKit agent

List agents

Query parameters

Response fields

Example

Get an agent

Path parameters

Response fields

Example

Add a connection

Path parameters

Request body

Response fields

Example

​Register an agent

​Request body

​Response fields

​Example — register a Retell agent

​Example — register a LiveKit agent

​List agents

​Query parameters

​Response fields

​Example

​Get an agent

​Path parameters

​Response fields

​Example

​Add a connection

​Path parameters

​Request body

​Response fields

​Example

Register an agent

Request body

Response fields

Example — register a Retell agent

Example — register a LiveKit agent

List agents

Query parameters

Response fields

Example

Get an agent

Path parameters

Response fields

Example

Add a connection

Path parameters

Request body

Response fields

Example