Search collection documents

Runs search over the documents in a collection, ranked by relevance to query. Searches currently run vector retrieval (semantic similarity). The collection’s retrieval_type setting is the forward-compatible selector: hybrid (vector similarity fused with keyword matching) can be set but cannot be searched yet, and keyword (lexical BM25 matching) is not accepted yet — setting it returns 422 unsupported_retrieval_type. A per-request retrieval_type is accepted but ignored; meta.retrieval_type echoes the mode that actually ran. When query is omitted, returns a plain catalog listing of the collection’s documents.

How it works:

The query text is embedded into a 1024-dimensional vector using the multilingual-e5-large model.
The embedding is compared against the collection’s indexed document chunks using semantic similarity. When hybrid and keyword execution ship, those scores will be fused with, or replaced by, lexical BM25 matching.
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/knowledge/collections/my-collection/documents?query=billing+issue&top_k=10
GET /v2/ai/knowledge/collections/my-collection/documents?query=refund&sources=voice,message
GET /v2/ai/knowledge/collections/my-collection/documents?query=outage&filter[record_created_at][gte]=2026-01-01T00:00:00Z

GET

knowledge

collections

{slug}

documents

JavaScript

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});

const response = await client.ai.knowledge.collections.retrieveDocuments('slug');

console.log(response.data);

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
)
response = client.ai.knowledge.collections.retrieve_documents(
    "slug",
)
print(response.data)

package main

import (
	"context"
	"fmt"

	"github.com/team-telnyx/telnyx-go"
	"github.com/team-telnyx/telnyx-go/option"
)

func main() {
	client := telnyx.NewClient(
		option.WithAPIKey("My API Key"),
	)
	response, err := client.AI.Knowledge.Collections.GetDocuments(
		context.TODO(),
		"slug",
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", response.Data)
}

package com.telnyx.sdk.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        var response = client.ai().knowledge().collections().retrieveDocuments("slug");
    }
}

<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

use Telnyx\Client;
use Telnyx\Core\Exceptions\APIException;

$client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API Key');

try {
  $response = $client->ai->knowledge->collections->retrieveDocuments(
    'slug',
  );

  var_dump($response);
} catch (APIException $e) {
  echo $e->getMessage();
}

{
  "data": [
    {
      "id": "<string>",
      "record_id": "<string>",
      "record_type": "voice",
      "chunk_index": 123,
      "chunk_total": 123,
      "text": "<string>",
      "score": 123,
      "region": "<string>",
      "user_id": "<string>",
      "organization_id": "<string>",
      "record_created_at": "2023-11-07T05:31:56Z",
      "ingested_at": "2023-11-07T05:31:56Z",
      "metadata": {}
    }
  ],
  "meta": {
    "collection_slug": "support-transcripts",
    "searched_sources": [
      "voice",
      "message"
    ],
    "retrieval_type": "vector",
    "top_k": 5,
    "total_results": 42,
    "total_pages": 3,
    "page_number": 1,
    "page_size": 20
  }
}

{
  "errors": [
    {
      "code": "10015",
      "title": "Bad Request",
      "detail": "The request failed because it was not well-formed.",
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/10015"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10009",
      "title": "Authentication failed",
      "detail": "The required authentication headers were either invalid or not included in the request.",
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/10009"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10005",
      "title": "Resource not found",
      "detail": "The requested resource or URL could not be found.",
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/10005"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10027",
      "title": "Unprocessable Entity",
      "detail": "The server understood the syntax of the request but was unable to process the instructions.",
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/10027"
      }
    }
  ]
}

Authorizations

Authorization

string

header

required

Telnyx API key. Collections and results are automatically scoped to the authenticated user's organization.

Path Parameters

slug

string

required

The collection's slug (unique within your organization).

Example:

"support-transcripts"

Query Parameters

query

string

Natural-language search query. When provided, the text is matched against the collection's document chunks using the collection's retrieval_type (vector or hybrid). When omitted, documents are returned as a plain catalog listing.

Minimum string length: 1

Example:

"customer called about billing issue"

top_k

integer

Maximum number of ranked results to consider. When omitted, the collection's configured top_k setting is used.

Required range: 1 <= x <= 50

Example:

10

sources

string

Comma-separated list of source types to restrict the search to. When omitted, all of the collection's sources are searched.

Example:

"voice,message"

retrieval_type

enum<string>

Reserved; not yet functional. A value supplied here is accepted but ignored — it does not override the collection's configured strategy, and it is not echoed back. Searches run vector retrieval, and meta.retrieval_type reports the mode that actually ran. To change retrieval strategy, set it on the collection's settings subresource.

Available options:

vector,

hybrid,

keyword

Example:

"vector"

filter

object

Field filters applied before ranking, using filter[field][operator]=value. Supported operators: eq (default), in, gte, gt, lte, lt, contains. Known fields: record_type, record_id, user_id, record_created_at, ingested_at; any other name resolves to a metadata.<field> filter. Example: filter[record_id][eq]=rec_123.

page[number]

integer

default:1

Page number to return (1-based). Defaults to 1.

Required range: x >= 1

Example:

1

page[size]

integer

default:20

Number of results per page. Defaults to 20.

Required range: 1 <= x <= 100

Example:

20

Response

Ranked (or listed) collection documents.

data

object[]

Show child attributes

meta

object

Show child attributes

JavaScript

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});

const response = await client.ai.knowledge.collections.retrieveDocuments('slug');

console.log(response.data);

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
)
response = client.ai.knowledge.collections.retrieve_documents(
    "slug",
)
print(response.data)

package main

import (
	"context"
	"fmt"

	"github.com/team-telnyx/telnyx-go"
	"github.com/team-telnyx/telnyx-go/option"
)

func main() {
	client := telnyx.NewClient(
		option.WithAPIKey("My API Key"),
	)
	response, err := client.AI.Knowledge.Collections.GetDocuments(
		context.TODO(),
		"slug",
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", response.Data)
}

package com.telnyx.sdk.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        var response = client.ai().knowledge().collections().retrieveDocuments("slug");
    }
}

<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

use Telnyx\Client;
use Telnyx\Core\Exceptions\APIException;

$client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API Key');

try {
  $response = $client->ai->knowledge->collections->retrieveDocuments(
    'slug',
  );

  var_dump($response);
} catch (APIException $e) {
  echo $e->getMessage();
}

{
  "data": [
    {
      "id": "<string>",
      "record_id": "<string>",
      "record_type": "voice",
      "chunk_index": 123,
      "chunk_total": 123,
      "text": "<string>",
      "score": 123,
      "region": "<string>",
      "user_id": "<string>",
      "organization_id": "<string>",
      "record_created_at": "2023-11-07T05:31:56Z",
      "ingested_at": "2023-11-07T05:31:56Z",
      "metadata": {}
    }
  ],
  "meta": {
    "collection_slug": "support-transcripts",
    "searched_sources": [
      "voice",
      "message"
    ],
    "retrieval_type": "vector",
    "top_k": 5,
    "total_results": 42,
    "total_pages": 3,
    "page_number": 1,
    "page_size": 20
  }
}

{
  "errors": [
    {
      "code": "10015",
      "title": "Bad Request",
      "detail": "The request failed because it was not well-formed.",
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/10015"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10009",
      "title": "Authentication failed",
      "detail": "The required authentication headers were either invalid or not included in the request.",
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/10009"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10005",
      "title": "Resource not found",
      "detail": "The requested resource or URL could not be found.",
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/10005"
      }
    }
  ]
}

{
  "errors": [
    {
      "code": "10027",
      "title": "Unprocessable Entity",
      "detail": "The server understood the syntax of the request but was unable to process the instructions.",
      "meta": {
        "url": "https://developers.telnyx.com/docs/overview/errors/10027"
      }
    }
  ]
}

AI Search

Concepts

Configuration

API

For AI Agents

Search collection documents

Authorizations

Path Parameters

Query Parameters

Response