---
title: "Search collection documents"
method: GET
path: "/ai/collections/{slug}/documents"
tags: ["AI Collections"]
---

# Search collection documents

`GET /ai/collections/{slug}/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`

## Path parameters

- `slug` string, required

## Query parameters

- `query` string
- `top_k` integer
- `sources` string
- `retrieval_type` 'vector' | 'hybrid' | 'keyword'
- `filter` object
- `page[number]` integer
- `page[size]` integer

## Response `200`

Ranked (or listed) collection documents.

- CollectionSearchResponse
  - `data` CollectionDocumentRecord[]
    - `chunk_index` integer
    - `chunk_total` integer
    - `id` string
    - `ingested_at` string, date-time
    - `metadata` object
    - `organization_id` string
    - `record_created_at` string, date-time
    - `record_id` string
    - `record_type` string — The source record kind this chunk came from (e.g. `voice`, `meeting_bot`, `message`).
    - `region` string
    - `score` number, float — Relevance score (higher = more relevant) for ranked search. `0.0` for plain catalog listings (when `query` is omitted).
    - `text` string
    - `user_id` string
  - `meta` CollectionSearchMeta
    - `collection_slug` string
    - `page_number` integer
    - `page_size` integer
    - `retrieval_type` string
    - `searched_sources` string[]
    - `top_k` integer
    - `total_pages` integer
    - `total_results` integer

## Other responses

- `400` — The request was malformed or failed validation.
- `401` — Missing or invalid authentication.
- `404` — The collection does not exist or is not searchable.
- `422` — The collection has no searchable sources.

---

[API](https://skmtc.net/team-telnyx/apis/telnyx-api-2.md) · [All operations](https://skmtc.net/team-telnyx/apis/telnyx-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/team-telnyx/telnyx-api-2/revisions/ec31f78cf002/schema)