> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Started

> Create your first Search collection, attach a source, and run your first search in a few minutes.

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](https://portal.telnyx.com/#/api-keys). Export it so the examples work as-is:

```bash theme={null}
export TELNYX_API_KEY="KEY..."
```

* Content to search. The `voice` source indexes your account's persisted voice call transcriptions -- see [how to enable persistence](/docs/ai-search/sources/voice). An account with no persisted transcriptions returns empty results, but the API calls below still work.

<Steps>
  <Step title="Create a Collection">
    A collection is a named search index. `name` is required; everything else has defaults.

    ```bash theme={null}
    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"
      }'
    ```

    ```json theme={null}
    {
      "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.
  </Step>

  <Step title="Attach a Source">
    Add the `voice` source -- your account's call transcriptions:

    ```bash theme={null}
    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" }'
    ```

    ```json theme={null}
    {
      "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](/docs/ai-search/sources).
  </Step>

  <Step title="Search It">
    Search is a `GET` on the collection's documents, addressed by slug:

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

    ```json theme={null}
    {
      "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:

    ```bash theme={null}
    # 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](/docs/ai-search/searching) for the full parameter and filter reference.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="How Search Works" href="/docs/ai-search/how-it-works">
    The indexing and query pipelines, and what a collection actually is.
  </Card>

  <Card title="Sources" href="/docs/ai-search/sources">
    Attach sources and enable the data behind them.
  </Card>

  <Card title="Settings" href="/docs/ai-search/settings">
    Configure retrieval mode and result count per collection.
  </Card>

  <Card title="Search" href="/docs/ai-search/searching">
    Filters, pagination, document reassembly, and errors.
  </Card>
</CardGroup>