> ## 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. # Collections > Create, list, retrieve, update, and delete Search collections with the Telnyx Collections API. 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](/docs/ai-search/sources) and [Settings](/docs/ai-search/settings) have their own subresources, documented separately. Management operations address a collection by `uuid`; [search](/docs/ai-search/searching) 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`). ```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": "Collections for personal calls", "description": "Searchable personal call transcripts", "sources": [ { "source_type": "voice" } ], "settings": { "retrieval": { "top_k": 10, "retrieval_type": "vector" } } }' ``` ```json theme={null} { "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`: ```json theme={null} { "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 ```bash theme={null} 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: ```json theme={null} { "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`. ```bash theme={null} # 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. ```bash theme={null} 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. ```bash theme={null} 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. ```bash theme={null} 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. Add, replace, and remove data sources. 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`. ```bash theme={null} 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. ## Related * [Get started](/docs/ai-search/get-started) -- first collection to first search * [Sources](/docs/ai-search/sources) -- add, replace, and remove data sources * [Settings](/docs/ai-search/settings) -- configure retrieval type and top\_k * [Search](/docs/ai-search/searching) -- query a collection's documents