telnyx 5.174.0 → 5.175.0

data/rbi/telnyx/resources/agent_gateways.rbi

@@ -0,0 +1,159 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    class AgentGateways
+      # REST APIs on an instance, served to agents as tools.
+      sig { returns(Telnyx::Resources::AgentGateways::APIs) }
+      attr_reader :apis
+
+      # Checks an instance runs on model and tool requests.
+      sig { returns(Telnyx::Resources::AgentGateways::Guardrails) }
+      attr_reader :guardrails
+
+      # Keys on an instance.
+      sig { returns(Telnyx::Resources::AgentGateways::Keys) }
+      attr_reader :keys
+
+      # MCP servers on an instance, served to agents at one MCP endpoint.
+      sig { returns(Telnyx::Resources::AgentGateways::McpServers) }
+      attr_reader :mcp_servers
+
+      # Named sets of guardrails an instance applies to requests.
+      sig { returns(Telnyx::Resources::AgentGateways::Policies) }
+      attr_reader :policies
+
+      # Where an instance applies each policy.
+      sig { returns(Telnyx::Resources::AgentGateways::PolicyAttachments) }
+      attr_reader :policy_attachments
+
+      # Teams on an instance: shared model lists, budgets, and rate limits.
+      sig { returns(Telnyx::Resources::AgentGateways::Teams) }
+      attr_reader :teams
+
+      # Creates an Agent Gateway instance on one of the account's WireGuard Interfaces.
+      # The instance starts `pending`, moves to `provisioning`, and then to `ready` or
+      # `failed`. It joins the WireGuard Interface as a peer named `agw-<instance id>`,
+      # and its `gateway_url` is set when it is `ready`.
+      sig do
+        params(
+          wireguard_interface_id: String,
+          name: T.nilable(String),
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::AgentGatewayResponse)
+      end
+      def create(
+        # One of the account's WireGuard Interfaces. The instance joins it as a peer, and
+        # the interface's other peers reach the instance.
+        wireguard_interface_id:,
+        # A label for people.
+        name: nil,
+        request_options: {}
+      )
+      end
+
+      # Returns one of the account's Agent Gateway instances.
+      sig do
+        params(
+          instance_id: String,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::AgentGatewayResponse)
+      end
+      def retrieve(
+        # The Agent Gateway's `id`.
+        instance_id,
+        request_options: {}
+      )
+      end
+
+      # Lists the account's Agent Gateway instances, newest first, one page at a time.
+      sig do
+        params(
+          page_number: Integer,
+          page_size: Integer,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::Internal::DefaultFlatPagination[Telnyx::AgentGateway])
+      end
+      def list(
+        # The page to return, counting from 1.
+        page_number: nil,
+        # Results per page.
+        page_size: nil,
+        request_options: {}
+      )
+      end
+
+      # Deletes an Agent Gateway instance in any status. The response shows it
+      # `deleting`; repeating the request answers the same until the instance is gone,
+      # and then `404`. The instance's engine and everything stored on it are removed.
+      sig do
+        params(
+          instance_id: String,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::AgentGatewayResponse)
+      end
+      def delete(
+        # The Agent Gateway's `id`.
+        instance_id,
+        request_options: {}
+      )
+      end
+
+      # Lists the models the instance serves. Each has the name a request uses, the
+      # Telnyx Inference model behind it, and its price per million tokens.
+      sig do
+        params(
+          instance_id: String,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::Models::AgentGatewayRetrieveModelsResponse)
+      end
+      def retrieve_models(
+        # The Agent Gateway's `id`.
+        instance_id,
+        request_options: {}
+      )
+      end
+
+      # Lists the requests the instance served with its keys, newest first, one page at
+      # a time. The window defaults to the last 24 hours and spans at most 31 days. A
+      # row appears a few seconds after its request. The instance must be `ready`;
+      # otherwise the request answers `409`.
+      sig do
+        params(
+          instance_id: String,
+          end_: Time,
+          key_id: String,
+          page_number: Integer,
+          page_size: Integer,
+          start: Time,
+          team_id: String,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::Models::AgentGatewayRetrieveSpendLogsResponse)
+      end
+      def retrieve_spend_logs(
+        # The Agent Gateway's `id`.
+        instance_id,
+        # The window's end, an RFC 3339 timestamp with an offset. Defaults to now.
+        end_: nil,
+        # Only the requests made with this key.
+        key_id: nil,
+        # The page to return, counting from 1.
+        page_number: nil,
+        # Results per page.
+        page_size: nil,
+        # The window's start, an RFC 3339 timestamp with an offset. Defaults to 24 hours
+        # before `end`.
+        start: nil,
+        # Only the requests made with this team's keys.
+        team_id: nil,
+        request_options: {}
+      )
+      end
+
+      # @api private
+      sig { params(client: Telnyx::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/telnyx/resources/ai/conversations.rbi

@@ -148,7 +148,11 @@ module Telnyx
         )
         end
 
-        # Delete a specific conversation by its ID.
+        # Delete a specific conversation by its ID. Permanently deletes the conversation
+        # and its associated data: the conversation's messages, its insight generation
+        # results, any conversation memories, and its webhook request logs. Recordings are
+        # not deleted — recordings are managed separately through the /v2/recordings
+        # endpoints. This action cannot be undone.
         sig do
           params(
             conversation_id: String,
@@ -216,6 +220,30 @@ module Telnyx
         )
         end
 
+        # Delete one insight generation request for a conversation. Generation results are
+        # stored per conversation and per insight template; deleting a request permanently
+        # removes the stored result but does not stop insight generation from running
+        # again. To remove every insight result for the conversation, delete the
+        # conversation itself. A successful delete returns an empty response.
+        sig do
+          params(
+            insight_id: String,
+            conversation_id: String,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).void
+        end
+        def delete_delete(
+          # Unique identifier of the insight generation request to delete, as returned as
+          # `data.id` by the insight generation and insights-list operations. Note that the
+          # nested `conversation_insights[].insight_id` field returned in the insights-list
+          # response is the insight template ID, not the ID accepted here.
+          insight_id,
+          # Unique identifier of the conversation.
+          conversation_id:,
+          request_options: {}
+        )
+        end
+
         # Retrieve insights for a specific conversation
         sig do
           params(

data/rbi/telnyx/resources/ai/openai/chat.rbi

@@ -90,14 +90,12 @@ module Telnyx
             # /v2/ai/openai/models). An omitted limit on an excluded model remains unset even
             # when metadata declares a ceiling. Input and output together must fit the model's
             # context window. Set an explicit limit when a bounded generation budget is
-            # required. For current Telnyx-hosted models, omitted or null limits default to
-            # 8192 for `zai-org/GLM-5.3`, `zai-org/GLM-5.3-Flash` and
-            # `deepseek-ai/DeepSeek-V4.1-Flash`. The hosted exclusions are
+            # required. For example, omitted or null limits default to 8192 for
+            # `zai-org/GLM-5.3` and `zai-org/GLM-5.3-Flash`. Hosted exclusions include
             # `moonshotai/Kimi-K3`, `moonshotai/Kimi-K2.6`, `moonshotai/Kimi-K2.5`,
             # `zai-org/GLM-5.2`, `zai-org/GLM-5.1-FP8`, `MiniMaxAI/MiniMax-M3-MXFP8`,
             # `MiniMaxAI/MiniMax-M2.7`, `Qwen/Qwen3.8-27B`, `Qwen/Qwen3-235B-A22B`,
-            # `deepseek-ai/DeepSeek-V4-Flash-0731`, `meta-llama/Llama-3.3-70B-Instruct`,
-            # `meta-llama/Meta-Llama-3.1-70B-Instruct`,
+            # `meta-llama/Llama-3.3-70B-Instruct`, `meta-llama/Meta-Llama-3.1-70B-Instruct`,
             # `meta-llama/Meta-Llama-3.1-8B-Instruct` and `google/gemma-2b-it`. Legacy
             # external and fine-tuned model IDs can also bypass the default; model discovery
             # reports completion ceilings, not whether this default applies. Set an explicit

data/rbi/telnyx/resources/browser_sessions.rbi

@@ -15,7 +15,7 @@ module Telnyx
           policy: Telnyx::BrowserSessionCreateParams::Policy::OrHash,
           idempotency_key: String,
           limits: Telnyx::BrowserSessionCreateParams::Limits::OrHash,
-          metadata: T.anything,
+          metadata: T::Hash[Symbol, T.anything],
           request_options: Telnyx::RequestOptions::OrHash
         ).returns(Telnyx::Models::BrowserSessionCreateResponse)
       end

data/rbi/telnyx/resources/calendar_connections/meetings.rbi

@@ -0,0 +1,62 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    class CalendarConnections
+      # Connect calendars and manage automatic meeting joins.
+      class Meetings
+        # Set an individual meeting override: true opts in, false opts out, null follows
+        # the connection policy. A supported meeting link is required. Changes re-evaluate
+        # the meeting immediately; poll the linked session for its final lifecycle
+        # outcome.
+        sig do
+          params(
+            meeting_id: String,
+            id: String,
+            bot_will_join: T.nilable(T::Boolean),
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(Telnyx::Models::CalendarConnections::MeetingUpdateResponse)
+        end
+        def update(
+          # Path param: Tracked meeting ID.
+          meeting_id,
+          # Path param: Calendar connection ID.
+          id:,
+          # Body param: True opts in, false opts out, null follows connection policy. A
+          # supported meeting URL is still required.
+          bot_will_join:,
+          request_options: {}
+        )
+        end
+
+        # List tracked meetings in a window. Defaults from now through seven days from
+        # now. from must not exceed to and the window must not exceed 31 days.
+        # bot_will_join is the effective policy decision; check session_id and the linked
+        # session status for actual attendance.
+        sig do
+          params(
+            id: String,
+            from: Time,
+            to: Time,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(Telnyx::Models::CalendarConnections::MeetingListResponse)
+        end
+        def list(
+          # Calendar connection ID.
+          id,
+          # Window start; defaults to now.
+          from: nil,
+          # Window end; defaults to seven days from now.
+          to: nil,
+          request_options: {}
+        )
+        end
+
+        # @api private
+        sig { params(client: Telnyx::Client).returns(T.attached_class) }
+        def self.new(client:)
+        end
+      end
+    end
+  end
+end

data/rbi/telnyx/resources/calendar_connections.rbi

@@ -0,0 +1,137 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    # Connect calendars and manage automatic meeting joins.
+    class CalendarConnections
+      # Connect calendars and manage automatic meeting joins.
+      sig { returns(Telnyx::Resources::CalendarConnections::Meetings) }
+      attr_reader :meetings
+
+      # Start Google Calendar or Microsoft Outlook OAuth. Open oauth_url in a browser.
+      # No connection exists until authorization succeeds. The resulting connection is
+      # owned by the connecting user.
+      sig do
+        params(
+          platform: Telnyx::CalendarConnectionCreateParams::Platform::OrSymbol,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::Models::CalendarConnectionCreateResponse)
+      end
+      def create(
+        # Calendar provider: Google Calendar or Microsoft Outlook.
+        platform:,
+        request_options: {}
+      )
+      end
+
+      # Retrieve a calendar connection owned by the authenticated connecting user.
+      # Missing and foreign connections both return 404. Signing secrets are omitted.
+      sig do
+        params(
+          id: String,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::CalendarConnectionResponse)
+      end
+      def retrieve(
+        # Calendar connection ID.
+        id,
+        request_options: {}
+      )
+      end
+
+      # Update policy or defaults for future sessions. Supply at least one field.
+      # Existing sessions retain their configuration. Null clears nullable overrides.
+      # Assistant, recording, and webhook defaults apply to Google Meet and Teams.
+      # Assistant defaults require default_barge_in to be false or null and
+      # default_voice to be null. Recording=true requires a destination; false rejects
+      # one. A non-null default_webhook_url update returns webhook_secret once; save it
+      # to verify future session deliveries.
+      sig do
+        params(
+          id: String,
+          auto_join_policy:
+            Telnyx::CalendarConnectionUpdateParams::AutoJoinPolicy::OrSymbol,
+          bot_name: T.nilable(String),
+          default_assistant:
+            T.nilable(
+              Telnyx::CalendarConnectionUpdateParams::DefaultAssistant::OrHash
+            ),
+          default_barge_in: T.nilable(T::Boolean),
+          default_recording: T.nilable(T::Boolean),
+          default_recording_export:
+            T.nilable(Telnyx::MeetingSessionRecordingDestination::OrHash),
+          default_summarize_on_end: T.nilable(T::Boolean),
+          default_voice: T.nilable(String),
+          default_webhook_url: T.nilable(String),
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::Models::CalendarConnectionUpdateResponse)
+      end
+      def update(
+        # Calendar connection ID.
+        id,
+        # all_meetings joins eligible events; external_organizer_excluded requires the
+        # connected user to be the organizer; per_meeting requires an explicit opt-in.
+        auto_join_policy: nil,
+        # Bot display name; null clears the override.
+        bot_name: nil,
+        # Default assistant for future calendar-scheduled Google Meet and Teams sessions.
+        # The saved configuration must fit within 8 KiB. Use id, audio_gate,
+        # dynamic_variables, and leave_on_end; avatar is not accepted. audio_gate defaults
+        # to full_duplex.
+        default_assistant: nil,
+        # Default manual speech interruption. Cannot be true with default_assistant.
+        default_barge_in: nil,
+        # Google Meet and Teams recording intent. When null, recording is enabled only if
+        # a destination is set. True requires default_recording_export; false cannot be
+        # combined with a destination.
+        default_recording: nil,
+        # Customer-owned Telnyx Storage destination for recording exports. Uses the
+        # authenticated organization and user; do not supply credentials, region,
+        # organization ID or object key.
+        default_recording_export: nil,
+        # Generate a summary when each future session transcript finalizes.
+        default_summarize_on_end: nil,
+        # Manual-speech voice; must be null when default_assistant is set.
+        default_voice: nil,
+        # HTTPS destination for future session webhooks. Null clears the default. A
+        # non-null update returns webhook_secret once; save it to verify signatures for
+        # sessions created with this default. Existing sessions retain their original
+        # signing secret.
+        default_webhook_url: nil,
+        request_options: {}
+      )
+      end
+
+      # List only the authenticated connecting user’s calendar connections. Session
+      # resources created by those connections are shared within the organization.
+      sig do
+        params(request_options: Telnyx::RequestOptions::OrHash).returns(
+          Telnyx::Models::CalendarConnectionListResponse
+        )
+      end
+      def list(request_options: {})
+      end
+
+      # Disconnect the calendar, cancel future joins, and clear retained calendar
+      # identity fields. Previously created session records, transcripts, artifacts, and
+      # Storage objects remain. The response is the updated connection.
+      sig do
+        params(
+          id: String,
+          request_options: Telnyx::RequestOptions::OrHash
+        ).returns(Telnyx::CalendarConnectionResponse)
+      end
+      def delete(
+        # Calendar connection ID.
+        id,
+        request_options: {}
+      )
+      end
+
+      # @api private
+      sig { params(client: Telnyx::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/telnyx/resources/calls/actions.rbi

@@ -498,7 +498,8 @@ module Telnyx
                 Telnyx::AzureVoiceSettings::OrHash,
                 Telnyx::ResembleVoiceSettings::OrHash,
                 Telnyx::XaiVoiceSettings::OrHash,
-                Telnyx::Calls::SonioxVoiceSettings::OrHash
+                Telnyx::Calls::SonioxVoiceSettings::OrHash,
+                Telnyx::Calls::AssemblyAIVoiceSettings::OrHash
               ),
             request_options: Telnyx::RequestOptions::OrHash
           ).returns(Telnyx::Models::Calls::ActionGatherUsingAIResponse)
@@ -724,7 +725,8 @@ module Telnyx
                 Telnyx::ResembleVoiceSettings::OrHash,
                 Telnyx::InworldVoiceSettings::OrHash,
                 Telnyx::XaiVoiceSettings::OrHash,
-                Telnyx::Calls::SonioxVoiceSettings::OrHash
+                Telnyx::Calls::SonioxVoiceSettings::OrHash,
+                Telnyx::Calls::AssemblyAIVoiceSettings::OrHash
               ),
             request_options: Telnyx::RequestOptions::OrHash
           ).returns(Telnyx::Models::Calls::ActionGatherUsingSpeakResponse)
@@ -1284,7 +1286,8 @@ module Telnyx
                 Telnyx::ResembleVoiceSettings::OrHash,
                 Telnyx::InworldVoiceSettings::OrHash,
                 Telnyx::XaiVoiceSettings::OrHash,
-                Telnyx::Calls::SonioxVoiceSettings::OrHash
+                Telnyx::Calls::SonioxVoiceSettings::OrHash,
+                Telnyx::Calls::AssemblyAIVoiceSettings::OrHash
               ),
             request_options: Telnyx::RequestOptions::OrHash
           ).returns(Telnyx::Models::Calls::ActionSpeakResponse)
@@ -1512,7 +1515,8 @@ module Telnyx
                 Telnyx::ResembleVoiceSettings::OrHash,
                 Telnyx::InworldVoiceSettings::OrHash,
                 Telnyx::XaiVoiceSettings::OrHash,
-                Telnyx::Calls::SonioxVoiceSettings::OrHash
+                Telnyx::Calls::SonioxVoiceSettings::OrHash,
+                Telnyx::Calls::AssemblyAIVoiceSettings::OrHash
               ),
             request_options: Telnyx::RequestOptions::OrHash
           ).returns(Telnyx::Models::Calls::ActionStartConversationRelayResponse)

data/rbi/telnyx/resources/conferences/actions.rbi

@@ -535,7 +535,8 @@ module Telnyx
                 Telnyx::ResembleVoiceSettings::OrHash,
                 Telnyx::InworldVoiceSettings::OrHash,
                 Telnyx::XaiVoiceSettings::OrHash,
-                Telnyx::Calls::SonioxVoiceSettings::OrHash
+                Telnyx::Calls::SonioxVoiceSettings::OrHash,
+                Telnyx::Calls::AssemblyAIVoiceSettings::OrHash
               ),
             request_options: Telnyx::RequestOptions::OrHash
           ).returns(Telnyx::Models::Conferences::ActionSpeakResponse)

data/rbi/telnyx/resources/email_events.rbi

@@ -28,7 +28,11 @@ module Telnyx
           page_cursor: String,
           to: Time,
           request_options: Telnyx::RequestOptions::OrHash
-        ).returns(Telnyx::Models::EmailEventListResponse)
+        ).returns(
+          Telnyx::Internal::EmailEventsCursorPagination[
+            Telnyx::Models::EmailEventListResponse
+          ]
+        )
       end
       def list(
         # Filter events for a specific email message UUID. Invalid UUID values are

data/rbi/telnyx/resources/meeting_bot/calendar.rbi

@@ -0,0 +1,38 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    class MeetingBot
+      # Connect calendars and manage automatic meeting joins.
+      class Calendar
+        # Browser redirect after calendar consent. Use the returned oauth_url rather than
+        # constructing this request. Verified state identifies the connecting user.
+        # Returns HTML for success, cancellation, or failure; no JSON error envelope or
+        # bearer token is used.
+        sig do
+          params(
+            code: String,
+            error: String,
+            state: String,
+            request_options: Telnyx::RequestOptions::OrHash
+          ).returns(String)
+        end
+        def retrieve_oauth_callback(
+          # Authorization code supplied by the calendar provider.
+          code: nil,
+          # Authorization error supplied by the calendar provider, such as access_denied.
+          error: nil,
+          # Unmodified signed state from the authorization URL.
+          state: nil,
+          request_options: {}
+        )
+        end
+
+        # @api private
+        sig { params(client: Telnyx::Client).returns(T.attached_class) }
+        def self.new(client:)
+        end
+      end
+    end
+  end
+end

data/rbi/telnyx/resources/meeting_bot.rbi

@@ -0,0 +1,16 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    class MeetingBot
+      # Connect calendars and manage automatic meeting joins.
+      sig { returns(Telnyx::Resources::MeetingBot::Calendar) }
+      attr_reader :calendar
+
+      # @api private
+      sig { params(client: Telnyx::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/telnyx/resources/meeting_sessions/actions.rbi

@@ -5,7 +5,13 @@ module Telnyx
     class MeetingSessions
       # Send real-time speech and chat actions to an active meeting session.
       class Actions
-        # Sends a chat message into a meeting session.
+        # Send chat as the bot in an active meeting. Returns 202 with data.accepted=true.
+        # Google Meet and Teams confirm sending before success; 502 chat_not_sent means
+        # not sent, while chat_delivery_unknown means delivery may have occurred. Inspect
+        # chat and chat.sent events before retrying an uncertain send. Each request is a
+        # new message and is not idempotent. Google Meet and Teams allow at most 1000 chat
+        # requests per session, including an entrance message; exceeding this returns 409
+        # invalid_state.
         sig do
           params(
             id: String,
@@ -16,22 +22,22 @@ module Telnyx
         def send_chat(
           # Unique identifier for the meeting session.
           id,
-          # Chat message text to send in the meeting.
+          # Message text, 1–4000 characters. On Google Meet and Teams, also at most 4096
+          # UTF-8 bytes and nonblank; control characters other than tab and line breaks are
+          # rejected. CRLF is normalized to LF.
           text:,
           request_options: {}
         )
         end
 
         # Sends audio / text-to-speech into a meeting session. With a Telnyx AI Assistant
-        # attached, the bot is a webpage-output bot: the speak audio routes through the
-        # assistant's output page rather than the bot mic and plays once the assistant is
-        # connected -- it is not refused. If that page cannot be reached, delivery fails
-        # with the 502 below, which may arrive without an error envelope, so branch on the
-        # status code before parsing a body. The assistant is designed to own the
-        # conversation, so prefer letting it speak or use `send_chat`. With a digital
-        # avatar (`assistant.avatar: true`), speak is refused with 409 `invalid_state`
-        # (message prefix `avatar_requires_assistant_speech:`): the avatar renders only
-        # the assistant's own speech.
+        # attached, wait for the assistant to connect before requesting speech. If audio
+        # delivery fails, the response can be 502, which may arrive without an error
+        # envelope, so branch on the status code before parsing a body. The assistant is
+        # designed to own the conversation, so prefer letting it speak or use `send_chat`.
+        # With a digital avatar (`assistant.avatar: true`), speak is refused with 409
+        # `invalid_state` (message prefix `avatar_requires_assistant_speech:`): the avatar
+        # renders only the assistant's own speech.
         sig do
           params(
             id: String,

data/rbi/telnyx/resources/meeting_sessions/artifacts.rbi

@@ -9,13 +9,14 @@ module Telnyx
         # `decisions`, `topics`, `open_questions`, or `custom`. Each request produces one
         # artifact. `custom` is answered from a `prompt` you supply, which is required for
         # `custom` and rejected on the five named types. Generation requires transcript
-        # content and configured inference and currently reads at most the first 10,000
-        # segments, so exceptionally long transcripts may produce incomplete artifacts or
-        # fail model limits. **Not idempotent, and every call is billed**: each request is
-        # a separate inference run, so a retry or a duplicate POST produces a second
-        # artifact and a second charge. Guard the call rather than relying on the service
-        # to collapse it. The automatic `summarize_on_end` attempt is billed on the same
-        # basis.
+        # content. Input is limited to 10,000 segments and 1,000,000 UTF-8 bytes including
+        # segment text, speaker labels, timestamps, and sequence numbers. An oversized
+        # transcript returns 409 invalid_state before an artifact is created; it is not
+        # silently truncated. Model context limits can still cause an accepted artifact to
+        # fail. **Not idempotent, and every call is billed**: each request is a separate
+        # inference run, so a retry or a duplicate POST produces a second artifact and a
+        # second charge. Guard the call rather than relying on the service to collapse it.
+        # The automatic `summarize_on_end` attempt is billed on the same basis.
         sig do
           params(
             id: String,