Class: Telnyx::Resources::AI::Collections

Inherits:
Object
  • Object
show all
Defined in:
lib/telnyx/resources/ai/collections.rb,
lib/telnyx/resources/ai/collections/sources.rb,
lib/telnyx/resources/ai/collections/settings.rb,
sig/telnyx/resources/ai/collections.rbs,
sig/telnyx/resources/ai/collections/sources.rbs,
sig/telnyx/resources/ai/collections/settings.rbs

Overview

Create and manage logical collections of your Telnyx data, tune retrieval settings, manage sources, and run collection-scoped semantic search.

Defined Under Namespace

Classes: Settings, Sources

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ Collections

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Collections.

Parameters:



236
237
238
239
240
 
# File 'lib/telnyx/resources/ai/collections.rb', line 236

def initialize(client:)
  @client = client
  @settings = Telnyx::Resources::AI::Collections::Settings.new(client: client)
  @sources = Telnyx::Resources::AI::Collections::Sources.new(client: client)
end

Instance Attribute Details

#settings ⇒ Telnyx::Resources::AI::Collections::Settings (readonly)

Create and manage logical collections of your Telnyx data, tune retrieval settings, manage sources, and run collection-scoped semantic search.

Returns:



12
13
14
 
# File 'lib/telnyx/resources/ai/collections.rb', line 12

def settings
  @settings
end

#sources ⇒ Telnyx::Resources::AI::Collections::Sources (readonly)

Create and manage logical collections of your Telnyx data, tune retrieval settings, manage sources, and run collection-scoped semantic search.

Returns:



17
18
19
 
# File 'lib/telnyx/resources/ai/collections.rb', line 17

def sources
  @sources
end

Instance Method Details

#create(name:, description: nil, settings: nil, slug: nil, sources: nil, request_options: {}) ⇒ Telnyx::Models::AI::CollectionEnvelope

Creates a new collection scoped to your organization. Optionally attach sources and retrieval settings at creation time. If slug is omitted, one is derived from name and must be unique within your organization.

Parameters:

Returns:

See Also:



40
41
42
43
44
45
46
47
48
49
 
# File 'lib/telnyx/resources/ai/collections.rb', line 40

def create(params)
  parsed, options = Telnyx::AI::CollectionCreateParams.dump_request(params)
  @client.request(
    method: :post,
    path: "ai/collections",
    body: parsed,
    model: Telnyx::AI::CollectionEnvelope,
    options: options
  )
end

#delete(uuid, request_options: {}) ⇒ nil

Soft-deletes a collection. Its slug is freed and may be reused by a new collection.

Parameters:

  • uuid (String) —

    The collection's unique identifier.

  • request_options (Telnyx::RequestOptions, Hash{Symbol=>Object}, nil)
  • request_options: (Telnyx::request_opts)

Returns:

  • (nil)

See Also:



136
137
138
139
140
141
142
143
 
# File 'lib/telnyx/resources/ai/collections.rb', line 136

def delete(uuid, params = {})
  @client.request(
    method: :delete,
    path: ["ai/collections/%1$s", uuid],
    model: NilClass,
    options: params[:request_options]
  )
end

#list(page_number: nil, page_size: nil, request_options: {}) ⇒ Telnyx::Internal::DefaultFlatPagination<Telnyx::Models::AI::Collection>

Returns a paginated list of collections in your organization.

Parameters:

  • page_number (Integer) —

    Page number to return (1-based). Defaults to 1.

  • page_size (Integer) —

    Number of results per page. Defaults to 20.

  • request_options (Telnyx::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



111
112
113
114
115
116
117
118
119
120
121
122
 
# File 'lib/telnyx/resources/ai/collections.rb', line 111

def list(params = {})
  parsed, options = Telnyx::AI::CollectionListParams.dump_request(params)
  query = Telnyx::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: "ai/collections",
    query: query.transform_keys(page_number: "page[number]", page_size: "page[size]"),
    page: Telnyx::Internal::DefaultFlatPagination,
    model: Telnyx::AI::Collection,
    options: options
  )
end

#retrieve(slug, request_options: {}) ⇒ Telnyx::Models::AI::CollectionEnvelope

Fetches a single collection by its slug.

Parameters:

  • slug (String) —

    The collection's slug (unique within your organization).

  • request_options (Telnyx::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



62
63
64
65
66
67
68
69
 
# File 'lib/telnyx/resources/ai/collections.rb', line 62

def retrieve(slug, params = {})
  @client.request(
    method: :get,
    path: ["ai/collections/slug/%1$s", slug],
    model: Telnyx::AI::CollectionEnvelope,
    options: params[:request_options]
  )
end

#retrieve_by_id(uuid, request_options: {}) ⇒ Telnyx::Models::AI::CollectionEnvelope

Fetches a single collection by its uuid.

Parameters:

  • uuid (String) —

    The collection's unique identifier.

  • request_options (Telnyx::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



156
157
158
159
160
161
162
163
 
# File 'lib/telnyx/resources/ai/collections.rb', line 156

def retrieve_by_id(uuid, params = {})
  @client.request(
    method: :get,
    path: ["ai/collections/%1$s", uuid],
    model: Telnyx::AI::CollectionEnvelope,
    options: params[:request_options]
  )
end

#retrieve_documents(slug, filter: nil, page_number: nil, page_size: nil, query: nil, retrieval_type: nil, sources: nil, top_k: nil, request_options: {}) ⇒ Telnyx::Models::AI::CollectionRetrieveDocumentsResponse

Some parameter documentations has been truncated, see Models::AI::CollectionRetrieveDocumentsParams for more details.

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

Parameters:

  • slug (String) —

    The collection's slug (unique within your organization).

  • filter (Hash{Symbol=>Object}) —

    Field filters applied before ranking, using filter[field][operator]=value. Sup

  • page_number (Integer) —

    Page number to return (1-based). Defaults to 1.

  • page_size (Integer) —

    Number of results per page. Defaults to 20.

  • query (String) —

    Natural-language search query. When provided, the text is matched against the co

  • retrieval_type (Symbol, Telnyx::Models::AI::CollectionRetrieveDocumentsParams::RetrievalType) —

    Override the collection's configured retrieval strategy for this request. Echoed

  • sources (String) —

    Comma-separated list of source types to restrict the search to. When omitted, al

  • top_k (Integer) —

    Maximum number of ranked results to consider. When omitted, the collection's con

  • request_options (Telnyx::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



221
222
223
224
225
226
227
228
229
230
231
 
# File 'lib/telnyx/resources/ai/collections.rb', line 221

def retrieve_documents(slug, params = {})
  parsed, options = Telnyx::AI::CollectionRetrieveDocumentsParams.dump_request(params)
  query = Telnyx::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: ["ai/collections/%1$s/documents", slug],
    query: query.transform_keys(page_number: "page[number]", page_size: "page[size]"),
    model: Telnyx::Models::AI::CollectionRetrieveDocumentsResponse,
    options: options
  )
end

#update(uuid, description: nil, name: nil, request_options: {}) ⇒ Telnyx::Models::AI::CollectionEnvelope

Updates a collection's metadata (name and/or description). Sources and settings are managed through their own sub-resources.

Parameters:

  • uuid (String) —

    The collection's unique identifier.

  • description (String)
  • name (String)
  • request_options (Telnyx::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



87
88
89
90
91
92
93
94
95
96
 
# File 'lib/telnyx/resources/ai/collections.rb', line 87

def update(uuid, params = {})
  parsed, options = Telnyx::AI::CollectionUpdateParams.dump_request(params)
  @client.request(
    method: :patch,
    path: ["ai/collections/%1$s", uuid],
    body: parsed,
    model: Telnyx::AI::CollectionEnvelope,
    options: options
  )
end