Agents

Configure and list the real-time Conversational AI personas powering call automation workflows.

List Agents

Retrieve a list of all configured Voice Agents in the active workspace.

<div class="endpoint-path">
  <span class="badge badge-get">GET</span>
  <code>/v1/agents</code>
</div>

<h3>Authorizations</h3>
<div class="param-row">
  <div class="param-name">X-API-Key</div>
  <div class="param-badges">
    <span class="badge-type">string</span>
    <span class="badge-loc">header</span>
    <span class="badge-req">required</span>
  </div>
  <div class="param-desc">Voice Platform authentication secret token key.</div>
</div>

<h3>Response</h3>
<span class="response-status-info">200 - application/json</span>

<div class="param-row">
  <div class="param-name">id</div>
  <div class="param-badges">
    <span class="badge-type">string</span>
    <span class="badge-req">required</span>
  </div>
  <div class="param-desc">Unique identifier of the agent.</div>
</div>

<div class="param-row">
  <div class="param-name">name</div>
  <div class="param-badges">
    <span class="badge-type">string</span>
    <span class="badge-req">required</span>
  </div>
  <div class="param-desc">Display name of the agent.</div>
</div>

<div class="param-row">
  <div class="param-name">model</div>
  <div class="param-badges">
    <span class="badge-type">string</span>
    <span class="badge-req">required</span>
  </div>
  <div class="param-desc">LLM model used (e.g. <code>gpt-4o-realtime-preview</code>).</div>
</div>

curl --request GET \
  --url https://api.branofy.cloud/v1/agents \
  --header 'X-API-Key: your_voice_api_secret_key'

<div class="response-preview">
  <div class="response-header">
    <span>Response</span>
    <span class="status-200">200 OK</span>
  </div>

{
  "data": [
    {
      "id": "agent_12345",
      "name": "Customer Support Agent",
      "callingProvider": "local_voice",
      "firstMessage": "Hello, how can I help you today?",
      "language": "en",
      "model": "gpt-4o-realtime-preview",
      "status": "active",
      "temperature": 70,
      "toolIds": ["tool_abc123"],
      "ttsVoice": "af_heart",
      "voiceId": "alloy",
      "updatedAt": "2026-06-21T10:00:00Z"
    }
  ]
}

</div>

Create Agent

Configure a new conversational voice agent with specific persona instructions, synthetic voices, and API tools.

<div class="endpoint-path">
  <span class="badge badge-post">POST</span>
  <code>/v1/agents</code>
</div>

<h3>Request Body</h3>
<div class="param-row">
  <div class="param-name">name</div>
  <div class="param-badges">
    <span class="badge-type">string</span>
    <span class="badge-req">required</span>
  </div>
  <div class="param-desc">Display name for the agent setup.</div>
</div>

<div class="param-row">
  <div class="param-name">systemPrompt</div>
  <div class="param-badges">
    <span class="badge-type">string</span>
    <span class="badge-req">required</span>
  </div>
  <div class="param-desc">The core persona behavior directive guidelines.</div>
</div>

<div class="param-row">
  <div class="param-name">voiceId</div>
  <div class="param-badges">
    <span class="badge-type">string</span>
    <span class="badge-opt">optional</span>
  </div>
  <div class="param-desc">The voice sound profile (e.g. <code>alloy</code>).</div>
</div>

curl --request POST \
  --url https://api.branofy.cloud/v1/agents \
  --header 'X-API-Key: your_voice_api_secret_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Billing Agent",
    "callingProvider": "local_voice",
    "firstMessage": "Hello, am I speaking with the customer?",
    "language": "en",
    "model": "gpt-4o-realtime-preview",
    "systemPrompt": "You are a billing representative.",
    "temperature": 70,
    "toolIds": [],
    "ttsVoice": "af_heart",
    "voiceId": "alloy"
  }'

<div class="response-preview">
  <div class="response-header">
    <span>Response</span>
    <span class="status-201">201 Created</span>
  </div>

{
  "id": "agent_67890",
  "name": "Billing Agent",
  "callingProvider": "local_voice",
  "firstMessage": "Hello, am I speaking with the customer?",
  "language": "en",
  "model": "gpt-4o-realtime-preview",
  "status": "active",
  "temperature": 70,
  "toolIds": [],
  "ttsVoice": "af_heart",
  "voiceId": "alloy",
  "updatedAt": "2026-06-21T16:11:00Z"
}

</div>