Search for documents

POST

/ai/embeddings/similarity-search

Perform a similarity search on a Telnyx Storage Bucket, returning the most similar num_docs document chunks to the query.

Currently the only available distance metric is cosine similarity which will return a distance between 0 and 1.
The lower the distance, the more similar the returned document chunks are to the query.
A certainty will also be returned, which is a value between 0 and 1 where the higher the certainty, the more similar the document.
You can read more about Weaviate distance metrics here: Weaviate Docs

If a bucket was embedded using a custom loader, such as intercom, the additional metadata will be returned in the
loader_metadata field.

Request

Authorization

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Body Params application/json

Examples

Responses

🟢200OK

application/json

Successful Response

Body

🟠422Parameter Error

Request Example

Shell

JavaScript

Java

Swift

curl --location --request POST '/ai/embeddings/similarity-search' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "bucket_name": "string",
    "num_of_docs": 3,
    "query": "string"
}'

Response Example

200 - Example 1

{
    "data": [
        {
            "distance": 0,
            "document_chunk": "string",
            "metadata": {
                "certainty": 0,
                "checksum": "string",
                "embedding": "string",
                "filename": "string",
                "loader_metadata": {},
                "source": "string"
            }
        }
    ]
}

Modified at 2025-06-16 19:14:41

Get file-level embedding statuses for a bucket

Embed URL content