Update an agent

curl --request POST \
  --url https://api.pyai.com/v1/agents/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "persona_system_prompt": "<string>",
  "greeting": "<string>",
  "greeting_variants": [
    "<string>"
  ],
  "voice_id": "<string>",
  "brain_model": "<string>",
  "barge_sensitivity": "<string>",
  "ack_mode": "<string>",
  "recordings_enabled": true,
  "consent_line": "<string>",
  "metadata": {},
  "keyterms": [
    "<string>"
  ],
  "goals": [
    "<string>"
  ],
  "extraction_schema": {},
  "extraction_webhook_url": "<string>",
  "tools": [
    {
      "tool_id": "<string>",
      "enabled": true,
      "config": {},
      "name": "<string>",
      "description": "<string>",
      "input_schema": {}
    }
  ]
}
'

import requests

url = "https://api.pyai.com/v1/agents/{id}"

payload = {
    "name": "<string>",
    "persona_system_prompt": "<string>",
    "greeting": "<string>",
    "greeting_variants": ["<string>"],
    "voice_id": "<string>",
    "brain_model": "<string>",
    "barge_sensitivity": "<string>",
    "ack_mode": "<string>",
    "recordings_enabled": True,
    "consent_line": "<string>",
    "metadata": {},
    "keyterms": ["<string>"],
    "goals": ["<string>"],
    "extraction_schema": {},
    "extraction_webhook_url": "<string>",
    "tools": [
        {
            "tool_id": "<string>",
            "enabled": True,
            "config": {},
            "name": "<string>",
            "description": "<string>",
            "input_schema": {}
        }
    ]
}
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>',
    brain_model: '<string>',
    barge_sensitivity: '<string>',
    ack_mode: '<string>',
    recordings_enabled: true,
    consent_line: '<string>',
    metadata: {},
    keyterms: ['<string>'],
    goals: ['<string>'],
    extraction_schema: {},
    extraction_webhook_url: '<string>',
    tools: [
      {
        tool_id: '<string>',
        enabled: true,
        config: {},
        name: '<string>',
        description: '<string>',
        input_schema: {}
      }
    ]
  })
};

fetch('https://api.pyai.com/v1/agents/{id}', 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/{id}",
  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>',
    'brain_model' => '<string>',
    'barge_sensitivity' => '<string>',
    'ack_mode' => '<string>',
    'recordings_enabled' => true,
    'consent_line' => '<string>',
    'metadata' => [
        
    ],
    'keyterms' => [
        '<string>'
    ],
    'goals' => [
        '<string>'
    ],
    'extraction_schema' => [
        
    ],
    'extraction_webhook_url' => '<string>',
    'tools' => [
        [
                'tool_id' => '<string>',
                'enabled' => true,
                'config' => [
                                
                ],
                'name' => '<string>',
                'description' => '<string>',
                'input_schema' => [
                                
                ]
        ]
    ]
  ]),
  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/{id}"

	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  \"brain_model\": \"<string>\",\n  \"barge_sensitivity\": \"<string>\",\n  \"ack_mode\": \"<string>\",\n  \"recordings_enabled\": true,\n  \"consent_line\": \"<string>\",\n  \"metadata\": {},\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}")

	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/{id}")
  .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  \"brain_model\": \"<string>\",\n  \"barge_sensitivity\": \"<string>\",\n  \"ack_mode\": \"<string>\",\n  \"recordings_enabled\": true,\n  \"consent_line\": \"<string>\",\n  \"metadata\": {},\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}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.pyai.com/v1/agents/{id}")

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  \"brain_model\": \"<string>\",\n  \"barge_sensitivity\": \"<string>\",\n  \"ack_mode\": \"<string>\",\n  \"recordings_enabled\": true,\n  \"consent_line\": \"<string>\",\n  \"metadata\": {},\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}"

response = http.request(request)
puts response.read_body

{
  "object": "agent",
  "agent_id": "agent_7f3a0b12",
  "name": "<string>",
  "persona_system_prompt": "<string>",
  "greeting": "<string>",
  "greeting_variants": [
    "<string>"
  ],
  "voice_id": "<string>",
  "brain_model": "default",
  "barge_sensitivity": "normal",
  "ack_mode": "auto",
  "mode": "default",
  "role": "<string>",
  "recordings_enabled": true,
  "consent_line": "<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": {}
    }
  ],
  "created_at": 123
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>"
  }
}

POST

agents

{id}

Update an agent

curl --request POST \
  --url https://api.pyai.com/v1/agents/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "persona_system_prompt": "<string>",
  "greeting": "<string>",
  "greeting_variants": [
    "<string>"
  ],
  "voice_id": "<string>",
  "brain_model": "<string>",
  "barge_sensitivity": "<string>",
  "ack_mode": "<string>",
  "recordings_enabled": true,
  "consent_line": "<string>",
  "metadata": {},
  "keyterms": [
    "<string>"
  ],
  "goals": [
    "<string>"
  ],
  "extraction_schema": {},
  "extraction_webhook_url": "<string>",
  "tools": [
    {
      "tool_id": "<string>",
      "enabled": true,
      "config": {},
      "name": "<string>",
      "description": "<string>",
      "input_schema": {}
    }
  ]
}
'

import requests

url = "https://api.pyai.com/v1/agents/{id}"

payload = {
    "name": "<string>",
    "persona_system_prompt": "<string>",
    "greeting": "<string>",
    "greeting_variants": ["<string>"],
    "voice_id": "<string>",
    "brain_model": "<string>",
    "barge_sensitivity": "<string>",
    "ack_mode": "<string>",
    "recordings_enabled": True,
    "consent_line": "<string>",
    "metadata": {},
    "keyterms": ["<string>"],
    "goals": ["<string>"],
    "extraction_schema": {},
    "extraction_webhook_url": "<string>",
    "tools": [
        {
            "tool_id": "<string>",
            "enabled": True,
            "config": {},
            "name": "<string>",
            "description": "<string>",
            "input_schema": {}
        }
    ]
}
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>',
    brain_model: '<string>',
    barge_sensitivity: '<string>',
    ack_mode: '<string>',
    recordings_enabled: true,
    consent_line: '<string>',
    metadata: {},
    keyterms: ['<string>'],
    goals: ['<string>'],
    extraction_schema: {},
    extraction_webhook_url: '<string>',
    tools: [
      {
        tool_id: '<string>',
        enabled: true,
        config: {},
        name: '<string>',
        description: '<string>',
        input_schema: {}
      }
    ]
  })
};

fetch('https://api.pyai.com/v1/agents/{id}', 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/{id}",
  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>',
    'brain_model' => '<string>',
    'barge_sensitivity' => '<string>',
    'ack_mode' => '<string>',
    'recordings_enabled' => true,
    'consent_line' => '<string>',
    'metadata' => [
        
    ],
    'keyterms' => [
        '<string>'
    ],
    'goals' => [
        '<string>'
    ],
    'extraction_schema' => [
        
    ],
    'extraction_webhook_url' => '<string>',
    'tools' => [
        [
                'tool_id' => '<string>',
                'enabled' => true,
                'config' => [
                                
                ],
                'name' => '<string>',
                'description' => '<string>',
                'input_schema' => [
                                
                ]
        ]
    ]
  ]),
  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/{id}"

	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  \"brain_model\": \"<string>\",\n  \"barge_sensitivity\": \"<string>\",\n  \"ack_mode\": \"<string>\",\n  \"recordings_enabled\": true,\n  \"consent_line\": \"<string>\",\n  \"metadata\": {},\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}")

	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/{id}")
  .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  \"brain_model\": \"<string>\",\n  \"barge_sensitivity\": \"<string>\",\n  \"ack_mode\": \"<string>\",\n  \"recordings_enabled\": true,\n  \"consent_line\": \"<string>\",\n  \"metadata\": {},\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}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.pyai.com/v1/agents/{id}")

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  \"brain_model\": \"<string>\",\n  \"barge_sensitivity\": \"<string>\",\n  \"ack_mode\": \"<string>\",\n  \"recordings_enabled\": true,\n  \"consent_line\": \"<string>\",\n  \"metadata\": {},\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}"

response = http.request(request)
puts response.read_body

{
  "object": "agent",
  "agent_id": "agent_7f3a0b12",
  "name": "<string>",
  "persona_system_prompt": "<string>",
  "greeting": "<string>",
  "greeting_variants": [
    "<string>"
  ],
  "voice_id": "<string>",
  "brain_model": "default",
  "barge_sensitivity": "normal",
  "ack_mode": "auto",
  "mode": "default",
  "role": "<string>",
  "recordings_enabled": true,
  "consent_line": "<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": {}
    }
  ],
  "created_at": 123
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>"
  }
}

{
  "error": {
    "message": "<string>",
    "type": "<string>",
    "param": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Use Authorization: Bearer pyai_live_... (or pyai_test_...).

Path Parameters

string

required

Body

application/json

Writable agent fields. On update, present fields are set, null clears, absent fields are untouched.

name

string

Display name. Required on create.

Maximum string length: 200

persona_system_prompt

string | null

The agent's entire character, role, policies, and business context.

Maximum string length: 32000

greeting

string | null

Greeting message, opening line spoken at turn 0 when a call connects (before the caller speaks). Stored on the agent profile; played automatically when connecting with session_label={agent_id}. May also be sent inline in the Omni configure frame.

Maximum string length: 1000

greeting_variants

string[] | null

Approved opening-line variants. PyAI selects one for each newly resolved call profile; null or empty falls back to greeting. Recording consent is fixed and never rotated.

Maximum array length: 15

Maximum string length: 1000

voice_id

string | null

A stock voice id from GET /v1/voices or a cloned voice id.

brain_model

string | null

Per-agent model selection. Omit for the platform default.

barge_sensitivity

string | null

How eagerly the agent yields when talked over: low, normal, high, or an exact dBFS value.

ack_mode

string | null

Conversational-acknowledgment mode. Default auto.

idle_check_in

enum<string> | null

How patient the agent is before checking in on a silent caller ("Sorry, are you still there?"). auto (default) 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. Independent of ack_mode. May also be sent inline in the Omni configure frame, which wins for that session.

Available options:

auto,

patient,

off,

null

persona_perspective

enum<string> | 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.

Available options:

agent,

caller,

null

recordings_enabled

boolean | null

Enable stereo call recordings. Default false.

Recording disclosure spoken before recording starts when recordings_enabled is true. Required for compliance when recordings are on. Playback order: consent_line, then greeting, then conversation.

Maximum string length: 500

language

enum<string> | null

The language this agent's Omni sessions run in, end to end (recognition, reasoning, and voice). null or absent means the default, en, identical to pre-multilingual behavior. Hindi is served on the standard voice tier by default; the natural (telephony premium) tier bills an add-on per minute, see Pricing. Availability per language is staged, see the Language support reference.

Available options:

en,

fr,

es,

de,

hi,

null

metadata

object | null

Up to 16 key/value annotations (keys ≤64 chars, values ≤512 chars).

Show child attributes

keyterms

string[] | null

Vocabulary-boost terms for speech recognition (stored now; engine biasing rolls out per the keyterms roadmap).

Maximum array length: 100

goals

string[] | null

Goal checklist for post-call outcome scoring (stored now; scoring ships with summaries).

Maximum array length: 20

extraction_schema

object | null

JSON Schema of fields to capture from each completed call's transcript. When set with extraction_webhook_url, PyAI runs a post-call extraction pass and POSTs the structured JSON to your webhook (signed with X-PyAI-Signature). Null disables extraction.

extraction_webhook_url

string<uri> | null

HTTPS URL that receives the signed post-call extraction result (event omni.call.extracted). Requires extraction_schema. The call's agent is resolved from the connect-URL session_label when it equals this agent's id.

tools

object[] | null

Tool bindings for this agent profile (references tools from GET /v1/tools). Inline Omni configure.tools[] definitions are separate, see the Omni protocol docs.

Show child attributes

Response

Updated agent

object

string

Example:

"agent"

agent_id

string

Example:

"agent_7f3a0b12"

name

string

persona_system_prompt

string | null

greeting

string | null

greeting_variants

string[]

Maximum array length: 15

voice_id

string | null

brain_model

string

Example:

"default"

barge_sensitivity

string

Example:

"normal"

ack_mode

string

Example:

"auto"

idle_check_in

enum<string>

Idle check-in patience. Renders the effective default (auto) when unset.

Available options:

auto,

patient,

off

persona_perspective

enum<string>

Which side of the call the persona is on. Renders the effective default (agent) when unset.

Available options:

agent,

caller

mode

string

read-only

Read-only runtime mode derived from the agent's role (default, sales, or collections). Set indirectly by choosing a role in the console; not writable through this API.

Example:

"default"

role

string | null

read-only

Read-only archetype the agent was created from, or null. Set in the console; not writable through this API.

recordings_enabled

boolean

language

enum<string>

Session language for this agent's calls. Renders the effective default (en) when unset.

Available options:

en,

fr,

es,

de,

hi

keyterms

string[]

goals

string[]

metadata

object

Show child attributes

extraction_schema

object | null

Post-call extraction JSON Schema, or null.

extraction_webhook_url

string | null

Signed delivery target for post-call extraction, or null.

tools

object[]

Show child attributes

created_at

integer

Unix seconds.

Identity

Call Integrations

Sandbox

Models

Hear

Speak

Agents

Studio

Transcription Jobs

Trace

Recap

Integrations

AMD

Omni

Knowledge Bases

Telephony

Realtime

Update an agent

Authorizations

Path Parameters

Body

Response