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

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

Overview

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

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:



85
86
87
 
# File 'lib/telnyx/resources/ai/knowledge/collections.rb', line 85

def initialize(client:)
  @client = client
end

Instance Method Details

#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::Knowledge::CollectionRetrieveDocumentsResponse

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

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

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::Knowledge::CollectionRetrieveDocumentsParams::RetrievalType) —

    Reserved; not yet functional. A value supplied here is accepted but ignored — it

  • 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:



70
71
72
73
74
75
76
77
78
79
80
 
# File 'lib/telnyx/resources/ai/knowledge/collections.rb', line 70

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