Get Started

Create a collection, attach your voice call transcriptions as a source, and search them with natural language. This quickstart uses the REST API — every step is a copy-paste request.

Prerequisites

A Telnyx API key from the portal. Export it so the examples work as-is:

export TELNYX_API_KEY="KEY..."

Content to search. The voice source indexes your account’s persisted voice call transcriptions — see how to enable persistence. An account with no persisted transcriptions returns empty results, but the API calls below still work.

Create a Collection

A collection is a named search index. name is required; everything else has defaults.

curl -X POST https://api.telnyx.com/v2/ai/collections \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support search",
    "description": "Searchable support call transcripts"
  }'

{
  "data": {
    "uuid": "fc96a26f-c4a1-484e-afc4-d94b903778cc",
    "slug": "support-search",
    "record_type": "ai_collection",
    "name": "Support search",
    "description": "Searchable support call transcripts",
    "status": "ready",
    "sources": [],
    "settings": { "retrieval": { "top_k": 5, "retrieval_type": "vector" } },
    "created_at": "2026-08-07T14:56:55.558737Z",
    "updated_at": "2026-08-07T14:56:55.558737Z"
  }
}

Two identifiers come back: the uuid (used by the management API) and the slug, derived from name (used by the search API). Default settings apply — top_k: 5, retrieval_type: vector. The collection has no sources yet, so there is nothing to search.

Attach a Source

Add the voice source — your account’s call transcriptions:

curl -X POST https://api.telnyx.com/v2/ai/collections/fc96a26f-c4a1-484e-afc4-d94b903778cc/sources \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "source_type": "voice" }'

{
  "data": {
    "id": "source_8vkvtcksnawvbnxq48yv2l06wx",
    "record_type": "ai_collection_source",
    "collection_id": "fc96a26f-c4a1-484e-afc4-d94b903778cc",
    "source_type": "voice",
    "status": "ready"
  }
}

The source is ready and its content is indexed for search. More source types are coming soon — see Sources.

Search It

Search is a GET on the collection’s documents, addressed by slug:

curl -H "Authorization: Bearer $TELNYX_API_KEY" \
  "https://api.telnyx.com/v2/ai/collections/support-search/documents?query=did+we+promise+a+refund"

{
  "data": [
    {
      "id": "e30570b6-68d5-11f1-838c-02420a0ddb20:0",
      "record_id": "e30570b6-68d5-11f1-838c-02420a0ddb20",
      "chunk_index": 0,
      "chunk_total": 1,
      "text": "...The refund of $200 has been deposited back in your account...",
      "score": 0.904,
      "record_type": "voice",
      "region": "USA",
      "record_created_at": "2026-06-15T16:18:49.981698+00:00",
      "ingested_at": "2026-06-15T16:20:12.170251+00:00",
      "metadata": { "source": "Trunking" }
    }
  ],
  "meta": {
    "collection_slug": "support-search",
    "searched_sources": ["voice"],
    "retrieval_type": "vector",
    "top_k": 5,
    "total_results": 56,
    "total_pages": 12,
    "page_number": 1,
    "page_size": 5
  }
}

Each result is a scored chunk that says what it is and where it came from — record_id, record_type, timestamps, and metadata. The match works on meaning, not exact words: “did we promise a refund” finds “the refund has been deposited”.Per-request parameters override the collection defaults for that one request:

# Fewer results and a date filter (--globoff: the [ ] are literal)
curl --globoff -H "Authorization: Bearer $TELNYX_API_KEY" \
  "https://api.telnyx.com/v2/ai/collections/support-search/documents?query=refund&top_k=3&filter[record_created_at][gte]=2026-06-01T00:00:00Z"

See Search for the full parameter and filter reference.

Ground Your LLM

The search response is grounding, ready to hand to any LLM as tool output — Search never generates answers itself. Declare the search call as a function tool, run it when the model asks, and feed the chunks back.

Next Steps

How Search Works

The indexing and query pipelines, and what a collection actually is.

Sources

Attach sources and enable the data behind them.

Settings

Configure retrieval mode and result count per collection.

Search

Filters, pagination, document reassembly, and errors.

Search

Concepts

Configuration

API

For AI Agents

Prerequisites

Next Steps

How Search Works

Sources

Settings

Search

​Prerequisites

​Next Steps

How Search Works

Sources

Settings

Search

Prerequisites

Next Steps