---
title: "Embed documents"
method: POST
path: "/ai/embeddings"
tags: ["Embeddings"]
---

# Embed documents

`POST /ai/embeddings`

Perform embedding on a Telnyx Storage Bucket using the a embedding model.
The current supported file types are:
- PDF
- HTML
- txt/unstructured text files
- json
- csv
- audio / video (mp3, mp4, mpeg, mpga, m4a, wav, or webm ) - Max of 100mb file size.

Any files not matching the above types will be attempted to be embedded as unstructured text.

This process can be slow, so it runs in the background and the user can check
the status of the task using the endpoint `/ai/embeddings/{task_id}`.

 **Important Note**: When you update documents in a Telnyx Storage bucket, their associated embeddings are automatically kept up to date. If you add or update a file, it is automatically embedded. If you delete a file, the embeddings are deleted for that particular file.

You can also specify a custom `loader` param. Currently the only supported loader value is
`intercom` which loads Intercom article jsons as specified by [the Intercom article API](https://developers.intercom.com/docs/references/rest-api/api.intercom.io/Articles/article/)
This loader will split each article into paragraphs and save additional parameters relevant to Intercom docs, such as
`article_url` and `heading`. These values will be returned by the `/v2/ai/embeddings/similarity-search` endpoint in the `loader_metadata` field.

## Headers

- `Idempotency-Key` string

## Request body

- EmbeddingBucketRequest
  - `bucket_name` string, required
  - `document_chunk_size` integer
  - `document_chunk_overlap_size` integer
  - `embedding_model` 'thenlper/gte-large' | 'intfloat/multilingual-e5-large' — Supported models to vectorize and embed documents.
  - `loader` 'default' | 'intercom' — Supported types of custom document loaders for embeddings.

## Response `200`

Successful Response

- EmbeddingResponse
  - `data` object, required
    - `task_id` string, uuid
    - `task_name` string
    - `status` string
    - `created_at` string
    - `finished_at` string, nullable
    - `user_id` string, uuid

## Other responses

- `400` — Bad Request / Validation Failed (10015). Invalid, duplicate, empty, malformed, or overlong Idempotency-Key headers are rejected by Edge with HTTP 400 and error code 10015.
- `409` — A request with the same Idempotency-Key is still being processed (10036). Retry later with the same key and request.
- `413` — Payload Too Large. A request sent with an Idempotency-Key whose body exceeds the endpoint's Edge replay-protection limit (256 KB) is rejected before it reaches the service. Requests sent without the header are not subject to this limit.
- `422` — Validation Error. Reusing an Idempotency-Key with a different request body also returns 422 with error code 10027.
- `503` — Service unavailable (10016), including unavailable Edge idempotency protection for a keyed request.

## Changes

> 72 revisions in range; 1 not diffed.

- **2026-09-16** `a6a61a29ecdd` — 1 breaking, 1 warning, 6 info
  - the response's body type changed from `object` to no type for status `422`
  - removed the optional property `detail` from the response with the `422` status
  - added the new optional `header` request parameter `Idempotency-Key`
  - added `#/components/schemas/HTTPValidationError, #/components/schemas/inference-embedding_ErrorResponse` to the response body `anyOf` list for the response status `422`
  - …4 more

[Change history](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/changes/ai/embeddings/post.md)

---

[API](https://skmtc.dev/team-telnyx/apis/telnyx-api-2.md) · [All operations](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/llms.txt) · [OpenAPI document](https://skmtc.dev/team-telnyx/apis/telnyx-api-2/revisions/e0de72cf4744?raw)