---
title: 'Create Call Agent'
api: 'POST /v1/api/agents'
description: 'Create a new agent for a workspace.'
---

> **For AI agents:** the complete documentation index is at [llms.txt](/llms.txt). Append `.md` to any page URL for its markdown version.

## Headers
<ParamField header="x-workspace-id" type="string" required>
Workspace identifier for the API.
</ParamField>

## Request Body

<ParamField body="name" type="string" required>
Name of the agent being created.
</ParamField>

<ParamField body="ttsModel" type="object" required>
Text-to-Speech (TTS) configuration for the agent.

<Expandable title="properties">

<ParamField body="provider" type="string" required>
TTS provider. Must be one of the following: openai, rime, elevenlabs, 11labs_byo, google.
</ParamField>

<ParamField body="voiceId" type="string" required>
The voice ID used for generating speech. e.g for Trillet Voices,
"mistv2_Wildflower" - Alt Female, Smart
"mistv2_Brook" - Male, Friendly
"mistv2_Violet" - Female, Professional
</ParamField>


<ParamField body="language" type="string" default='en' required>
Language code (e.g., en, fr).
</ParamField>

<ParamField body="elevenLabsApiKey" type="string">
ElevenLabs API key (required only when provider is "11labs_byo"). This will be encrypted and stored securely.
</ParamField>

</Expandable>
</ParamField>

<ParamField body="smartCallback" type="boolean" default="false">
Enable smart callback functionality for the agent.
</ParamField>

<ParamField body="maxAttemptsForSmartCallback" type="number" default="5">
Maximum number of callback attempts when smart callback is enabled.
</ParamField>

<ParamField body="gapBetweenEachAttemptForSmartCallback" type="array">
Array of time intervals between each callback attempt. Each item contains days and hours.

<Expandable title="Array Item Properties">

<ParamField body="days" type="number" default="1" min="0" max="30">
Number of days to wait before the next attempt.
</ParamField>

<ParamField body="hours" type="number" default="0" min="0" max="23">
Number of hours to wait before the next attempt.
</ParamField>

</Expandable>
</ParamField>

<ParamField body="phoneNumberIds" type="array">
Array of phone number IDs to associate with the agent.
</ParamField>

<ParamField body="llmModel" type="string" default='gpt-4o-mini' required>
Language Model to be used by the agent to generate responses. Must be one of: gpt-4o-mini, gpt-4o, gpt-4o-enterprise, gpt-4.1, gpt-4.1-mini, gpt-4.1-enterprise, gpt-4.1-mini-enterprise, gemini-2.5-flash, gemini-2.0-flash-001.
</ParamField>

<ParamField body="settings" type="object">
Additional settings for the agent.

<Expandable title="properties">

<ParamField body="speed" type="number" default="0.7">
Value between 0 and 1 that determines how fast the TTS narrates text.
</ParamField>

<ParamField body="volume" type="number" default="1">
Value between 0 and 1 that adjusts the TTS volume.
</ParamField>

<ParamField body="temperature" type="number" default="0.7">
Value between 0 and 1 for controlling the creativity of the LLM.
</ParamField>

</Expandable>
</ParamField>

<ParamField body="variables" type="object">
Custom variables to store for the agent.
</ParamField>

## Response Fields

<ResponseField name="_id" type="string">
Unique identifier for the newly created agent.
</ResponseField>

<ResponseField name="workspaceId" type="string">
Workspace ID associated with the agent.
</ResponseField>

<ResponseField name="userId" type="string">
User ID of the agent creator.
</ResponseField>

<ResponseField name="name" type="string">
Name of the agent.
</ResponseField>

<ResponseField name="ttsModel" type="object">
Text-to-Speech configuration for the agent.

<ResponseField name="provider" type="string">
TTS provider used by the agent.
</ResponseField>

<ResponseField name="voiceId" default="mistv2_Wildflower" type="string">
Voice ID used for generating speech. (e.g., mistv2_Brook, mistv2_Violet, mistv2_Wildflower)
</ResponseField>


<ResponseField name="language" type="string">
Language code of the TTS voice.
</ResponseField>

<ResponseField name="elevenLabsApiKey" type="string">
Encrypted ElevenLabs API key (only present if provider is "11labs_byo").
</ResponseField>
</ResponseField>

<ResponseField name="llmModel" type="string">
Language Model used by the agent to generate responses.
</ResponseField>

<ResponseField name="smartCallback" type="boolean">
Whether smart callback is enabled for the agent.
</ResponseField>

<ResponseField name="maxAttemptsForSmartCallback" type="number">
Maximum number of callback attempts.
</ResponseField>

<ResponseField name="gapBetweenEachAttemptForSmartCallback" type="array">
Array of time intervals between callback attempts.
</ResponseField>

<ResponseField name="phoneNumberIds" type="array">
Array of phone number IDs associated with the agent.
</ResponseField>

<ResponseField name="activeSessions" type="array">
Array of active sessions for the agent.
</ResponseField>

<ResponseField name="settings" type="object">
Additional settings configured for the agent.
</ResponseField>

<ResponseField name="status" type="string">
Current status of the agent (pending, ready, or error).
</ResponseField>

<ResponseField name="currentNode" type="string">
Current node or state within the agent's flow.
</ResponseField>

<ResponseField name="variables" type="object">
Custom variables stored for the agent.
</ResponseField>

<ResponseField name="createdAt" type="string">
Timestamp when the agent was created.
</ResponseField>

<ResponseField name="updatedAt" type="string">
Timestamp when the agent was last updated.
</ResponseField>

<ResponseExample>
```json
{
  "name": "Customer Support Agent",
  "ttsModel": {
    "provider": "rime",
    "voiceId": "mistv2_Wildflower",
    "name": "Sophie",
    "language": "en"
  },
  "llmModel": "gpt-4o",
  "type": "voice",
  "smartCallback": true,
  "maxAttemptsForSmartCallback": 3,
  "gapBetweenEachAttemptForSmartCallback": [
    { "days": 1, "hours": 2 },
    { "days": 2, "hours": 0 },
    { "days": 3, "hours": 6 }
  ],
  "settings": {
    "speed": 0.8,
    "volume": 1,
    "temperature": 0.7
  }
}
```
</ResponseExample>