Skip to main content
POST
/
v2
/
ai-agents
/
Create AI Agent
curl --request POST \
  --url https://api.example.com/v2/ai-agents/ \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_name": "<string>",
  "llm": {
    "llm_type": "<string>",
    "model_name": "<string>",
    "system_prompt": "<string>",
    "model_temperature": 0,
    "required_dynamic_data": [
      "<string>"
    ],
    "tools": [
      {}
    ],
    "llm_name": "<string>",
    "llm_description": "<string>",
    "base_url": "<string>",
    "api_key": "<string>",
    "max_token": 123
  },
  "tts": {
    "voice_id": "<string>",
    "provider": "elevenlabs",
    "voice_name": "<string>",
    "voice_temperature": 0.2
  },
  "stt": {
    "provider": "<string>"
  },
  "language_code": "en-US",
  "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>",
      "response_data": [
        {
          "name": "<string>",
          "data": "<string>",
          "context": "<string>"
        }
      ],
      "method": "GET",
      "timeout": 2000,
      "headers": {},
      "body": {},
      "query": {},
      "cache": true
    }
  ],
  "post_call_analysis": [
    {
      "name": "<string>",
      "description": "<string>",
      "system_prompt": "<string>",
      "type": "string",
      "examples": [
        "<string>"
      ]
    }
  ]
}
'
import requests

url = "https://api.example.com/v2/ai-agents/"

payload = {
    "agent_name": "<string>",
    "llm": {
        "llm_type": "<string>",
        "model_name": "<string>",
        "system_prompt": "<string>",
        "model_temperature": 0,
        "required_dynamic_data": ["<string>"],
        "tools": [{}],
        "llm_name": "<string>",
        "llm_description": "<string>",
        "base_url": "<string>",
        "api_key": "<string>",
        "max_token": 123
    },
    "tts": {
        "voice_id": "<string>",
        "provider": "elevenlabs",
        "voice_name": "<string>",
        "voice_temperature": 0.2
    },
    "stt": { "provider": "<string>" },
    "language_code": "en-US",
    "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>",
            "response_data": [
                {
                    "name": "<string>",
                    "data": "<string>",
                    "context": "<string>"
                }
            ],
            "method": "GET",
            "timeout": 2000,
            "headers": {},
            "body": {},
            "query": {},
            "cache": True
        }
    ],
    "post_call_analysis": [
        {
            "name": "<string>",
            "description": "<string>",
            "system_prompt": "<string>",
            "type": "string",
            "examples": ["<string>"]
        }
    ]
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    agent_name: '<string>',
    llm: {
      llm_type: '<string>',
      model_name: '<string>',
      system_prompt: '<string>',
      model_temperature: 0,
      required_dynamic_data: ['<string>'],
      tools: [{}],
      llm_name: '<string>',
      llm_description: '<string>',
      base_url: '<string>',
      api_key: '<string>',
      max_token: 123
    },
    tts: {
      voice_id: '<string>',
      provider: 'elevenlabs',
      voice_name: '<string>',
      voice_temperature: 0.2
    },
    stt: {provider: '<string>'},
    language_code: 'en-US',
    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>',
        response_data: [{name: '<string>', data: '<string>', context: '<string>'}],
        method: 'GET',
        timeout: 2000,
        headers: {},
        body: JSON.stringify({}),
        query: {},
        cache: true
      }
    ],
    post_call_analysis: [
      {
        name: '<string>',
        description: '<string>',
        system_prompt: '<string>',
        type: 'string',
        examples: ['<string>']
      }
    ]
  })
};

fetch('https://api.example.com/v2/ai-agents/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/v2/ai-agents/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'agent_name' => '<string>',
    'llm' => [
        'llm_type' => '<string>',
        'model_name' => '<string>',
        'system_prompt' => '<string>',
        'model_temperature' => 0,
        'required_dynamic_data' => [
                '<string>'
        ],
        'tools' => [
                [
                                
                ]
        ],
        'llm_name' => '<string>',
        'llm_description' => '<string>',
        'base_url' => '<string>',
        'api_key' => '<string>',
        'max_token' => 123
    ],
    'tts' => [
        'voice_id' => '<string>',
        'provider' => 'elevenlabs',
        'voice_name' => '<string>',
        'voice_temperature' => 0.2
    ],
    'stt' => [
        'provider' => '<string>'
    ],
    'language_code' => 'en-US',
    '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>',
                'response_data' => [
                                [
                                                                'name' => '<string>',
                                                                'data' => '<string>',
                                                                'context' => '<string>'
                                ]
                ],
                'method' => 'GET',
                'timeout' => 2000,
                'headers' => [
                                
                ],
                'body' => [
                                
                ],
                'query' => [
                                
                ],
                'cache' => true
        ]
    ],
    'post_call_analysis' => [
        [
                'name' => '<string>',
                'description' => '<string>',
                'system_prompt' => '<string>',
                'type' => 'string',
                'examples' => [
                                '<string>'
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v2/ai-agents/"

	payload := strings.NewReader("{\n  \"agent_name\": \"<string>\",\n  \"llm\": {\n    \"llm_type\": \"<string>\",\n    \"model_name\": \"<string>\",\n    \"system_prompt\": \"<string>\",\n    \"model_temperature\": 0,\n    \"required_dynamic_data\": [\n      \"<string>\"\n    ],\n    \"tools\": [\n      {}\n    ],\n    \"llm_name\": \"<string>\",\n    \"llm_description\": \"<string>\",\n    \"base_url\": \"<string>\",\n    \"api_key\": \"<string>\",\n    \"max_token\": 123\n  },\n  \"tts\": {\n    \"voice_id\": \"<string>\",\n    \"provider\": \"elevenlabs\",\n    \"voice_name\": \"<string>\",\n    \"voice_temperature\": 0.2\n  },\n  \"stt\": {\n    \"provider\": \"<string>\"\n  },\n  \"language_code\": \"en-US\",\n  \"knowledge_base_id\": \"<string>\",\n  \"enable_user_interruptions\": true,\n  \"minimum_speech_duration_for_interruptions\": 0.5,\n  \"minimum_words_before_interruption\": 0,\n  \"wait_time_before_detecting_end_of_speech\": 0.5,\n  \"ambient_sound\": \"none\",\n  \"ambient_sound_volume\": 1,\n  \"webhook_url\": \"<string>\",\n  \"end_call_after_silence_seconds\": 10,\n  \"max_call_duration_seconds\": 1800,\n  \"welcome_message\": \"<string>\",\n  \"voicemail_detection_timeout_seconds\": 90,\n  \"dynamic_data_config\": [\n    {\n      \"url\": \"<string>\",\n      \"response_data\": [\n        {\n          \"name\": \"<string>\",\n          \"data\": \"<string>\",\n          \"context\": \"<string>\"\n        }\n      ],\n      \"method\": \"GET\",\n      \"timeout\": 2000,\n      \"headers\": {},\n      \"body\": {},\n      \"query\": {},\n      \"cache\": true\n    }\n  ],\n  \"post_call_analysis\": [\n    {\n      \"name\": \"<string>\",\n      \"description\": \"<string>\",\n      \"system_prompt\": \"<string>\",\n      \"type\": \"string\",\n      \"examples\": [\n        \"<string>\"\n      ]\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api.example.com/v2/ai-agents/")
  .header("Content-Type", "application/json")
  .body("{\n  \"agent_name\": \"<string>\",\n  \"llm\": {\n    \"llm_type\": \"<string>\",\n    \"model_name\": \"<string>\",\n    \"system_prompt\": \"<string>\",\n    \"model_temperature\": 0,\n    \"required_dynamic_data\": [\n      \"<string>\"\n    ],\n    \"tools\": [\n      {}\n    ],\n    \"llm_name\": \"<string>\",\n    \"llm_description\": \"<string>\",\n    \"base_url\": \"<string>\",\n    \"api_key\": \"<string>\",\n    \"max_token\": 123\n  },\n  \"tts\": {\n    \"voice_id\": \"<string>\",\n    \"provider\": \"elevenlabs\",\n    \"voice_name\": \"<string>\",\n    \"voice_temperature\": 0.2\n  },\n  \"stt\": {\n    \"provider\": \"<string>\"\n  },\n  \"language_code\": \"en-US\",\n  \"knowledge_base_id\": \"<string>\",\n  \"enable_user_interruptions\": true,\n  \"minimum_speech_duration_for_interruptions\": 0.5,\n  \"minimum_words_before_interruption\": 0,\n  \"wait_time_before_detecting_end_of_speech\": 0.5,\n  \"ambient_sound\": \"none\",\n  \"ambient_sound_volume\": 1,\n  \"webhook_url\": \"<string>\",\n  \"end_call_after_silence_seconds\": 10,\n  \"max_call_duration_seconds\": 1800,\n  \"welcome_message\": \"<string>\",\n  \"voicemail_detection_timeout_seconds\": 90,\n  \"dynamic_data_config\": [\n    {\n      \"url\": \"<string>\",\n      \"response_data\": [\n        {\n          \"name\": \"<string>\",\n          \"data\": \"<string>\",\n          \"context\": \"<string>\"\n        }\n      ],\n      \"method\": \"GET\",\n      \"timeout\": 2000,\n      \"headers\": {},\n      \"body\": {},\n      \"query\": {},\n      \"cache\": true\n    }\n  ],\n  \"post_call_analysis\": [\n    {\n      \"name\": \"<string>\",\n      \"description\": \"<string>\",\n      \"system_prompt\": \"<string>\",\n      \"type\": \"string\",\n      \"examples\": [\n        \"<string>\"\n      ]\n    }\n  ]\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.example.com/v2/ai-agents/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"agent_name\": \"<string>\",\n  \"llm\": {\n    \"llm_type\": \"<string>\",\n    \"model_name\": \"<string>\",\n    \"system_prompt\": \"<string>\",\n    \"model_temperature\": 0,\n    \"required_dynamic_data\": [\n      \"<string>\"\n    ],\n    \"tools\": [\n      {}\n    ],\n    \"llm_name\": \"<string>\",\n    \"llm_description\": \"<string>\",\n    \"base_url\": \"<string>\",\n    \"api_key\": \"<string>\",\n    \"max_token\": 123\n  },\n  \"tts\": {\n    \"voice_id\": \"<string>\",\n    \"provider\": \"elevenlabs\",\n    \"voice_name\": \"<string>\",\n    \"voice_temperature\": 0.2\n  },\n  \"stt\": {\n    \"provider\": \"<string>\"\n  },\n  \"language_code\": \"en-US\",\n  \"knowledge_base_id\": \"<string>\",\n  \"enable_user_interruptions\": true,\n  \"minimum_speech_duration_for_interruptions\": 0.5,\n  \"minimum_words_before_interruption\": 0,\n  \"wait_time_before_detecting_end_of_speech\": 0.5,\n  \"ambient_sound\": \"none\",\n  \"ambient_sound_volume\": 1,\n  \"webhook_url\": \"<string>\",\n  \"end_call_after_silence_seconds\": 10,\n  \"max_call_duration_seconds\": 1800,\n  \"welcome_message\": \"<string>\",\n  \"voicemail_detection_timeout_seconds\": 90,\n  \"dynamic_data_config\": [\n    {\n      \"url\": \"<string>\",\n      \"response_data\": [\n        {\n          \"name\": \"<string>\",\n          \"data\": \"<string>\",\n          \"context\": \"<string>\"\n        }\n      ],\n      \"method\": \"GET\",\n      \"timeout\": 2000,\n      \"headers\": {},\n      \"body\": {},\n      \"query\": {},\n      \"cache\": true\n    }\n  ],\n  \"post_call_analysis\": [\n    {\n      \"name\": \"<string>\",\n      \"description\": \"<string>\",\n      \"system_prompt\": \"<string>\",\n      \"type\": \"string\",\n      \"examples\": [\n        \"<string>\"\n      ]\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body
{
  "ai_agent_id": "<string>",
  "agent_name": "<string>",
  "llm": {
    "llm_id": "<string>",
    "llm_type": "<string>",
    "model_name": "<string>",
    "system_prompt": "<string>",
    "model_temperature": 0,
    "llm_name": "<string>",
    "llm_description": "<string>",
    "base_url": "<string>",
    "api_key": "<string>",
    "max_tokens": 123,
    "required_dynamic_data": [
      "<string>"
    ],
    "tools": [
      {}
    ]
  },
  "stt": {
    "provider": "<string>"
  },
  "tts": {
    "provider": "<string>",
    "voice_id": "<string>",
    "voice_name": "<string>",
    "voice_temperature": 0.2
  },
  "created_by_user_id": "<string>",
  "language_code": "en-US",
  "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>"
      ]
    }
  ]
}
{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

Body

application/json
​
agent_name
string
required

Name identifier for the AI agent

​
llm
CreateSimplePiaLLMRequest · object
required

Language model configuration for the agent

​
tts
CreateElevenLabsTTSRequest · object
required

Text-to-Speech configuration for voice synthesis

​
stt
CreateDeepgramSTTRequest · object
required

Speech-to-Text configuration for voice recognition

​
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
(CreateStringPostCallAnalysisItemRequest · object | CreateEnumPostCallAnalysisItemRequest · object | CreateBooleanPostCallAnalysisItemRequest · object | CreateNumberPostCallAnalysisItemRequest · object)[] | null

Configuration for analysis items to be processed after the call

Response

Successful Response

​
ai_agent_id
string
required

Unique identifier for the AI agent

​
agent_name
string
required

Name of the AI agent

​
llm
SimplePiaLLMResponse · object
required

Language model configuration for the AI agent

​
stt
DeepgramSTTResponse · object
required

Speech-to-text configuration for the AI agent

​
tts
ElevenLabsTTSResponse · object
required

Text-to-speech configuration for the AI agent

​
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
(StringPostCallAnalysisItemResponse · object | EnumPostCallAnalysisItemResponse · object | BooleanPostCallAnalysisItemResponse · object | NumberPostCallAnalysisItemResponse · object)[] | null

Configuration for analysis items to be processed after calls