Agents

Endpointhttps://api.neuratel.ai

Create, configure, and manage AI voice agents. Agents handle voice conversations with customizable LLM, TTS, and STT settings.

List Templates

GET

https://api.neuratel.ai

/v1/agents/templates

List all available agent templates with metadata.

List Templates › Responses

200

Successful Response

No data returned

List Agents

GET

https://api.neuratel.ai

/v1/agents

List all agents for your organization.

Supports filtering with both snake_case and camelCase query parameters.

Date Filters

createdAtGt / created_at_gt: After this datetime
createdAtLt / created_at_lt: Before this datetime
createdAtGe / created_at_ge: On or after this datetime
createdAtLe / created_at_le: On or before this datetime
Same patterns for updatedAt* / updated_at_*

Pagination

limit: Max records (default 100, max 1000)
skip: Offset for pagination
sortOrder: ASC or DESC (default DESC)

Example Request (cURL)

Code
curl 'https://api.neuratel.ai/v1/agents?limit=10&sortOrder=DESC' \
  -H 'Authorization: Bearer YOUR_API_KEY'

JavaScript Example


Code
const response = await fetch('https://api.neuratel.ai/v1/agents?limit=10', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
const { results, metadata } = await response.json();

Python Example


Code
import httpx

response = httpx.get(
    'https://api.neuratel.ai/v1/agents',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params={'limit': 10, 'createdAtGt': '2026-01-01T00:00:00Z'}
)
data = response.json()
agents = data['results']

List Agents › query Parameters

skip

integer · min: 0

Number of records to skip for pagination. Defaults to 0.

Default: 0

limit

integer · min: 1 · max: 1000

Maximum number of records to return. Defaults to 100. Max 1000.

Default: 100

sortOrder

string · enum

Sort order: ASC (oldest first) or DESC (newest first). Defaults to DESC.

Sort order for list endpoints

Enum values:

ASC

DESC

Default: DESC

createdAtGt

Filter records created after this datetime (ISO 8601). Example: 2024-01-01T00:00:00Z

createdAtLt

Filter records created before this datetime (ISO 8601). Example: 2024-12-31T23:59:59Z

createdAtGe

Filter records created on or after this datetime (ISO 8601). Example: 2024-01-01T00:00:00Z

createdAtLe

Filter records created on or before this datetime (ISO 8601). Example: 2024-12-31T23:59:59Z

updatedAtGt

Filter records updated after this datetime (ISO 8601). Example: 2024-01-01T00:00:00Z

updatedAtLt

Filter records updated before this datetime (ISO 8601). Example: 2024-12-31T23:59:59Z

updatedAtGe

Filter records updated on or after this datetime (ISO 8601). Example: 2024-01-01T00:00:00Z

updatedAtLe

Filter records updated on or before this datetime (ISO 8601). Example: 2024-12-31T23:59:59Z

List Agents › Responses

Successful Response

API response for agent list. Standardized pagination format: - results: List of items - metadata: Pagination info (skip, limit, total, has_more, count)

object[] · required

List of agents

object · required

Pagination metadata

Create Agent

POST

https://api.neuratel.ai

/v1/agents

Create a new AI agent with nested V3 configuration.

Only name is required - all other fields have production-ready defaults.

Example Request

Code
curl -X POST 'https://api.neuratel.ai/v1/agents' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Sales Assistant",
    "brain": {
      "provider": "openai",
      "model": "gpt-4.1-mini",
      "instructions": "You are a helpful sales assistant."
    }
  }'

JavaScript Example


Code
const response = await fetch('https://api.neuratel.ai/v1/agents', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Sales Assistant',
    brain: { provider: 'openai', model: 'gpt-4.1-mini' }
  })
});
const agent = await response.json();

Python Example


Code
import httpx

response = httpx.post(
    'https://api.neuratel.ai/v1/agents',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={'name': 'Sales Assistant', 'brain': {'provider': 'openai', 'model': 'gpt-4.1-mini'}}
)
agent = response.json()

Create Agent › Request Body

Request schema for creating a new agent. Only `name` is required - all other fields have production-ready defaults. Users can override any field with their own values. The service layer applies defaults via deep_merge_config().

name

string · minLength: 1 · maxLength: 255 · required

Agent display name (required)

agent_type

string · enum

Agent type: advanced (form-based) or workflow (graph-based)

Enum values:

advanced

workflow

Default: advanced

Template ID to apply preset instructions and config. See GET /v1/templates for available templates.

tags

string[] · maxItems: 20

Tags for organization

Agent description

LLM configuration. Default: OpenAI GPT-4.1

TTS configuration. Default: ElevenLabs Flash v2.5

STT configuration. Default: ElevenLabs Scribe v2

Vocal backchanneling config

Enable ultra-low latency word-by-word streaming

Tool and capability settings

Call transfer settings

Analytics and monitoring settings

Create Agent › Responses

Successful Response

Flat API response for single agent. Returns agent data directly without wrapper.

id

string · required

Unique agent identifier

name

string · required

Agent display name

organization_id

string · required

Owning organization ID

status

string

Agent status

Default: ready

is_active

boolean

Whether agent is active

Default: true

object

LLM/Brain configuration

TTS configuration

STT configuration

object

Vocal backchanneling config

stream_response

boolean

Enable ultra-low latency word-by-word streaming

Default: true

min_consecutive_speech_delay

number

Default: 0

object

Tools configuration

Transfer settings

Analytics settings

tags

string[]

Tags

Description

agent_type

string

Agent type

Default: advanced

Linked workflow summary for workflow agents: {id, name, is_active, current_version}

version

integer · min: 1

Config version number

Default: 1

call_count

integer · min: 0

Total number of calls for this agent

Default: 0

Creation timestamp

Last update timestamp

Configured per-call inbound webhook URL

inbound_webhook_secret_set

boolean

True when an HMAC secret is configured. The secret value itself is never returned — operator re-enters it to change.

Default: false

POST/v1/agents

curl --request POST \
  --url https://api.neuratel.ai/v1/agents \
  --header 'Content-Type: application/json' \
  --data '
{
  "brain": {
    "instructions": "You are a helpful sales assistant.",
    "model": "gpt-4.1-mini",
    "provider": "openai"
  },
  "description": "AI assistant for sales calls",
  "name": "Sales Assistant",
  "tags": [
    "sales",
    "inbound"
  ]
}
'

shell

Example Request Body

{
  "brain": {
    "instructions": "You are a helpful sales assistant.",
    "model": "gpt-4.1-mini",
    "provider": "openai"
  },
  "description": "AI assistant for sales calls",
  "name": "Sales Assistant",
  "tags": [
    "sales",
    "inbound"
  ]
}

json

Example Responses

{
  "brain": {
    "instructions": "You are a helpful sales assistant...",
    "model": "gpt-4.1-mini",
    "provider": "openai",
    "temperature": 0.8
  },
  "call_count": 42,
  "created_at": "2026-01-14T10:00:00Z",
  "description": "AI assistant for handling sales inquiries",
  "first_message": {
    "enabled": true,
    "text": "Hello! How can I help you today?"
  },
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "is_active": true,
  "name": "Sales Assistant",
  "organization_id": "1c46c4ba-4462-417a-a34b-a7652c8e8724",
  "status": "ready",
  "tags": [
    "sales",
    "inbound"
  ],
  "tools": {
    "mcp_servers": []
  },
  "transcriber": {
    "language": "en-US",
    "model": "nova-3",
    "provider": "deepgram"
  },
  "turn_detection": {
    "mode": "semantic_vad"
  },
  "updated_at": "2026-01-14T15:30:00Z",
  "version": 1,
  "voice": {
    "model": "sonic-3",
    "provider": "cartesia",
    "voice_id": "ca2a0a92-1d3c-4b8f-9e87-4e8b9a0c5d3e"
  }
}

json

application/json

Get Agent

GET

https://api.neuratel.ai

/v1/agents/{agent_id}

Get agent details with V3 nested configuration.

Get Agent › path Parameters

agent_id

string · uuid · required

The unique identifier of the agent.

Get Agent › Responses

Successful Response

Flat API response for single agent. Returns agent data directly without wrapper.

id

string · required

Unique agent identifier

name

string · required

Agent display name

organization_id

string · required

Owning organization ID

status

string

Agent status

Default: ready

is_active

boolean

Whether agent is active

Default: true

object

LLM/Brain configuration

TTS configuration

STT configuration

object

Vocal backchanneling config

stream_response

boolean

Enable ultra-low latency word-by-word streaming

Default: true

min_consecutive_speech_delay

number

Default: 0

object

Tools configuration

Transfer settings

Analytics settings

tags

string[]

Tags

Description

agent_type

string

Agent type

Default: advanced

Linked workflow summary for workflow agents: {id, name, is_active, current_version}

version

integer · min: 1

Config version number

Default: 1

call_count

integer · min: 0

Total number of calls for this agent

Default: 0

Creation timestamp

Last update timestamp

Configured per-call inbound webhook URL

inbound_webhook_secret_set

boolean

True when an HMAC secret is configured. The secret value itself is never returned — operator re-enters it to change.

Default: false

GET/v1/agents/{agent_id}

curl --request GET \
  --url https://api.neuratel.ai/v1/agents/:agent_id

shell

Example Responses

{
  "brain": {
    "instructions": "You are a helpful sales assistant...",
    "model": "gpt-4.1-mini",
    "provider": "openai",
    "temperature": 0.8
  },
  "call_count": 42,
  "created_at": "2026-01-14T10:00:00Z",
  "description": "AI assistant for handling sales inquiries",
  "first_message": {
    "enabled": true,
    "text": "Hello! How can I help you today?"
  },
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "is_active": true,
  "name": "Sales Assistant",
  "organization_id": "1c46c4ba-4462-417a-a34b-a7652c8e8724",
  "status": "ready",
  "tags": [
    "sales",
    "inbound"
  ],
  "tools": {
    "mcp_servers": []
  },
  "transcriber": {
    "language": "en-US",
    "model": "nova-3",
    "provider": "deepgram"
  },
  "turn_detection": {
    "mode": "semantic_vad"
  },
  "updated_at": "2026-01-14T15:30:00Z",
  "version": 1,
  "voice": {
    "model": "sonic-3",
    "provider": "cartesia",
    "voice_id": "ca2a0a92-1d3c-4b8f-9e87-4e8b9a0c5d3e"
  }
}

json

application/json

Delete Agent

DELETE

https://api.neuratel.ai

/v1/agents/{agent_id}

Delete an agent.

Delete Agent › path Parameters

agent_id

string · uuid · required

The unique identifier of the agent to delete.

Delete Agent › Responses

Successful Response

No data returned

Update Agent

PATCH

https://api.neuratel.ai

/v1/agents/{agent_id}

Update agent. PATCH semantics: only fields the client sends are changed. null clears a field.

Update Agent › path Parameters

agent_id

string · uuid · required

The unique identifier of the agent to update.

Update Agent › Request Body

Request schema for updating an agent. All fields are optional - only provided fields are updated.

Agent display name

Tags for organization

Agent description

Whether agent is active

LLM configuration (brain - what thinks)

TTS configuration

STT configuration

Vocal backchanneling config

Enable ultra-low latency word-by-word streaming

Tool and capability settings

Call transfer settings

Analytics and monitoring settings

If provided, the update will fail with 409 if the agent's current version does not match. Prevents concurrent overwrites.

HTTPS URL invoked at call/message connect to fetch per-call dynamic_variables and (optional) prompt overrides. Empty/null disables the fetch. Phone-number-level URLs (when configured) take precedence for inbound voice — agent URL is the fallback.

Shared secret used to sign every webhook request with HMAC-SHA256 in the X-Neuratel-Signature header. Optional — null means no signature is sent (acceptable for internal/dev endpoints only).

Update Agent › Responses

Successful Response

Flat API response for single agent. Returns agent data directly without wrapper.

id

string · required

Unique agent identifier

name

string · required

Agent display name

organization_id

string · required

Owning organization ID

status

string

Agent status

Default: ready

is_active

boolean

Whether agent is active

Default: true

object

LLM/Brain configuration

TTS configuration

STT configuration

object

Vocal backchanneling config

stream_response

boolean

Enable ultra-low latency word-by-word streaming

Default: true

min_consecutive_speech_delay

number

Default: 0

object

Tools configuration

Transfer settings

Analytics settings

tags

string[]

Tags

Description

agent_type

string

Agent type

Default: advanced

Linked workflow summary for workflow agents: {id, name, is_active, current_version}

version

integer · min: 1

Config version number

Default: 1

call_count

integer · min: 0

Total number of calls for this agent

Default: 0

Creation timestamp

Last update timestamp

Configured per-call inbound webhook URL

inbound_webhook_secret_set

boolean

True when an HMAC secret is configured. The secret value itself is never returned — operator re-enters it to change.

Default: false

PATCH/v1/agents/{agent_id}

curl --request PATCH \
  --url https://api.neuratel.ai/v1/agents/:agent_id \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "name": "string",
  "tags": [
    "string"
  ],
  "description": "string",
  "is_active": true,
  "brain": {
    "provider": "openai",
    "model": "gpt-4.1-mini",
    "instructions": "You are a helpful AI assistant.",
    "chat_instructions": "string",
    "voice_instructions": "string",
    "system_timezone": "UTC",
    "temperature": 0.8,
    "max_completion_tokens": 4096,
    "tool_choice": "auto",
    "parallel_tool_calls": true,
    "max_tool_steps": 3,
    "reasoning_effort": "none"
  },
  "voice": {
    "provider": "cartesia",
    "voice_id": "8d8ce8c9-44a4-46c4-b10f-9a927b99a853",
    "model": "sonic-3",
    "speed": "fastest",
    "emotion": [
      "Happy"
    ],
    "volume": 0,
    "language": "en"
  },
  "transcriber": {
    "provider": "deepgram",
    "model": "nova-3",
    "language": "en-US",
    "smart_format": false,
    "punctuate": true,
    "numerals": false,
    "enable_diarization": false,
    "keyterms": [
      "string"
    ],
    "interim_results": true,
    "endpointing_ms": 300,
    "filler_words": false,
    "profanity_filter": false,
    "mip_opt_out": false
  },
  "turn_detection": {
    "mode": "semantic_vad",
    "min_delay": 0.5,
    "max_delay": 3,
    "endpointing_mode": "dynamic"
  },
  "first_message": {
    "enabled": true,
    "text": "Hello! How can I help you today?",
    "delay_ms": 400,
    "allow_interruptions": false
  },
  "interruption": {
    "enabled": true,
    "mode": "vad",
    "backchannel_boundary_start": 1,
    "backchannel_boundary_end": 1,
    "discard_audio_if_uninterruptible": true,
    "min_duration": 0.5,
    "min_words": 0,
    "false_interruption_timeout": 2,
    "resume_false_interruption": true
  },
  "timeout": {
    "enabled": true,
    "trigger_seconds": 15,
    "warning_count": 2,
    "warning_messages": [
      "Are you still there?",
      "Hello?"
    ],
    "final_message": "I'll end the call now. Goodbye!"
  },
  "call_duration": {
    "enabled": true,
    "max_seconds": 1800,
    "warning_message": "We're approaching the end of our allotted time.",
    "warning_seconds_before": 60,
    "exceeded_message": "We've reached the maximum call duration. Thank you for calling!"
  },
  "background_audio": {
    "ambient": {
      "enabled": false,
      "source": "office_ambience",
      "volume": 0.8
    },
    "thinking": {
      "enabled": false,
      "source": "keyboard_typing",
      "volume": 0.8
    }
  },
  "backchannel": {
    "enabled": false,
    "listening_delayed_enabled": true,
    "thinking_cognitive_enabled": true,
    "thinking_cognitive_probability": 0.5,
    "interruption_hums_enabled": true,
    "volume_multiplier": 0.75,
    "tool_fillers_enabled": false,
    "tool_fillers_delay": 1.5,
    "tool_fillers_pool": [
      "string"
    ],
    "listening_cues": [
      "string"
    ],
    "thinking_cues": [
      "string"
    ]
  },
  "stream_response": true,
  "tts_text_transforms": [
    "filter_markdown"
  ],
  "min_consecutive_speech_delay": 0,
  "tools": {
    "hangup": {
      "enabled": true,
      "farewell_message": "Goodbye!",
      "keywords": [
        "goodbye",
        "bye",
        "end call",
        "hang up"
      ],
      "confirm_before_hangup": false,
      "confirmation_prompt": "Are you sure you'd like to end the call?"
    },
    "collect_dtmf": {
      "enabled": false,
      "max_digits": 10,
      "timeout_seconds": 10,
      "stop_character": "#",
      "allow_spoken": true,
      "inter_digit_timeout": 3
    },
    "send_dtmf": {
      "enabled": false,
      "tone_duration_ms": 100,
      "gap_duration_ms": 100
    },
    "voicemail": {
      "enabled": true,
      "action": "hangup",
      "message": "Hi, this is a message from your assistant. I'll try calling back later.",
      "wait_for_beep": true,
      "post_message_delay_ms": 500
    },
    "add_to_dnc": {
      "enabled": false
    },
    "place_outbound_call": {
      "enabled": false,
      "permission_request_template_name": "call_permission_request",
      "permission_request_template_language_code": "en_US"
    },
    "send_audio_message": {
      "enabled": false,
      "max_text_length": 500,
      "tool_fillers_enabled": true,
      "tool_fillers_pool": [
        "string"
      ]
    },
    "send_whatsapp_message": {
      "enabled": false,
      "tool_fillers_enabled": true,
      "tool_fillers_pool": [
        "string"
      ]
    },
    "rag": {
      "enabled": false,
      "knowledge_base_ids": [
        "string"
      ],
      "top_k": 5,
      "score_threshold": 0.7,
      "include_metadata": true,
      "context_template": "Here is relevant information:\n{chunks}"
    },
    "mcp_servers": [
      {
        "server_id": "server_id",
        "allowed_tools": [
          "string"
        ]
      }
    ]
  },
  "transfer": {
    "enabled": false,
    "mode": "blind",
    "destinations": [
      {
        "id": "id",
        "name": "name",
        "number": "number",
        "keywords": [
          "string"
        ],
        "description": "string",
        "message": "Transferring you now.",
        "timeout_seconds": 30,
        "priority": 0,
        "working_hours": {
          "enabled": false,
          "days": [
            1,
            2,
            3,
            4,
            5
          ],
          "start_time": "09:00",
          "end_time": "17:00",
          "timezone": "America/New_York",
          "unavailable_message": "This team is currently unavailable. Please try again during business hours."
        }
      }
    ],
    "fallback_destination": {
      "id": "id",
      "name": "name",
      "number": "number",
      "keywords": [
        "string"
      ],
      "description": "string",
      "message": "Transferring you now.",
      "timeout_seconds": 30,
      "priority": 0,
      "working_hours": {
        "enabled": false,
        "days": [
          1,
          2,
          3,
          4,
          5
        ],
        "start_time": "09:00",
        "end_time": "17:00",
        "timezone": "America/New_York",
        "unavailable_message": "This team is currently unavailable. Please try again during business hours."
      }
    },
    "warm_intro_template": "Hi, I'm transferring a caller who needs help with {reason}. They said: {summary}",
    "warm_intro_timeout_seconds": 60,
    "on_fail": "return",
    "fail_message": "I'm sorry, I wasn't able to transfer your call. Let me help you directly.",
    "max_retries": 2,
    "hold_music": true,
    "hold_music_url": "string",
    "announce_position": false
  },
  "analytics": {
    "enabled": true,
    "track_sentiment": true,
    "webhook": {
      "enabled": false,
      "url": "string",
      "events": [
        "session_report",
        "call_ended",
        "error"
      ],
      "include_transcript": true,
      "include_analytics": true,
      "include_recording_url": true,
      "auth_header": "Authorization",
      "auth_token": "string",
      "retry_count": 3,
      "timeout_seconds": 30
    },
    "recording": {
      "enabled": false,
      "retention_days": 30
    },
    "post_call": {
      "analysisPlan": {
        "summaryPrompt": "string",
        "structuredDataPrompt": "string",
        "structuredDataSchema": {},
        "successEvaluationPrompt": "string",
        "successEvaluationRubric": "PassFail",
        "extract_topics": false,
        "extract_action_items": false,
        "compute_user_sentiment": false,
        "minMessagesThreshold": 2
      }
    }
  },
  "expected_version": 0,
  "inbound_webhook_url": "string",
  "inbound_webhook_secret": "string"
}
EOF

shell

Example Request Body

{
  "name": "string",
  "tags": [
    "string"
  ],
  "description": "string",
  "is_active": true,
  "brain": {
    "provider": "openai",
    "model": "gpt-4.1-mini",
    "instructions": "You are a helpful AI assistant.",
    "chat_instructions": "string",
    "voice_instructions": "string",
    "system_timezone": "UTC",
    "temperature": 0.8,
    "max_completion_tokens": 4096,
    "tool_choice": "auto",
    "parallel_tool_calls": true,
    "max_tool_steps": 3,
    "reasoning_effort": "none"
  },
  "voice": {
    "provider": "cartesia",
    "voice_id": "8d8ce8c9-44a4-46c4-b10f-9a927b99a853",
    "model": "sonic-3",
    "speed": "fastest",
    "emotion": [
      "Happy"
    ],
    "volume": 0,
    "language": "en"
  },
  "transcriber": {
    "provider": "deepgram",
    "model": "nova-3",
    "language": "en-US",
    "smart_format": false,
    "punctuate": true,
    "numerals": false,
    "enable_diarization": false,
    "keyterms": [
      "string"
    ],
    "interim_results": true,
    "endpointing_ms": 300,
    "filler_words": false,
    "profanity_filter": false,
    "mip_opt_out": false
  },
  "turn_detection": {
    "mode": "semantic_vad",
    "min_delay": 0.5,
    "max_delay": 3,
    "endpointing_mode": "dynamic"
  },
  "first_message": {
    "enabled": true,
    "text": "Hello! How can I help you today?",
    "delay_ms": 400,
    "allow_interruptions": false
  },
  "interruption": {
    "enabled": true,
    "mode": "vad",
    "backchannel_boundary_start": 1,
    "backchannel_boundary_end": 1,
    "discard_audio_if_uninterruptible": true,
    "min_duration": 0.5,
    "min_words": 0,
    "false_interruption_timeout": 2,
    "resume_false_interruption": true
  },
  "timeout": {
    "enabled": true,
    "trigger_seconds": 15,
    "warning_count": 2,
    "warning_messages": [
      "Are you still there?",
      "Hello?"
    ],
    "final_message": "I'll end the call now. Goodbye!"
  },
  "call_duration": {
    "enabled": true,
    "max_seconds": 1800,
    "warning_message": "We're approaching the end of our allotted time.",
    "warning_seconds_before": 60,
    "exceeded_message": "We've reached the maximum call duration. Thank you for calling!"
  },
  "background_audio": {
    "ambient": {
      "enabled": false,
      "source": "office_ambience",
      "volume": 0.8
    },
    "thinking": {
      "enabled": false,
      "source": "keyboard_typing",
      "volume": 0.8
    }
  },
  "backchannel": {
    "enabled": false,
    "listening_delayed_enabled": true,
    "thinking_cognitive_enabled": true,
    "thinking_cognitive_probability": 0.5,
    "interruption_hums_enabled": true,
    "volume_multiplier": 0.75,
    "tool_fillers_enabled": false,
    "tool_fillers_delay": 1.5,
    "tool_fillers_pool": [
      "string"
    ],
    "listening_cues": [
      "string"
    ],
    "thinking_cues": [
      "string"
    ]
  },
  "stream_response": true,
  "tts_text_transforms": [
    "filter_markdown"
  ],
  "min_consecutive_speech_delay": 0,
  "tools": {
    "hangup": {
      "enabled": true,
      "farewell_message": "Goodbye!",
      "keywords": [
        "goodbye",
        "bye",
        "end call",
        "hang up"
      ],
      "confirm_before_hangup": false,
      "confirmation_prompt": "Are you sure you'd like to end the call?"
    },
    "collect_dtmf": {
      "enabled": false,
      "max_digits": 10,
      "timeout_seconds": 10,
      "stop_character": "#",
      "allow_spoken": true,
      "inter_digit_timeout": 3
    },
    "send_dtmf": {
      "enabled": false,
      "tone_duration_ms": 100,
      "gap_duration_ms": 100
    },
    "voicemail": {
      "enabled": true,
      "action": "hangup",
      "message": "Hi, this is a message from your assistant. I'll try calling back later.",
      "wait_for_beep": true,
      "post_message_delay_ms": 500
    },
    "add_to_dnc": {
      "enabled": false
    },
    "place_outbound_call": {
      "enabled": false,
      "permission_request_template_name": "call_permission_request",
      "permission_request_template_language_code": "en_US"
    },
    "send_audio_message": {
      "enabled": false,
      "max_text_length": 500,
      "tool_fillers_enabled": true,
      "tool_fillers_pool": [
        "string"
      ]
    },
    "send_whatsapp_message": {
      "enabled": false,
      "tool_fillers_enabled": true,
      "tool_fillers_pool": [
        "string"
      ]
    },
    "rag": {
      "enabled": false,
      "knowledge_base_ids": [
        "string"
      ],
      "top_k": 5,
      "score_threshold": 0.7,
      "include_metadata": true,
      "context_template": "Here is relevant information:\n{chunks}"
    },
    "mcp_servers": [
      {
        "server_id": "server_id",
        "allowed_tools": [
          "string"
        ]
      }
    ]
  },
  "transfer": {
    "enabled": false,
    "mode": "blind",
    "destinations": [
      {
        "id": "id",
        "name": "name",
        "number": "number",
        "keywords": [
          "string"
        ],
        "description": "string",
        "message": "Transferring you now.",
        "timeout_seconds": 30,
        "priority": 0,
        "working_hours": {
          "enabled": false,
          "days": [
            1,
            2,
            3,
            4,
            5
          ],
          "start_time": "09:00",
          "end_time": "17:00",
          "timezone": "America/New_York",
          "unavailable_message": "This team is currently unavailable. Please try again during business hours."
        }
      }
    ],
    "fallback_destination": {
      "id": "id",
      "name": "name",
      "number": "number",
      "keywords": [
        "string"
      ],
      "description": "string",
      "message": "Transferring you now.",
      "timeout_seconds": 30,
      "priority": 0,
      "working_hours": {
        "enabled": false,
        "days": [
          1,
          2,
          3,
          4,
          5
        ],
        "start_time": "09:00",
        "end_time": "17:00",
        "timezone": "America/New_York",
        "unavailable_message": "This team is currently unavailable. Please try again during business hours."
      }
    },
    "warm_intro_template": "Hi, I'm transferring a caller who needs help with {reason}. They said: {summary}",
    "warm_intro_timeout_seconds": 60,
    "on_fail": "return",
    "fail_message": "I'm sorry, I wasn't able to transfer your call. Let me help you directly.",
    "max_retries": 2,
    "hold_music": true,
    "hold_music_url": "string",
    "announce_position": false
  },
  "analytics": {
    "enabled": true,
    "track_sentiment": true,
    "webhook": {
      "enabled": false,
      "url": "string",
      "events": [
        "session_report",
        "call_ended",
        "error"
      ],
      "include_transcript": true,
      "include_analytics": true,
      "include_recording_url": true,
      "auth_header": "Authorization",
      "auth_token": "string",
      "retry_count": 3,
      "timeout_seconds": 30
    },
    "recording": {
      "enabled": false,
      "retention_days": 30
    },
    "post_call": {
      "analysisPlan": {
        "summaryPrompt": "string",
        "structuredDataPrompt": "string",
        "structuredDataSchema": {},
        "successEvaluationPrompt": "string",
        "successEvaluationRubric": "PassFail",
        "extract_topics": false,
        "extract_action_items": false,
        "compute_user_sentiment": false,
        "minMessagesThreshold": 2
      }
    }
  },
  "expected_version": 0,
  "inbound_webhook_url": "string",
  "inbound_webhook_secret": "string"
}

json

Example Responses

{
  "brain": {
    "instructions": "You are a helpful sales assistant...",
    "model": "gpt-4.1-mini",
    "provider": "openai",
    "temperature": 0.8
  },
  "call_count": 42,
  "created_at": "2026-01-14T10:00:00Z",
  "description": "AI assistant for handling sales inquiries",
  "first_message": {
    "enabled": true,
    "text": "Hello! How can I help you today?"
  },
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "is_active": true,
  "name": "Sales Assistant",
  "organization_id": "1c46c4ba-4462-417a-a34b-a7652c8e8724",
  "status": "ready",
  "tags": [
    "sales",
    "inbound"
  ],
  "tools": {
    "mcp_servers": []
  },
  "transcriber": {
    "language": "en-US",
    "model": "nova-3",
    "provider": "deepgram"
  },
  "turn_detection": {
    "mode": "semantic_vad"
  },
  "updated_at": "2026-01-14T15:30:00Z",
  "version": 1,
  "voice": {
    "model": "sonic-3",
    "provider": "cartesia",
    "voice_id": "ca2a0a92-1d3c-4b8f-9e87-4e8b9a0c5d3e"
  }
}

json

application/json

Duplicate Agent

POST

https://api.neuratel.ai

/v1/agents/{agent_id}/duplicate

Duplicate an existing agent.

Duplicate Agent › path Parameters

agent_id

string · uuid · required

The unique identifier of the agent to duplicate.

Duplicate Agent › query Parameters

new_name

Optional custom name for the duplicated agent. If not provided, appends ' (Copy)' to the original name.

Duplicate Agent › Responses

Successful Response

Flat API response for single agent. Returns agent data directly without wrapper.

id

string · required

Unique agent identifier

name

string · required

Agent display name

organization_id

string · required

Owning organization ID

status

string

Agent status

Default: ready

is_active

boolean

Whether agent is active

Default: true

object

LLM/Brain configuration

TTS configuration

STT configuration

object

Vocal backchanneling config

stream_response

boolean

Enable ultra-low latency word-by-word streaming

Default: true

min_consecutive_speech_delay

number

Default: 0

object

Tools configuration

Transfer settings

Analytics settings

tags

string[]

Tags

Description

agent_type

string

Agent type

Default: advanced

Linked workflow summary for workflow agents: {id, name, is_active, current_version}

version

integer · min: 1

Config version number

Default: 1

call_count

integer · min: 0

Total number of calls for this agent

Default: 0

Creation timestamp

Last update timestamp

Configured per-call inbound webhook URL

inbound_webhook_secret_set

boolean

True when an HMAC secret is configured. The secret value itself is never returned — operator re-enters it to change.

Default: false

POST/v1/agents/{agent_id}/duplicate

curl --request POST \
  --url https://api.neuratel.ai/v1/agents/:agent_id/duplicate

shell

Example Responses

{
  "brain": {
    "instructions": "You are a helpful sales assistant...",
    "model": "gpt-4.1-mini",
    "provider": "openai",
    "temperature": 0.8
  },
  "call_count": 42,
  "created_at": "2026-01-14T10:00:00Z",
  "description": "AI assistant for handling sales inquiries",
  "first_message": {
    "enabled": true,
    "text": "Hello! How can I help you today?"
  },
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "is_active": true,
  "name": "Sales Assistant",
  "organization_id": "1c46c4ba-4462-417a-a34b-a7652c8e8724",
  "status": "ready",
  "tags": [
    "sales",
    "inbound"
  ],
  "tools": {
    "mcp_servers": []
  },
  "transcriber": {
    "language": "en-US",
    "model": "nova-3",
    "provider": "deepgram"
  },
  "turn_detection": {
    "mode": "semantic_vad"
  },
  "updated_at": "2026-01-14T15:30:00Z",
  "version": 1,
  "voice": {
    "model": "sonic-3",
    "provider": "cartesia",
    "voice_id": "ca2a0a92-1d3c-4b8f-9e87-4e8b9a0c5d3e"
  }
}

json

application/json

List Agent Version History

GET

https://api.neuratel.ai

/v1/agents/{agent_id}/versions

List all saved configuration versions of an agent.

List Agent Version History › path Parameters

agent_id

string · uuid · required

Agent ID

List Agent Version History › Responses

Successful Response

Response for listing all versions of an agent.

agent_id

string · required

total

integer · required

object[] · required

Get Agent Version

GET

https://api.neuratel.ai

/v1/agents/{agent_id}/versions/{version}

Get a specific historical version of an agent's configuration.

Get Agent Version › path Parameters

agent_id

string · uuid · required

Agent ID

version

integer · min: 1 · required

Version number

Get Agent Version › Responses

Successful Response

Response for a single agent version.

version

integer · required

Restore Agent Version

POST

https://api.neuratel.ai

/v1/agents/{agent_id}/versions/{version}/restore

Restore an agent's configuration to a specific historical version.

Restore Agent Version › path Parameters

agent_id

string · uuid · required

Agent ID

version

integer · min: 1 · required

Version number to restore

Restore Agent Version › Responses

Successful Response

Response after restoring an agent to a historical version.

success

boolean · required

message

string · required

List Required Template Variables

GET

https://api.neuratel.ai

/v1/agents/{agent_id}/required-variables

Inspect an agent's config and return every {{template}} placeholder it references, split into auto-injected system__* variables and contact variables that must be present on the call list.

List Required Template Variables › path Parameters

agent_id

string · uuid · required

Agent ID

List Required Template Variables › Responses

Successful Response

Variables an agent's config references. Field meanings (matches the frontend `AgentRequiredVariables` interface consumed by the outbound-campaigns Form): - `required_variables`: every `{{name}}` extracted from the agent config. - `contact_variables`: subset that must come from the call-list contact row (i.e. NOT auto-injected `system__*` variables). - `system_variables`: subset auto-injected by the worker at call time. - `total_required`: convenience count of `required_variables`. - `sources`: where each variable was found (currently grouped by "system" vs "contact" — extensible for future per-config-section breakdown without a new endpoint).

required_variables

string[]

contact_variables

string[]

system_variables

string[]

total_required

integer

Default: 0

object

Numbers