v66

latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-04176310979.2 KB

agents

Create Agent

Create a new agent

post/api/v1/agents/

Request body

namestring required

The agent name

descriptionstring nullable

The agent description

labelstring nullable

The agent label (DEPRECATED - use labels instead.)

labelsstring[] nullable

The agent labels

typestring required

The agent type. Must be "ca_v1" currently.

prompt_idinteger required

ID of the prompt associated with the agent

prompt_version_numberinteger nullable

Optional pin to a specific version of the prompt (prompt history version number). When omitted or null, the agent tracks the latest/current version of the prompt. When set, the agent runs that specific prompt version. Must reference an existing version of the agent's prompt.

custom_message_idinteger nullable

Internal ID of the custom message that should be delivered at the beginning of a conversation with the agent

language_group_idinteger nullable

Internal ID of the language group associated with the agent

bridge_phrases_idinteger nullable

Internal ID of the bridge phrases config associated with the agent

timezonestring required

The time zone in which the agent operates

languagesstring[]

BCP 47 codes of languages the agent supports. (DEPRECATED - pass an empty list here and use language group ID to link agent to a language group instead.)

variablesobject required

Custom context variables for the conversation session. Keys should be prefixed with "vars.".

tool_headersobject nullable required

Optional headers to include in tool calls for agent. (It is discouraged to use this field for "Authorization" headers, as values here are not encrypted. Instead, set up a service with either basic, bearer, or custom header auth; attach the appropriate tools to that service, and the attached tools will automatically use the auth configured on the service.)

agent_initiatedboolean

Whether the agent initiates conversation with a user after the custom message is delivered

Speech-to-text providers supported by agents.

wait_sound'No Sound' | 'Keyboard 1' | 'Keyboard 2' | 'Call Center'

Wait sounds supported by agents.

enable_verbal_language_changeboolean

Enables Dynamic Language Switching - when true and a voice group is configured, callers may switch among group languages by speaking at any point in the conversation (in addition to DTMF in response to the language menu).

Example request

{
  "name": "Weather agent",
  "description": "Agent for answering questions about weather.",
  "label": "Information",
  "labels": [
    "Information",
    "Weather"
  ],
  "type": "ca_v1",
  "prompt_id": 1,
  "prompt_version_number": 3,
  "custom_message_id": 1,
  "language_group_id": 1,
  "bridge_phrases_id": 1,
  "timezone": "America/New_York",
  "prompt_tool_defaults": [
    {
      "default_values": [
        {
          "default_value": "fahrenheit",
          "field_name": "temperature_unit"
        }
      ],
      "tool_name": "get_weather"
    }
  ],
  "languages": [
    "en-US",
    "es-US"
  ],
  "variables": {
    "vars.location_name": "Main Street Pizza"
  },
  "tool_headers": {
    "some-header": "some-value"
  }
}

Response

Successful Response