---
title: "Search for documents"
method: POST
path: "/ai/embeddings/similarity-search"
tags: ["Embeddings"]
---

# 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](https://weaviate.io/developers/weaviate/config-refs/distances)

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

## Request body

- EmbeddingSimilaritySearchRequest
  - `bucket_name` string, required
  - `query` string, required
  - `num_of_docs` integer

## Response `200`

Successful Response

- EmbeddingSimilaritySearchResponse
  - `data` EmbeddingSimilaritySearchDocument[], required
    - `document_chunk` string, required
    - `distance` number, required
    - `metadata` EmbeddingMetadata, required
      - `source` string, required
      - `checksum` string, required
      - `embedding` string, required
      - `filename` string, required
      - `certainty` number
      - `loader_metadata` object

## Other responses

- `422` — Validation Error

---

[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/versions/8f5f4e537994/schema)