Collections

A collection is the core resource in Search — a named container for data sources with its own retrieval settings. This page covers the full CRUD lifecycle. Sources and Settings have their own subresources, documented separately. Management operations address a collection by uuid; search addresses it by slug.

Create a Collection

name is required. slug is derived from name when omitted and must be unique per organization. A collection may be created with or without initial sources. settings is optional — defaults apply (top_k = 5, retrieval_type = vector).

curl -X POST https://api.telnyx.com/v2/ai/collections \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Collections for personal calls",
    "description": "Searchable personal call transcripts",
    "sources": [
      { "source_type": "voice" }
    ],
    "settings": {
      "retrieval": { "top_k": 10, "retrieval_type": "vector" }
    }
  }'

{
  "data": {
    "uuid": "b3b1c8a2-9f4e-4d2a-9c1e-2f7a6d5b4c3a",
    "slug": "collections-personal-calls",
    "record_type": "ai_collection",
    "name": "Collections for personal calls",
    "description": "Searchable personal call transcripts",
    "status": "ready",
    "sources": [
      { "id": "source_8vkvtcksnawvbnxq48yv2l06wx", "record_type": "ai_collection_source",
        "collection_id": "b3b1c8a2-9f4e-4d2a-9c1e-2f7a6d5b4c3a",
        "source_type": "voice", "status": "ready" }
    ],
    "settings": { "retrieval": { "top_k": 10, "retrieval_type": "vector" } },
    "created_at": "2026-08-07T14:56:55.558737Z",
    "updated_at": "2026-08-07T14:56:55.558737Z"
  }
}

Returns 201 Created with the full collection record.

Slug Conflicts

If a collection with the same slug already exists for the account, the request returns 409 Conflict:

{
  "errors": [{
    "code": "collection_slug_taken",
    "title": "Collection slug already in use",
    "detail": "A collection with slug 'collections-personal-calls' already exists for this account.",
    "source": { "pointer": "/slug" }
  }]
}

List Collections

curl -H "Authorization: Bearer $TELNYX_API_KEY" \
  "https://api.telnyx.com/v2/ai/collections"

Returns 200 OK with the Telnyx V2 data + meta envelope — each item is a full collection record:

{
  "data": [
    {
      "uuid": "b3b1c8a2-9f4e-4d2a-9c1e-2f7a6d5b4c3a",
      "slug": "collections-personal-calls",
      "record_type": "ai_collection",
      "name": "Collections for personal calls",
      "description": "Searchable personal call transcripts",
      "status": "ready",
      "sources": [
        { "id": "source_8vkvtcksnawvbnxq48yv2l06wx", "record_type": "ai_collection_source",
          "collection_id": "b3b1c8a2-9f4e-4d2a-9c1e-2f7a6d5b4c3a",
          "source_type": "voice", "status": "ready" }
      ],
      "settings": { "retrieval": { "top_k": 10, "retrieval_type": "vector" } },
      "created_at": "2026-08-07T14:56:55.558737Z",
      "updated_at": "2026-08-07T14:56:55.558737Z"
    }
  ],
  "meta": { "total_pages": 1, "total_results": 1, "page_number": 1, "page_size": 20 }
}

Pagination

Pagination is optional. Use page[number]/page[size] query parameters (default size 20, max 100). Results are sorted by slug then created_at.

# Second page (--globoff so curl does not treat [ ] as globs)
curl --globoff -H "Authorization: Bearer $TELNYX_API_KEY" \
  "https://api.telnyx.com/v2/ai/collections?page[number]=2&page[size]=20"

Retrieve a Collection by UUID

Lookup by UUID returns the full collection record.

curl -H "Authorization: Bearer $TELNYX_API_KEY" \
  "https://api.telnyx.com/v2/ai/collections/b3b1c8a2-9f4e-4d2a-9c1e-2f7a6d5b4c3a"

If no collection exists with that UUID for the account, the request returns 404 Not Found.

Retrieve a Collection by Slug

Lookup by slug returns the same full record. Slugs are unique per organization.

curl -H "Authorization: Bearer $TELNYX_API_KEY" \
  "https://api.telnyx.com/v2/ai/collections/slug/collections-personal-calls"

If no collection exists with that slug for the account, the request returns 404 Not Found.

Update Collection Metadata

PATCH updates metadata only (name, description). Partial — omitted fields are untouched. slug is immutable; renaming does not regenerate it. Sources and settings have their own subresources.

curl -X PATCH https://api.telnyx.com/v2/ai/collections/b3b1c8a2-9f4e-4d2a-9c1e-2f7a6d5b4c3a \
  -H "Authorization: Bearer $TELNYX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Conversation Intelligence",
    "description": "Calls and meetings used by the support AI"
  }'

Returns the full updated collection record with a refreshed updated_at. Slug is unchanged.

Sources

Add, replace, and remove data sources.

Settings

Configure retrieval type and top_k.

Delete a Collection

Soft delete. Sets deleted_at and status = deleted, then excludes the collection from list results and returns 404 on detail lookups. The slug is freed for reuse immediately. No external data is touched — transcriptions, embeddings, and credential connections are not affected. Deleting an already-deleted or unknown collection returns 404.

curl -X DELETE -H "Authorization: Bearer $TELNYX_API_KEY" \
  "https://api.telnyx.com/v2/ai/collections/b3b1c8a2-9f4e-4d2a-9c1e-2f7a6d5b4c3a"

Returns 204 No Content — no body.

Get started — first collection to first search
Sources — add, replace, and remove data sources
Settings — configure retrieval type and top_k
Search — query a collection’s documents

Search

Concepts

Configuration

API

For AI Agents

Create a Collection

Slug Conflicts

List Collections

Retrieve a Collection by UUID

Retrieve a Collection by Slug

Update Collection Metadata

Sources

Settings

Delete a Collection

​Create a Collection

​Slug Conflicts

​List Collections

​Pagination

​Retrieve a Collection by UUID

​Retrieve a Collection by Slug

​Update Collection Metadata

Sources

Settings

​Delete a Collection

​Related

Create a Collection

Slug Conflicts

List Collections

Pagination

Retrieve a Collection by UUID

Retrieve a Collection by Slug

Update Collection Metadata

Delete a Collection

Related