Create an agent profile
Create an OPTIONAL agent profile (persona, greeting, voice, 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; agent_id is the deprecated alias); per-call headers (X-PyAI-Voice, X-PyAI-Persona) and the configure frame override profile config. Purely optional sugar over the zero-state primitive — distinct from the upcoming Agents feature (the no-code create/manage/track surface). Requires the omni:session scope.
Authorizations
Use Authorization: Bearer pyai_live_... (or pyai_test_...).
Body
Writable agent fields. On update, present fields are set, null clears, absent fields are untouched.
Display name. Required on create.
200The agent's entire character, role, policies, and business context.
32000Opening line spoken instantly on connect.
1000A stock voice id from GET /v1/voices or a cloned voice id.
Per-agent model selection. Omit for the platform default.
How eagerly the agent yields when talked over: low, normal, high, or an exact dBFS value.
Conversational-acknowledgment mode. Default auto.
Enable stereo call recordings. Default false.
Compliance line spoken first when recordings are enabled.
500Up to 16 key/value annotations (keys ≤64 chars, values ≤512 chars).
Vocabulary-boost terms for speech recognition (stored now; engine biasing rolls out per the keyterms roadmap).
100Goal checklist for post-call outcome scoring (stored now; scoring ships with summaries).
20Response
Created agent
"agent"
"agent_7f3a0b12"
"default"
"normal"
"auto"
Unix seconds.