telnyx 5.162.0 → 5.164.0

data/rbi/telnyx/resources/ai/embeddings.rbi

@@ -46,17 +46,30 @@ module Telnyx
             embedding_model:
               Telnyx::AI::EmbeddingCreateParams::EmbeddingModel::OrSymbol,
             loader: Telnyx::AI::EmbeddingCreateParams::Loader::OrSymbol,
+            idempotency_key: String,
             request_options: Telnyx::RequestOptions::OrHash
           ).returns(Telnyx::AI::EmbeddingResponse)
         end
         def create(
+          # Body param
           bucket_name:,
+          # Body param
           document_chunk_overlap_size: nil,
+          # Body param
           document_chunk_size: nil,
-          # Supported models to vectorize and embed documents.
+          # Body param: Supported models to vectorize and embed documents.
           embedding_model: nil,
-          # Supported types of custom document loaders for embeddings.
+          # Body param: Supported types of custom document loaders for embeddings.
           loader: nil,
+          # Header param: Optional opaque, unquoted key for safely retrying the same logical
+          # request. Keys must contain 1 to 255 letters, numbers, hyphens, or underscores.
+          # Generate a unique UUID v4 for each operation and reuse it only when retrying
+          # that operation with the same request. Invalid headers—including duplicate,
+          # empty, malformed, or overlong values—return 400 with error code 10015. A request
+          # already in progress with the same key returns 409; reusing the key with a
+          # different request returns 422. Only successful responses are replayed, for up to
+          # 24 hours. Do not include sensitive data in the key.
+          idempotency_key: nil,
           request_options: {}
         )
         end
@@ -138,14 +151,25 @@ module Telnyx
           params(
             bucket_name: String,
             url: String,
+            idempotency_key: String,
             request_options: Telnyx::RequestOptions::OrHash
           ).returns(Telnyx::AI::EmbeddingResponse)
         end
         def url(
-          # Name of the bucket to store the embeddings. This bucket must already exist.
+          # Body param: Name of the bucket to store the embeddings. This bucket must already
+          # exist.
           bucket_name:,
-          # The URL of the webpage to embed
+          # Body param: The URL of the webpage to embed
           url:,
+          # Header param: Optional opaque, unquoted key for safely retrying the same logical
+          # request. Keys must contain 1 to 255 letters, numbers, hyphens, or underscores.
+          # Generate a unique UUID v4 for each operation and reuse it only when retrying
+          # that operation with the same request. Invalid headers—including duplicate,
+          # empty, malformed, or overlong values—return 400 with error code 10015. A request
+          # already in progress with the same key returns 409; reusing the key with a
+          # different request returns 422. Only successful responses are replayed, for up to
+          # 24 hours. Do not include sensitive data in the key.
+          idempotency_key: nil,
           request_options: {}
         )
         end

data/rbi/telnyx/resources/ai/fine_tuning/jobs.rbi

@@ -6,7 +6,8 @@ module Telnyx
       class FineTuning
         # Customize LLMs for your unique needs
         class Jobs
-          # Create a new fine tuning job.
+          # Creates a new fine-tuning job that trains a model on the provided dataset, and
+          # returns the created job.
           sig do
             params(
               model: String,
@@ -30,7 +31,8 @@ module Telnyx
           )
           end
 
-          # Retrieve a fine tuning job by `job_id`.
+          # Returns the details of a single fine-tuning job by its job_id, including its
+          # current status.
           sig do
             params(
               job_id: String,
@@ -53,7 +55,7 @@ module Telnyx
           def list(request_options: {})
           end
 
-          # Cancel a fine tuning job.
+          # Cancels the specified in-progress fine-tuning job and returns the updated job.
           sig do
             params(
               job_id: String,

data/rbi/telnyx/resources/ai/integrations/connections.rbi

@@ -5,7 +5,7 @@ module Telnyx
     class AI
       class Integrations
         class Connections
-          # Get user setup integrations
+          # Returns the details of a single integration connection by its ID.
           sig do
             params(
               user_connection_id: String,
@@ -21,7 +21,8 @@ module Telnyx
           )
           end
 
-          # List user setup integrations
+          # Returns the list of integration connections you have set up, linking your
+          # account to third-party services.
           sig do
             params(request_options: Telnyx::RequestOptions::OrHash).returns(
               Telnyx::Models::AI::Integrations::ConnectionListResponse

data/rbi/telnyx/resources/ai/integrations.rbi

@@ -7,7 +7,8 @@ module Telnyx
         sig { returns(Telnyx::Resources::AI::Integrations::Connections) }
         attr_reader :connections
 
-        # Retrieve integration details
+        # Returns the details of a single available integration, including its
+        # configuration details.
         sig do
           params(
             integration_id: String,
@@ -21,7 +22,8 @@ module Telnyx
         )
         end
 
-        # List all available integrations.
+        # Returns the list of third-party integrations available to connect to your AI
+        # assistants and workflows.
         sig do
           params(request_options: Telnyx::RequestOptions::OrHash).returns(
             Telnyx::Models::AI::IntegrationListResponse

data/rbi/telnyx/resources/ai/knowledge/collections.rbi

@@ -0,0 +1,99 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    class AI
+      class Knowledge
+        # Create and manage logical collections of your Telnyx data, tune retrieval
+        # settings, manage sources, and run collection-scoped semantic search.
+        class Collections
+          # Runs search over the documents in a collection, ranked by relevance to `query`.
+          # Searches currently run `vector` retrieval (semantic similarity). The
+          # collection's `retrieval_type` setting is the forward-compatible selector:
+          # `hybrid` (vector similarity fused with keyword matching) can be set but cannot
+          # be searched yet, and `keyword` (lexical BM25 matching) is not accepted yet --
+          # setting it returns 422 `unsupported_retrieval_type`. A per-request
+          # `retrieval_type` is accepted but ignored; `meta.retrieval_type` echoes the mode
+          # that actually ran. When `query` is omitted, returns a plain catalog listing of
+          # the collection's documents.
+          #
+          # **How it works:**
+          #
+          # 1. The `query` text is embedded into a 1024-dimensional vector using the
+          #    multilingual-e5-large model.
+          # 2. The embedding is compared against the collection's indexed document chunks
+          #    using semantic similarity. When `hybrid` and `keyword` execution ship, those
+          #    scores will be fused with, or replaced by, lexical BM25 matching.
+          # 3. Results are ranked by `score` (descending) and paginated via `page[number]` /
+          #    `page[size]`.
+          #
+          # **Authentication:** Requires a Telnyx API key via `Authorization: Bearer <key>`.
+          # Results are automatically scoped to your organization and cannot be overridden.
+          #
+          # **Filtering:** Use `filter[field][operator]=value` query parameters to narrow
+          # results before search. Supported operators: `eq` (default), `in`, `gte`, `gt`,
+          # `lte`, `lt`, `contains`. Metadata fields resolve to `metadata.<field>`.
+          #
+          # **Examples:**
+          #
+          # - `GET /v2/ai/knowledge/collections/my-collection/documents?query=billing+issue&top_k=10`
+          # - `GET /v2/ai/knowledge/collections/my-collection/documents?query=refund&sources=voice,message`
+          # - `GET /v2/ai/knowledge/collections/my-collection/documents?query=outage&filter[record_created_at][gte]=2026-01-01T00:00:00Z`
+          sig do
+            params(
+              slug: String,
+              filter: T::Hash[Symbol, T.anything],
+              page_number: Integer,
+              page_size: Integer,
+              query: String,
+              retrieval_type:
+                Telnyx::AI::Knowledge::CollectionRetrieveDocumentsParams::RetrievalType::OrSymbol,
+              sources: String,
+              top_k: Integer,
+              request_options: Telnyx::RequestOptions::OrHash
+            ).returns(
+              Telnyx::Models::AI::Knowledge::CollectionRetrieveDocumentsResponse
+            )
+          end
+          def retrieve_documents(
+            # The collection's slug (unique within your organization).
+            slug,
+            # Field filters applied before ranking, using `filter[field][operator]=value`.
+            # Supported operators: `eq` (default), `in`, `gte`, `gt`, `lte`, `lt`, `contains`.
+            # Known fields: `record_type`, `record_id`, `user_id`, `record_created_at`,
+            # `ingested_at`; any other name resolves to a `metadata.<field>` filter. Example:
+            # `filter[record_id][eq]=rec_123`.
+            filter: nil,
+            # Page number to return (1-based). Defaults to 1.
+            page_number: nil,
+            # Number of results per page. Defaults to 20.
+            page_size: nil,
+            # Natural-language search query. When provided, the text is matched against the
+            # collection's document chunks using the collection's `retrieval_type` (vector or
+            # hybrid). When omitted, documents are returned as a plain catalog listing.
+            query: nil,
+            # Reserved; not yet functional. A value supplied here is accepted but ignored — it
+            # does not override the collection's configured strategy, and it is not echoed
+            # back. Searches run `vector` retrieval, and `meta.retrieval_type` reports the
+            # mode that actually ran. To change retrieval strategy, set it on the collection's
+            # settings subresource.
+            retrieval_type: nil,
+            # Comma-separated list of source types to restrict the search to. When omitted,
+            # all of the collection's sources are searched.
+            sources: nil,
+            # Maximum number of ranked results to consider. When omitted, the collection's
+            # configured `top_k` setting is used.
+            top_k: nil,
+            request_options: {}
+          )
+          end
+
+          # @api private
+          sig { params(client: Telnyx::Client).returns(T.attached_class) }
+          def self.new(client:)
+          end
+        end
+      end
+    end
+  end
+end

data/rbi/telnyx/resources/ai/knowledge.rbi

@@ -0,0 +1,19 @@
+# typed: strong
+
+module Telnyx
+  module Resources
+    class AI
+      class Knowledge
+        # Create and manage logical collections of your Telnyx data, tune retrieval
+        # settings, manage sources, and run collection-scoped semantic search.
+        sig { returns(Telnyx::Resources::AI::Knowledge::Collections) }
+        attr_reader :collections
+
+        # @api private
+        sig { params(client: Telnyx::Client).returns(T.attached_class) }
+        def self.new(client:)
+        end
+      end
+    end
+  end
+end

data/rbi/telnyx/resources/ai/mcp_servers.rbi

@@ -4,7 +4,8 @@ module Telnyx
   module Resources
     class AI
       class McpServers
-        # Create a new MCP server.
+        # Creates a new MCP server configuration on your account and returns the created
+        # server.
         sig do
           params(
             name: String,
@@ -12,15 +13,30 @@ module Telnyx
             url: String,
             allowed_tools: T.nilable(T::Array[String]),
             api_key_ref: T.nilable(String),
+            idempotency_key: String,
             request_options: Telnyx::RequestOptions::OrHash
           ).returns(Telnyx::AI::McpServer)
         end
         def create(
+          # Body param
           name:,
+          # Body param
           type:,
+          # Body param
           url:,
+          # Body param
           allowed_tools: nil,
+          # Body param
           api_key_ref: nil,
+          # Header param: Optional opaque, unquoted key for safely retrying the same logical
+          # request. Keys must contain 1 to 255 letters, numbers, hyphens, or underscores.
+          # Generate a unique UUID v4 for each operation and reuse it only when retrying
+          # that operation with the same request. Invalid headers—including duplicate,
+          # empty, malformed, or overlong values—return 400 with error code 10015. A request
+          # already in progress with the same key returns 409; reusing the key with a
+          # different request returns 422. Only successful responses are replayed, for up to
+          # 24 hours. Do not include sensitive data in the key.
+          idempotency_key: nil,
           request_options: {}
         )
         end
@@ -39,7 +55,7 @@ module Telnyx
         )
         end
 
-        # Update an existing MCP server.
+        # Updates the specified MCP server's configuration and returns the updated server.
         sig do
           params(
             mcp_server_id: String,
@@ -67,7 +83,8 @@ module Telnyx
         )
         end
 
-        # Retrieve a list of MCP servers.
+        # Returns a paginated list of the MCP servers configured on your account, with
+        # optional filtering by type or URL.
         sig do
           params(
             page_number: Integer,
@@ -94,7 +111,7 @@ module Telnyx
         )
         end
 
-        # Delete a specific MCP server.
+        # Permanently deletes the specified MCP server configuration from your account.
         sig do
           params(
             mcp_server_id: String,

data/rbi/telnyx/resources/ai/missions/knowledge_bases.rbi

@@ -19,7 +19,8 @@ module Telnyx
           )
           end
 
-          # Delete a knowledge base from a mission
+          # Detaches the specified knowledge base from the mission so its content is no
+          # longer available to agents in subsequent runs.
           sig do
             params(
               knowledge_base_id: String,
@@ -36,7 +37,8 @@ module Telnyx
           )
           end
 
-          # Get a specific knowledge base by ID
+          # Returns the details of a single knowledge base attached to the specified
+          # mission.
           sig do
             params(
               knowledge_base_id: String,
@@ -53,7 +55,8 @@ module Telnyx
           )
           end
 
-          # List all knowledge bases for a mission
+          # Returns the knowledge bases attached to the specified mission. Knowledge bases
+          # provide reference content agents can draw on during runs.
           sig do
             params(
               mission_id: String,
@@ -67,7 +70,7 @@ module Telnyx
           )
           end
 
-          # Update a knowledge base definition
+          # Replaces the definition of the specified knowledge base on this mission.
           sig do
             params(
               knowledge_base_id: String,

data/rbi/telnyx/resources/ai/missions/mcp_servers.rbi

@@ -5,7 +5,8 @@ module Telnyx
     class AI
       class Missions
         class McpServers
-          # Create a new MCP server for a mission
+          # Adds an MCP server to the specified mission, making the server's tools available
+          # to agents during runs of this mission.
           sig do
             params(
               mission_id: String,
@@ -19,7 +20,8 @@ module Telnyx
           )
           end
 
-          # Delete an MCP server from a mission
+          # Removes the specified MCP server from the mission, revoking agent access to its
+          # tools in subsequent runs.
           sig do
             params(
               mcp_server_id: String,
@@ -36,7 +38,8 @@ module Telnyx
           )
           end
 
-          # Get a specific MCP server by ID
+          # Returns the configuration of a single MCP server attached to the specified
+          # mission.
           sig do
             params(
               mcp_server_id: String,
@@ -53,7 +56,8 @@ module Telnyx
           )
           end
 
-          # List all MCP servers for a mission
+          # Returns the MCP servers configured on the specified mission. MCP servers expose
+          # external tools and data sources agents can use during runs.
           sig do
             params(
               mission_id: String,
@@ -67,7 +71,7 @@ module Telnyx
           )
           end
 
-          # Update an MCP server definition
+          # Replaces the configuration of the specified MCP server on this mission.
           sig do
             params(
               mcp_server_id: String,

data/rbi/telnyx/resources/ai/missions/runs/events.rbi

@@ -6,7 +6,9 @@ module Telnyx
       class Missions
         class Runs
           class Events
-            # List events for a run (paginated)
+            # Returns a paginated list of events logged for the specified run, filterable by
+            # event type, plan step, and agent, so you can reconstruct exactly what happened
+            # during execution.
             sig do
               params(
                 run_id: String,
@@ -42,7 +44,8 @@ module Telnyx
             )
             end
 
-            # Get details of a specific event
+            # Returns the details of a single event logged for the specified run, including
+            # its type and payload.
             sig do
               params(
                 event_id: String,
@@ -62,7 +65,8 @@ module Telnyx
             )
             end
 
-            # Log an event for a run
+            # Logs a new event against the specified run and returns the created event. Events
+            # form the run's audit trail and can reference a plan step or agent.
             sig do
               params(
                 run_id: String,

data/rbi/telnyx/resources/ai/missions/runs/plan.rbi

@@ -6,7 +6,9 @@ module Telnyx
       class Missions
         class Runs
           class Plan
-            # Create the initial plan for a run
+            # Creates the initial plan for the specified run from the provided steps and
+            # returns the created plan steps. Progress is subsequently reported by updating
+            # individual steps.
             sig do
               params(
                 run_id: String,
@@ -29,7 +31,9 @@ module Telnyx
             )
             end
 
-            # Get the plan (all steps) for a run
+            # Returns the plan for the specified run, including all plan steps and their
+            # statuses, so you can see how the mission was decomposed and how far execution
+            # has progressed.
             sig do
               params(
                 run_id: String,
@@ -71,7 +75,8 @@ module Telnyx
             )
             end
 
-            # Get details of a specific plan step
+            # Returns the details of a single plan step within a run's plan, including its
+            # status.
             sig do
               params(
                 step_id: String,
@@ -91,7 +96,8 @@ module Telnyx
             )
             end
 
-            # Update the status of a plan step
+            # Updates the status of a single plan step and returns the updated step. Typically
+            # called by the executing agent as it works through the plan.
             sig do
               params(
                 step_id: String,

data/rbi/telnyx/resources/ai/missions/runs/telnyx_agents.rbi

@@ -6,7 +6,8 @@ module Telnyx
       class Missions
         class Runs
           class TelnyxAgents
-            # List all Telnyx agents linked to a run
+            # Returns the Telnyx agents currently linked to the specified run. Linked agents
+            # participate in executing the run's plan.
             sig do
               params(
                 run_id: String,
@@ -47,7 +48,8 @@ module Telnyx
             )
             end
 
-            # Unlink a Telnyx agent from a run
+            # Unlinks the specified Telnyx agent from the run so it no longer participates in
+            # execution. The run itself and its history are unaffected.
             sig do
               params(
                 telnyx_agent_id: String,

data/rbi/telnyx/resources/ai/missions/runs.rbi

@@ -14,7 +14,8 @@ module Telnyx
           sig { returns(Telnyx::Resources::AI::Missions::Runs::TelnyxAgents) }
           attr_reader :telnyx_agents
 
-          # Start a new run for a mission
+          # Starts a new run of the specified mission and returns the created run object.
+          # Track its progress through the run detail, plan, and events endpoints.
           sig do
             params(
               mission_id: String,
@@ -32,7 +33,8 @@ module Telnyx
           )
           end
 
-          # Get details of a specific run
+          # Returns the full details of a single run, including its current status. Use this
+          # to poll an in-flight run or inspect the outcome of a completed one.
           sig do
             params(
               run_id: String,
@@ -49,7 +51,9 @@ module Telnyx
           )
           end
 
-          # Update run status and/or result
+          # Updates a run's status and/or result and returns the updated run object.
+          # Typically used by executing agents to report progress or record the final
+          # outcome.
           sig do
             params(
               run_id: String,
@@ -81,7 +85,8 @@ module Telnyx
           )
           end
 
-          # List all runs for a specific mission
+          # Returns a paginated list of runs for the specified mission, optionally filtered
+          # by run status, so you can track the mission's execution history over time.
           sig do
             params(
               mission_id: String,
@@ -108,7 +113,8 @@ module Telnyx
           )
           end
 
-          # Cancel a running or paused run
+          # Cancels a running or paused run and returns the updated run object. A cancelled
+          # run stops executing; start a new run to execute the mission again.
           sig do
             params(
               run_id: String,
@@ -125,7 +131,9 @@ module Telnyx
           )
           end
 
-          # List recent runs across all missions
+          # Returns a paginated list of recent runs across every mission in your
+          # organization, optionally filtered by run status. Useful for monitoring overall
+          # mission activity without querying each mission individually.
           sig do
             params(
               page_number: Integer,
@@ -149,7 +157,8 @@ module Telnyx
           )
           end
 
-          # Pause a running run
+          # Pauses a currently running run and returns the updated run object. Execution
+          # halts until the run is resumed.
           sig do
             params(
               run_id: String,
@@ -166,7 +175,8 @@ module Telnyx
           )
           end
 
-          # Resume a paused run
+          # Resumes a previously paused run and returns the updated run object, letting
+          # execution continue from where it was paused.
           sig do
             params(
               run_id: String,

data/rbi/telnyx/resources/ai/missions/tools.rbi

@@ -5,7 +5,8 @@ module Telnyx
     class AI
       class Missions
         class Tools
-          # Create a new tool for a mission
+          # Adds a new tool to the specified mission, defining an action agents can invoke
+          # during runs of this mission.
           sig do
             params(
               mission_id: String,
@@ -19,7 +20,8 @@ module Telnyx
           )
           end
 
-          # Delete a tool from a mission
+          # Removes the specified tool from the mission so agents can no longer invoke it in
+          # subsequent runs.
           sig do
             params(
               tool_id: String,
@@ -36,7 +38,7 @@ module Telnyx
           )
           end
 
-          # Get a specific tool by ID
+          # Returns the definition of a single tool configured on the specified mission.
           sig do
             params(
               tool_id: String,
@@ -53,7 +55,8 @@ module Telnyx
           )
           end
 
-          # List all tools for a mission
+          # Returns the tools configured on the specified mission. Tools define the actions
+          # agents may invoke while executing the mission's runs.
           sig do
             params(
               mission_id: String,
@@ -67,7 +70,7 @@ module Telnyx
           )
           end
 
-          # Update a tool definition
+          # Replaces the definition of the specified tool on this mission.
           sig do
             params(
               tool_id: String,