curl --request POST \
--url https://api.pyai.com/v1/agents \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"persona_system_prompt": "<string>",
"greeting": "<string>",
"greeting_variants": [
"<string>"
],
"voice_id": "<string>",
"voice_instruct": "<string>",
"brain_model": "<string>",
"barge_sensitivity": "<string>",
"ack_mode": "<string>",
"platform_guidance": "<string>",
"inherit_org_knowledgebases": true,
"recordings_enabled": true,
"consent_line": "<string>",
"metadata": {},
"vocabulary": [
"<string>"
],
"keyterms": [
"<string>"
],
"goals": [
"<string>"
],
"extraction_schema": {},
"extraction_webhook_url": "<string>",
"tools": [
{
"tool_id": "<string>",
"enabled": true,
"config": {},
"name": "<string>",
"description": "<string>",
"input_schema": {}
}
],
"continuity": true
}
'import requests
url = "https://api.pyai.com/v1/agents"
payload = {
"name": "<string>",
"persona_system_prompt": "<string>",
"greeting": "<string>",
"greeting_variants": ["<string>"],
"voice_id": "<string>",
"voice_instruct": "<string>",
"brain_model": "<string>",
"barge_sensitivity": "<string>",
"ack_mode": "<string>",
"platform_guidance": "<string>",
"inherit_org_knowledgebases": True,
"recordings_enabled": True,
"consent_line": "<string>",
"metadata": {},
"vocabulary": ["<string>"],
"keyterms": ["<string>"],
"goals": ["<string>"],
"extraction_schema": {},
"extraction_webhook_url": "<string>",
"tools": [
{
"tool_id": "<string>",
"enabled": True,
"config": {},
"name": "<string>",
"description": "<string>",
"input_schema": {}
}
],
"continuity": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: '<string>',
persona_system_prompt: '<string>',
greeting: '<string>',
greeting_variants: ['<string>'],
voice_id: '<string>',
voice_instruct: '<string>',
brain_model: '<string>',
barge_sensitivity: '<string>',
ack_mode: '<string>',
platform_guidance: '<string>',
inherit_org_knowledgebases: true,
recordings_enabled: true,
consent_line: '<string>',
metadata: {},
vocabulary: ['<string>'],
keyterms: ['<string>'],
goals: ['<string>'],
extraction_schema: {},
extraction_webhook_url: '<string>',
tools: [
{
tool_id: '<string>',
enabled: true,
config: {},
name: '<string>',
description: '<string>',
input_schema: {}
}
],
continuity: true
})
};
fetch('https://api.pyai.com/v1/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.pyai.com/v1/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([
'name' => '<string>',
'persona_system_prompt' => '<string>',
'greeting' => '<string>',
'greeting_variants' => [
'<string>'
],
'voice_id' => '<string>',
'voice_instruct' => '<string>',
'brain_model' => '<string>',
'barge_sensitivity' => '<string>',
'ack_mode' => '<string>',
'platform_guidance' => '<string>',
'inherit_org_knowledgebases' => true,
'recordings_enabled' => true,
'consent_line' => '<string>',
'metadata' => [
],
'vocabulary' => [
'<string>'
],
'keyterms' => [
'<string>'
],
'goals' => [
'<string>'
],
'extraction_schema' => [
],
'extraction_webhook_url' => '<string>',
'tools' => [
[
'tool_id' => '<string>',
'enabled' => true,
'config' => [
],
'name' => '<string>',
'description' => '<string>',
'input_schema' => [
]
]
],
'continuity' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"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.pyai.com/v1/agents"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"persona_system_prompt\": \"<string>\",\n \"greeting\": \"<string>\",\n \"greeting_variants\": [\n \"<string>\"\n ],\n \"voice_id\": \"<string>\",\n \"voice_instruct\": \"<string>\",\n \"brain_model\": \"<string>\",\n \"barge_sensitivity\": \"<string>\",\n \"ack_mode\": \"<string>\",\n \"platform_guidance\": \"<string>\",\n \"inherit_org_knowledgebases\": true,\n \"recordings_enabled\": true,\n \"consent_line\": \"<string>\",\n \"metadata\": {},\n \"vocabulary\": [\n \"<string>\"\n ],\n \"keyterms\": [\n \"<string>\"\n ],\n \"goals\": [\n \"<string>\"\n ],\n \"extraction_schema\": {},\n \"extraction_webhook_url\": \"<string>\",\n \"tools\": [\n {\n \"tool_id\": \"<string>\",\n \"enabled\": true,\n \"config\": {},\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"input_schema\": {}\n }\n ],\n \"continuity\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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.pyai.com/v1/agents")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"persona_system_prompt\": \"<string>\",\n \"greeting\": \"<string>\",\n \"greeting_variants\": [\n \"<string>\"\n ],\n \"voice_id\": \"<string>\",\n \"voice_instruct\": \"<string>\",\n \"brain_model\": \"<string>\",\n \"barge_sensitivity\": \"<string>\",\n \"ack_mode\": \"<string>\",\n \"platform_guidance\": \"<string>\",\n \"inherit_org_knowledgebases\": true,\n \"recordings_enabled\": true,\n \"consent_line\": \"<string>\",\n \"metadata\": {},\n \"vocabulary\": [\n \"<string>\"\n ],\n \"keyterms\": [\n \"<string>\"\n ],\n \"goals\": [\n \"<string>\"\n ],\n \"extraction_schema\": {},\n \"extraction_webhook_url\": \"<string>\",\n \"tools\": [\n {\n \"tool_id\": \"<string>\",\n \"enabled\": true,\n \"config\": {},\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"input_schema\": {}\n }\n ],\n \"continuity\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.pyai.com/v1/agents")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"persona_system_prompt\": \"<string>\",\n \"greeting\": \"<string>\",\n \"greeting_variants\": [\n \"<string>\"\n ],\n \"voice_id\": \"<string>\",\n \"voice_instruct\": \"<string>\",\n \"brain_model\": \"<string>\",\n \"barge_sensitivity\": \"<string>\",\n \"ack_mode\": \"<string>\",\n \"platform_guidance\": \"<string>\",\n \"inherit_org_knowledgebases\": true,\n \"recordings_enabled\": true,\n \"consent_line\": \"<string>\",\n \"metadata\": {},\n \"vocabulary\": [\n \"<string>\"\n ],\n \"keyterms\": [\n \"<string>\"\n ],\n \"goals\": [\n \"<string>\"\n ],\n \"extraction_schema\": {},\n \"extraction_webhook_url\": \"<string>\",\n \"tools\": [\n {\n \"tool_id\": \"<string>\",\n \"enabled\": true,\n \"config\": {},\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"input_schema\": {}\n }\n ],\n \"continuity\": true\n}"
response = http.request(request)
puts response.read_body{
"object": "agent",
"agent_id": "agent_7f3a0b12",
"name": "<string>",
"persona_system_prompt": "<string>",
"platform_guidance": "<string>",
"prompt_limit_characters": 8000,
"greeting": "<string>",
"greeting_variants": [
"<string>"
],
"voice_id": "<string>",
"voice_instruct": "<string>",
"brain_model": "default",
"barge_sensitivity": "<string>",
"ack_mode": "<string>",
"idle_check_in": "auto",
"persona_perspective": "agent",
"mode": "default",
"role": "<string>",
"continuity": true,
"inherit_org_knowledgebases": true,
"knowledgebases": [
{
"kb_id": "<string>",
"weight": 1
}
],
"recordings_enabled": true,
"consent_line": "<string>",
"language": "en",
"vocabulary": [
"<string>"
],
"keyterms": [
"<string>"
],
"goals": [
"<string>"
],
"metadata": {},
"extraction_schema": {},
"extraction_webhook_url": "<string>",
"tools": [
{
"tool_id": "<string>",
"enabled": true,
"config": {},
"name": "<string>",
"description": "<string>",
"input_schema": {},
"execution": "hosted"
}
],
"created_at": 123
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "invalid_request_error",
"param": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "invalid_request_error",
"param": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "invalid_request_error",
"param": "<string>"
}
}Create an agent profile
Create an OPTIONAL agent profile (persona, greeting message, voice, language, recording disclosure, conversation knobs) so you can reference it by id instead of sending a full configure frame each call. Drive it with wss://api.pyai.com/v1/omni?session_label=agent_… (the profile id doubles as the opaque session label); per-call headers (X-PyAI-Voice, X-PyAI-Persona) and the configure frame override profile config. The engine speaks greeting at turn 0 and consent_line before recording when enabled. Requires the omni:session scope.
curl --request POST \
--url https://api.pyai.com/v1/agents \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"persona_system_prompt": "<string>",
"greeting": "<string>",
"greeting_variants": [
"<string>"
],
"voice_id": "<string>",
"voice_instruct": "<string>",
"brain_model": "<string>",
"barge_sensitivity": "<string>",
"ack_mode": "<string>",
"platform_guidance": "<string>",
"inherit_org_knowledgebases": true,
"recordings_enabled": true,
"consent_line": "<string>",
"metadata": {},
"vocabulary": [
"<string>"
],
"keyterms": [
"<string>"
],
"goals": [
"<string>"
],
"extraction_schema": {},
"extraction_webhook_url": "<string>",
"tools": [
{
"tool_id": "<string>",
"enabled": true,
"config": {},
"name": "<string>",
"description": "<string>",
"input_schema": {}
}
],
"continuity": true
}
'import requests
url = "https://api.pyai.com/v1/agents"
payload = {
"name": "<string>",
"persona_system_prompt": "<string>",
"greeting": "<string>",
"greeting_variants": ["<string>"],
"voice_id": "<string>",
"voice_instruct": "<string>",
"brain_model": "<string>",
"barge_sensitivity": "<string>",
"ack_mode": "<string>",
"platform_guidance": "<string>",
"inherit_org_knowledgebases": True,
"recordings_enabled": True,
"consent_line": "<string>",
"metadata": {},
"vocabulary": ["<string>"],
"keyterms": ["<string>"],
"goals": ["<string>"],
"extraction_schema": {},
"extraction_webhook_url": "<string>",
"tools": [
{
"tool_id": "<string>",
"enabled": True,
"config": {},
"name": "<string>",
"description": "<string>",
"input_schema": {}
}
],
"continuity": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: '<string>',
persona_system_prompt: '<string>',
greeting: '<string>',
greeting_variants: ['<string>'],
voice_id: '<string>',
voice_instruct: '<string>',
brain_model: '<string>',
barge_sensitivity: '<string>',
ack_mode: '<string>',
platform_guidance: '<string>',
inherit_org_knowledgebases: true,
recordings_enabled: true,
consent_line: '<string>',
metadata: {},
vocabulary: ['<string>'],
keyterms: ['<string>'],
goals: ['<string>'],
extraction_schema: {},
extraction_webhook_url: '<string>',
tools: [
{
tool_id: '<string>',
enabled: true,
config: {},
name: '<string>',
description: '<string>',
input_schema: {}
}
],
continuity: true
})
};
fetch('https://api.pyai.com/v1/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.pyai.com/v1/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([
'name' => '<string>',
'persona_system_prompt' => '<string>',
'greeting' => '<string>',
'greeting_variants' => [
'<string>'
],
'voice_id' => '<string>',
'voice_instruct' => '<string>',
'brain_model' => '<string>',
'barge_sensitivity' => '<string>',
'ack_mode' => '<string>',
'platform_guidance' => '<string>',
'inherit_org_knowledgebases' => true,
'recordings_enabled' => true,
'consent_line' => '<string>',
'metadata' => [
],
'vocabulary' => [
'<string>'
],
'keyterms' => [
'<string>'
],
'goals' => [
'<string>'
],
'extraction_schema' => [
],
'extraction_webhook_url' => '<string>',
'tools' => [
[
'tool_id' => '<string>',
'enabled' => true,
'config' => [
],
'name' => '<string>',
'description' => '<string>',
'input_schema' => [
]
]
],
'continuity' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"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.pyai.com/v1/agents"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"persona_system_prompt\": \"<string>\",\n \"greeting\": \"<string>\",\n \"greeting_variants\": [\n \"<string>\"\n ],\n \"voice_id\": \"<string>\",\n \"voice_instruct\": \"<string>\",\n \"brain_model\": \"<string>\",\n \"barge_sensitivity\": \"<string>\",\n \"ack_mode\": \"<string>\",\n \"platform_guidance\": \"<string>\",\n \"inherit_org_knowledgebases\": true,\n \"recordings_enabled\": true,\n \"consent_line\": \"<string>\",\n \"metadata\": {},\n \"vocabulary\": [\n \"<string>\"\n ],\n \"keyterms\": [\n \"<string>\"\n ],\n \"goals\": [\n \"<string>\"\n ],\n \"extraction_schema\": {},\n \"extraction_webhook_url\": \"<string>\",\n \"tools\": [\n {\n \"tool_id\": \"<string>\",\n \"enabled\": true,\n \"config\": {},\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"input_schema\": {}\n }\n ],\n \"continuity\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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.pyai.com/v1/agents")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"persona_system_prompt\": \"<string>\",\n \"greeting\": \"<string>\",\n \"greeting_variants\": [\n \"<string>\"\n ],\n \"voice_id\": \"<string>\",\n \"voice_instruct\": \"<string>\",\n \"brain_model\": \"<string>\",\n \"barge_sensitivity\": \"<string>\",\n \"ack_mode\": \"<string>\",\n \"platform_guidance\": \"<string>\",\n \"inherit_org_knowledgebases\": true,\n \"recordings_enabled\": true,\n \"consent_line\": \"<string>\",\n \"metadata\": {},\n \"vocabulary\": [\n \"<string>\"\n ],\n \"keyterms\": [\n \"<string>\"\n ],\n \"goals\": [\n \"<string>\"\n ],\n \"extraction_schema\": {},\n \"extraction_webhook_url\": \"<string>\",\n \"tools\": [\n {\n \"tool_id\": \"<string>\",\n \"enabled\": true,\n \"config\": {},\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"input_schema\": {}\n }\n ],\n \"continuity\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.pyai.com/v1/agents")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"<string>\",\n \"persona_system_prompt\": \"<string>\",\n \"greeting\": \"<string>\",\n \"greeting_variants\": [\n \"<string>\"\n ],\n \"voice_id\": \"<string>\",\n \"voice_instruct\": \"<string>\",\n \"brain_model\": \"<string>\",\n \"barge_sensitivity\": \"<string>\",\n \"ack_mode\": \"<string>\",\n \"platform_guidance\": \"<string>\",\n \"inherit_org_knowledgebases\": true,\n \"recordings_enabled\": true,\n \"consent_line\": \"<string>\",\n \"metadata\": {},\n \"vocabulary\": [\n \"<string>\"\n ],\n \"keyterms\": [\n \"<string>\"\n ],\n \"goals\": [\n \"<string>\"\n ],\n \"extraction_schema\": {},\n \"extraction_webhook_url\": \"<string>\",\n \"tools\": [\n {\n \"tool_id\": \"<string>\",\n \"enabled\": true,\n \"config\": {},\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"input_schema\": {}\n }\n ],\n \"continuity\": true\n}"
response = http.request(request)
puts response.read_body{
"object": "agent",
"agent_id": "agent_7f3a0b12",
"name": "<string>",
"persona_system_prompt": "<string>",
"platform_guidance": "<string>",
"prompt_limit_characters": 8000,
"greeting": "<string>",
"greeting_variants": [
"<string>"
],
"voice_id": "<string>",
"voice_instruct": "<string>",
"brain_model": "default",
"barge_sensitivity": "<string>",
"ack_mode": "<string>",
"idle_check_in": "auto",
"persona_perspective": "agent",
"mode": "default",
"role": "<string>",
"continuity": true,
"inherit_org_knowledgebases": true,
"knowledgebases": [
{
"kb_id": "<string>",
"weight": 1
}
],
"recordings_enabled": true,
"consent_line": "<string>",
"language": "en",
"vocabulary": [
"<string>"
],
"keyterms": [
"<string>"
],
"goals": [
"<string>"
],
"metadata": {},
"extraction_schema": {},
"extraction_webhook_url": "<string>",
"tools": [
{
"tool_id": "<string>",
"enabled": true,
"config": {},
"name": "<string>",
"description": "<string>",
"input_schema": {},
"execution": "hosted"
}
],
"created_at": 123
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "invalid_request_error",
"param": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "invalid_request_error",
"param": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "invalid_request_error",
"param": "<string>"
}
}Authorizations
Body
Writable agent fields. On update, present fields are set, null clears, absent fields are untouched.
Customer-authored agent instructions: 8,000 Unicode characters by default, or 32,000 with an active monthly commitment plan. Read prompt_limit_characters on the agent for your allowance. Platform conversation and safety guidance is applied separately and does not count toward this allowance. This is a character limit, not a token count.
32000Role archetype. Adds PyAI's role operating standard beneath your persona and derives the runtime mode (receptionist, sales, and collections enable their matching deterministic conversation guards; everything else runs the default mode). Your stored persona is unchanged and remains authoritative for identity and business policy. Null clears the role.
receptionist, support, sales, collections, ea, concierge, custom, null Stored delivery direction for instruct-capable voice tiers. Current Omni routes support neutral delivery only: omit or set null for neutral speech. A saved custom value is rejected when configuring Omni; an inline empty configure.voice_instruct resets it to neutral for that session.
200How patient the agent is before checking in on a silent caller ("Sorry, are you still there?"). auto checks in after a few seconds of silence; patient waits far longer, for callers who routinely think, read, or look something up mid-call; off disables the check-in entirely, so the agent stays silent until the caller speaks. When unset, most roles render auto; support agents render patient. Independent of ack_mode. May also be sent inline in the Omni configure frame, which wins for that session.
auto, patient, off, null Which side of the call the persona is on. agent (default) means the persona is the business being called, so PyAI adds its conversation layer for handling a caller (capability honesty, handoffs, turn discipline). caller means the persona is the individual on the call instead, as in QA and simulation callers, mystery shopping, or training partners; PyAI drops that operator-voice layer so it cannot contradict an inverted persona. May also be sent inline in the Omni configure frame, which wins for that session.
agent, caller, null Integration-owned setup guidance. Requires an explicitly enrolled server credential; ordinary customer keys receive 403. Separate from persona_system_prompt and its account allowance. Published before the customer instructions without truncation.
12000Recording disclosure spoken before recording starts when recordings_enabled is true. Required for compliance when recordings are on and must contain a meaningful spoken phrase (at least 10 characters and 5 letters). Playback order: consent_line, then greeting, then conversation.
10 - 500Requested language for this Agent's Omni sessions. null or absent means en. Availability is staged: public serving includes en, fr, es, hi, it, pt, ja, and ko; de and the legacy zh alias fall back to English unless explicitly enabled with qualified endpoints. Canonical staged route identifiers are exposed in x-staged-language-ids for internal integration only and are rejected by the public control plane until qualified. Inspect the session's configured.language_active and language_fallback fields before assuming the requested language is active. See the Language support reference.
en, fr, es, de, hi, zh, it, pt, ja, ko, null Optional custom vocabulary for this Agent's Omni speech recognition. A non-empty list is the opt-in. PyAI keeps at most five effective terms, with at most five words per term. It trims whitespace, deduplicates without regard to case while preserving the first spelling and order, and drops common-only phrases. Set [] or null to turn it off. The list is fixed when a session starts. Organization Hear vocabulary is never applied to Omni.
54 - 64Response
Created agent