# PyAI Developers

> Build voice agents through the console or API, powered by Omni. Agents, Hear, Speak, Clone, Cast, and Dub documentation.

- [Quickstart](https://docs.pyai.com/quickstart.md): Mint an instant key and make your first PyAI call: Agents powered by Omni, Hear, Speak, Clone, Cast, AMD, or Trace.
- [Getting started with SDKs and coding agents](https://docs.pyai.com/getting-started.md): Get a PyAI key, run a complete SDK starter, and connect Cursor, Codex or Claude Code to the same public API contract.
- [Choose your path](https://docs.pyai.com/choose-your-path.md): Pick the first PyAI surface that matches the job: Agents through UI or API, speech APIs, or a speech layer inside LiveKit or Pipecat.
- [SDKs](https://docs.pyai.com/guides/sdks.md): Install the official Python and TypeScript SDKs, know when to use them versus curl or a raw WebSocket, and find the LiveKit and Pipecat adapters.
- [PyAI CLI](https://docs.pyai.com/guides/cli.md): Render speech, transcribe files, run Dub jobs, and manage PyAI from your terminal. Shortcuts, browser login, JSON output, and agent-ready project starters.
- [Vercel](https://docs.pyai.com/guides/vercel.md): Use PyAI speech and transcription from your Vercel app.
- [PyAI MCP: connect your AI app](https://docs.pyai.com/guides/mcp.md): Connect ChatGPT, Claude, Cursor, Codex and Devin to speech, transcription, voice agents, Trace, Recap, Dub and Cast with browser OAuth.
- [Authentication](https://docs.pyai.com/authentication.md): Authenticate PyAI requests with bearer API keys: pyai_test_ vs pyai_live_ environments, per-product scopes, WebSocket subprotocol auth, and key rotation.
- [Pricing & metering](https://docs.pyai.com/pricing-and-metering.md): How PyAI meters Hear, Speak, Omni, Agents, Cast, and managed telephony.
- [Production readiness](https://docs.pyai.com/production-readiness.md): Move from a PyAI sandbox key to production with the current region, language, billing, reconnect, retention, limits, and reliability contracts.
- [Webhooks](https://docs.pyai.com/webhooks.md): Configure PyAI completion callbacks, verify raw-body signatures, deduplicate deliveries, and run a complete Node.js receiver.
- [Build and run Agents](https://docs.pyai.com/agents/getting-started.md): Build and manage the same voice agent through the console or API, then run it on the Omni realtime runtime.
- [Create agents via API](https://docs.pyai.com/guides/create-agents-api.md): Use the Agents REST API to manage the same profiles as the console, then run voice sessions on the Omni realtime runtime.
- [Omni realtime runtime](https://docs.pyai.com/guides/omni-overview.md): Build a complete realtime voice agent through one WebSocket instead of wiring together speech-to-text, an LLM, text-to-speech, VAD, turn detection, and interruption handling.
- [Build a browser voice agent](https://docs.pyai.com/guides/browser-voice-agent.md): Capture the mic, stream PCM16 to Omni over WebSocket, and play the agent's voice back, a full talking agent in the browser in about 10 minutes.
- [Add your Agent to a website](https://docs.pyai.com/guides/website-voice-widget.md): Publish a secure browser voice agent with one script tag and no customer backend.
- [Agent greeting messages](https://docs.pyai.com/guides/agent-greeting.md): Set an opening greeting on an Omni agent profile in the console or via POST /v1/agents, spoken at turn 0 before the caller speaks.
- [Omni function calling (tools)](https://docs.pyai.com/guides/omni-tools.md): Let a voice agent call functions mid-conversation, PyAI-hosted catalog tools, your signed webhook (server mode), or the client loop on the WebSocket.
- [Knowledge bases: ground your agent in your content](https://docs.pyai.com/guides/knowledge-bases.md): Create a hosted knowledge base, add documents (file, URL, pasted text, or a website crawl), and bind it to an Omni agent or your org defaults, so agents answer from your content with no retrieval server of your own.
- [Post-call data capture](https://docs.pyai.com/guides/post-call-extraction.md): Turn every voice call into structured JSON. Declare a schema on your agent; PyAI extracts the fields after each call and POSTs them, signed, to your webhook.
- [Build a phone voice agent with Twilio](https://docs.pyai.com/guides/twilio-voice-agent.md): Bridge Twilio Media Streams to an Omni agent: a deployable Node server that handles μ-law↔PCM16, barge-in, DTMF, and live transfer to a human.
- [Integrate Omni with FreeSWITCH](https://docs.pyai.com/guides/freeswitch-voice-agent.md): Fork channel audio (L16/16 kHz) to an Omni agent over WebSocket, with barge-in via uuid_break, live transfer via uuid_transfer, and DTMF over ESL.
- [Answer WhatsApp calls with an Omni agent](https://docs.pyai.com/guides/whatsapp-voice-agent.md): Connect a WhatsApp Business number to Omni: register the number, enable calling, and let your agent answer WhatsApp voice calls (and place them, with the user's permission).
- [Omni wire protocol (v2)](https://docs.pyai.com/realtime/omni-protocol.md): Full reference for the Omni realtime WebSocket: connect URL, auth, audio and configure frames, kb_endpoint grounding, lifecycle, close codes, metering.
- [Migrate to the canonical Omni WebSocket](https://docs.pyai.com/guides/migrate-omni-v2-chat.md): Move a client from the discontinued Omni v2 chat URL to /v1/omni, including auth, query parameters, configure frames, binary framing, and error handling.
- [Speech To Text (Hear)](https://docs.pyai.com/guides/hear-overview.md): Phone-tuned multilingual speech-to-text with about 200 ms first partials in-region, an OpenAI-compatible drop-in, and optional cleanup on English finals.
- [Stream speech-to-text in real time](https://docs.pyai.com/guides/streaming-stt.md): Build live captions on Hear's streaming WebSocket: send PCM16 audio, render greyed interim partials, force-finalize with commit, and lock in finals on the fly.
- [Transcribe recordings with timestamps](https://docs.pyai.com/guides/async-transcription-jobs.md): Submit async Hear jobs, read word and segment timestamps, preserve the media timeline, receive signed webhooks, and understand retention and limits.
- [Speaker diarization with Hear](https://docs.pyai.com/guides/speaker-diarization.md): Add speaker diarization to recorded audio with PyAI Hear. Choose mono speaker labels or stereo channel separation, read timestamps, and handle transcript fallback.
- [Format Hear transcripts](https://docs.pyai.com/guides/hear-transcript-formatting.md): Use numerals, smart_format, and optional dictation, drop_fillers, and custom vocabulary on Hear finals.
- [Telephony audio (8 kHz μ-law)](https://docs.pyai.com/reference/telephony-audio.md): Move phone audio in and out of Speak, Hear, and Omni cleanly: native G.711 μ-law/A-law at 8 kHz, μ-law companding, and exact integer resample ratios.
- [Text To Speech (Speak)](https://docs.pyai.com/guides/speak-overview.md): Choose a voice, synthesize streaming or buffered audio, select an output format, and move cleanly into telephony.
- [Clone a voice end to end](https://docs.pyai.com/guides/voice-cloning.md): Enroll a custom voice from a short reference clip, preview it, synthesize speech with it, drop it into an Omni agent, and debug why clips get rejected.
- [Cast expressive voice rendering](https://docs.pyai.com/guides/cast-overview.md): Discover live Cast capabilities, direct a script into performance lines, preview delivery, and submit a durable long-form render.
- [Dub: audio dubbing](https://docs.pyai.com/guides/dub-overview.md): Dub audio and video across supported languages with an asynchronous job. Submit a recording, follow transcription and translation, then download the dubbed WAV.
- [Answering machine detection (AMD)](https://docs.pyai.com/guides/amd-answering-machine-detection.md): Stream the called party's audio, choose a decision deadline, and route the result. Includes a Twilio AMD migration guide.
- [Replace Twilio AMD](https://docs.pyai.com/guides/replace-twilio-amd.md): Keep Twilio for outbound calling and use PyAI for answer detection. Migrate the media stream, decision callback and routing policy.
- [Conversation intelligence](https://docs.pyai.com/guides/conversation-intelligence.md): Choose Hear, Recap, post-call data capture, or Trace for transcripts, summaries, structured fields, and compliance evidence.
- [Recap: post-call notes](https://docs.pyai.com/guides/recap-call-intelligence.md): Notes, next steps, and structured fields the moment a call ends. No bot to invite. Webhook delivery, plus Salesforce when you map fields.
- [Trace: compliance guardrails](https://docs.pyai.com/guides/trace-guardrails.md): Score eligible calls against compliance rule packs, get a tamper-evident scorecard per scanned call, and read your org's exposure.
- [Use PyAI with LiveKit Agents](https://docs.pyai.com/guides/livekit-agents.md): Keep LiveKit rooms and orchestration while using PyAI Hear for streaming speech-to-text and PyAI Speak for agent audio through a Python plugin.
- [Use PyAI with Pipecat](https://docs.pyai.com/guides/pipecat.md): Keep Pipecat's explicit frame pipeline and custom transports while using PyAI Hear for streaming speech-to-text and PyAI Speak for agent audio.
- [Use PyAI in Cursor and coding agents](https://docs.pyai.com/guides/use-pyai-in-cursor.md): Connect PyAI through browser OAuth and use speech, transcription, voice agents, compliance, summaries, dubbing and narration from your coding agent.
- [Integrations overview](https://docs.pyai.com/guides/integrations-overview.md): How PyAI integrations work: outbound destinations (Slack, Zapier, CRM, helpdesk) and inbound call imports (JustCall, and more in certification), with signed, retried, visible delivery.
- [Slack integration](https://docs.pyai.com/guides/integrations-slack.md): Post a formatted Slack message after every completed call: TL;DR, summary, next steps, and AMD verdicts. One-minute setup with an incoming webhook.
- [Zapier integration](https://docs.pyai.com/guides/integrations-zapier.md): Trigger Zaps from completed calls with a signed, deduplicated envelope. Connect with a Catch Hook URL or the REST-hooks API; full event catalog with samples.
- [Google Sheets integration](https://docs.pyai.com/guides/integrations-google-sheets.md): Append one Google Sheets row per completed call: TL;DR, summary, next steps, caller number, or AMD verdict. Service-account auth, five-minute setup.
- [HubSpot integration](https://docs.pyai.com/guides/integrations-hubspot.md): Post a note with the TL;DR, summary, and next steps on the matching HubSpot contact after every completed call. Private app token setup in two minutes.
- [Salesforce integration](https://docs.pyai.com/guides/integrations-salesforce.md): Map Recap fields onto your Salesforce object after every completed call, with an optional follow-up Task. Connected-app auth, your field map, your object.
- [Pipedrive integration](https://docs.pyai.com/guides/integrations-pipedrive.md): Log a completed call activity in Pipedrive after every call: TL;DR subject, full recap in the note, attached to the person matched by phone. Two-minute setup.
- [Zoho CRM integration](https://docs.pyai.com/guides/integrations-zoho-crm.md): Attach a note with the call TL;DR and recap to the matching Zoho CRM contact after every completed call. Works in every Zoho data center.
- [Zendesk integration](https://docs.pyai.com/guides/integrations-zendesk.md): Open a Zendesk ticket after every completed call: TL;DR subject, summary and next steps in the first comment, tagged for your views and triggers.
- [Apollo integration](https://docs.pyai.com/guides/integrations-apollo.md): Create a follow-up call task on the matching Apollo contact after every completed call: TL;DR title, full recap in the note, due next day, high priority.
- [Clay integration](https://docs.pyai.com/guides/integrations-clay.md): Append each completed call as a row in your Clay table via the table's webhook source: TL;DR, summary, next steps, caller number, or AMD verdict. Direct, no Zapier hop.
- [JustCall import](https://docs.pyai.com/guides/integrations-justcall.md): Import completed JustCall calls into PyAI automatically for transcription and any enabled Recap/Trace processing, verified and deduplicated. Live today.
- [Aircall import (in certification)](https://docs.pyai.com/guides/integrations-aircall.md): Coming soon: import Aircall calls into PyAI with two-event coalescing, authenticated recording refresh, Recap summaries, and Trace scorecards.
- [Dialpad import (in certification)](https://docs.pyai.com/guides/integrations-dialpad.md): Coming soon: import Dialpad hangup, recording, and transcription events into PyAI, verified with Dialpad's HS256 webhook JWT, for Recap summaries and Trace scorecards.
- [Twilio import (in certification)](https://docs.pyai.com/guides/integrations-twilio.md): Coming soon: import Twilio Voice calls into PyAI with verified callbacks, authenticated recording fetch, and enabled Recap/Trace processing.
- [RingCentral import (in certification)](https://docs.pyai.com/guides/integrations-ringcentral.md): Coming soon: import RingCentral calls into PyAI with auto-created webhook subscriptions, OAuth recording fetch, Recap summaries, and Trace scorecards.
- [Build with PyAI: use-case guides](https://docs.pyai.com/use-cases/overview.md): Step-by-step build guides for the products developers create on PyAI: conversation intelligence, voice dictation, AI receptionists, and call-center QA, with the exact APIs each one uses.
- [Build your own Gong: conversation intelligence on PyAI](https://docs.pyai.com/use-cases/build-your-own-gong.md): Build a Gong-style product: Hear transcribes calls, Recap writes summaries and actions, and Trace scores eligible compliance paths.
- [Build your own Wispr Flow: a voice dictation app on PyAI](https://docs.pyai.com/use-cases/build-your-own-wispr-flow.md): Build a Wispr Flow-style voice dictation app on PyAI Hear streaming: push-to-talk mic capture, PCM16 over one WebSocket, interim partials rendered at the cursor, finals committed as you speak.
- [Build an AI receptionist: 24/7 phone answering with PyAI Omni](https://docs.pyai.com/use-cases/ai-receptionist.md): Build an AI receptionist that answers every call, greets callers, answers questions from your knowledge base, books appointments through your tools, and transfers to a human, on one PyAI Omni session.
- [Build call-center QA with PyAI Trace](https://docs.pyai.com/use-cases/call-center-qa.md): Score eligible calls against TCPA, HIPAA, PII, and custom rule packs, with scorecards, violation drill-down, and an exposure dashboard.
- [Errors & limits](https://docs.pyai.com/errors-and-limits.md): PyAI error envelopes (OpenAI-style and RFC 7807 problem+json), stable error codes, rate limits, retry guidance, and Idempotency-Key semantics.
- [Security & data](https://docs.pyai.com/security-and-data.md): How PyAI protects your data: API key hashing, TLS in transit, org-level tenancy isolation, retention windows for jobs and calls, and abuse controls.
- [Language support](https://docs.pyai.com/reference/language-support.md): Which languages PyAI supports on Hear, Omni, Speak, and Dub today, including staged availability and explicit unsupported-language behavior.
- [Voices, languages, and controls](https://docs.pyai.com/reference/voices-languages-and-controls.md): Choose a compatible PyAI configuration, distinguish requested from served behavior, and copy a safe Omni, Hear, or Speak starting point.
- [Reliability, latency & regions](https://docs.pyai.com/reference/reliability.md): PyAI's status page, uptime targets and contractual SLA path, expected realtime latency, single-region topology and data residency, and reconnect guidance.
- [PyAI changelog: API, SDK, and Omni protocol releases](https://docs.pyai.com/changelog.md): Release notes for the PyAI API, SDKs, and docs covering Hear, Speak, and Omni protocol updates, telephony audio, and developer-experience improvements.
- [Read the machine-readable Omni frame contract](https://docs.pyai.com/api-reference/omni/read-the-machine-readable-omni-frame-contract.md): Public AsyncAPI 3.0 JSON generated from the canonical Omni protocol source, including binary tags, control payloads and SDK integration notes. No key required.
- [List Omni call records](https://docs.pyai.com/api-reference/omni/list-omni-call-records.md): Recent Omni realtime sessions for this org, newest first. Each record has one stable, opaque PyAI call identifier plus recording and summary availability. Use that same `call_id` for detail, recording, transcript, and summary reads. Requires the `omni:read` scope. Filter by `session_label` (the opaq…
- [Get an Omni call record](https://docs.pyai.com/api-reference/omni/get-an-omni-call-record.md): Full record for one Omni session, addressed by the stable opaque PyAI `call_id` returned by the list: transcript (inline or via `transcript_url`), recording availability, and `summary` when generated. Recording bytes are retrieved from the dedicated recording sub-resource. Requires `omni:read`.
- [Download an Omni call recording](https://docs.pyai.com/api-reference/omni/download-an-omni-call-recording.md): Fetch the call's audio recording, when one exists (recording is off by default). Requires `omni:read`.
- [Get an Omni call summary](https://docs.pyai.com/api-reference/omni/get-an-omni-call-summary.md): The structured post-call summary, when one was generated. `404` if there is no summary for the call. Requires `omni:read`.
- [Get an Omni call transcript](https://docs.pyai.com/api-reference/omni/get-an-omni-call-transcript.md): The full conversation transcript for the call. Resolves whether the transcript is stored inline or offloaded to an external URL, the response is always the transcript document itself. `404` if no transcript exists (e.g. the call failed before any speech, or the engine has not yet pushed the record).…
- [Mint an ephemeral Omni session token](https://docs.pyai.com/api-reference/omni/mint-an-ephemeral-omni-session-token.md): **Most integrations do not need this endpoint.** Server-side apps, telephony, and backend agents connect to `wss /v1/omni` directly with their API key (see "Open an Omni voice-agent session"). Use this only when a browser or other untrusted client must open an Omni session without holding your secre…
- [Open an Omni voice-agent session (WebSocket)](https://docs.pyai.com/api-reference/omni/open-an-omni-voice-agent-session-websocket.md): **This is the primary way to build an AI voice agent on PyAI.** Open this WebSocket, send one `configure` frame (voice, persona, knowledge endpoint, tools), then stream PCM16 audio both ways. There is nothing to create first: the session is authorized by your key's org, and the whole agent travels i…
- [Discover PyAI MCP authorization](https://docs.pyai.com/api-reference/mcp/discover-pyai-mcp-authorization.md)
- [Discover authorization for the MCP endpoint](https://docs.pyai.com/api-reference/mcp/discover-authorization-for-the-mcp-endpoint.md)
- [Discover OAuth endpoints and S256 PKCE support](https://docs.pyai.com/api-reference/mcp/discover-oauth-endpoints-and-s256-pkce-support.md)
- [Register an MCP OAuth public client](https://docs.pyai.com/api-reference/mcp/register-an-mcp-oauth-public-client.md)
- [Start browser OAuth consent](https://docs.pyai.com/api-reference/mcp/start-browser-oauth-consent.md): Authorization code with S256 PKCE, exact registered redirect URI and resource=https://api.pyai.com/mcp. Returns to the approved client with state and issuer identification.
- [Exchange an authorization code or rotate a refresh token](https://docs.pyai.com/api-reference/mcp/exchange-an-authorization-code-or-rotate-a-refresh-token.md): Form-encoded OAuth code or refresh exchange. Tokens are restricted to the MCP resource. Access tokens expire after 15 minutes; connections last up to 30 days. Refresh reuse revokes the connection.
- [Revoke an MCP OAuth connection using a token](https://docs.pyai.com/api-reference/mcp/revoke-an-mcp-oauth-connection-using-a-token.md)
- [PyAI MCP Streamable HTTP endpoint](https://docs.pyai.com/api-reference/mcp/pyai-mcp-streamable-http-endpoint.md): Use a standards-compliant MCP client. OAuth authentication is required; ordinary API keys are not accepted here. Tools cover Speak, Hear, voice Agent profiles, Trace, Recap, Dub and Cast. Stateless transport returns JSON responses; notifications return 202.
- [Poll a Cast narration render](https://docs.pyai.com/api-reference/cast/poll-a-cast-narration-render.md)
- [Download completed Cast narration](https://docs.pyai.com/api-reference/cast/download-completed-cast-narration.md)
- [Get live Cast capabilities](https://docs.pyai.com/api-reference/cast/get-live-cast-capabilities.md): Returns the voice IDs, emotions, intensity tiers, and languages currently available to Cast. Requires `cast:render`. Clients must render controls from this response instead of assuming every voice in the general catalog is Cast-compatible.
- [Auto-direct a script](https://docs.pyai.com/api-reference/cast/auto-direct-a-script.md): Preserves non-empty newline-delimited performance units, or splits plain text by sentence, then assigns emotion and intensity to every unit. Requires `cast:render`.
- [Preview one directed line](https://docs.pyai.com/api-reference/cast/preview-one-directed-line.md): Synchronously renders a single line for quick preview. Long-form renders must use render jobs. Requires `cast:render`.
- [Create an asynchronous Cast render](https://docs.pyai.com/api-reference/cast/create-an-asynchronous-cast-render.md): Submit narration as script text or directed lines. Returns job_id and status_url. Poll the status URL until done or error, then GET its audio path. Requires `cast:render`. A console Cast project is not required. Submissions are not automatically retried.
- [Start a Vercel connection](https://docs.pyai.com/api-reference/integrations/start-a-vercel-connection.md): Requires a signed-in PyAI console session and an allowed browser Origin. Available only when the Vercel integration is enabled. Key creation and disconnection require owner/admin project access.
- [Verify the Vercel authorization callback](https://docs.pyai.com/api-reference/integrations/verify-the-vercel-authorization-callback.md): Requires a signed-in PyAI console session and an allowed browser Origin. Available only when the Vercel integration is enabled. Key creation and disconnection require owner/admin project access.
- [Read your existing Vercel connection](https://docs.pyai.com/api-reference/integrations/read-your-existing-vercel-connection.md): Requires a signed-in PyAI console session and an allowed browser Origin. Available only when the Vercel integration is enabled. Key creation and disconnection require owner/admin project access.
- [Read Vercel connection status](https://docs.pyai.com/api-reference/integrations/read-vercel-connection-status.md): Requires a signed-in PyAI console session and an allowed browser Origin. Available only when the Vercel integration is enabled. Key creation and disconnection require owner/admin project access.
- [List authorized Vercel projects](https://docs.pyai.com/api-reference/integrations/list-authorized-vercel-projects.md): Requires a signed-in PyAI console session and an allowed browser Origin. Available only when the Vercel integration is enabled. Key creation and disconnection require owner/admin project access.
- [Create and install a scoped PyAI project key](https://docs.pyai.com/api-reference/integrations/create-and-install-a-scoped-pyai-project-key.md): Requires a signed-in PyAI console session and an allowed browser Origin. Available only when the Vercel integration is enabled. Key creation and disconnection require owner/admin project access.
- [Revoke this integration key and remove its environment variable](https://docs.pyai.com/api-reference/integrations/revoke-this-integration-key-and-remove-its-environment-variable.md): Requires a signed-in PyAI console session and an allowed browser Origin. Available only when the Vercel integration is enabled. Key creation and disconnection require owner/admin project access.
- [Receive a signed Vercel lifecycle event](https://docs.pyai.com/api-reference/integrations/receive-a-signed-vercel-lifecycle-event.md): Validates x-vercel-signature using the Integration Secret and exact request bytes. Removal and transfer revoke the installation key.
- [List integration events](https://docs.pyai.com/api-reference/integrations/list-integration-events.md): The completed-call event catalog for outbound integrations, with representative delivery payloads for field mapping. Any active key may call this.
- [Subscribe a Zapier REST hook](https://docs.pyai.com/api-reference/integrations/subscribe-a-zapier-rest-hook.md): Zapier REST-hook subscribe: delivers every completed call of the given event type to `target_url` as `{id, type, occurred_at, data}`, signed with `X-PyAI-Signature` and carrying an `Idempotency-Key`. Idempotent on `(org, event, target_url)` — re-subscribing refreshes in place (HTTP `201` with the sa…
- [Unsubscribe a Zapier REST hook](https://docs.pyai.com/api-reference/integrations/unsubscribe-a-zapier-rest-hook.md): Zapier REST-hook unsubscribe. Only the owning org can delete its hooks.
- [Read editable dubbing passages](https://docs.pyai.com/api-reference/dub/read-editable-dubbing-passages.md): Requires dub:render. Read source transcript, displayed translation, optional spoken pronunciation text, and source/output times. rendered holds the text matching the current audio; changed marks saved edits awaiting regeneration. Available when job.editable is true. No delivery units are charged.
- [Save transcript, translation and pronunciation edits](https://docs.pyai.com/api-reference/dub/save-transcript-translation-and-pronunciation-edits.md): Save draft text without generating audio or changing current subtitles. Include the latest revision to prevent overwriting another tab. A revision mismatch returns 409 dub_edit_conflict. No delivery units are charged.
- [Regenerate selected passages as a new dub](https://docs.pyai.com/api-reference/dub/regenerate-selected-passages-as-a-new-dub.md): Create a new asynchronous job using saved edits for 1–50 selected passages and the existing rendered audio for all other passages. The previous job is unchanged. If only a passage's source text changed, its translation is refreshed. A supplied pronunciation_text is the full spoken passage and does n…
- [Export original or translated subtitles](https://docs.pyai.com/api-reference/dub/export-original-or-translated-subtitles.md): Requires dub:render. Exports text matching the current rendered audio. Source subtitles use source timings; translated subtitles use actual dubbed passage placements and durations. Pending draft edits and pronunciation spellings are excluded. Regenerate edited passages first to export those changes.…
- [Load the original audio for comparison](https://docs.pyai.com/api-reference/dub/load-the-original-audio-for-comparison.md): Requires dub:render and ownership of the completed job. Returns the original audio for comparison, including extracted audio for video sources. No delivery units are charged. Retention matches the job's media retention.
- [Dubbing availability and languages](https://docs.pyai.com/api-reference/dub/dubbing-availability-and-languages.md): Read the intersection of adapter and worker capabilities. Source and target language lists are independent. No API key is needed.
- [Create a dubbing job](https://docs.pyai.com/api-reference/dub/create-a-dubbing-job.md): Submit exactly one file or source_url as multipart form data. Requires dub:render. Choose a supported source and target language. GET /healthz/dub reports the currently available languages. Processing is asynchronous: keep the returned job_id and poll status_url until done or error.
- [Get dubbing job status](https://docs.pyai.com/api-reference/dub/get-dubbing-job-status.md): Requires dub:render. Jobs belong to the calling organization. queued and running are nonterminal; done and error are terminal. Download outputs only after done. A failed job is returned as HTTP 200 with status error and error_code.
- [Download dubbed audio](https://docs.pyai.com/api-reference/dub/download-dubbed-audio.md): Requires dub:render. Returns the completed job's WAV audio. Save the output in your application; an expired result must be rendered again. Downloads are included and never create a new generation charge. Job billing uses source-audio duration, not output duration.
- [Download a dubbed video output](https://docs.pyai.com/api-reference/dub/download-a-dubbed-video-output.md): Requires dub:render. Use only when the completed job includes video_url or outputs.video. Audio-source jobs have no video output. The source picture is retained with a dubbed audio track; this is not lip synchronization. Video and audio exports are included in the same generation job.
- [Preview current creation rates](https://docs.pyai.com/api-reference/console-creations/preview-current-creation-rates.md): Read-only standard USD rates from the billing engine. Optional source duration produces a usage estimate for Transcription and Dubbing. Speech and Cast return a rate only because generated duration is not known beforehand. Estimates are not reservations or final charges; measured usage and account t…
- [Get background creation progress](https://docs.pyai.com/api-reference/console-creations/get-background-creation-progress.md): Poll queued/running jobs. completed exposes creation_id, available through the project's creations API and My work. Failed jobs preserve their original input. charge is not_started, unconfirmed, or metered; unconfirmed requires checking usage before an explicit retry. A worker interruption never sil…
- [Start a durable Speech or Transcription job](https://docs.pyai.com/api-reference/console-creations/start-a-durable-speech-or-transcription-job.md): Console cookie authentication and a trusted console Origin are required. Choose a client UUID prefixed crj_. Speech accepts JSON metadata. Transcription accepts multipart metadata (a JSON string) plus media (up to 25 MiB). A 202 means the input is stored and the job will continue after the browser c…
- [Restore a background transcription's original recording](https://docs.pyai.com/api-reference/console-creations/restore-a-background-transcriptions-original-recording.md)
- [Regenerate Dubbing passages and save the revision to My work](https://docs.pyai.com/api-reference/console-creations/regenerate-dubbing-passages-and-save-the-revision-to-my-work.md): Requires a signed-in creator, trusted console Origin, and a parent job saved in this project. Accepts DubRevisionInput. The backend creates an idempotent revision and saves it to the project library before responding, so browser departure does not discard the accepted job. Retry with the same key af…
- [Review a CLI login request](https://docs.pyai.com/api-reference/identity/review-a-cli-login-request.md)
- [Start browser login for the CLI](https://docs.pyai.com/api-reference/identity/start-browser-login-for-the-cli.md): Creates a ten-minute device grant bound to the CLI's S256 verifier. Open verification_uri_complete in a browser, compare its user code with the terminal, then approve. The grant is rate limited per source network; no API key is required. Responses must not be cached.
- [Approve CLI access to a project](https://docs.pyai.com/api-reference/identity/approve-cli-access-to-a-project.md): Requires an explicit browser action, application/json, an allowed console Origin, and an owner/admin membership in the active project's organization. Approves the displayed scopes and a thirty-day credential. No API key is created until the waiting CLI exchanges the grant.
- [Deny a CLI login request](https://docs.pyai.com/api-reference/identity/deny-a-cli-login-request.md)
- [Poll and exchange an approved CLI login](https://docs.pyai.com/api-reference/identity/poll-and-exchange-an-approved-cli-login.md): Poll no faster than the returned interval. authorization_pending means continue; slow_down permanently increases the interval by five seconds (also reflected in Retry-After). Stop for access_denied, expired_token, or invalid_grant. On approval, current membership, project status and organization key…
- [Create an account and organization](https://docs.pyai.com/api-reference/identity/create-an-account-and-organization.md)
- [Introspect the calling key (whoami)](https://docs.pyai.com/api-reference/identity/introspect-the-calling-key-whoami.md): Return the identity the gateway resolved for your key: `key_id`, `org_id`, `project_id`, environment (`test`/`live`), `status`, the granted `scopes`, and the rate-limit/credit posture. Any active key may call it (no special scope), so it is the fastest way to self-diagnose a `403 insufficient_scope`…
- [Receive Aircall call events](https://docs.pyai.com/api-reference/call-integrations/receive-aircall-call-events.md): Receives `call.ended` and `call.comm_assets_generated`. The Aircall subscription token in the payload identifies and authenticates the connection. Dark unless call integrations and the Aircall provider gate are enabled.
- [Receive Dialpad call events](https://docs.pyai.com/api-reference/call-integrations/receive-dialpad-call-events.md): Receives `hangup`, `recording`, and `call_transcription` states as an HS256 JWT. Unsigned JSON is rejected. Dark unless call integrations and the Dialpad provider gate are enabled.
- [Receive JustCall completed-call events](https://docs.pyai.com/api-reference/call-integrations/receive-justcall-completed-call-events.md): Receives JustCall `call.completed` with its documented v1 signature. Existing Phase 1 behavior is unchanged.
- [Mint a sandbox key (no auth)](https://docs.pyai.com/api-reference/sandbox/mint-a-sandbox-key-no-auth.md): Create a free, instant `pyai_test_` sandbox key with **no human steps**, no email, no password, no card. Built for AI coding agents (Cursor, Lovable, Claude Code, Codex) and the PyAI MCP server's `create_sandbox_key` tool, so agent-generated code runs on its first execution instead of stalling at a…
- [Apply to PyAI for Startups (no auth)](https://docs.pyai.com/api-reference/startup-program/apply-to-pyai-for-startups-no-auth.md): Submit an application to the PyAI for Startups credit program ($20k, $50k, or $100k in PyAI credit plus a managed phone-minute allowance; see https://pyai.com/startups). Public and unauthenticated; rate-limited per source network. On success the applicant receives a confirmation email and a person r…
- [List available models](https://docs.pyai.com/api-reference/models/list-available-models.md)
- [Transcribe audio](https://docs.pyai.com/api-reference/speech-to-text-hear/transcribe-audio.md): OpenAI-compatible transcription. Requires the `hear:transcribe` scope.
- [Stream transcription (WebSocket)](https://docs.pyai.com/api-reference/speech-to-text-hear/stream-transcription-websocket.md): Upgrade to a WebSocket for streaming speech-to-text with eager partials (PyAI Hear first partial measured at about 200 ms in-region. It is revisable and not an SLA). Requires the `hear:stream` scope. The only frame protocol is `pyai-hear-v1`, the published frame catalog below.
- [Get stored Hear vocabulary](https://docs.pyai.com/api-reference/speech-to-text-hear/get-stored-hear-vocabulary.md): Return the organization's stored custom vocabulary and its explicit activation profiles. Stored terms do not affect any transcription unless `enabled_for` includes `batch` or `hear_stream`. Requires the `hear:configure` scope.
- [Set stored Hear vocabulary](https://docs.pyai.com/api-reference/speech-to-text-hear/set-stored-hear-vocabulary.md): Replace the organization's stored custom vocabulary and activation profiles. PyAI keeps at most five sanitized terms. Stored terms bias known vocabulary only for the profiles named in `enabled_for`. Per-job or per-session vocabulary comes first, then stored suggestions fill remaining slots up to fiv…
- [Synthesize speech](https://docs.pyai.com/api-reference/text-to-speech-speak/synthesize-speech.md): OpenAI-compatible text-to-speech. Returns audio bytes. The serving adapter defaults to incremental delivery from the streaming lane. Set `stream: false` when you require a complete buffered body with `Content-Length`. Requires the `speak:synthesize` scope.
- [List voices](https://docs.pyai.com/api-reference/text-to-speech-speak/list-voices.md): Your unified voice library: the prebuilt PyAI catalog (with presentation metadata; some entries include an avatar or pre-generated audio preview) merged with your saved **designed** voices, each tagged by `source` (`stock` | `design`). Any active key may read it (no specific scope). Inspect `availab…
- [Get a stock voice](https://docs.pyai.com/api-reference/text-to-speech-speak/get-a-stock-voice.md)
- [Delete a designed voice](https://docs.pyai.com/api-reference/text-to-speech-speak/delete-a-designed-voice.md): Remove a saved designed (prompt-to-voice) voice, freeing a library-cap slot. Tenant-isolated, you can only delete your own (otherwise `404`). Stock voices can't be deleted; cloned voices delete via `DELETE /v1/voice/clones/{id}`.
- [Design a voice from a prompt](https://docs.pyai.com/api-reference/text-to-speech-speak/design-a-voice-from-a-prompt.md): Generate a brand-new **synthetic** voice from a text description (distinct from cloning, which copies a real person). Async: returns `202` with a `design_id`; poll `GET /v1/voice/design/{id}` for candidate previews, then `POST /v1/voice/design/{id}/save` to keep one. Send a stable `Idempotency-Key`…
- [Get design candidates](https://docs.pyai.com/api-reference/text-to-speech-speak/get-design-candidates.md): Poll a design job. When `status` is `completed`, `candidates` carries signed preview URLs (24h TTL). Candidates below the quality gate are omitted. Requires the `speak:design` scope.
- [Preview a designed-voice candidate](https://docs.pyai.com/api-reference/text-to-speech-speak/preview-a-designed-voice-candidate.md): Fetch a short-lived audio preview for a candidate owned by the authenticated organization. Cross-organization and malformed lookups return the same not-found response. Requires the `speak:design` scope.
- [Save a designed voice](https://docs.pyai.com/api-reference/text-to-speech-speak/save-a-designed-voice.md): Enroll the chosen candidate as a permanent `voice_id`, usable immediately in `POST /v1/audio/speech` (`voice: vd_…`) and in Omni agents. Requires the `speak:design` scope.
- [List agent profiles](https://docs.pyai.com/api-reference/agents/list-agent-profiles.md): All active agent profiles in your organization. Agent profiles are optional pre-stored Omni session config; they are not required to open an Omni session. Requires the `omni:session` scope.
- [Create an agent profile](https://docs.pyai.com/api-reference/agents/create-an-agent-profile.md): Create an OPTIONAL agent profile (persona, **greeting message**, voice, **language**, recording disclosure, 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 double…
- [Get an agent](https://docs.pyai.com/api-reference/agents/get-an-agent.md)
- [Update an agent](https://docs.pyai.com/api-reference/agents/update-an-agent.md): Partial update: present fields are set, `null` clears a field, absent fields are untouched. Config edits are live on the agent's next call.
- [Delete an agent](https://docs.pyai.com/api-reference/agents/delete-an-agent.md)
- [Bind tools to an agent](https://docs.pyai.com/api-reference/agents/bind-tools-to-an-agent.md): Replace the agent's tool bindings. Each entry references a tool id from `GET /v1/tools`. Requires the `omni:session` scope.
- [List tools](https://docs.pyai.com/api-reference/agents/list-tools.md): Org-owned custom tools plus PyAI prebuilt tools. Requires the `omni:session` scope.
- [Create or update a custom tool](https://docs.pyai.com/api-reference/agents/create-or-update-a-custom-tool.md): Register a custom tool. **Idempotent upsert on `(org, name)`:** if your org already has a tool with this `name`, it is updated in place (HTTP `200`, no duplicate, `hmac_secret` preserved), so re-syncing the same tool from a multi-tenant deploy is safe; otherwise a new tool is created (HTTP `201`, `h…
- [Get a tool](https://docs.pyai.com/api-reference/agents/get-a-tool.md)
- [Update a tool](https://docs.pyai.com/api-reference/agents/update-a-tool.md): Update a tool by id. Pass `rotate_secret: true` to mint a new webhook signing secret, returned once as `hmac_secret`. Requires the `omni:session` scope.
- [Delete a custom tool](https://docs.pyai.com/api-reference/agents/delete-a-custom-tool.md)
- [Test a tool configuration](https://docs.pyai.com/api-reference/agents/test-a-tool-configuration.md)
- [List recent tool calls](https://docs.pyai.com/api-reference/agents/list-recent-tool-calls.md): Audit log of recent tool invocations across the org's agents, tool name, execution mode, outcome, error and latency. No arguments or results are stored. Requires the `omni:session` scope.
- [Get webhook signing secret status](https://docs.pyai.com/api-reference/agents/get-webhook-signing-secret-status.md): Whether your org has a per-org webhook signing secret used to verify post-call extraction (and transcription-job) webhooks. Returns status only, never the secret value. Requires the `omni:session` scope.
- [Mint or rotate the webhook signing secret](https://docs.pyai.com/api-reference/agents/mint-or-rotate-the-webhook-signing-secret.md): Mint (or rotate) your org's webhook signing secret and return it **once**. Verify the `X-PyAI-Signature` on post-call extraction (and transcription-job) webhooks with it: HMAC-SHA256 over `"<t>.<rawBody>"`. Zero-drop rotation: deploy verification that accepts both the old and new secret, call this,…
- [Bind knowledge bases to an agent](https://docs.pyai.com/api-reference/agents/bind-knowledge-bases-to-an-agent.md): Replace the agent's knowledge base bindings (with per-base retrieval weights). Omni sessions opened with `session_label` equal to this agent's id ground against these; sessions without an agent profile use the org defaults (`/v1/knowledgebases/default`). Requires the `omni:session` scope.
- [Resolve a hosted website widget](https://docs.pyai.com/api-reference/agents/resolve-a-hosted-website-widget.md): Returns hosted runtime version 7, caller-only transcript capability, the published widget's safe display configuration, and public profile. Agent text is not inferred from audio. Requires an exact `Origin` header match. The opaque public id does not expose the organization, project, Agent, or creden…
- [Mint a hosted widget voice session](https://docs.pyai.com/api-reference/agents/mint-a-hosted-widget-voice-session.md): Validates the published widget, exact browser Origin, Agent/account status, credit posture, and durable per-widget/per-IP daily limits, then returns one short-lived origin-locked `omni:session` token. The request body cannot select an organization, project, or Agent.
- [List cloned voices](https://docs.pyai.com/api-reference/clone/list-cloned-voices.md)
- [Create a cloned voice](https://docs.pyai.com/api-reference/clone/create-a-cloned-voice.md): Enroll a custom voice from reference audio. Send the audio in the canonical multipart field `file`; SDKs, examples, and the console use this field. EN-only today. Requires the `speak:clone` scope.
- [Delete a cloned voice](https://docs.pyai.com/api-reference/clone/delete-a-cloned-voice.md): Remove a cloned voice. Voices are tenant-isolated, you can only delete your own (otherwise `403`). Requires the `speak:clone` scope.
- [List transcription jobs](https://docs.pyai.com/api-reference/transcription-jobs/list-transcription-jobs.md): Cursor-paginated, newest first. Pass `limit` (1-100, default 20) and the `next_cursor` from the previous page as `cursor` to continue. `next_cursor` is null on the last page.
- [Create an async transcription job](https://docs.pyai.com/api-reference/transcription-jobs/create-an-async-transcription-job.md): Submit audio for batch transcription. Provide **exactly one** source: either `audio_url` (an https URL we fetch; the input is processed transiently and never written to durable input storage) a multipart upload (`multipart/form-data` with an `audio` file part and the same fields as form fields), **o…
- [Get a transcription job](https://docs.pyai.com/api-reference/transcription-jobs/get-a-transcription-job.md)
- [Cancel a transcription job](https://docs.pyai.com/api-reference/transcription-jobs/cancel-a-transcription-job.md): Cancels a `queued`/`running` job; idempotent on terminal jobs (returns them unchanged). This operation does not erase completed results, uploaded input objects, logs, or backups.
- [Get Trace config for an agent (or the org default)](https://docs.pyai.com/api-reference/trace/get-trace-config-for-an-agent-or-the-org-default.md): Returns the per-agent Trace config (spec §5.1). Pass `agent_id` to read a specific agent's config; omit it for the org-wide default a new agent inherits. When nothing has been configured yet, returns the safe default (`enabled:false`, `mode:warn`, `fail_open:true`). Requires the `trace:configure` sc…
- [Set Trace config for an agent (or the org default)](https://docs.pyai.com/api-reference/trace/set-trace-config-for-an-agent-or-the-org-default.md): Upsert the per-agent Trace config (spec §5.1). The body is the §5.1 object (optionally wrapped as `{ agent_id, config }`). Modes: `warn` (log only, never blocks) · `modify` (redact PII / inject disclosures) · `block` · `human_handoff`. Always fail-open; the deterministic inline gate runs models-side…
- [List rule packs](https://docs.pyai.com/api-reference/trace/list-rule-packs.md): Built-in packs (TCPA, HIPAA, PII, brand-voice) plus this tenant's custom uploads. Requires the `trace:configure` scope.
- [Upload a custom rule pack](https://docs.pyai.com/api-reference/trace/upload-a-custom-rule-pack.md): Register a custom rule pack (spec §5.3) in the Trace DSL. Structural validation only here (`pack_id`, `version`, non-empty `rules`); the kernel compiles + deep-validates it models-side at pull time, and citations/wording are attorney-curated out of band. Requires the `trace:configure` scope.
- [Get a rule pack](https://docs.pyai.com/api-reference/trace/get-a-rule-pack.md): Resolve a pack by `pack_id` (latest active by default; pass `version` to pin a specific version). Requires the `trace:configure` scope.
- [List scanned interactions (scorecards)](https://docs.pyai.com/api-reference/trace/list-scanned-interactions-scorecards.md): Cursor-paginated, newest first. Each row is one call's Tier-0 compliance scorecard. Filter by `verdict` (PASS/WARN/FAIL) or `agent_id`. Requires the `trace:read` scope.
- [Get an interaction (the evidence view)](https://docs.pyai.com/api-reference/trace/get-an-interaction-the-evidence-view.md): The full per-call scorecard (findings with plain-English reasons + cited regulations, satisfied requirements, redactions, gate health, verdict) plus the tamper-evident `audit_hash`. With scorecard-v1 the response also carries the optional per-call `timeline` and `quality_metrics` eval blocks (empty…
- [List violations (findings)](https://docs.pyai.com/api-reference/trace/list-violations-findings.md): Cursor-paginated drill-down of every fired rule across scorecards. Filter by `rule_id`, `severity`, or `interaction_id`. Requires the `trace:read` scope.
- [List Tier-2 semantic findings](https://docs.pyai.com/api-reference/trace/list-tier-2-semantic-findings.md): Cursor-paginated Tier-2 (async semantic) findings, the model-judged concerns deterministic rules can't catch (HIPAA minimum-necessary, brand tone, hallucination-vs-knowledge-base, indirect opt-out, context-dependent PII). These are advisory and non-blocking, and are kept separate from the hash-chain…
- [Compliance exposure summary](https://docs.pyai.com/api-reference/trace/compliance-exposure-summary.md): The dashboard headline / Exposure Scan: interactions scanned, the share with a compliance gap, a per-rule exposure ranking, and the verdict mix over a trailing window. Requires the `trace:read` scope.
- [Get Recap config](https://docs.pyai.com/api-reference/recap/get-recap-config.md): Org Recap enablement, customer webhook URL, and default pack. Requires `recap:configure`.
- [Update Recap config](https://docs.pyai.com/api-reference/recap/update-recap-config.md): Enable Recap and set the customer webhook + default pack. Requires `recap:configure`.
- [Get Recap CRM config](https://docs.pyai.com/api-reference/recap/get-recap-crm-config.md): Salesforce field mapping and credentials (secrets redacted on GET). Requires `recap:configure`.
- [Update Recap CRM config](https://docs.pyai.com/api-reference/recap/update-recap-crm-config.md): Hand-configured Salesforce mapping for design partners. Omit secret fields on update to preserve existing values.
- [List recap records](https://docs.pyai.com/api-reference/recap/list-recap-records.md): Recent post-call recaps for this org. Requires `recap:read` and the Recap add-on enabled.
- [Get a recap record](https://docs.pyai.com/api-reference/recap/get-a-recap-record.md)
- [Manually trigger recap for a call](https://docs.pyai.com/api-reference/recap/manually-trigger-recap-for-a-call.md)
- [Correct transcript speaker roles](https://docs.pyai.com/api-reference/recap/correct-transcript-speaker-roles.md): Tenant-scoped correction of Recap speaker roles. Requires `recap:read` and the Recap add-on. Marks each edited utterance as a customer correction; does not rename upstream carriers.
- [Answering-machine detection (WebSocket)](https://docs.pyai.com/api-reference/amd/answering-machine-detection-websocket.md): Realtime answering-machine detection over a WebSocket. **This surface speaks Twilio's Media Streams protocol natively** (`start` / `media` / `stop` frames, G.711 μ-law 8 kHz base64, ~20 ms), so migrating from Twilio AMD is a one-line-TwiML change, point the call's media at PyAI, keep your carrier an…
- [Get AMD config](https://docs.pyai.com/api-reference/amd/get-amd-config.md): The org's AMD operating point (`aggressiveness`, 0-1) and webhook URL. Requires `amd:configure`.
- [Set AMD config](https://docs.pyai.com/api-reference/amd/set-amd-config.md): Set the account-default operating point and webhook. `aggressiveness` is one dial on the ROC curve: near **0** is human-safe (never hang up on a person, for live-agent dialers; on the deadline it returns `unknown` rather than risk a false `machine`), near **1** fires `machine` fast (for AI voicemail…
- [List AMD decisions](https://docs.pyai.com/api-reference/amd/list-amd-decisions.md): Recent AMD decisions for this org, newest first. Requires `amd:read`. Filter by `session_label` (the opaque tag you passed on the connect URL / TwiML).
- [Get an AMD decision](https://docs.pyai.com/api-reference/amd/get-an-amd-decision.md): The full decision for one call: `answered_by`, `answered_by_twilio`, `confidence`, `decision_ms`, and the word-level `reason`. Requires `amd:read`.
- [List knowledge bases](https://docs.pyai.com/api-reference/knowledge-bases/list-knowledge-bases.md): All hosted knowledge bases in your organization. Requires the `kb:manage` scope.
- [Create a knowledge base](https://docs.pyai.com/api-reference/knowledge-bases/create-a-knowledge-base.md): Create a hosted knowledge base. Names are unique per organization (case-insensitive). Requires the `kb:manage` scope.
- [List org-default KB bindings](https://docs.pyai.com/api-reference/knowledge-bases/list-org-default-kb-bindings.md): The knowledge bases every Omni session in your org grounds against when its agent has no specific binding. Requires the `kb:manage` scope.
- [Set org-default KB bindings](https://docs.pyai.com/api-reference/knowledge-bases/set-org-default-kb-bindings.md): Replace the org-default knowledge base bindings. Omni sessions opened without an agent profile (or whose profile binds nothing) ground against these. Requires the `kb:manage` scope.
- [Get a knowledge base (with documents)](https://docs.pyai.com/api-reference/knowledge-bases/get-a-knowledge-base-with-documents.md)
- [Delete a knowledge base](https://docs.pyai.com/api-reference/knowledge-bases/delete-a-knowledge-base.md): Marks the knowledge base deleted; its documents and chunks are removed. Agents bound to it fall back to the org defaults. Requires the `kb:manage` scope.
- [Rename a knowledge base](https://docs.pyai.com/api-reference/knowledge-bases/rename-a-knowledge-base.md)
- [List documents in a knowledge base](https://docs.pyai.com/api-reference/knowledge-bases/list-documents-in-a-knowledge-base.md)
- [Add a document (file, URL, or text)](https://docs.pyai.com/api-reference/knowledge-bases/add-a-document-file-url-or-text.md): Three ways to add content: a multipart file upload (pdf, docx, xlsx, txt, md, csv, html, json; 25MB max), a JSON `{ "url" }` to fetch and parse, or a JSON `{ "text" }` to paste content directly. The document registers as `pending` and is chunked + embedded asynchronously; poll its `status` until `in…
- [Crawl a public website into a knowledge base](https://docs.pyai.com/api-reference/knowledge-bases/crawl-a-public-website-into-a-knowledge-base.md): Discover same-origin pages from a public seed URL (robots.txt / sitemap, then a shallow link walk), rank them, and register each selected page as a normal URL document. Private, loopback, and metadata addresses are rejected. Defaults to 25 pages, hard-capped at 40. Already-ingested URLs in this know…
- [Remove a document](https://docs.pyai.com/api-reference/knowledge-bases/remove-a-document.md)
- [Edit a pasted-text document](https://docs.pyai.com/api-reference/knowledge-bases/edit-a-pasted-text-document.md): Edit in place and re-ingest. Only documents added as pasted text (`source: "api"`) can be edited; re-add files or URLs instead. Requires the `kb:manage` scope.
- [Inspect a document's extracted content](https://docs.pyai.com/api-reference/knowledge-bases/inspect-a-documents-extracted-content.md): Returns the document, its source text (for pasted-text documents), and the first 200 indexed chunks, so you can verify what agents will retrieve. Requires the `kb:manage` scope.
- [Retry document ingestion](https://docs.pyai.com/api-reference/knowledge-bases/retry-document-ingestion.md): Re-queue a `pending` or `failed` document for chunking + embedding. Requires the `kb:manage` scope.
- [List number compliance cases](https://docs.pyai.com/api-reference/telephony/list-number-compliance-cases.md)
- [Start a number compliance or porting case](https://docs.pyai.com/api-reference/telephony/start-a-number-compliance-or-porting-case.md): Starts a project-scoped workflow for a new number or port-in request in the US, Canada, India, the UK, or Australia. The applicable requirements and execution budgets are frozen at creation. Missing market rules fail closed. Requires `telephony:manage` and an `Idempotency-Key`.
- [Get a number compliance case](https://docs.pyai.com/api-reference/telephony/get-a-number-compliance-case.md)
- [Compute the current blocking checklist](https://docs.pyai.com/api-reference/telephony/compute-the-current-blocking-checklist.md)
- [Create a short-lived document upload grant](https://docs.pyai.com/api-reference/telephony/create-a-short-lived-document-upload-grant.md): Returns an opaque object reference and a five-minute, single-object V4 upload URL. The client must send every returned required header. The declared MIME type, size, and SHA-256 are pinned into object metadata; no URL or document bytes are persisted in the control-plane database.
- [Register document upload metadata](https://docs.pyai.com/api-reference/telephony/register-document-upload-metadata.md): Finalizes a previously granted upload. The immutable object generation, ownership path, signed metadata, byte length, SHA-256, and actual file signature are verified before a bounded malware scan runs. Extraction remains blocked unless the terminal scan result is clean.
- [Create a short-lived clean-document download grant](https://docs.pyai.com/api-reference/telephony/create-a-short-lived-clean-document-download-grant.md): Returns a five-minute V4 URL pinned to the verified object generation. Pending, failed, or infected documents fail closed.
- [Run document extraction](https://docs.pyai.com/api-reference/telephony/run-document-extraction.md): Runs bounded extraction for clean uploads. PyAI selects the processing route. Every selected upload receives a terminal success, failure, timeout, or cancellation record.
- [Correct an extracted field](https://docs.pyai.com/api-reference/telephony/correct-an-extracted-field.md)
- [Sign a required attestation](https://docs.pyai.com/api-reference/telephony/sign-a-required-attestation.md)
- [Human-approve and submit for network review](https://docs.pyai.com/api-reference/telephony/human-approve-and-submit-for-network-review.md): Submits for network review only after all evidence, confidence, matching, malware, and attestation gates pass and a human approver is named. Requires `Idempotency-Key`.
- [Cancel a number compliance case](https://docs.pyai.com/api-reference/telephony/cancel-a-number-compliance-case.md)
- [List normalized network status](https://docs.pyai.com/api-reference/telephony/list-normalized-network-status.md): Returns the provider-neutral network timeline for a compliance or porting case. Automated and operator-assisted paths use the same normalized statuses; internal notes and operator identities are never returned.
- [Search available numbers](https://docs.pyai.com/api-reference/telephony/search-available-numbers.md): Search PyAI's managed number inventory in the US, Canada, or India. `country` selects the market (US default; India numbers are subject to regulatory review). Filter by `area_code` (NPA, US and Canada) or a `contains` digit pattern. Monthly line prices are $1 for US and Canada numbers and $6 for Ind…
- [List your numbers](https://docs.pyai.com/api-reference/telephony/list-your-numbers.md): Your org's managed numbers, newest first. Active only unless `include_released=true`. Requires the `telephony:manage` scope.
- [Provision (buy) a number](https://docs.pyai.com/api-reference/telephony/provision-buy-a-number.md): Buy a specific available number and attach it to your org, optionally binding it to an `agent_id` for inbound routing. When search reports assisted ordering, support may pre-order the number and you can explicitly set `provisioning_mode=adopt_preowned`; this never places a new order. Recording runs…
- [Route a number to an agent](https://docs.pyai.com/api-reference/telephony/route-a-number-to-an-agent.md): Bind the number to an `agent_id` (or pass `null` to unassign) so inbound calls open that agent's Omni session. Requires the `telephony:manage` scope.
- [Release a number](https://docs.pyai.com/api-reference/telephony/release-a-number.md): Release the managed number (stops the monthly rental). Idempotent. Requires the `telephony:manage` scope.
- [Get outbound compliance policy](https://docs.pyai.com/api-reference/telephony/get-outbound-compliance-policy.md)
- [Configure outbound compliance policy](https://docs.pyai.com/api-reference/telephony/configure-outbound-compliance-policy.md): Set bounded calling windows, countries, velocity limits, and at most two pre-answer attempts. Strong defaults apply to omitted fields.
- [Record destination consent](https://docs.pyai.com/api-reference/telephony/record-destination-consent.md): Store tenant-scoped consent evidence. Sales requires express written consent. The response masks the destination.
- [Suppress an outbound destination](https://docs.pyai.com/api-reference/telephony/suppress-an-outbound-destination.md): Add a tenant-scoped opt-out or do-not-call suppression. The response masks the destination.
- [List caller identity readiness](https://docs.pyai.com/api-reference/telephony/list-caller-identity-readiness.md): List masked, tenant-scoped caller identity and attestation readiness.
- [List outbound calls](https://docs.pyai.com/api-reference/telephony/list-outbound-calls.md): Recent outbound call requests for your organization, with normalized network outcomes. Requires `telephony:manage`.
- [Start an outbound agent call](https://docs.pyai.com/api-reference/telephony/start-an-outbound-agent-call.md): Start an outbound call from one of your active managed numbers into an Omni agent. A valid Idempotency-Key is mandatory. PyAI never retries an ambiguous dispatch and never changes routes after answer; only a confirmed retryable pre-answer result may advance an approved route plan. Limited availabili…
- [Get an outbound call](https://docs.pyai.com/api-reference/telephony/get-an-outbound-call.md): Current state of one outbound call. Requires `telephony:manage`.
- [List your WhatsApp numbers](https://docs.pyai.com/api-reference/whatsapp/list-your-whatsapp-numbers.md): WhatsApp Business numbers registered to your org, newest first. Active only unless `include_released=true`. Requires the `telephony:manage` scope.
- [Register a WhatsApp Business number](https://docs.pyai.com/api-reference/whatsapp/register-a-whatsapp-business-number.md): Attach a WhatsApp Business number you already own on Meta's Cloud API to your org so an Omni agent can answer its calls. You bring the WhatsApp Business Account id, the number's `phone_number_id`, and a system-user access token with `whatsapp_business_messaging`; PyAI stores the token encrypted and…
- [Get a WhatsApp number](https://docs.pyai.com/api-reference/whatsapp/get-a-whatsapp-number.md)
- [Release a WhatsApp number](https://docs.pyai.com/api-reference/whatsapp/release-a-whatsapp-number.md): Detach the number from your org. Inbound WhatsApp calls to it are rejected from then on; nothing changes on Meta's side. Requires the `telephony:manage` scope.
- [Route a WhatsApp number to an agent](https://docs.pyai.com/api-reference/whatsapp/route-a-whatsapp-number-to-an-agent.md): Bind (or unbind with `agent_id: null`) the Omni agent that answers inbound WhatsApp calls to this number and is the default for outbound calls from it. Requires the `telephony:manage` scope.
- [Enable or disable calling on a WhatsApp number](https://docs.pyai.com/api-reference/whatsapp/enable-or-disable-calling-on-a-whatsapp-number.md): Pushes Meta's calling configuration for the number (`POST /{phone_number_id}/settings`): turns the call button on or off, and whether a user calling you automatically grants a 7-day call-back permission. Meta requires the number to have a messaging limit of at least 2,000 conversations per day befor…
- [Check call permission for a user](https://docs.pyai.com/api-reference/whatsapp/check-call-permission-for-a-user.md): Whether you may place a business-initiated call to `user` from `number_id`. Temporary permissions last 7 days; permanent ones until the user revokes them. Served from PyAI's cache when live, otherwise refreshed from Meta (`refresh=true` forces it). Requires the `telephony:manage` scope.
- [Ask a user for permission to call them](https://docs.pyai.com/api-reference/whatsapp/ask-a-user-for-permission-to-call-them.md): Sends Meta's interactive `call_permission_request` message from `number_id` to `user` with your `text`. Meta limits this to 1 request per 24 hours and 2 per 7 days per user; the user's reply is recorded from the webhook and gates `POST /v1/whatsapp/calls`. Requires the `telephony:manage` scope.
- [List WhatsApp calls](https://docs.pyai.com/api-reference/whatsapp/list-whatsapp-calls.md)
- [Place a WhatsApp call](https://docs.pyai.com/api-reference/whatsapp/place-a-whatsapp-call.md): Business-initiated WhatsApp call from `number_id` to `to`, answered by `agent_id` (defaults to the number's agent). Fails with 403 `call_permission_required` unless the user has a live call permission. Not available in every country (Meta blocks business-initiated calls in the US, Canada, Egypt, Vie…
- [Get a WhatsApp call](https://docs.pyai.com/api-reference/whatsapp/get-a-whatsapp-call.md)
- [Hang up a WhatsApp call](https://docs.pyai.com/api-reference/whatsapp/hang-up-a-whatsapp-call.md)

## OpenAPI Specs

- [openapi](https://api.pyai.com/openapi.json)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.