telnyx 7.17.0 → 7.19.0

package/src/resources/ai/assistants/assistants.ts

@@ -574,6 +574,21 @@ export namespace AssistantTool {
        */
       warm_message_delay_ms?: number | null;
 
+      /**
+       * Requires the transfer destination to accept the call before the caller is
+       * bridged. When enabled, the assistant speaks privately with the destination after
+       * they answer — delivering the warm transfer message and asking whether they take
+       * the call — while the caller keeps hearing ringback. The assistant then finalizes
+       * the transfer with the built-in `complete_transfer` tool: an accept bridges the
+       * calls, a decline hangs up the destination and returns the assistant to the
+       * caller with the reason the destination gave. Requires either
+       * `warm_transfer_instructions` or a `message` on every target, otherwise the
+       * assistant fails to save. Only available for calls started with
+       * `ai_assistant_start`; single-caller conversations only (a conference or
+       * additional invited participants fall back to a regular warm transfer).
+       */
+      warm_transfer_acceptance?: Transfer.WarmTransferAcceptance;
+
       /**
        * Natural language instructions for your agent for how to provide context for the
        * transfer recipient.
@@ -588,6 +603,13 @@ export namespace AssistantTool {
          */
         to: string;
 
+        /**
+         * The warm transfer message to deliver to this specific target. When set, it takes
+         * precedence over the message the assistant composes from
+         * `warm_transfer_instructions`.
+         */
+        message?: string;
+
         /**
          * The name of the target.
          */
@@ -730,6 +752,35 @@ export namespace AssistantTool {
           }
         }
       }
+
+      /**
+       * Requires the transfer destination to accept the call before the caller is
+       * bridged. When enabled, the assistant speaks privately with the destination after
+       * they answer — delivering the warm transfer message and asking whether they take
+       * the call — while the caller keeps hearing ringback. The assistant then finalizes
+       * the transfer with the built-in `complete_transfer` tool: an accept bridges the
+       * calls, a decline hangs up the destination and returns the assistant to the
+       * caller with the reason the destination gave. Requires either
+       * `warm_transfer_instructions` or a `message` on every target, otherwise the
+       * assistant fails to save. Only available for calls started with
+       * `ai_assistant_start`; single-caller conversations only (a conference or
+       * additional invited participants fall back to a regular warm transfer).
+       */
+      export interface WarmTransferAcceptance {
+        /**
+         * Whether the destination must accept the transfer before the calls are bridged.
+         */
+        enabled?: boolean;
+
+        /**
+         * Controls whether the private exchange between the assistant and the transfer
+         * destination is kept out of the conversation. With `private` (default) the
+         * exchange never reaches the conversation history, AI conversations, webhooks or
+         * insights, and the transfer tool result is rewritten with the outcome only. With
+         * `shared` the exchange stays in the conversation like any other messages.
+         */
+        end_user_target_context_mode?: 'private' | 'shared';
+      }
     }
   }
 
@@ -1907,6 +1958,29 @@ export namespace InferenceEmbeddingWebhookToolParams {
      */
     path_parameters?: Webhook.PathParameters;
 
+    /**
+     * Body fields supplied by the assistant configuration rather than by the model.
+     * They are never advertised in the tool definition, so the LLM can neither see nor
+     * set them, and they take precedence over a `body_parameters` value of the same
+     * name. Values support mustache templating, so they can hold dynamic variables
+     * (`{{customer_id}}`) and integration secrets
+     * (`{{#integration_secret}}my-secret{{/integration_secret}}`). Not sent on `GET`
+     * requests, which carry no body.
+     */
+    preset_body_fields?: { [key: string]: unknown };
+
+    /**
+     * Query string parameters supplied by the assistant configuration rather than by
+     * the model. They are never advertised in the tool definition, so the LLM can
+     * neither see nor set them, and they take precedence over a `query_parameters`
+     * value of the same name. Values support mustache templating, so they can hold
+     * dynamic variables (`{{telnyx_end_user_target}}`) and integration secrets
+     * (`{{#integration_secret}}my-secret{{/integration_secret}}`). Unlike values
+     * templated directly into the `url`, these are percent-encoded, so a value such as
+     * `+15551234567` survives the round trip.
+     */
+    preset_query_params?: { [key: string]: unknown };
+
     /**
      * The query parameters the webhook tool accepts, described as a JSON Schema
      * object. These parameters will be passed to the webhook as the query of the
@@ -2348,6 +2422,18 @@ export interface TelephonySettings {
    */
   recording_settings?: TelephonySettings.RecordingSettings;
 
+  /**
+   * Whether the assistant sends a `call.ai_gather.message_history_updated` webhook
+   * with the full message history every time the conversation history changes. Leave
+   * unset to inherit the `send_message_history_updates` value from the
+   * `ai_assistant_start` or `gather_using_ai` command that started the conversation.
+   * Setting it here is authoritative: `true` turns the webhooks on even when the
+   * start command did not request them, and `false` turns them off even when it did.
+   * Messages exchanged during a private warm transfer acceptance phase are never
+   * included.
+   */
+  send_message_history_updates?: boolean;
+
   /**
    * When enabled, allows users to interact with your AI assistant directly from your
    * website without requiring authentication. This is required for FE widgets that
@@ -2615,15 +2701,19 @@ export interface TranscriptionSettings {
    * supported models will automatically detect the language. For `deepgram/flux`,
    * supported values are: `auto` (Telnyx language detection controls the language
    * hint), `multi` (no language hint), and language-specific hints `en`, `es`, `fr`,
-   * `de`, `hi`, `ru`, `pt`, `ja`, `it`, and `nl`. For `soniox/stt-rt-v4`, `auto`
-   * omits the language hint and lets Soniox auto-detect; ISO 639-1 codes (e.g. `en`,
-   * `es`) bias detection toward that language. For `humain/realtime`, supported
-   * values are `ar`, `en`, `codeswitch` (Arabic/English code-switching), and `auto`
-   * (resolves server-side to code-switching). Unlike other models, `humain/realtime`
-   * does not fall back to `auto` when `language` is omitted — omitting it applies
-   * `en` instead. For `reson8/turns`, supported values are `auto` (or unset) for
-   * automatic language detection, and the language codes `nl`, `en`, `fr`, `fy`,
-   * `de`, `it`, `pl`, `pt`, `es`, and `sv` to fix the transcription language.
+   * `de`, `hi`, `ru`, `pt`, `ja`, `it`, and `nl`. For `soniox/stt-rt-v4` and
+   * `soniox/stt-rt-v5`, `auto` omits the language hint and lets Soniox auto-detect;
+   * ISO 639-1 codes (e.g. `en`, `es`) bias detection toward that language;
+   * `settings.language_hints` can pin multiple languages at once instead. For
+   * `humain/realtime`, supported values are `ar`, `en`, `codeswitch` (Arabic/English
+   * code-switching), and `auto` (resolves server-side to code-switching). Unlike
+   * other models, `humain/realtime` does not fall back to `auto` when `language` is
+   * omitted — omitting it applies `en` instead. For `reson8/turns`, supported values
+   * are `auto` (or unset) for automatic language detection, and the language codes
+   * `nl`, `en`, `fr`, `fy`, `de`, `it`, `pl`, `pt`, `es`, and `sv` to fix the
+   * transcription language. For `cohere/ar-stt`, supported values are `ar` and `en`;
+   * unlike other models, this model does not auto-detect and defaults to `ar` when
+   * `language` is omitted.
    */
   language?: string;
 
@@ -2638,14 +2728,16 @@ export interface TranscriptionSettings {
    * - `assemblyai/universal-streaming` is a multilingual streaming model with
    *   configurable turn detection.
    * - `xai/grok-stt` is a multilingual Grok STT model.
-   * - `soniox/stt-rt-v4` is a multilingual streaming model with automatic language
-   *   detection and configurable endpointing.
+   * - `soniox/stt-rt-v4` and `soniox/stt-rt-v5` are multilingual streaming models
+   *   with automatic language detection, configurable endpointing, term biasing
+   *   (`context`), and `language_hints`.
    * - `nvidia/parakeet-v3` is a multilingual transcription model with automatic
    *   language detection.
    * - `humain/realtime` is a streaming model with native Arabic and Arabic/English
    *   code-switching support.
    * - `reson8/turns` is a turn-based streaming model covering 10 European languages
    *   with automatic language detection.
+   * - `cohere/ar-stt` is a non-streaming Arabic and English transcription model.
    */
   model?:
     | 'deepgram/flux'
@@ -2655,9 +2747,11 @@ export interface TranscriptionSettings {
     | 'assemblyai/universal-streaming'
     | 'xai/grok-stt'
     | 'soniox/stt-rt-v4'
+    | 'soniox/stt-rt-v5'
     | 'nvidia/parakeet-v3'
     | 'humain/realtime'
     | 'reson8/turns'
+    | 'cohere/ar-stt'
     | 'distil-whisper/distil-large-v2'
     | 'openai/whisper-large-v3-turbo';
 
@@ -2671,6 +2765,17 @@ export interface TranscriptionSettings {
 }
 
 export interface TranscriptionSettingsConfig {
+  /**
+   * Available only for soniox/stt-rt-v4 and soniox/stt-rt-v5. A comma-separated list
+   * of terms to boost for recognition during transcription, for staff names,
+   * building names, or other domain-specific vocabulary. This field may be templated
+   * with
+   * [dynamic variables](https://developers.telnyx.com/docs/inference/ai-assistants/dynamic-variables)
+   * using mustache syntax (e.g. `Telnyx,{{customer_name}},VoIP`). Variables are
+   * resolved at call time before the value is sent to Soniox.
+   */
+  context?: string;
+
   /**
    * Available only for deepgram/flux. Confidence threshold for eager end of turn
    * detection. Must be lower than or equal to eot_threshold. Setting this equal to
@@ -2679,8 +2784,9 @@ export interface TranscriptionSettingsConfig {
   eager_eot_threshold?: number;
 
   /**
-   * Available only for soniox/stt-rt-v4. When true, Soniox emits end-of-utterance
-   * events at the cadence configured by `max_endpoint_delay_ms`.
+   * Available only for soniox/stt-rt-v4 and soniox/stt-rt-v5. When true, Soniox
+   * emits end-of-utterance events at the cadence configured by
+   * `max_endpoint_delay_ms`.
    */
   enable_endpoint_detection?: boolean;
 
@@ -2704,8 +2810,8 @@ export interface TranscriptionSettingsConfig {
   eot_timeout_ms?: number;
 
   /**
-   * Available only for soniox/stt-rt-v4. When true, Soniox streams interim
-   * (non-final) results in addition to finalized transcripts.
+   * Available only for soniox/stt-rt-v4 and soniox/stt-rt-v5. When true, Soniox
+   * streams interim (non-final) results in addition to finalized transcripts.
    */
   interim_results?: boolean;
 
@@ -2721,8 +2827,15 @@ export interface TranscriptionSettingsConfig {
   keyterm?: string;
 
   /**
-   * Available only for soniox/stt-rt-v4. Maximum silence (in milliseconds) before
-   * Soniox emits an end-of-utterance event. Only honored when
+   * Available only for soniox/stt-rt-v4 and soniox/stt-rt-v5. A list of ISO 639-1
+   * language codes (e.g. `["nl", "fr"]`) to pin recognition to multiple languages at
+   * once, overriding the single hint derived from `language`.
+   */
+  language_hints?: Array<string>;
+
+  /**
+   * Available only for soniox/stt-rt-v4 and soniox/stt-rt-v5. Maximum silence (in
+   * milliseconds) before Soniox emits an end-of-utterance event. Only honored when
    * `enable_endpoint_detection` is true.
    */
   max_endpoint_delay_ms?: number;

package/src/resources/ai/chat.ts

@@ -113,6 +113,15 @@ export interface ChatCompletionRequest {
    */
   presence_penalty?: number;
 
+  /**
+   * Controls the reasoning effort for models that support it. When set, the model
+   * spends more or less compute on internal reasoning before generating its
+   * response. Supported values: none, minimal, low, medium, high, xhigh, max. Not
+   * all models support all values; unsupported values are rejected with a 400 error.
+   * When omitted, reasoning models use their default effort level.
+   */
+  reasoning_effort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+
   /**
    * Use this is you want to guarantee a JSON output without defining a schema. For
    * control over the schema, use `guided_json`.

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

@@ -109,62 +109,6 @@ export class Collections extends APIResource {
     return this._client.get(path`/ai/collections/slug/${slug}`, options);
   }
 
-  /**
-   * Runs search over the documents in a collection, ranked by relevance to `query`.
-   * The collection's `retrieval_type` setting selects the strategy: `vector`
-   * (semantic similarity), `hybrid` (vector similarity fused with keyword matching),
-   * or `keyword` (lexical BM25 matching). When `query` is omitted, returns a plain
-   * catalog listing of the collection's documents.
-   *
-   * **How it works:**
-   *
-   * 1. For `vector` and `hybrid`, the `query` text is embedded into a
-   *    1024-dimensional vector using the multilingual-e5-large model.
-   * 2. For `vector`, the embedding is compared against the collection's indexed
-   *    document chunks using semantic similarity; for `hybrid`, those similarity
-   *    scores are fused with keyword-match scores; for `keyword`, only lexical BM25
-   *    matching is applied.
-   * 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/collections/my-collection/documents?query=billing+issue&top_k=10`
-   * - `GET /v2/ai/collections/my-collection/documents?query=refund&sources=voice,message`
-   * - `GET /v2/ai/collections/my-collection/documents?query=outage&filter[record_created_at][gte]=2026-01-01T00:00:00Z`
-   *
-   * @example
-   * ```ts
-   * // Automatically fetches more pages as needed.
-   * for await (const collectionRetrieveDocumentsResponse of client.ai.collections.retrieveDocuments(
-   *   'support-transcripts',
-   * )) {
-   *   // ...
-   * }
-   * ```
-   */
-  retrieveDocuments(
-    slug: string,
-    query: CollectionRetrieveDocumentsParams | null | undefined = {},
-    options?: RequestOptions,
-  ): PagePromise<
-    CollectionRetrieveDocumentsResponsesDefaultFlatPagination,
-    CollectionRetrieveDocumentsResponse
-  > {
-    return this._client.getAPIList(
-      path`/ai/collections/${slug}/documents`,
-      DefaultFlatPagination<CollectionRetrieveDocumentsResponse>,
-      { query, ...options },
-    );
-  }
-
   /**
    * Soft-deletes a collection. Its `slug` is freed and may be reused by a new
    * collection.
@@ -206,9 +150,6 @@ export class Collections extends APIResource {
 
 export type CollectionsDefaultFlatPagination = DefaultFlatPagination<Collection>;
 
-export type CollectionRetrieveDocumentsResponsesDefaultFlatPagination =
-  DefaultFlatPagination<CollectionRetrieveDocumentsResponse>;
-
 export interface Collection {
   created_at?: string;
 
@@ -238,42 +179,6 @@ export interface CollectionEnvelope {
   data?: Collection;
 }
 
-export interface CollectionRetrieveDocumentsResponse {
-  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 CollectionListParams extends DefaultFlatPaginationParams {}
 
 export interface CollectionCreateParams {
@@ -303,42 +208,6 @@ export interface CollectionCreateParams {
   sources?: Array<SourcesAPI.SourceRequest>;
 }
 
-export interface CollectionRetrieveDocumentsParams extends DefaultFlatPaginationParams {
-  /**
-   * 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 };
-
-  /**
-   * 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;
-
-  /**
-   * Override the collection's configured retrieval strategy for this request. Echoed
-   * back in `meta.retrieval_type`.
-   */
-  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 interface CollectionUpdateParams {
   description?: string;
 
@@ -352,12 +221,9 @@ export declare namespace Collections {
   export {
     type Collection as Collection,
     type CollectionEnvelope as CollectionEnvelope,
-    type CollectionRetrieveDocumentsResponse as CollectionRetrieveDocumentsResponse,
     type CollectionsDefaultFlatPagination as CollectionsDefaultFlatPagination,
-    type CollectionRetrieveDocumentsResponsesDefaultFlatPagination as CollectionRetrieveDocumentsResponsesDefaultFlatPagination,
     type CollectionListParams as CollectionListParams,
     type CollectionCreateParams as CollectionCreateParams,
-    type CollectionRetrieveDocumentsParams as CollectionRetrieveDocumentsParams,
     type CollectionUpdateParams as CollectionUpdateParams,
   };
 

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

@@ -4,13 +4,10 @@ export {
   Collections,
   type Collection,
   type CollectionEnvelope,
-  type CollectionRetrieveDocumentsResponse,
   type CollectionListParams,
   type CollectionCreateParams,
-  type CollectionRetrieveDocumentsParams,
   type CollectionUpdateParams,
   type CollectionsDefaultFlatPagination,
-  type CollectionRetrieveDocumentsResponsesDefaultFlatPagination,
 } from './collections';
 export {
   Settings,

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

@@ -66,8 +66,11 @@ export interface RetrievalSettings {
   /**
    * Retrieval strategy. `vector` runs semantic similarity search; `hybrid` combines
    * vector similarity with keyword matching; `keyword` runs lexical (BM25) matching.
+   * `keyword` is not accepted yet: setting it returns 422
+   * `unsupported_retrieval_type`. A collection set to `hybrid` is accepted here but
+   * cannot be searched until hybrid execution ships.
    */
-  retrieval_type?: 'vector' | 'hybrid' | 'keyword';
+  retrieval_type?: 'vector' | 'hybrid';
 
   /**
    * Number of top results to retrieve (1–50).

package/src/resources/ai/index.ts

@@ -94,13 +94,10 @@ export {
   Collections,
   type Collection,
   type CollectionEnvelope,
-  type CollectionRetrieveDocumentsResponse,
   type CollectionListParams,
   type CollectionCreateParams,
-  type CollectionRetrieveDocumentsParams,
   type CollectionUpdateParams,
   type CollectionsDefaultFlatPagination,
-  type CollectionRetrieveDocumentsResponsesDefaultFlatPagination,
 } from './collections/index';
 export {
   Conversations,
@@ -128,6 +125,7 @@ export {
 } from './embeddings/index';
 export { FineTuning } from './fine-tuning/index';
 export { Integrations, type Integration, type IntegrationListResponse } from './integrations/index';
+export { Knowledge } from './knowledge/index';
 export {
   McpServers,
   type McpServer,

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';