Skip to main content
POST
Create an agent profile

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
role
enum<string> | null

Role 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.

Available options:
receptionist,
support,
sales,
collections,
ea,
concierge,
custom,
null
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, one of its permanent aliases from GET /v1/voices, or a cloned voice id. Omni reports the canonical served stock id in configured.voice_id.

voice_instruct
string | null

TTS delivery direction for this managed Agent on instruct-capable voice tiers. Omit or set null for PyAI's natural conversational pace; an inline Omni configure.voice_instruct wins for that session.

Maximum string length: 200
brain_model
string | null

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

barge_sensitivity
string | null
deprecated

Deprecated compatibility field. Stored values are not applied to Omni runtime.

ack_mode
string | null
deprecated

Deprecated compatibility field. Stored values are not applied to Omni runtime.

idle_check_in
enum<string> | null

How 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.

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 and must contain a meaningful spoken phrase (at least 10 characters and 5 letters). Playback order: consent_line, then greeting, then conversation.

Required string length: 10 - 500
language
enum<string> | null

Requested language for this Agent's Omni sessions. null or absent means en. Availability is staged: as of 2026-08-13 public serving is en, fr, es, and hi; de falls back to English. Inspect the session's configured.language_active and language_fallback fields before assuming the requested language is active. 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).

vocabulary
string[] | 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.

Maximum array length: 5
Required string length: 4 - 64
keyterms
string[] | null
deprecated

Deprecated stored compatibility field. It does not affect speech recognition. Use vocabulary.

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). Omni configure.tools[] may list hosted catalog names or client-loop schemas; server webhooks must be registered here. An inline configure endpoint is not supported.

continuity
boolean | null

Reuse a tiny caller card on the next call when PyAI can resolve the caller (phone number or a signed customer id). The card is advisory — the agent may recall a name or open thread, and must not refund, book, or transfer from it. Default false.

Response

Created 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
voice_instruct
string

Effective TTS delivery direction for instruct-capable voice tiers. Renders PyAI's natural conversational pace when no override is stored.

brain_model
string
Example:

"default"

barge_sensitivity
string | null
deprecated
ack_mode
string | null
deprecated
idle_check_in
enum<string>

Idle check-in patience. Renders auto when unset, except support agents render patient.

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
enum<string>
read-only

Read-only runtime mode derived from the agent's role (default, receptionist, sales, or collections). Set indirectly via the writable role field.

Available options:
default,
receptionist,
sales,
collections
Example:

"default"

role
string | null

Role archetype the agent runs as, or null. Writable on create and update.

continuity
boolean

Whether this agent reuses a prior-call caller card when a caller key is available. Default false.

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
vocabulary
string[]

Sanitized Agent vocabulary. An empty list means speech-recognition biasing is off.

Maximum array length: 5
Required string length: 4 - 64
keyterms
string[]
deprecated
goals
string[]
metadata
object
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[]
created_at
integer

Unix seconds.