{ "version": "0.3.2", "endpoint": "https://api.pyai.com/mcp", "authoritative": "tools/list on the connected MCP server", "tools": [ { "name": "get_started", "description": "Return a concise, correct quickstart for building with PyAI (auth, SDK install, TTS/STT/realtime snippets, error handling). No key or network needed, read this before writing PyAI code so you use the right endpoints and the official SDK.", "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false }, "title": "Get Started", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "securitySchemes": [ { "type": "noauth" } ] } }, { "name": "whoami", "description": "Introspect the active key (GET /v1/me): org, environment (test/live), granted scopes, and rate-limit/credit posture. Use it to self-diagnose a 401/403/402.", "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false }, "title": "Who Am I", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "noauth" } ] } }, { "name": "list_models", "description": "List the available PyAI models (catalog). No arguments.", "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false }, "title": "List Models", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "noauth" } ] } }, { "name": "list_voices", "description": "List PyAI stock + cloned voices. Optionally filter by gender or region. Use a returned voice id as the `voice` for synthesize_speech.", "inputSchema": { "type": "object", "properties": { "gender": { "type": "string", "description": "Filter by voice gender (e.g. female, male)." }, "region": { "type": "string", "description": "Filter by accent/region (e.g. en_us, en_gb)." } }, "additionalProperties": false }, "title": "List Voices", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "noauth" } ] } }, { "name": "synthesize_speech", "description": "Text-to-speech. Synthesizes `input` with `voice` and writes the audio to `output_path`. Returns the file path and byte count. Note: consumes sandbox usage quota, for writing app code, prefer get_started over running this.", "inputSchema": { "type": "object", "properties": { "input": { "type": "string", "description": "Text to synthesize." }, "voice": { "type": "string", "description": "Voice id from list_voices. Omit for the account default." }, "output_path": { "type": "string", "description": "Absolute file path to write the audio to." }, "model": { "type": "string", "description": "Defaults to pyai-speak." }, "response_format": { "type": "string", "enum": [ "wav", "mp3", "opus", "pcm" ], "description": "Defaults to wav." } }, "required": [ "input" ], "additionalProperties": false }, "title": "Synthesize Speech", "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "oauth2", "scopes": [ "speak:synthesize" ] } ] } }, { "name": "create_transcription_job", "description": "Submit an async speech-to-text job for an audio URL (https). Returns a job_id; poll with get_transcription_job. Supports diarization.", "inputSchema": { "type": "object", "properties": { "audio_url": { "type": "string", "description": "https URL of the audio to transcribe." }, "model": { "type": "string" }, "diarize": { "type": "boolean", "description": "Single-track speaker diarization." }, "channel": { "type": "boolean", "description": "Dual-channel (stereo) per-channel speakers." }, "call_id": { "type": "string", "description": "Stable id for the post-call Recap. Defaults to the job id." }, "pack_id": { "type": "string", "description": "Optional Recap pack (default sales_outbound)." }, "call_direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "customer_name": { "type": "string" }, "output_formats": { "type": "array", "items": { "type": "string", "enum": [ "json", "srt", "vtt" ] }, "description": "Defaults to [json]." } }, "required": [ "audio_url" ], "additionalProperties": false }, "title": "Create Transcription Job", "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "oauth2", "scopes": [ "transcribe:jobs" ] } ] } }, { "name": "get_transcription_job", "description": "Get the status + result of a transcription job by id.", "inputSchema": { "type": "object", "properties": { "job_id": { "type": "string", "description": "The job_id from create_transcription_job." } }, "required": [ "job_id" ], "additionalProperties": false }, "title": "Get Transcription Job", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "oauth2", "scopes": [ "transcribe:jobs" ] } ] } }, { "name": "configure_amd", "description": "Set the PyAI AMD (answering-machine detection) operating point + webhook (POST /v1/amd/config). `aggressiveness` is one dial 0-1: near 0 is human-safe (never hang up on a person), near 1 fires 'machine' fast. The realtime detection itself is a Twilio Media Streams WebSocket (wss /v1/amd/stream), a one-line-TwiML drop-in, not an MCP tool.", "inputSchema": { "type": "object", "properties": { "aggressiveness": { "type": "number", "minimum": 0, "maximum": 1, "description": "Operating point 0-1 (default 0.25)." }, "webhook_url": { "type": "string", "description": "https URL to POST amd.call.completed events to." } }, "additionalProperties": false }, "title": "Configure AMD", "annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": false, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "oauth2", "scopes": [ "amd:configure" ] } ] } }, { "name": "list_amd_calls", "description": "List recent PyAI AMD decisions (GET /v1/amd/calls). Each carries answered_by (human/voicemail/ivr/screening/sit_invalid/…), answered_by_twilio (Twilio's enum, for routing parity), confidence, decision_ms, and the word-level reason.", "inputSchema": { "type": "object", "properties": { "limit": { "type": "number", "description": "Max results (1-100, default 20)." }, "session_label": { "type": "string", "description": "Filter by the opaque connect-URL/TwiML tag." } }, "additionalProperties": false }, "title": "List AMD Calls", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "oauth2", "scopes": [ "amd:read" ] } ] } }, { "name": "get_amd_call", "description": "Get one PyAI AMD decision by call id (GET /v1/amd/calls/{id}): who/what answered, with the reason.", "inputSchema": { "type": "object", "properties": { "call_id": { "type": "string", "description": "The call id the decision was recorded under." } }, "required": [ "call_id" ], "additionalProperties": false }, "title": "Get AMD Call", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "oauth2", "scopes": [ "amd:read" ] } ] } }, { "name": "enable_recap", "description": "Enable Recap for the key's org (PUT /v1/recap/config). Sandbox keys already mint with Recap on; call this to set a webhook or pack, or to enable Recap on a signup/live key. Requires recap:configure.", "inputSchema": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Defaults to true." }, "webhook_url": { "type": "string", "description": "https URL for recap.complete events." }, "default_pack_id": { "type": "string", "description": "Defaults to sales_outbound." } }, "additionalProperties": false }, "title": "Enable Recap", "annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": false, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "oauth2", "scopes": [ "recap:configure" ] } ] } }, { "name": "create_recap", "description": "Submit speaker-labelled utterances and get a recap.call (POST /v1/recap/calls/{call_id}). Poll with get_recap. Prefer this over a DIY LLM summary. Requires recap:read and Recap enabled.", "inputSchema": { "type": "object", "properties": { "call_id": { "type": "string", "description": "Stable id you will read back." }, "utterances": { "type": "array", "items": { "type": "object", "properties": { "speaker_role": { "type": "string", "enum": [ "agent", "customer" ] }, "text": { "type": "string" }, "offset_s": { "type": "number" }, "duration_s": { "type": "number" } }, "required": [ "speaker_role", "text", "offset_s", "duration_s" ] } }, "pack_id": { "type": "string" }, "call_direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "customer_name": { "type": "string" } }, "required": [ "call_id", "utterances" ], "additionalProperties": false }, "title": "Create Recap", "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "oauth2", "scopes": [ "recap:read" ] } ] } }, { "name": "get_recap", "description": "Read one Recap by call id (GET /v1/recap/calls/{call_id}). When complete, `record` is recap.record.v1 (tldr, summary, action_items, disposition, next_steps, talk_ratio, signals, fields).", "inputSchema": { "type": "object", "properties": { "call_id": { "type": "string", "description": "The call_id passed to create_recap or the Hear job." } }, "required": [ "call_id" ], "additionalProperties": false }, "title": "Get Recap", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "oauth2", "scopes": [ "recap:read" ] } ] } }, { "name": "list_recap_calls", "description": "List recent Recap records (GET /v1/recap/calls). Requires recap:read and Recap enabled.", "inputSchema": { "type": "object", "properties": { "limit": { "type": "number", "description": "Max results (1-100, default 20)." }, "status": { "type": "string", "enum": [ "pending", "processing", "complete", "failed" ] } }, "additionalProperties": false }, "title": "List Recap Calls", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "oauth2", "scopes": [ "recap:read" ] } ] } }, { "name": "list_agents", "title": "List Agents", "description": "List saved voice Agent profiles before creating or changing one.", "inputSchema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "oauth2", "scopes": [ "omni:session" ] } ] } }, { "name": "create_agent", "title": "Create Agent", "description": "Create a reusable voice Agent profile: persona, greeting, voice, language, tools and knowledge. Does not place a call.", "inputSchema": { "type": "object", "properties": { "body": { "type": "object", "description": "Writable agent fields. On update, present fields are set, `null` clears, absent fields are untouched.", "properties": { "name": { "type": "string", "maxLength": 200, "description": "Display name. Required on create." }, "persona_system_prompt": { "type": [ "string", "null" ], "maxLength": 32000, "description": "The agent's entire character, role, policies, and business context." }, "role": { "type": [ "string", "null" ], "enum": [ "receptionist", "support", "sales", "collections", "ea", "concierge", "custom", null ], "description": "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." }, "greeting": { "type": [ "string", "null" ], "maxLength": 1000, "description": "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." }, "greeting_variants": { "type": [ "array", "null" ], "maxItems": 15, "items": { "type": "string", "maxLength": 1000 }, "description": "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." }, "voice_id": { "type": [ "string", "null" ], "description": "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": { "type": [ "string", "null" ], "maxLength": 200, "description": "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." }, "brain_model": { "type": [ "string", "null" ], "description": "Per-agent model selection. Omit for the platform default." }, "barge_sensitivity": { "type": [ "string", "null" ], "deprecated": true, "description": "Deprecated compatibility field. Stored values are not applied to Omni runtime." }, "ack_mode": { "type": [ "string", "null" ], "deprecated": true, "description": "Deprecated compatibility field. Stored values are not applied to Omni runtime." }, "idle_check_in": { "type": [ "string", "null" ], "enum": [ "auto", "patient", "off", null ], "description": "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." }, "persona_perspective": { "type": [ "string", "null" ], "enum": [ "agent", "caller", null ], "description": "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." }, "recordings_enabled": { "type": [ "boolean", "null" ], "description": "Enable stereo call recordings. Default false." }, "consent_line": { "type": [ "string", "null" ], "minLength": 10, "maxLength": 500, "description": "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." }, "language": { "type": [ "string", "null" ], "enum": [ "en", "fr", "es", "de", "hi", null ], "description": "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." }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Up to 16 key/value annotations (keys ≤64 chars, values ≤512 chars)." }, "vocabulary": { "type": [ "array", "null" ], "maxItems": 5, "items": { "type": "string", "minLength": 4, "maxLength": 64 }, "description": "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." }, "keyterms": { "type": [ "array", "null" ], "items": { "type": "string" }, "maxItems": 100, "deprecated": true, "description": "Deprecated stored compatibility field. It does not affect speech recognition. Use `vocabulary`." }, "goals": { "type": [ "array", "null" ], "items": { "type": "string" }, "maxItems": 20, "description": "Goal checklist for post-call outcome scoring (stored now; scoring ships with summaries)." }, "extraction_schema": { "type": [ "object", "null" ], "additionalProperties": true, "description": "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": { "type": [ "string", "null" ], "format": "uri", "description": "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": { "type": [ "array", "null" ], "items": { "type": "object", "required": [ "tool_id" ], "properties": { "tool_id": { "type": "string" }, "enabled": { "type": "boolean", "default": true }, "config": { "type": "object", "additionalProperties": true, "description": "Customer SETTINGS for this tool on this agent, keyed by the tool's config_schema field keys (e.g. { from_number, provider_api_key }). Fields marked secret are encrypted at rest and returned masked ('********'); re-send the mask (or omit) to keep the stored value." }, "name": { "type": "string", "description": "Present on agent reads when the tool resolves." }, "description": { "type": "string" }, "input_schema": { "type": "object", "additionalProperties": true, "description": "Per-call model argument schema. Present on agent reads when the tool resolves." }, "execution": { "type": "string", "enum": [ "hosted", "server", "engine", "client" ], "description": "Resolved execution mode. Present on agent reads when the tool resolves." } } }, "description": "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": { "type": [ "boolean", "null" ], "description": "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." } } } }, "required": [ "body" ], "additionalProperties": false }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "oauth2", "scopes": [ "omni:session" ] } ] } }, { "name": "get_agent", "title": "Get Agent", "description": "Read a saved voice Agent profile and its current configuration.", "inputSchema": { "type": "object", "properties": { "id": { "type": "string", "description": "Agent id, e.g. `agent_7f3a…`." } }, "required": [ "id" ], "additionalProperties": false }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "oauth2", "scopes": [ "omni:session" ] } ] } }, { "name": "update_agent", "title": "Update Agent", "description": "Update a voice Agent profile. Read it first and change only user-requested fields.", "inputSchema": { "type": "object", "properties": { "id": { "type": "string" }, "body": { "type": "object", "description": "Writable agent fields. On update, present fields are set, `null` clears, absent fields are untouched.", "properties": { "name": { "type": "string", "maxLength": 200, "description": "Display name. Required on create." }, "persona_system_prompt": { "type": [ "string", "null" ], "maxLength": 32000, "description": "The agent's entire character, role, policies, and business context." }, "role": { "type": [ "string", "null" ], "enum": [ "receptionist", "support", "sales", "collections", "ea", "concierge", "custom", null ], "description": "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." }, "greeting": { "type": [ "string", "null" ], "maxLength": 1000, "description": "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." }, "greeting_variants": { "type": [ "array", "null" ], "maxItems": 15, "items": { "type": "string", "maxLength": 1000 }, "description": "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." }, "voice_id": { "type": [ "string", "null" ], "description": "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": { "type": [ "string", "null" ], "maxLength": 200, "description": "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." }, "brain_model": { "type": [ "string", "null" ], "description": "Per-agent model selection. Omit for the platform default." }, "barge_sensitivity": { "type": [ "string", "null" ], "deprecated": true, "description": "Deprecated compatibility field. Stored values are not applied to Omni runtime." }, "ack_mode": { "type": [ "string", "null" ], "deprecated": true, "description": "Deprecated compatibility field. Stored values are not applied to Omni runtime." }, "idle_check_in": { "type": [ "string", "null" ], "enum": [ "auto", "patient", "off", null ], "description": "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." }, "persona_perspective": { "type": [ "string", "null" ], "enum": [ "agent", "caller", null ], "description": "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." }, "recordings_enabled": { "type": [ "boolean", "null" ], "description": "Enable stereo call recordings. Default false." }, "consent_line": { "type": [ "string", "null" ], "minLength": 10, "maxLength": 500, "description": "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." }, "language": { "type": [ "string", "null" ], "enum": [ "en", "fr", "es", "de", "hi", null ], "description": "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." }, "metadata": { "type": [ "object", "null" ], "additionalProperties": { "type": "string" }, "description": "Up to 16 key/value annotations (keys ≤64 chars, values ≤512 chars)." }, "vocabulary": { "type": [ "array", "null" ], "maxItems": 5, "items": { "type": "string", "minLength": 4, "maxLength": 64 }, "description": "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." }, "keyterms": { "type": [ "array", "null" ], "items": { "type": "string" }, "maxItems": 100, "deprecated": true, "description": "Deprecated stored compatibility field. It does not affect speech recognition. Use `vocabulary`." }, "goals": { "type": [ "array", "null" ], "items": { "type": "string" }, "maxItems": 20, "description": "Goal checklist for post-call outcome scoring (stored now; scoring ships with summaries)." }, "extraction_schema": { "type": [ "object", "null" ], "additionalProperties": true, "description": "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": { "type": [ "string", "null" ], "format": "uri", "description": "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": { "type": [ "array", "null" ], "items": { "type": "object", "required": [ "tool_id" ], "properties": { "tool_id": { "type": "string" }, "enabled": { "type": "boolean", "default": true }, "config": { "type": "object", "additionalProperties": true, "description": "Customer SETTINGS for this tool on this agent, keyed by the tool's config_schema field keys (e.g. { from_number, provider_api_key }). Fields marked secret are encrypted at rest and returned masked ('********'); re-send the mask (or omit) to keep the stored value." }, "name": { "type": "string", "description": "Present on agent reads when the tool resolves." }, "description": { "type": "string" }, "input_schema": { "type": "object", "additionalProperties": true, "description": "Per-call model argument schema. Present on agent reads when the tool resolves." }, "execution": { "type": "string", "enum": [ "hosted", "server", "engine", "client" ], "description": "Resolved execution mode. Present on agent reads when the tool resolves." } } }, "description": "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": { "type": [ "boolean", "null" ], "description": "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." } } } }, "required": [ "id", "body" ], "additionalProperties": false }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "oauth2", "scopes": [ "omni:session" ] } ] } }, { "name": "set_agent_tools", "title": "Set Agent Tools", "description": "Replace the tools bound to an Agent. Read the current Agent first; this replaces its bindings.", "inputSchema": { "type": "object", "properties": { "id": { "type": "string" }, "body": { "type": "array", "items": { "type": "object", "required": [ "tool_id" ], "properties": { "tool_id": { "type": "string" }, "enabled": { "type": "boolean", "default": true }, "config": { "type": "object", "additionalProperties": true, "description": "Customer SETTINGS for this tool on this agent, keyed by the tool's config_schema field keys (e.g. { from_number, provider_api_key }). Fields marked secret are encrypted at rest and returned masked ('********'); re-send the mask (or omit) to keep the stored value." }, "name": { "type": "string", "description": "Present on agent reads when the tool resolves." }, "description": { "type": "string" }, "input_schema": { "type": "object", "additionalProperties": true, "description": "Per-call model argument schema. Present on agent reads when the tool resolves." }, "execution": { "type": "string", "enum": [ "hosted", "server", "engine", "client" ], "description": "Resolved execution mode. Present on agent reads when the tool resolves." } } } } }, "required": [ "id", "body" ], "additionalProperties": false }, "annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "oauth2", "scopes": [ "omni:session" ] } ] } }, { "name": "set_agent_knowledge", "title": "Set Agent Knowledge", "description": "Replace the knowledge bases bound to an Agent. Read its existing bindings first.", "inputSchema": { "type": "object", "properties": { "id": { "type": "string" }, "body": { "type": "array", "items": { "type": "object", "required": [ "kb_id" ], "properties": { "kb_id": { "type": "string", "description": "Knowledge base id." }, "weight": { "type": "number", "default": 1, "description": "Retrieval weight relative to other bound bases." } } } } }, "required": [ "id", "body" ], "additionalProperties": false }, "annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "oauth2", "scopes": [ "omni:session" ] } ] } }, { "name": "get_trace_config", "title": "Get Trace Config", "description": "Inspect Trace call-compliance configuration.", "inputSchema": { "type": "object", "properties": { "agent_id": { "type": "string", "description": "Agent to read config for; omit for the org default." } }, "required": [], "additionalProperties": false }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "oauth2", "scopes": [ "trace:configure" ] } ] } }, { "name": "configure_trace", "title": "Configure Trace", "description": "Configure Trace compliance monitoring for the selected workspace.", "inputSchema": { "type": "object", "properties": { "body": { "type": "object", "description": "Per-agent Trace config (spec §5.1). May be wrapped as { agent_id, config } or sent raw.", "properties": { "agent_id": { "type": "string", "description": "Agent to configure; omit for the org-wide default." }, "enabled": { "type": "boolean", "default": false }, "channels": { "type": "array", "items": { "type": "string", "enum": [ "voice", "text" ] }, "default": [ "voice" ] }, "rule_packs": { "type": "object", "additionalProperties": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "version": { "type": "string", "nullable": true } } }, "description": "Map of pack_id → { enabled, version }, e.g. { tcpa: { enabled: true } }." }, "guardrails": { "type": "object", "description": "Inline guardrails compiled into a synthesized rule pack (spec §5.1).", "properties": { "mode": { "type": "string", "enum": [ "warn", "modify", "block", "human_handoff" ], "default": "warn", "description": "warn = log only (never blocks); modify = redact/inject; block = suppress; human_handoff = escalate." }, "block_pii": { "type": "object", "properties": { "patterns": { "type": "array", "items": { "type": "string", "enum": [ "ssn", "credit_card", "email", "us_phone" ] }, "description": "Deterministically-redactable PII (context-dependent PII like DOB is Tier-2, not inline)." } } }, "mandatory_disclosures": { "type": "array", "items": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "Phrase the agent must speak, e.g. an AI / recording disclosure." }, "trigger": { "type": "string", "enum": [ "call_start", "any" ], "description": "call_start = must appear on the first agent turn." }, "required_within_seconds": { "type": "number", "description": "Deadline in seconds; otherwise a 2-turn default applies." } } } }, "blocked_phrases": { "type": "array", "items": { "type": "string" }, "description": "Phrases the agent must never say." }, "fail_open": { "type": "boolean", "default": true, "description": "Trace down must never make a call worse, log 'unavailable' instead of blocking." }, "inline_timeout_ms": { "type": "number", "default": 10, "description": "Inline budget; the in-process gate is ~14µs p99, far under this." } } } } } }, "required": [ "body" ], "additionalProperties": false }, "annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": true, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "oauth2", "scopes": [ "trace:configure" ] } ] } }, { "name": "list_trace_rule_packs", "title": "List Trace Rule Packs", "description": "Discover available Trace compliance rule packs before enabling monitoring.", "inputSchema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "oauth2", "scopes": [ "trace:configure" ] } ] } }, { "name": "create_trace_rule_pack", "title": "Create Trace Rule Pack", "description": "Create a workspace Trace compliance rule pack. This creates persistent configuration.", "inputSchema": { "type": "object", "properties": { "body": { "type": "object", "required": [ "pack_id", "version", "rules" ], "description": "An authored rule pack in the Trace DSL (rule_pack_schema.json).", "properties": { "pack_id": { "type": "string", "pattern": "^[a-z0-9_]+$" }, "version": { "type": "string" }, "jurisdiction": { "type": "string" }, "legal_status": { "type": "string", "description": "Provenance / attorney-curation status." }, "rules": { "type": "array", "minItems": 1, "items": { "type": "object" } } } } }, "required": [ "body" ], "additionalProperties": false }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "oauth2", "scopes": [ "trace:configure" ] } ] } }, { "name": "list_trace_interactions", "title": "List Trace Interactions", "description": "Find monitored calls and interactions for compliance review.", "inputSchema": { "type": "object", "properties": { "verdict": { "type": "string", "enum": [ "PASS", "WARN", "FAIL" ] }, "agent_id": { "type": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "cursor": { "type": "string" } }, "required": [], "additionalProperties": false }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "oauth2", "scopes": [ "trace:read" ] } ] } }, { "name": "get_trace_interaction", "title": "Get Trace Interaction", "description": "Read one monitored interaction and its compliance evidence.", "inputSchema": { "type": "object", "properties": { "id": { "type": "string", "description": "The call_id." } }, "required": [ "id" ], "additionalProperties": false }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "oauth2", "scopes": [ "trace:read" ] } ] } }, { "name": "list_trace_findings", "title": "List Trace Findings", "description": "Find compliance findings with source evidence. Findings are signals for review, not legal conclusions.", "inputSchema": { "type": "object", "properties": { "check_id": { "type": "string" }, "action": { "type": "string", "enum": [ "flag", "preempt_next", "escalate" ] }, "severity": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "interaction_id": { "type": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "cursor": { "type": "string" } }, "required": [], "additionalProperties": false }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "oauth2", "scopes": [ "trace:read" ] } ] } }, { "name": "list_trace_violations", "title": "List Trace Violations", "description": "List Trace rule violations for compliance review.", "inputSchema": { "type": "object", "properties": { "rule_id": { "type": "string" }, "severity": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "interaction_id": { "type": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 }, "cursor": { "type": "string" } }, "required": [], "additionalProperties": false }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "oauth2", "scopes": [ "trace:read" ] } ] } }, { "name": "get_trace_exposure", "title": "Get Trace Exposure", "description": "Read aggregate compliance exposure for the workspace.", "inputSchema": { "type": "object", "properties": { "window_days": { "type": "integer", "minimum": 1, "maximum": 365, "default": 30, "description": "Trailing window in days." } }, "required": [], "additionalProperties": false }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "oauth2", "scopes": [ "trace:read" ] } ] } }, { "name": "get_recap_config", "title": "Get Recap Config", "description": "Read Recap summarization configuration before changing it.", "inputSchema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "oauth2", "scopes": [ "recap:configure" ] } ] } }, { "name": "get_cast_capabilities", "title": "Get Cast Capabilities", "description": "Discover Cast voices, emotions, formats and supported rendering capabilities.", "inputSchema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "oauth2", "scopes": [ "cast:render" ] } ] } }, { "name": "direct_cast_script", "title": "Direct Cast Script", "description": "Turn a narration script into directed Cast lines before rendering. Consumes usage.", "inputSchema": { "type": "object", "properties": { "body": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "minLength": 1 } } } }, "required": [ "body" ], "additionalProperties": false }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "oauth2", "scopes": [ "cast:render" ] } ] } }, { "name": "render_cast", "title": "Render Cast", "description": "Submit script text or a directed, multi-line Cast narration render. Returns a job; preserve its ID and poll with get_cast_render. Consumes usage; do not resubmit on timeout.", "inputSchema": { "type": "object", "properties": { "body": { "type": "object", "required": [ "voice" ], "anyOf": [ { "required": [ "script" ] }, { "required": [ "lines" ] } ], "properties": { "script": { "type": "string", "minLength": 1 }, "voice": { "type": "string", "minLength": 1 }, "lines": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "text", "emotion", "intensity" ], "properties": { "text": { "type": "string", "minLength": 1 }, "emotion": { "type": "string", "minLength": 1 }, "intensity": { "oneOf": [ { "type": "string" }, { "type": "number" } ] } } } }, "steps": { "type": "integer", "minimum": 1 } } } }, "required": [ "body" ], "additionalProperties": false }, "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "oauth2", "scopes": [ "cast:render" ] } ] } }, { "name": "list_transcription_jobs", "title": "List Transcription Jobs", "description": "Find existing audio processing and transcription jobs before submitting duplicates.", "inputSchema": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20, "description": "Max items to return (1-100)." }, "cursor": { "type": "string", "description": "Opaque token from a previous page's `next_cursor`. Omit for the first page." } }, "required": [], "additionalProperties": false }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "oauth2", "scopes": [ "transcribe:jobs" ] } ] } }, { "name": "discover_tools", "description": "Find the right PyAI tools and a short recipe for a use case: speech, STT, voice agents, compliance, summaries, dubbing or narration. No credentials or usage.", "inputSchema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "description": "Product name or task, e.g. “translate audio”, “voice agent”, “TTS”." } }, "required": [], "additionalProperties": false }, "title": "Discover Tools", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": false }, "_meta": { "securitySchemes": [ { "type": "noauth" } ] } }, { "name": "get_dub_capabilities", "description": "Read currently supported Dub input and output languages before submitting a translation.", "inputSchema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, "title": "Get Dub Capabilities", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "noauth" } ] } }, { "name": "create_dub", "description": "Submit an audio URL for translation and dubbing. Consumes usage. Keep job_id and poll get_dub_job; do not submit again after a timeout.", "inputSchema": { "type": "object", "properties": { "source_url": { "type": "string", "format": "uri", "pattern": "^https://" }, "source_lang": { "type": "string", "minLength": 1, "description": "Source language from get_dub_capabilities." }, "target_lang": { "type": "string", "minLength": 1, "description": "Target language from get_dub_capabilities." } }, "required": [ "source_url", "source_lang", "target_lang" ], "additionalProperties": false }, "title": "Create Dub", "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "oauth2", "scopes": [ "dub:render" ] } ] } }, { "name": "get_dub_job", "title": "Dubbing", "description": "Check a submitted Dub job. Poll pending/processing states without resubmitting.", "inputSchema": { "type": "object", "properties": { "job_id": { "type": "string", "minLength": 1, "description": "The ID returned by the original submission; do not invent one." } }, "required": [ "job_id" ], "additionalProperties": false }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "oauth2", "scopes": [ "dub:render" ] } ] } }, { "name": "get_dub_audio", "description": "Retrieve completed dubbed audio as a playable result or download. Call only when get_dub_job reports done.", "inputSchema": { "type": "object", "properties": { "job_id": { "type": "string", "minLength": 1, "description": "The ID returned by the original submission; do not invent one." } }, "required": [ "job_id" ], "additionalProperties": false }, "title": "Get Dub Audio", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "oauth2", "scopes": [ "dub:render" ] } ] } }, { "name": "get_cast_render", "description": "Check a durable Cast render job. Preserve the original job ID.", "inputSchema": { "type": "object", "properties": { "job_id": { "type": "string", "minLength": 1, "description": "The ID returned by the original submission; do not invent one." } }, "required": [ "job_id" ], "additionalProperties": false }, "title": "Get Cast Render", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "oauth2", "scopes": [ "cast:render" ] } ] } }, { "name": "get_cast_audio", "description": "Retrieve completed Cast narration as playable audio or a download.", "inputSchema": { "type": "object", "properties": { "job_id": { "type": "string", "minLength": 1, "description": "The ID returned by the original submission; do not invent one." } }, "required": [ "job_id" ], "additionalProperties": false }, "title": "Get Cast Audio", "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "oauth2", "scopes": [ "cast:render" ] } ] } }, { "name": "preview_cast_line", "description": "Generate one directed Cast line. Consumes usage. Check get_cast_capabilities for supported voice, emotion and intensity.", "inputSchema": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "description": "Narration text." }, "voice": { "type": "string", "minLength": 1, "description": "A supported Cast voice." }, "emotion": { "type": "string", "minLength": 1, "description": "Supported emotion." }, "intensity": { "anyOf": [ { "type": "number", "minimum": 0, "maximum": 1 }, { "type": "string", "enum": [ "low", "med", "high" ] } ] } }, "required": [ "text", "voice", "emotion", "intensity" ], "additionalProperties": false }, "title": "Preview Cast Line", "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "oauth2", "scopes": [ "cast:render" ] } ] } }, { "name": "transcribe_audio", "description": "Transcribe a small audio attachment supplied as base64 (up to 8 MiB decoded). For large or hosted recordings, use create_transcription_job. Consumes usage.", "inputSchema": { "type": "object", "properties": { "audio_base64": { "type": "string", "minLength": 4, "maxLength": 11184812, "description": "Base64-encoded audio bytes, without a data: prefix." }, "filename": { "type": "string", "pattern": "^[A-Za-z0-9_.-]+$", "maxLength": 120 }, "language": { "type": "string", "enum": [ "en", "es", "fr", "de", "hi", "it", "pt", "nl" ] } }, "required": [ "audio_base64", "filename" ], "additionalProperties": false }, "title": "Transcribe Audio", "annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true }, "_meta": { "securitySchemes": [ { "type": "oauth2", "scopes": [ "hear:transcribe" ] } ] } } ] }