Skip to main content
POST
/
v1
/
agents
Create an agent profile
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>",
  "voice_id": "<string>",
  "brain_model": "<string>",
  "barge_sensitivity": "<string>",
  "ack_mode": "<string>",
  "recordings_enabled": true,
  "consent_line": "<string>",
  "metadata": {},
  "keyterms": [
    "<string>"
  ],
  "goals": [
    "<string>"
  ]
}
'
{
  "object": "agent",
  "agent_id": "agent_7f3a0b12",
  "name": "<string>",
  "persona_system_prompt": "<string>",
  "greeting": "<string>",
  "voice_id": "<string>",
  "brain_model": "default",
  "barge_sensitivity": "normal",
  "ack_mode": "auto",
  "recordings_enabled": true,
  "consent_line": "<string>",
  "keyterms": [
    "<string>"
  ],
  "goals": [
    "<string>"
  ],
  "metadata": {},
  "created_at": 123
}

Authorizations

Authorization
string
header
required

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

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

Opening line spoken instantly on connect.

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.

recordings_enabled
boolean | null

Enable stereo call recordings. Default false.

Compliance line spoken first when recordings are enabled.

Maximum string length: 500
metadata
object

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

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

Response

Created agent

object
string
Example:

"agent"

agent_id
string
Example:

"agent_7f3a0b12"

name
string
persona_system_prompt
string | null
greeting
string | null
voice_id
string | null
brain_model
string
Example:

"default"

barge_sensitivity
string
Example:

"normal"

ack_mode
string
Example:

"auto"

recordings_enabled
boolean
keyterms
string[]
goals
string[]
metadata
object
created_at
integer

Unix seconds.