Skip to main content
POST
/
v2
/
ai-agents
/
{
  "ai_agent_id": "<string>",
  "agent_name": "<string>",
  "language_code": "en-US",
  "llm": {
    "llm_id": "<string>",
    "llm_type": "<string>",
    "model_provider": "openai",
    "model_name": "<string>",
    "model_temperature": 0,
    "llm_name": "<string>",
    "llm_description": "<string>",
    "base_url": "<string>",
    "api_key": "<string>",
    "max_tokens": 123,
    "required_dynamic_data": [
      "<string>"
    ],
    "system_prompt": "<string>",
    "tools": [
      {}
    ]
  },
  "stt": {
    "provider": "<string>",
    "model": "nova-2-general"
  },
  "tts": {
    "provider": "<string>",
    "voice_id": "<string>",
    "voice_name": "<string>",
    "model_name": "eleven_turbo_v2_5",
    "voice_temperature": 0.5
  },
  "knowledge_base_id": "<string>",
  "enable_user_interruptions": true,
  "minimum_speech_duration_for_interruptions": 0.5,
  "minimum_words_before_interruption": 0,
  "wait_time_before_detecting_end_of_speech": 0.5,
  "ambient_sound": "none",
  "ambient_sound_volume": 1,
  "webhook_url": "<string>",
  "end_call_after_silence_seconds": 10,
  "max_call_duration_seconds": 1800,
  "welcome_message": "<string>",
  "voicemail_detection_timeout_seconds": 90,
  "dynamic_data_config": [
    {
      "url": "<string>",
      "method": "<string>",
      "timeout": 123,
      "headers": {},
      "body": {},
      "query": {},
      "cache": true,
      "response_data": [
        {
          "name": "<string>",
          "data": "<string>",
          "context": "<string>"
        }
      ]
    }
  ],
  "post_call_analysis": [
    {
      "type": "<string>",
      "name": "<string>",
      "description": "<string>",
      "system_prompt": "<string>",
      "examples": [
        "<string>"
      ]
    }
  ],
  "created_by_user_id": "<string>"
}

Body

application/json
​
agent_name
string
required

Name identifier for the AI agent

​
llm
object
required

Language model configuration for the agent

  • CreateSimplePiaLLMRequest
  • CreateAgenticPiaLLMRequest
  • CreateCustomPiaLLMRequest
​
tts
object
required

Text-to-Speech configuration for voice synthesis

  • CreateElevenLabsTTSRequest
  • CreateGoogleTTSRequest
  • CreateAzureTTSRequest
  • CreateCartesiaTTSRequest
  • CreatePiaTTSRequest
​
stt
object
required

Speech-to-Text configuration for voice recognition

  • CreateDeepgramSTTRequest
  • CreateGoogleSTTRequest
  • CreatePiaSTTRequest
​
language_code
string
default:en-US

Language code for the agent (e.g., 'en-US' for US English)

​
knowledge_base_id
string | null

ID of the knowledge base to use for enhanced responses

​
enable_user_interruptions
boolean | null
default:true

Whether to allow users to interrupt the agent while speaking

​
minimum_speech_duration_for_interruptions
number | null
default:0.5

Minimum duration (in seconds) of speech before allowing interruption

Required range: 0 <= x <= 15
​
minimum_words_before_interruption
integer | null
default:0

Minimum number of words spoken before allowing interruption

Required range: 0 <= x <= 5
​
wait_time_before_detecting_end_of_speech
number | null
default:0.5

Time to wait before detecting end of speech

Required range: 0 <= x <= 15
​
ambient_sound
enum<string> | null
default:none

Type of ambient background sound to add to the call

Available options:
office,
cafe,
restaurant,
park,
street,
home,
library,
airport,
train_station,
beach,
none
​
ambient_sound_volume
number | null
default:1

Volume level for ambient sound (0-2, where 1 is normal volume)

Required range: 0 <= x <= 2
​
webhook_url
string | null

URL to receive webhook notifications about call events

​
end_call_after_silence_seconds
number | null
default:10

Number of seconds of silence before automatically ending the call

Required range: 10 <= x <= 30
​
max_call_duration_seconds
number | null
default:1800

Maximum duration of the call in seconds (30-3600)

Required range: 30 <= x <= 3600
​
welcome_message
string | null

Custom message to be spoken when the call begins

​
voicemail_detection_timeout_seconds
number | null
default:90

Time to wait for detecting voicemail before taking action

Required range: x >= 0
​
dynamic_data_config
CreateDynamicDataConfigItemRequest · object[] | null

Configuration for dynamic data sources used by the agent

​
post_call_analysis
Post Call Analysis · array

Configuration for analysis items to be processed after the call

  • CreateStringPostCallAnalysisItemRequest
  • CreateEnumPostCallAnalysisItemRequest
  • CreateBooleanPostCallAnalysisItemRequest
  • CreateNumberPostCallAnalysisItemRequest

Response

Successful Response

​
ai_agent_id
string
required

Unique identifier for the AI agent

​
agent_name
string
required

Name of the AI agent

​
llm
object
required

Language model configuration for the AI agent

  • SimplePiaLLMResponse
  • AgenticPiaLLMResponse
  • CustomPiaLLMResponse
​
stt
object
required

Speech-to-text configuration for the AI agent

  • DeepgramSTTResponse
  • GoogleSTTResponse
  • PiaSTTResponse
​
tts
object
required

Text-to-speech configuration for the AI agent

  • ElevenLabsTTSResponse
  • GoogleTTSResponse
  • AzureTTSResponse
  • CartesiaTTSResponse
  • PiaTTSResponse
​
created_by_user_id
string
required

ID of the user who created this AI agent

​
language_code
string
default:en-US

Language code for the AI agent in BCP-47 format

​
knowledge_base_id
string | null

ID of the associated knowledge base, if any

​
enable_user_interruptions
boolean
default:true

Whether to allow users to interrupt the AI agent while speaking

​
minimum_speech_duration_for_interruptions
number
default:0.5

Minimum duration of speech in seconds before interruptions are allowed

Required range: 0 <= x <= 15
​
minimum_words_before_interruption
integer
default:0

Minimum number of words that must be spoken before interruption is allowed

Required range: 0 <= x <= 5
​
wait_time_before_detecting_end_of_speech
number
default:0.5

Time in seconds to wait before considering speech has ended

Required range: 0 <= x <= 15
​
ambient_sound
enum<string>
default:none

Type of ambient background sound to use during calls

Available options:
office,
cafe,
restaurant,
park,
street,
home,
library,
airport,
train_station,
beach,
none
​
ambient_sound_volume
number
default:1

Volume level for ambient sound, from 0 (muted) to 2 (loud)

Required range: 0 <= x <= 2
​
webhook_url
string | null

URL to send webhook notifications about call events

​
end_call_after_silence_seconds
number
default:10

Number of seconds of silence before automatically ending the call

Required range: 10 <= x <= 30
​
max_call_duration_seconds
number
default:1800

Maximum duration of a call in seconds

Required range: 30 <= x <= 3600
​
welcome_message
string | null

Custom welcome message to play at the start of calls

​
voicemail_detection_timeout_seconds
number
default:90

Time in seconds to wait for voicemail detection

Required range: x >= 0
​
dynamic_data_config
DynamicDataConfigItemResponse · object[] | null

Configuration for dynamic data sources that can be used during calls

​
post_call_analysis
Post Call Analysis · array

Configuration for analysis items to be processed after calls

  • StringPostCallAnalysisItemResponse
  • EnumPostCallAnalysisItemResponse
  • BooleanPostCallAnalysisItemResponse
  • NumberPostCallAnalysisItemResponse