> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pyai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set an explicit managed inbound binding

> Compare-and-swap the number binding with expected_version (initially 0). Enable with project_id, agent_id, agent_release_id and agent_profile_sha256: SHA-256 of recursively key-sorted JSON for the full public Agent GET resource (array order retained). The profile must have no greeting variants or business tools. Explicit indexed knowledge requires agent_knowledge_receipt with exact owned document/source/index digests; organization inheritance and hidden context remain unsupported. The receipt is frozen with the binding and rechecked before answer and media admission. admission_mode=client waits up to 12 seconds before answer; platform accepts with a 120-second cap. Ordinary connected-number binding only reads already canonical carrier routing. Explicit activate_carrier_route=true with a stable carrier_operation_id captures encrypted prior routing before changing only this verified-owned carrier number's voice/status callbacks. Pending/unknown operations return 202, block new admissions and must be resumed with the same original request; GET exposes the immutable desired binding and original expected_version. Roll back with enabled=false, rollback_carrier_route=true, the same operation ID and current expected_version; routing is restored only if it still matches the operation's captured desired or prior hash. External drift is held unknown without overwrite. Existing admitted calls retain frozen authority. Set forward.menu.kind=keypad to save a spoken single-digit menu instead of forward.to. The number's menu capability is checked before saving or changing routing; unsupported numbers return unsupported_route. One attempt offers up to nine saved choices. Invalid input hangs up; an empty result uses timeout_choice_id or hangs up when null. A caller-bound callback freezes one selection before the ordinary target consent, country and capacity checks or dialing. Menu audio is not recorded; both recording notices run before forwarding connects. The original total call deadline stays fixed, and retries cannot change the saved prompt or selection or dial another target. Optional forward explicitly selects human forwarding on the registered switch instead of AI: the published profile remains pinned, target consent/country/capacity is checked before the sole target dispatch, and the original caller owns recording. This mode uses platform admission and a 30–3600 second absolute deadline; omitted/null forward retains AI behavior. No number acquisition occurs.



## OpenAPI

````yaml https://api.pyai.com/openapi.json put /v1/telephony/numbers/{id}/inbound-binding
openapi: 3.1.0
info:
  title: PyAI API
  version: 2.14.0
  description: >-
    Telephony-native Voice AI behind one bearer key:


    - **Hear**, speech-to-text · `POST /v1/audio/transcriptions` (streaming +
    batch)

    - **Speak**, text-to-speech · `POST /v1/audio/speech`, `GET /v1/voices`

    - **Clone**, custom voices from a short clip · `/v1/voice/clones`

    - **Cast**, auto-directed expressive voiceovers · `/v1/cast`

    - **Dub**, asynchronous audio and video dubbing · `POST /v1/dub`
    ([guide](https://docs.pyai.com/guides/dub-overview))

    - **Cue configuration frames (reserved)**; Hear streams skip knowledge-base
    retrieval by default

    - **Omni**, full-duplex agentic voice (speech-to-speech, grounded in your
    knowledge bases + tools) · `/v1/omni`

    - **Knowledge Bases**, hosted grounding for Omni: create bases, add
    documents (file, URL, or text), crawl a public website, bind to agents or
    org defaults · `/v1/knowledgebases`

    - **AMD API**, answering-machine detection: know *who or what* answered a
    call (human, voicemail, IVR, iPhone/Google screening, dead number) with the
    reason it decided · `wss …/v1/amd/stream` (Twilio Media Streams drop-in),
    `POST /v1/amd/config`, `GET /v1/amd/calls/{id}`

    - **Agents Beta**, the live console feature to create, configure, test, and
    connect Omni voice agents without code. Beta features and limits may change.


    ## Identity, billing and authentication

    - Before any generation or transcription, call GET /v1/me (MCP: whoami).
    Verify org_id, project_id, environment, scopes, limits and billing/credit
    context against the intended project. Do not infer identity or free usage
    from a key prefix or tool name. Stop on a mismatch or unknown budget; never
    switch to a live project automatically.

    - Test usage has enforced limits; live usage is billed. Current meters and
    rates: https://pyai.com/pricing. Agree a bounded input/request count before
    generating, and do not retry uncertain billable submissions blindly.


    Create a key in the [console](https://console.pyai.com) (it is shown once)
    and send it as a bearer token:


    ```

    Authorization: Bearer pyai_live_...

    ```


    Keys are environment-scoped: `pyai_live_...` (production) and
    `pyai_test_...` (sandbox). `POST /v1/sandbox/keys` creates an instant,
    short-lived test key without login or billing. Account signup also creates a
    sandbox key. Live keys consume prepaid credit; phone verification may unlock
    promotional credit under graduated-signup rules, but credit is not
    guaranteed at signup.


    Keys are self-validating signed tokens: they work on every PyAI surface the
    instant they are created, no activation or propagation delay. Treat them as
    opaque strings (up to 512 chars) and never parse their contents.


    Keep long-lived keys on trusted servers. For Omni browsers, mint an
    origin-locked short-lived token on your backend with POST /v1/omni/sessions;
    never expose a live or test API key in browser code. Offer the protocol
    marker and session token:


    ```

    Sec-WebSocket-Protocol: pyai.v1, pyai-key.<SESSION_TOKEN>

    ```


    (server-side clients may instead append `?api_key=...` to the URL). Your key
    is authenticated on the upgrade and never reaches the model.


    ## Quickstart, Hear (speech-to-text)


    ```

    curl https://api.pyai.com/v1/audio/transcriptions \
      -H "Authorization: Bearer $PYAI_API_KEY" \
      -F file=@audio.wav -F model=pyai-hear
    # -> { "text": "..." }

    ```


    ## Quickstart, Speak (text-to-speech)


    ```

    curl https://api.pyai.com/v1/audio/speech \
      -H "Authorization: Bearer $PYAI_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"model":"pyai-speak","input":"Hello from PyAI.","voice":"voice_abc"}' \
      --output speech.wav
    ```


    `voice` is a stock voice id from `GET /v1/voices` (the curated prebuilt
    catalog with personas and avatars) or a cloned voice id from
    `/v1/voice/clones`. Omit it to use the platform default voice
    (`stock_dorit_en_us`).


    ## Quickstart, Omni (realtime voice agent)


    Omni is **zero-state, there is nothing to create first.** Open a WebSocket,
    pass your key as a subprotocol, and send the agent's behavior (voice,
    persona, knowledge endpoint) in the first `configure` frame:


    ```

    wss://api.pyai.com/v1/omni?session_label=support&format=pcm16&rate=24000
      Sec-WebSocket-Protocol: pyai.v1, pyai-key.$PYAI_API_KEY
    ```


    The session is authorized by your key's **organization**; `session_label` is
    an **optional, opaque** tag (echoed to your own knowledge endpoint for
    correlation), omit it or use any value. When `session_label` equals a
    **`/v1/agents` profile id**, the engine loads persona, voice, and **greeting
    message** from that profile (turn-0 playback). `format` and `rate` are
    load-bearing on the connect URL (the SDK sets them). Prefix each PCM16 frame
    with byte `0x01`; prefix control JSON with byte `0x03`. **Optional
    convenience:** pre-store config via `POST /v1/agents` (including `greeting`,
    `consent_line`, `recordings_enabled`) and pass its id as `session_label`, or
    send everything inline in the post-handshake `configure` frame. Not required
    to connect.


    For reproducible eval runs, determinism controls (`seed`/`temperature`) ride
    the Omni session's `configure` frame, which the gateway passes through
    unchanged, they are honored once the engine supports them; no platform
    change is required.


    ## Scopes


    | Scope | Grants |

    | --- | --- |

    | `hear:transcribe` | `POST /v1/audio/transcriptions` |

    | `hear:stream` | `GET /v1/audio/transcriptions/stream` (WebSocket) |

    | `hear:configure` | `GET`/`PUT /v1/hear/vocabulary` |

    | `speak:synthesize` | `POST /v1/audio/speech` (Speak) |

    | `speak:clone` | `/v1/voice/clones` (Clone) |

    | `speak:design` | `/v1/voice/design` (Speak) |

    | `omni:session` | `/v1/omni` and `POST /v1/omni/sessions` (mint a browser
    session token) |

    | `omni:read` | `/v1/omni/calls` (Omni post-call records) |

    | `kb:manage` | `/v1/knowledgebases/*` (hosted knowledge bases for Omni
    grounding) |

    | `transcribe:jobs` | `/v1/transcription/jobs` |

    | `trace:configure` | `/v1/trace/config`, `/v1/trace/rule-packs` (Trace
    management) |

    | `trace:read` | `/v1/trace/interactions`, `/violations`, `/findings`,
    `/exposure` (Trace reads) |

    | `recap:configure` | `/v1/recap/config` (Recap management) |

    | `recap:configure` | `/v1/recap/crm-config` (Salesforce field mapping) |

    | `widgets:read` | Find published widget snippets in the selected project or
    preview a widget for a saved agent |

    | `widgets:manage` | Draft a website widget and publish an explicitly
    approved revision |

    | `recap:lookup` | GET `/v1/recap/calls` and GET by call ID (existing
    records in the organization) |

    | `recap:create` | POST `/v1/recap/calls/{call_id}` (submit a transcript for
    summary generation) |

    | `recap:read` | Legacy combined lookup, submission and speaker-role
    correction permission |

    | `amd:detect` | `wss …/v1/amd/stream` (AMD realtime detection, Twilio
    drop-in) |

    | `amd:configure` | `/v1/amd/config` (AMD operating-point dial + webhook) |

    | `amd:read` | `/v1/amd/calls` (AMD decision records) |

    | `telephony:manage` | `/v1/telephony/*` (managed numbers) |

    | `tenants:provision` | `/v1/managed-tenants` (registered integrations only;
    explicit grant) |


    `GET /v1/models`, `GET /v1/voices`, and `GET /v1/me` need no specific scope,
    any active key may call them. Wildcards (`hear:*`, `speak:*`, …, and the
    global `*`) grant every scope in their family.


    ## Canonical endpoints


    One row per product surface, endpoint, auth, required scope, and lifecycle
    status. **live** = generally available; **beta** = available now with
    features or limits that may change; **unavailable** = reserved in the
    contract but not active on the serving route.


    | Product | Endpoint | Auth | Scope | Status |

    | --- | --- | --- | --- | --- |

    | Identity | `GET /v1/me` | Bearer | _any active key_ | live |

    | Models | `GET /v1/models` | Bearer | _any active key_ | live |

    | Voices | `GET /v1/voices`, `GET /v1/voices/{id}` | Bearer | _any active
    key_ | live |

    | Hear (batch) | `POST /v1/audio/transcriptions` | Bearer |
    `hear:transcribe` | live |

    | Hear (vocabulary settings) | `GET`/`PUT /v1/hear/vocabulary` | Bearer |
    `hear:configure` | live |

    | Hear (streaming) | `GET /v1/audio/transcriptions/stream` (WS) |
    Subprotocol | `hear:stream` | live |

    | Cue | `GET /v1/audio/transcriptions/stream` + grounding (WS) | Subprotocol
    | `hear:stream` | unavailable |

    | Hear (async batch) | `POST`/`GET /v1/transcription/jobs` | Bearer |
    `transcribe:jobs` | live |

    | Speak (TTS) | `POST /v1/audio/speech` | Bearer | `speak:synthesize` | live
    |

    | Clone | `GET`/`POST /v1/voice/clones` | Bearer | `speak:clone` | live |

    | Speak (design) | `/v1/voice/design` | Bearer | `speak:design` | live |

    | Omni | `wss …/v1/omni?session_label=` | Subprotocol | `omni:session` |
    live |

    | Agent profiles (optional config) | `/v1/agents`, `/v1/agents/{id}` |
    Bearer | `omni:session` | live |

    | Knowledge Bases (hosted grounding) | `/v1/knowledgebases/*`, `PUT
    /v1/agents/{id}/knowledgebases` | Bearer | `kb:manage` (`omni:session` for
    the binding) | live |

    | Trace (config) | `/v1/trace/config`, `/v1/trace/rule-packs` | Bearer |
    `trace:configure` | beta |

    | Trace (reads) | `/v1/trace/interactions`, `/violations`, `/findings`,
    `/exposure` | Bearer | `trace:read` | beta |

    | Recap (config) | `/v1/recap/config` | Bearer | `recap:configure` | live |

    | Recap (CRM) | `/v1/recap/crm-config` | Bearer | `recap:configure` | live |

    | Integrations (Zapier) | `/v1/integrations/events`,
    `/v1/integrations/zapier/hooks` | Bearer | _any active key_ | live |

    | Recap (lookup) | GET `/v1/recap/calls[/{call_id}]` | Bearer |
    `recap:lookup` | active project with Recap enabled |

    | Omni call records | `/v1/omni/calls`, `/v1/omni/calls/{id}` | Bearer |
    `omni:read` | live |

    | AMD (stream) | `wss …/v1/amd/stream` (Twilio Media Streams drop-in) |
    TwiML `<Parameter name="api_key">` (from Twilio) or subprotocol
    (server-side) | `amd:detect` | live |

    | AMD (config) | `GET`/`POST /v1/amd/config` | Bearer | `amd:configure` |
    live |

    | AMD (reads) | `GET /v1/amd/calls`, `/v1/amd/calls/{id}` | Bearer |
    `amd:read` | live |

    | Telephony | `/v1/telephony/*` | Bearer | `telephony:manage` | live |

    | Agents (console builder) | `https://console.pyai.com/agents` | Console
    session |, | beta |


    WebSocket surfaces authenticate with the `Sec-WebSocket-Protocol: pyai.v1,
    pyai-key.<API_KEY>` subprotocol pair (or `?api_key=` server-side);
    everything else takes the `Authorization: Bearer` key. Managed-number calls
    return 404 until the PyAI network is enabled for the account.


    ## Rate limits & billing


    Every key has a per-second rate limit (with burst) and a cap on concurrent
    realtime sessions. Exceeding either returns `429` with a `Retry-After`
    header. Usage is metered per minute of audio, transcription minutes (Hear),
    synthesized audio minutes (Speak), and realtime session minutes (Omni), and
    billed against your plan and credits. List prices: Hear $0.001/min (async
    Transcribe $0.0005/min), Speak $0.04/min, Omni $0.05/min including speech
    plus brain, and Agents Live Beta $0.08/min. Managed telephony is separate at
    $0.01/min. English Natural (`en1`) is available on Speak (streaming and
    buffered) and Omni; Omni acknowledges the canonical id and `voice_tier:
    natural`. Hindi uses the Standard-tier voices `hi1`–`hi4` on Omni; the
    former Hindi Natural aliases (`hi5`–`hi8`) are retired and no longer in the
    catalog. Standard and Natural voices are included in their product's base
    rate with no voice-tier add-on. The AMD API bills per **answered** call, the
    first 5,000 answered calls each month are free, then $0.004/answered call
    (no-answers, busies, and failed calls are free; AMD bundled with PyAI
    telephony/Omni is included at no charge). Billing quantities depend on the
    endpoint. Synchronous Hear transcription rounds each non-empty request up to
    whole audio minutes, minimum one; a 5-second clip meters one minute. Speak
    uses fractional generated audio minutes. Omni uses session duration.
    Invoice-period rounding does not remove Hear's per-request rounding. Empty
    Hear transcripts and failed requests are not billed. Coarser pulses are
    available as an optional enterprise override. Managed telephony minutes keep
    a 1-minute pulse. Per-character Speak billing is available on enterprise
    contracts.
  contact:
    name: PyAI
    url: https://pyai.com
servers:
  - url: https://api.pyai.com
    description: Production
security:
  - apiKey: []
  - xApiKey: []
tags:
  - name: Dub
    description: >-
      Asynchronous dubbing: submit a recording, choose the languages, poll the
      job and download the output.
  - name: Omni
    description: >-
      The flagship: build an AI voice agent with one WebSocket (`GET /v1/omni`)
      and one `configure` frame, nothing to pre-create. This group also holds
      the optional browser-token mint and the post-call records.
  - name: Interpretation
    description: Live speech translation between two human call participants.
  - name: Knowledge Bases
    description: >-
      Hosted knowledge bases for Omni grounding: create a base, add documents
      (file upload, URL fetch, or pasted text), then bind it to agent profiles
      or set org-wide defaults. Bound bases are retrieved per turn, no
      `kb_endpoint` of your own required.
  - name: Identity
    description: >-
      Introspect the calling key: org/project, env, granted scopes, and
      limits/credit posture. Use it to self-diagnose a 401/403/402.
  - name: Speech To Text (Hear)
    description: Speech-to-text (streaming + batch)
  - name: Text To Speech (Speak)
    description: Text-to-speech, stock voices, and prompt-to-voice design
  - name: Clone
    description: Enroll, list, and delete custom voices from a short reference clip
  - name: Models
    description: Model catalog
  - name: Sandbox
    description: >-
      Zero-friction onboarding for coding agents: mint a free, instant, no-card
      sandbox key with no human steps.
  - name: Startup Program
    description: >-
      PyAI for Startups: $5k to $100k in non-cash promotional PyAI credit for
      early-stage teams building with speech, agents, translation, and
      compliance products. Public application endpoint; review and activation
      happen out of band.
  - name: Cast
    description: >-
      Auto-directed, expressive multi-line voiceover projects and asynchronous
      renders.
  - name: Transcription Jobs
    description: Async batch transcription
  - name: Agents
    description: >-
      Agent profiles used by the live Agents Beta console and available directly
      through the API. Store Omni session config (persona, greeting, voice,
      conversation knobs) and reference it by id instead of sending a full
      `configure` frame each call. Profiles remain optional for direct
      `/v1/omni` integrations.
  - name: Trace
    description: >-
      Compliance & guardrails: per-agent config, rule packs, and the exposure /
      violations / interaction-evidence read views
  - name: AMD
    description: >-
      Answering-machine detection: know who or what answered a call (human,
      voicemail, IVR, iPhone/Google screening, dead number), with the reason it
      decided. Twilio Media Streams drop-in over `wss …/v1/amd/stream`; one
      operating-point dial; billed per answered call.
  - name: Telephony
    description: >-
      Managed phone numbers: search, provision, route to an agent, and release.
      Call minutes bill on telephony.minutes ($0.01/min).
  - name: WhatsApp
    description: >-
      WhatsApp Business Calling: register a WhatsApp Business number, enable
      calling, and let an Omni agent answer (and, with the user's permission,
      place) WhatsApp voice calls. Requires the `telephony:manage` scope.
  - name: Call Integrations
    description: >-
      Signed provider webhooks that import completed calls into Hear, Recap, and
      offline Trace.
paths:
  /v1/telephony/numbers/{id}/inbound-binding:
    put:
      tags:
        - Telephony
      summary: Set an explicit managed inbound binding
      description: >-
        Compare-and-swap the number binding with expected_version (initially 0).
        Enable with project_id, agent_id, agent_release_id and
        agent_profile_sha256: SHA-256 of recursively key-sorted JSON for the
        full public Agent GET resource (array order retained). The profile must
        have no greeting variants or business tools. Explicit indexed knowledge
        requires agent_knowledge_receipt with exact owned document/source/index
        digests; organization inheritance and hidden context remain unsupported.
        The receipt is frozen with the binding and rechecked before answer and
        media admission. admission_mode=client waits up to 12 seconds before
        answer; platform accepts with a 120-second cap. Ordinary
        connected-number binding only reads already canonical carrier routing.
        Explicit activate_carrier_route=true with a stable carrier_operation_id
        captures encrypted prior routing before changing only this
        verified-owned carrier number's voice/status callbacks. Pending/unknown
        operations return 202, block new admissions and must be resumed with the
        same original request; GET exposes the immutable desired binding and
        original expected_version. Roll back with enabled=false,
        rollback_carrier_route=true, the same operation ID and current
        expected_version; routing is restored only if it still matches the
        operation's captured desired or prior hash. External drift is held
        unknown without overwrite. Existing admitted calls retain frozen
        authority. Set forward.menu.kind=keypad to save a spoken single-digit
        menu instead of forward.to. The number's menu capability is checked
        before saving or changing routing; unsupported numbers return
        unsupported_route. One attempt offers up to nine saved choices. Invalid
        input hangs up; an empty result uses timeout_choice_id or hangs up when
        null. A caller-bound callback freezes one selection before the ordinary
        target consent, country and capacity checks or dialing. Menu audio is
        not recorded; both recording notices run before forwarding connects. The
        original total call deadline stays fixed, and retries cannot change the
        saved prompt or selection or dial another target. Optional forward
        explicitly selects human forwarding on the registered switch instead of
        AI: the published profile remains pinned, target
        consent/country/capacity is checked before the sole target dispatch, and
        the original caller owns recording. This mode uses platform admission
        and a 30–3600 second absolute deadline; omitted/null forward retains AI
        behavior. No number acquisition occurs.
      operationId: setTelephonyInboundBinding
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - expected_version
                - enabled
              properties:
                expected_version:
                  type: integer
                  minimum: 0
                enabled:
                  type: boolean
                project_id:
                  type: string
                agent_id:
                  type: string
                agent_release_id:
                  type: string
                  maxLength: 200
                agent_profile_sha256:
                  type: string
                  pattern: ^[0-9a-f]{64}$
                agent_knowledge_receipt:
                  $ref: '#/components/schemas/TelephonyInboundKnowledgeReceipt'
                admission_mode:
                  type: string
                  enum:
                    - platform
                    - client
                  default: platform
                forward:
                  $ref: '#/components/schemas/TelephonyInboundForward'
                ring_group:
                  anyOf:
                    - $ref: '#/components/schemas/TelephonyInboundRingGroup'
                    - type: 'null'
                activate_carrier_route:
                  type: boolean
                  default: false
                rollback_carrier_route:
                  type: boolean
                  default: false
                carrier_operation_id:
                  type: string
                  minLength: 8
                  maxLength: 128
                  pattern: ^[A-Za-z0-9:_-]+$
      responses:
        '200':
          description: Saved binding
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TelephonyInboundBinding'
        '202':
          description: >-
            Carrier operation pending or unknown; inspect its safe receipt and
            resume the same request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TelephonyInboundBinding'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Binding revision, route or profile is unavailable.
components:
  schemas:
    TelephonyInboundKnowledgeReceipt:
      type: object
      additionalProperties: false
      required:
        - version
        - kb_id
        - documents
      properties:
        version:
          type: integer
          const: 1
        kb_id:
          type: string
          pattern: ^[A-Za-z0-9_-]{1,128}$
        documents:
          type: array
          minItems: 1
          maxItems: 6
          items:
            type: object
            additionalProperties: false
            required:
              - document_id
              - source_sha256
              - chunks_sha256
              - chunks
            properties:
              document_id:
                type: string
                pattern: ^[A-Za-z0-9_-]{1,128}$
              source_sha256:
                type: string
                pattern: ^[a-f0-9]{64}$
                description: >-
                  SHA-256 of recursively key-sorted JSON {title,sourceText}
                  matching the indexed private API document.
              chunks_sha256:
                type: string
                pattern: ^[a-f0-9]{64}$
                description: >-
                  SHA-256 of recursively key-sorted indexedChunks JSON; array
                  order retained.
              chunks:
                type: integer
                minimum: 1
                maximum: 200
    TelephonyInboundForward:
      type:
        - object
        - 'null'
      additionalProperties: false
      required:
        - max_duration_seconds
        - recording
      oneOf:
        - type: 'null'
        - type: object
          required:
            - to
          not:
            required:
              - menu
        - type: object
          required:
            - menu
          not:
            required:
              - to
      properties:
        to:
          type: string
          pattern: ^\+[1-9][0-9]{6,14}$
          description: >-
            Explicit US/AU/IN target, subject to current tenant consent and
            policy.
        menu:
          $ref: '#/components/schemas/TelephonyInboundMenu'
        max_duration_seconds:
          type: integer
          minimum: 30
          maximum: 3600
        recording:
          type: boolean
    TelephonyInboundRingGroup:
      type: object
      additionalProperties: false
      required:
        - mode
        - desktop_endpoint_ids
        - external_to
        - desktop_timeout_seconds
        - ring_timeout_seconds
        - on_no_answer
        - max_duration_seconds
        - recording
      description: >-
        One registered app desktop and one authorized external recipient. Choose
        simultaneous or desktop-first ringing. The total ring window and
        absolute original call deadline never reset on fallback. A registered
        but offline desktop is skipped. Only hangup on no answer is supported.
        Mutually exclusive with forward; null restores the explicitly supplied
        AI admission_mode without changing the original carrier activation.
      properties:
        mode:
          enum:
            - simultaneous
            - desktop_first
        desktop_endpoint_ids:
          type: array
          minItems: 1
          maxItems: 1
          items:
            type: string
            pattern: ^dsk_[a-f0-9]{32}$
        external_to:
          type: string
        desktop_timeout_seconds:
          type: integer
          minimum: 5
          maximum: 30
        ring_timeout_seconds:
          type: integer
          minimum: 10
          maximum: 60
        on_no_answer:
          const: hangup
        max_duration_seconds:
          type: integer
          minimum: 30
          maximum: 3600
        recording:
          type: boolean
    TelephonyInboundBinding:
      type: object
      required:
        - object
        - number_id
        - version
        - enabled
      properties:
        object:
          type: string
          const: telephony.inbound_binding
        number_id:
          type: string
        version:
          type: integer
          minimum: 0
        enabled:
          type: boolean
        project_id:
          type: string
        agent_id:
          type: string
        agent_release_id:
          type: string
        agent_profile_sha256:
          type: string
          pattern: ^[0-9a-f]{64}$
        agent_knowledge_receipt:
          $ref: '#/components/schemas/TelephonyInboundKnowledgeReceipt'
        forward:
          $ref: '#/components/schemas/TelephonyInboundForward'
        ring_group:
          $ref: '#/components/schemas/TelephonyInboundRingGroup'
        admission_mode:
          type: string
          enum:
            - client
            - platform
        carrier_operation:
          type: object
          required:
            - id
            - phase
            - revision
            - request_sha256
            - prior_route_sha256
            - desired_route_sha256
            - expected_version
            - desired_binding
          properties:
            id:
              type: string
            phase:
              type: string
              enum:
                - pending
                - unknown
                - active
                - rollback_pending
                - rolled_back
            revision:
              type: integer
              minimum: 1
            request_sha256:
              type: string
            prior_route_sha256:
              type: string
            desired_route_sha256:
              type: string
            expected_version:
              type: integer
              minimum: 0
            rollback_expected_version:
              type: integer
              minimum: 0
            desired_binding:
              type: object
              required:
                - project_id
                - agent_id
                - agent_release_id
                - agent_profile_sha256
                - admission_mode
              properties:
                project_id:
                  type: string
                agent_id:
                  type: string
                agent_release_id:
                  type: string
                agent_profile_sha256:
                  type: string
                agent_knowledge_receipt:
                  $ref: '#/components/schemas/TelephonyInboundKnowledgeReceipt'
                forward:
                  $ref: '#/components/schemas/TelephonyInboundForward'
                ring_group:
                  $ref: '#/components/schemas/TelephonyInboundRingGroup'
                admission_mode:
                  type: string
                  enum:
                    - client
                    - platform
    TelephonyInboundMenu:
      type: object
      additionalProperties: false
      required:
        - kind
        - prompt
        - choices
        - timeout_seconds
        - timeout_choice_id
      properties:
        kind:
          type: string
          const: keypad
        prompt:
          type: string
          minLength: 1
          maxLength: 1000
        choices:
          type: array
          minItems: 1
          maxItems: 9
          items:
            type: object
            additionalProperties: false
            required:
              - id
              - key
              - to
            properties:
              id:
                type: string
                pattern: ^[A-Za-z0-9_-]{1,64}$
              key:
                type: string
                pattern: ^[0-9]$
              to:
                type: string
                pattern: ^\+[1-9][0-9]{6,14}$
        timeout_seconds:
          type: integer
          minimum: 1
          maximum: 10
        timeout_choice_id:
          type:
            - string
            - 'null'
          maxLength: 64
    Problem:
      type: object
      description: >-
        RFC 7807 problem+json returned by the control plane (request-validation
        and resource errors such as 400/404/409). The stable code is the last
        path segment of `type`.
      required:
        - title
        - status
      properties:
        type:
          type: string
          description: Problem type URI; ends with the stable code.
        title:
          type: string
        status:
          type: integer
        detail:
          type: string
        request_id:
          type: string
  responses:
    BadRequest:
      description: Invalid request (bad field, unsupported value)
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    NotFound:
      description: 'Resource not found (`code: not_found`)'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: 'Use `Authorization: Bearer pyai_live_...` (or `pyai_test_...`).'
    xApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Header alias for bearer auth on HTTP endpoints. WebSocket auth uses the
        subprotocol pair `pyai.v1, pyai-key.<API_KEY>`.

````

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