Sign in
OpenAPI 3.1.0raw.githubusercontent.com2026-08-191,3412,1385.0 MB

ec31f78cf002

AI Collections

Search collection documents

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
get/ai/collections/{slug}/documents

Path parameters

slugstring required
Example:support-transcripts

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

Query parameters

querystring
Example:customer called about billing issue

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.

top_kinteger
Example:10

Maximum number of ranked results to consider. When omitted, the collection's configured top_k setting is used.

sourcesstring
Example:voice,message

Comma-separated list of source types to restrict the search to. When omitted, all of the collection's sources are searched.

retrieval_type'vector' | 'hybrid' | 'keyword'
Example:hybrid

Override the collection's configured retrieval strategy for this request. Echoed back in meta.retrieval_type.

filterobject

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.

page[number]integer
Example:1

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

page[size]integer
Example:20

Number of results per page. Defaults to 20.

Response

Ranked (or listed) collection documents.

Example response

{
  "data": [
    {
      "record_type": "voice"
    }
  ],
  "meta": {
    "collection_slug": "support-transcripts",
    "page_number": 1,
    "page_size": 20,
    "retrieval_type": "vector",
    "searched_sources": [
      "voice",
      "message"
    ],
    "top_k": 5,
    "total_pages": 3,
    "total_results": 42
  }
}