telnyx 7.16.0 → 7.18.0

package/src/resources/ai/knowledge/collections.ts

@@ -0,0 +1,179 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import { APIPromise } from '../../../core/api-promise';
+import { RequestOptions } from '../../../internal/request-options';
+import { path } from '../../../internal/utils/path';
+
+/**
+ * Create and manage logical collections of your Telnyx data, tune retrieval settings, manage sources, and run collection-scoped semantic search.
+ */
+export class Collections extends APIResource {
+  /**
+   * 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`
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.ai.knowledge.collections.retrieveDocuments(
+   *     'support-transcripts',
+   *   );
+   * ```
+   */
+  retrieveDocuments(
+    slug: string,
+    query: CollectionRetrieveDocumentsParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<CollectionRetrieveDocumentsResponse> {
+    return this._client.get(path`/ai/knowledge/collections/${slug}/documents`, { query, ...options });
+  }
+}
+
+export interface CollectionRetrieveDocumentsResponse {
+  data?: Array<CollectionRetrieveDocumentsResponse.Data>;
+
+  meta?: CollectionRetrieveDocumentsResponse.Meta;
+}
+
+export namespace CollectionRetrieveDocumentsResponse {
+  export interface Data {
+    id?: string;
+
+    chunk_index?: number;
+
+    chunk_total?: number;
+
+    ingested_at?: string;
+
+    metadata?: { [key: string]: unknown };
+
+    organization_id?: string;
+
+    record_created_at?: string;
+
+    record_id?: string;
+
+    /**
+     * The source record kind this chunk came from (e.g. `voice`, `meeting_bot`,
+     * `message`).
+     */
+    record_type?: string;
+
+    region?: string;
+
+    /**
+     * Relevance score (higher = more relevant) for ranked search. `0.0` for plain
+     * catalog listings (when `query` is omitted).
+     */
+    score?: number;
+
+    text?: string;
+
+    user_id?: string;
+  }
+
+  export interface Meta {
+    collection_slug?: string;
+
+    page_number?: number;
+
+    page_size?: number;
+
+    retrieval_type?: string;
+
+    searched_sources?: Array<string>;
+
+    top_k?: number;
+
+    total_pages?: number;
+
+    total_results?: number;
+  }
+}
+
+export interface CollectionRetrieveDocumentsParams {
+  /**
+   * 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?: { [key: string]: unknown };
+
+  /**
+   * Page number to return (1-based). Defaults to 1.
+   */
+  'page[number]'?: number;
+
+  /**
+   * Number of results per page. Defaults to 20.
+   */
+  'page[size]'?: number;
+
+  /**
+   * 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?: string;
+
+  /**
+   * 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?: 'vector' | 'hybrid' | 'keyword';
+
+  /**
+   * Comma-separated list of source types to restrict the search to. When omitted,
+   * all of the collection's sources are searched.
+   */
+  sources?: string;
+
+  /**
+   * Maximum number of ranked results to consider. When omitted, the collection's
+   * configured `top_k` setting is used.
+   */
+  top_k?: number;
+}
+
+export declare namespace Collections {
+  export {
+    type CollectionRetrieveDocumentsResponse as CollectionRetrieveDocumentsResponse,
+    type CollectionRetrieveDocumentsParams as CollectionRetrieveDocumentsParams,
+  };
+}

package/src/resources/ai/knowledge/index.ts

@@ -0,0 +1,8 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  Collections,
+  type CollectionRetrieveDocumentsResponse,
+  type CollectionRetrieveDocumentsParams,
+} from './collections';
+export { Knowledge } from './knowledge';

package/src/resources/ai/knowledge/knowledge.ts

@@ -0,0 +1,23 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import * as CollectionsAPI from './collections';
+import {
+  CollectionRetrieveDocumentsParams,
+  CollectionRetrieveDocumentsResponse,
+  Collections,
+} from './collections';
+
+export class Knowledge extends APIResource {
+  collections: CollectionsAPI.Collections = new CollectionsAPI.Collections(this._client);
+}
+
+Knowledge.Collections = Collections;
+
+export declare namespace Knowledge {
+  export {
+    Collections as Collections,
+    type CollectionRetrieveDocumentsResponse as CollectionRetrieveDocumentsResponse,
+    type CollectionRetrieveDocumentsParams as CollectionRetrieveDocumentsParams,
+  };
+}

package/src/resources/ai/knowledge.ts

@@ -0,0 +1,3 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export * from './knowledge/index';

package/src/resources/ai/mcp-servers.ts

@@ -13,7 +13,8 @@ import { path } from '../../internal/utils/path';
 
 export class McpServers extends APIResource {
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -34,7 +35,8 @@ export class McpServers extends APIResource {
   }
 
   /**
-   * Create a new MCP server.
+   * Creates a new MCP server configuration on your account and returns the created
+   * server.
    *
    * @example
    * ```ts
@@ -45,12 +47,20 @@ export class McpServers extends APIResource {
    * });
    * ```
    */
-  create(body: McpServerCreateParams, options?: RequestOptions): APIPromise<McpServer> {
-    return this._client.post('/ai/mcp_servers', { body, ...options });
+  create(params: McpServerCreateParams, options?: RequestOptions): APIPromise<McpServer> {
+    const { 'Idempotency-Key': idempotencyKey, ...body } = params;
+    return this._client.post('/ai/mcp_servers', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined) },
+        options?.headers,
+      ]),
+    });
   }
 
   /**
-   * Delete a specific MCP server.
+   * Permanently deletes the specified MCP server configuration from your account.
    *
    * @example
    * ```ts
@@ -79,7 +89,7 @@ export class McpServers extends APIResource {
   }
 
   /**
-   * Update an existing MCP server.
+   * Updates the specified MCP server's configuration and returns the updated server.
    *
    * @example
    * ```ts
@@ -131,15 +141,42 @@ export interface McpServerListParams extends DefaultFlatPaginationTopLevelArrayP
 }
 
 export interface McpServerCreateParams {
+  /**
+   * Body param
+   */
   name: string;
 
+  /**
+   * Body param
+   */
   type: string;
 
+  /**
+   * Body param
+   */
   url: string;
 
+  /**
+   * Body param
+   */
   allowed_tools?: Array<string> | null;
 
+  /**
+   * Body param
+   */
   api_key_ref?: string | null;
+
+  /**
+   * 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'?: string;
 }
 
 export interface McpServerUpdateParams {

package/src/resources/ai/missions/knowledge-bases.ts

@@ -8,7 +8,8 @@ import { path } from '../../../internal/utils/path';
 
 export class KnowledgeBases extends APIResource {
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -38,7 +39,8 @@ export class KnowledgeBases extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -61,7 +63,8 @@ export class KnowledgeBases extends APIResource {
   }
 
   /**
-   * Get a specific knowledge base by ID
+   * Returns the details of a single knowledge base attached to the specified
+   * mission.
    *
    * @example
    * ```ts
@@ -82,7 +85,7 @@ export class KnowledgeBases extends APIResource {
   }
 
   /**
-   * Update a knowledge base definition
+   * Replaces the definition of the specified knowledge base on this mission.
    *
    * @example
    * ```ts

package/src/resources/ai/missions/mcp-servers.ts

@@ -8,7 +8,8 @@ import { path } from '../../../internal/utils/path';
 
 export class McpServers extends APIResource {
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -23,7 +24,8 @@ export class McpServers extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -38,7 +40,8 @@ export class McpServers extends APIResource {
   }
 
   /**
-   * Delete an MCP server from a mission
+   * Removes the specified MCP server from the mission, revoking agent access to its
+   * tools in subsequent runs.
    *
    * @example
    * ```ts
@@ -61,7 +64,8 @@ export class McpServers extends APIResource {
   }
 
   /**
-   * Get a specific MCP server by ID
+   * Returns the configuration of a single MCP server attached to the specified
+   * mission.
    *
    * @example
    * ```ts
@@ -82,7 +86,7 @@ export class McpServers extends APIResource {
   }
 
   /**
-   * Update an MCP server definition
+   * Replaces the configuration of the specified MCP server on this mission.
    *
    * @example
    * ```ts

package/src/resources/ai/missions/missions.ts

@@ -71,7 +71,9 @@ export class Missions extends APIResource {
   tools: ToolsAPI.Tools = new ToolsAPI.Tools(this._client);
 
   /**
-   * List all missions for the organization
+   * Returns a paginated list of all mission definitions in your organization.
+   * Missions describe a goal and the tools, knowledge bases, and MCP servers agents
+   * may use to accomplish it.
    *
    * @example
    * ```ts
@@ -89,7 +91,8 @@ export class Missions extends APIResource {
   }
 
   /**
-   * Create a new mission definition
+   * Creates a new mission definition from the provided configuration and returns the
+   * created mission. Execute the mission by starting runs against it.
    *
    * @example
    * ```ts
@@ -121,7 +124,9 @@ export class Missions extends APIResource {
   }
 
   /**
-   * List recent events across all missions
+   * Returns a paginated list of recent events across every mission in your
+   * organization, optionally filtered by event type. Useful for building activity
+   * feeds or monitoring dashboards.
    *
    * @example
    * ```ts
@@ -142,7 +147,8 @@ export class Missions extends APIResource {
   }
 
   /**
-   * Delete a mission
+   * Permanently deletes the specified mission definition and returns no content on
+   * success.
    *
    * @example
    * ```ts
@@ -159,7 +165,8 @@ export class Missions extends APIResource {
   }
 
   /**
-   * Update a mission definition
+   * Replaces the specified mission's definition with the provided configuration and
+   * returns the updated mission.
    *
    * @example
    * ```ts
@@ -185,7 +192,8 @@ export class Missions extends APIResource {
   }
 
   /**
-   * Clone an existing mission
+   * Creates a copy of the specified mission as a new mission definition, so you can
+   * iterate on its configuration without modifying the original.
    *
    * @example
    * ```ts

package/src/resources/ai/missions/runs/events.ts

@@ -12,7 +12,9 @@ import { path } from '../../../../internal/utils/path';
 
 export class Events extends APIResource {
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -39,7 +41,8 @@ export class Events extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -63,7 +66,8 @@ export class Events extends APIResource {
   }
 
   /**
-   * Get details of a specific event
+   * Returns the details of a single event logged for the specified run, including
+   * its type and payload.
    *
    * @example
    * ```ts

package/src/resources/ai/missions/runs/plan.ts

@@ -7,7 +7,9 @@ import { path } from '../../../../internal/utils/path';
 
 export class Plan extends APIResource {
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -27,7 +29,9 @@ export class Plan extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -58,7 +62,8 @@ export class Plan extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -114,7 +119,8 @@ export class Plan extends APIResource {
   }
 
   /**
-   * Get details of a specific plan step
+   * Returns the details of a single plan step within a run's plan, including its
+   * status.
    *
    * @example
    * ```ts

package/src/resources/ai/missions/runs/runs.ts

@@ -53,7 +53,8 @@ export class Runs extends APIResource {
   telnyxAgents: TelnyxAgentsAPI.TelnyxAgents = new TelnyxAgentsAPI.TelnyxAgents(this._client);
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -78,7 +79,8 @@ export class Runs extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -104,7 +106,8 @@ export class Runs extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -125,7 +128,9 @@ export class Runs extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -147,7 +152,9 @@ export class Runs extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -168,7 +175,8 @@ export class Runs extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -189,7 +197,8 @@ export class Runs extends APIResource {
   }
 
   /**
-   * Pause a running run
+   * Pauses a currently running run and returns the updated run object. Execution
+   * halts until the run is resumed.
    *
    * @example
    * ```ts
@@ -210,7 +219,8 @@ export class Runs extends APIResource {
   }
 
   /**
-   * Resume a paused run
+   * Resumes a previously paused run and returns the updated run object, letting
+   * execution continue from where it was paused.
    *
    * @example
    * ```ts

package/src/resources/ai/missions/runs/telnyx-agents.ts

@@ -8,7 +8,8 @@ import { path } from '../../../../internal/utils/path';
 
 export class TelnyxAgents extends APIResource {
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -56,7 +57,8 @@ export class TelnyxAgents extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts

package/src/resources/ai/missions/tools.ts

@@ -8,7 +8,8 @@ import { path } from '../../../internal/utils/path';
 
 export class Tools extends APIResource {
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -22,7 +23,8 @@ export class Tools extends APIResource {
   }
 
   /**
-   * 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.
    *
    * @example
    * ```ts
@@ -36,7 +38,8 @@ export class Tools extends APIResource {
   }
 
   /**
-   * Delete a tool from a mission
+   * Removes the specified tool from the mission so agents can no longer invoke it in
+   * subsequent runs.
    *
    * @example
    * ```ts
@@ -54,7 +57,7 @@ export class Tools extends APIResource {
   }
 
   /**
-   * Get a specific tool by ID
+   * Returns the definition of a single tool configured on the specified mission.
    *
    * @example
    * ```ts
@@ -70,7 +73,7 @@ export class Tools extends APIResource {
   }
 
   /**
-   * Update a tool definition
+   * Replaces the definition of the specified tool on this mission.
    *
    * @example
    * ```ts