telnyx 7.16.0 → 7.18.0

package/src/resources/ai/assistants/canary-deploys.ts

@@ -82,10 +82,18 @@ export class CanaryDeploys extends APIResource {
    */
   create(
     assistantID: string,
-    body: CanaryDeployCreateParams,
+    params: CanaryDeployCreateParams,
     options?: RequestOptions,
   ): APIPromise<CanaryDeployResponse> {
-    return this._client.post(path`/ai/assistants/${assistantID}/canary-deploys`, { body, ...options });
+    const { 'Idempotency-Key': idempotencyKey, ...body } = params;
+    return this._client.post(path`/ai/assistants/${assistantID}/canary-deploys`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined) },
+        options?.headers,
+      ]),
+    });
   }
 
   /**
@@ -240,7 +248,22 @@ export interface Serve {
 }
 
 export interface CanaryDeployCreateParams {
+  /**
+   * Body param
+   */
   rules?: Array<RuleInput>;
+
+  /**
+   * 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 CanaryDeployUpdateParams {

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

@@ -12,6 +12,7 @@ export {
   type AuthenticationMethod,
   type BooleanOpExpression,
   type ComparisonExpression,
+  type ConversationFlow,
   type ConversationFlowReq,
   type EnabledFeatures,
   type Expression,
@@ -20,6 +21,8 @@ export {
   type FallbackConfig,
   type FallbackConfigReq,
   type FlowEdge,
+  type FlowNode,
+  type FlowNodeReq,
   type HangupTool,
   type HangupToolParams,
   type ImportMetadata,
@@ -37,8 +40,12 @@ export {
   type PrivacySettings,
   type PromptSyncStatus,
   type RetrievalTool,
+  type SpeakNode,
+  type SpeakNodeReq,
   type StartSpeakingPlan,
   type TelephonySettings,
+  type ToolNode,
+  type ToolNodeReq,
   type TranscriptionEndpointingPlan,
   type TranscriptionSettings,
   type TranscriptionSettingsConfig,
@@ -55,6 +62,7 @@ export {
   type AssistantRetrieveParams,
   type AssistantUpdateParams,
   type AssistantChatParams,
+  type AssistantCloneParams,
   type AssistantSendSMSParams,
 } from './assistants';
 export {

package/src/resources/ai/assistants/scheduled-events.ts

@@ -60,10 +60,18 @@ export class ScheduledEvents extends APIResource {
    */
   create(
     assistantID: string,
-    body: ScheduledEventCreateParams,
+    params: ScheduledEventCreateParams,
     options?: RequestOptions,
   ): APIPromise<ScheduledEventResponse> {
-    return this._client.post(path`/ai/assistants/${assistantID}/scheduled_events`, { body, ...options });
+    const { 'Idempotency-Key': idempotencyKey, ...body } = params;
+    return this._client.post(path`/ai/assistants/${assistantID}/scheduled_events`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined) },
+        options?.headers,
+      ]),
+    });
   }
 
   /**
@@ -87,7 +95,8 @@ export class ScheduledEvents extends APIResource {
   }
 
   /**
-   * Retrieve a scheduled event by event ID
+   * Returns the details of a single scheduled event configured for the specified
+   * assistant.
    *
    * @example
    * ```ts
@@ -278,53 +287,74 @@ export interface ScheduledEventListParams extends DefaultFlatPaginationParams {
 
 export interface ScheduledEventCreateParams {
   /**
-   * The datetime at which the event should be scheduled. Formatted as ISO 8601.
+   * Body param: The datetime at which the event should be scheduled. Formatted as
+   * ISO 8601.
    */
   scheduled_at_fixed_datetime: string;
 
   /**
-   * The phone number, SIP URI, to schedule the call or text from.
+   * Body param: The phone number, SIP URI, to schedule the call or text from.
    */
   telnyx_agent_target: string;
 
+  /**
+   * Body param
+   */
   telnyx_conversation_channel: ConversationChannelType;
 
   /**
-   * The phone number, SIP URI, to schedule the call or text to.
+   * Body param: The phone number, SIP URI, to schedule the call or text to.
    */
   telnyx_end_user_target: string;
 
   /**
-   * Per-call telephony overrides applied when a scheduled phone-call event
-   * dispatches. Phone-call events only. New per-call dispatch options should be
-   * added here rather than as top-level event fields.
+   * Body param: Per-call telephony overrides applied when a scheduled phone-call
+   * event dispatches. Phone-call events only. New per-call dispatch options should
+   * be added here rather than as top-level event fields.
    */
   call_settings?: ScheduledCallSettings;
 
   /**
-   * Metadata associated with the conversation. Telnyx provides several pieces of
-   * metadata, but customers can also add their own.
+   * Body param: Metadata associated with the conversation. Telnyx provides several
+   * pieces of metadata, but customers can also add their own.
    */
   conversation_metadata?: { [key: string]: string | number | boolean };
 
   /**
-   * A map of dynamic variable names to values. These variables can be referenced in
-   * the assistant's instructions and messages using {{variable_name}} syntax.
+   * Body param: A map of dynamic variable names to values. These variables can be
+   * referenced in the assistant's instructions and messages using {{variable_name}}
+   * syntax.
    */
   dynamic_variables?: { [key: string]: string };
 
   /**
-   * Configure number of retries on client errors: busy, no-answer, failed, canceled
-   * (caller hung up before the callee answered)
+   * Body param: Configure number of retries on client errors: busy, no-answer,
+   * failed, canceled (caller hung up before the callee answered)
    */
   max_retries_client_errors?: number;
 
+  /**
+   * Body param
+   */
   retry_interval_secs?: number;
 
   /**
-   * Required for sms scheduled events. The text to be sent to the end user.
+   * Body param: Required for sms scheduled events. The text to be sent to the end
+   * user.
    */
   text?: string;
+
+  /**
+   * 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 ScheduledEventDeleteParams {

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

@@ -37,7 +37,8 @@ export class Tags extends APIResource {
   }
 
   /**
-   * Remove a tag from an AI assistant.
+   * Removes the specified tag from the AI assistant and returns the assistant's
+   * updated tag list.
    *
    * @example
    * ```ts

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

@@ -7,6 +7,7 @@ import {
   type DefaultFlatPaginationParams,
   PagePromise,
 } from '../../../../core/pagination';
+import { buildHeaders } from '../../../../internal/headers';
 import { RequestOptions } from '../../../../internal/request-options';
 import { path } from '../../../../internal/utils/path';
 
@@ -51,10 +52,18 @@ export class Runs extends APIResource {
    */
   trigger(
     testID: string,
-    body: RunTriggerParams | null | undefined = {},
+    params: RunTriggerParams | null | undefined = {},
     options?: RequestOptions,
   ): APIPromise<TestRunResponse> {
-    return this._client.post(path`/ai/assistants/tests/${testID}/runs`, { body, ...options });
+    const { 'Idempotency-Key': idempotencyKey, ...body } = params ?? {};
+    return this._client.post(path`/ai/assistants/tests/${testID}/runs`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined) },
+        options?.headers,
+      ]),
+    });
   }
 
   /**
@@ -190,11 +199,23 @@ export interface RunListParams extends DefaultFlatPaginationParams {
 
 export interface RunTriggerParams {
   /**
-   * Optional assistant version ID to use for this test run. If provided, the version
-   * must exist or a 400 error will be returned. If not provided, test will run on
-   * main version
+   * Body param: Optional assistant version ID to use for this test run. If provided,
+   * the version must exist or a 400 error will be returned. If not provided, test
+   * will run on main version
    */
   destination_version_id?: string;
+
+  /**
+   * 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 RunRetrieveParams {

package/src/resources/ai/assistants/tests/test-suites/runs.ts

@@ -9,6 +9,7 @@ import {
   type DefaultFlatPaginationParams,
   PagePromise,
 } from '../../../../../core/pagination';
+import { buildHeaders } from '../../../../../internal/headers';
 import { RequestOptions } from '../../../../../internal/request-options';
 import { path } from '../../../../../internal/utils/path';
 
@@ -55,10 +56,18 @@ export class Runs extends APIResource {
    */
   trigger(
     suiteName: string,
-    body: RunTriggerParams | null | undefined = {},
+    params: RunTriggerParams | null | undefined = {},
     options?: RequestOptions,
   ): APIPromise<RunTriggerResponse> {
-    return this._client.post(path`/ai/assistants/tests/test-suites/${suiteName}/runs`, { body, ...options });
+    const { 'Idempotency-Key': idempotencyKey, ...body } = params ?? {};
+    return this._client.post(path`/ai/assistants/tests/test-suites/${suiteName}/runs`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined) },
+        options?.headers,
+      ]),
+    });
   }
 }
 
@@ -106,11 +115,23 @@ export interface RunListParams extends DefaultFlatPaginationParams {
 
 export interface RunTriggerParams {
   /**
-   * Optional assistant version ID to use for all test runs in this suite. If
-   * provided, the version must exist or a 400 error will be returned. If not
-   * provided, test will run on main version
+   * Body param: Optional assistant version ID to use for all test runs in this
+   * suite. If provided, the version must exist or a 400 error will be returned. If
+   * not provided, test will run on main version
    */
   destination_version_id?: string;
+
+  /**
+   * 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 declare namespace Runs {

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

@@ -78,8 +78,16 @@ export class Tests extends APIResource {
    *   });
    * ```
    */
-  create(body: TestCreateParams, options?: RequestOptions): APIPromise<AssistantTest> {
-    return this._client.post('/ai/assistants/tests', { body, ...options });
+  create(params: TestCreateParams, options?: RequestOptions): APIPromise<AssistantTest> {
+    const { 'Idempotency-Key': idempotencyKey, ...body } = params;
+    return this._client.post('/ai/assistants/tests', {
+      body,
+      ...options,
+      headers: buildHeaders([
+        { ...(idempotencyKey != null ? { 'Idempotency-Key': idempotencyKey } : undefined) },
+        options?.headers,
+      ]),
+    });
   }
 
   /**
@@ -230,52 +238,64 @@ export interface TestListParams extends DefaultFlatPaginationParams {
 
 export interface TestCreateParams {
   /**
-   * The target destination for the test conversation. Format depends on the channel:
-   * phone number for SMS/voice, webhook URL for web chat, etc.
+   * Body param: The target destination for the test conversation. Format depends on
+   * the channel: phone number for SMS/voice, webhook URL for web chat, etc.
    */
   destination: string;
 
   /**
-   * Detailed instructions that define the test scenario and what the assistant
-   * should accomplish. This guides the test execution and evaluation.
+   * Body param: Detailed instructions that define the test scenario and what the
+   * assistant should accomplish. This guides the test execution and evaluation.
    */
   instructions: string;
 
   /**
-   * A descriptive name for the assistant test. This will be used to identify the
-   * test in the UI and reports.
+   * Body param: A descriptive name for the assistant test. This will be used to
+   * identify the test in the UI and reports.
    */
   name: string;
 
   /**
-   * Evaluation criteria used to assess the assistant's performance. Each rubric item
-   * contains a name and specific criteria for evaluation.
+   * Body param: Evaluation criteria used to assess the assistant's performance. Each
+   * rubric item contains a name and specific criteria for evaluation.
    */
   rubric: Array<TestCreateParams.Rubric>;
 
   /**
-   * Optional detailed description of what this test evaluates and its purpose. Helps
-   * team members understand the test's objectives.
+   * Body param: Optional detailed description of what this test evaluates and its
+   * purpose. Helps team members understand the test's objectives.
    */
   description?: string;
 
   /**
-   * Maximum duration in seconds that the test conversation should run before timing
-   * out. If not specified, uses system default timeout.
+   * Body param: Maximum duration in seconds that the test conversation should run
+   * before timing out. If not specified, uses system default timeout.
    */
   max_duration_seconds?: number;
 
   /**
-   * The communication channel through which the test will be conducted. Determines
-   * how the assistant will receive and respond to test messages.
+   * Body param: The communication channel through which the test will be conducted.
+   * Determines how the assistant will receive and respond to test messages.
    */
   telnyx_conversation_channel?: TelnyxConversationChannel;
 
   /**
-   * Optional test suite name to group related tests together. Useful for organizing
-   * tests by feature, team, or release cycle.
+   * Body param: Optional test suite name to group related tests together. Useful for
+   * organizing tests by feature, team, or release cycle.
    */
   test_suite?: string;
+
+  /**
+   * 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 namespace TestCreateParams {

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

@@ -10,7 +10,9 @@ import { path } from '../../../internal/utils/path';
  */
 export class Tools extends APIResource {
   /**
-   * Test a webhook tool for an assistant
+   * Executes a test invocation of the specified webhook tool for the assistant and
+   * returns the outcome, so you can verify the webhook's behavior before relying on
+   * it in conversations.
    *
    * @example
    * ```ts
@@ -30,7 +32,8 @@ export class Tools extends APIResource {
   }
 
   /**
-   * Detach a tool from an AI assistant.
+   * Detaches the specified tool from the AI assistant so the assistant can no longer
+   * invoke it.
    *
    * @example
    * ```ts

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,53 +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
-   * const response =
-   *   await client.ai.collections.retrieveDocuments(
-   *     'support-transcripts',
-   *   );
-   * ```
-   */
-  retrieveDocuments(
-    slug: string,
-    query: CollectionRetrieveDocumentsParams | null | undefined = {},
-    options?: RequestOptions,
-  ): APIPromise<CollectionRetrieveDocumentsResponse> {
-    return this._client.get(path`/ai/collections/${slug}/documents`, { query, ...options });
-  }
-
   /**
    * Soft-deletes a collection. Its `slug` is freed and may be reused by a new
    * collection.
@@ -226,68 +179,6 @@ export interface CollectionEnvelope {
   data?: Collection;
 }
 
-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 CollectionListParams extends DefaultFlatPaginationParams {}
 
 export interface CollectionCreateParams {
@@ -317,52 +208,6 @@ export interface CollectionCreateParams {
   sources?: Array<SourcesAPI.SourceRequest>;
 }
 
-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;
-
-  /**
-   * 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;
 
@@ -376,11 +221,9 @@ export declare namespace Collections {
   export {
     type Collection as Collection,
     type CollectionEnvelope as CollectionEnvelope,
-    type CollectionRetrieveDocumentsResponse as CollectionRetrieveDocumentsResponse,
     type CollectionsDefaultFlatPagination as CollectionsDefaultFlatPagination,
     type CollectionListParams as CollectionListParams,
     type CollectionCreateParams as CollectionCreateParams,
-    type CollectionRetrieveDocumentsParams as CollectionRetrieveDocumentsParams,
     type CollectionUpdateParams as CollectionUpdateParams,
   };
 

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

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

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).