OpenAPI Specification
openapi: 3.1.0
info:
contact:
email: support@telnyx.com
description: Telnyx provides global communications and connectivity APIs for developers — including SIP trunking, programmable voice, SMS, MMS, WhatsApp Business Messaging, Call Control, Fax, Wireless (IoT & eSIM), Phone Numbers (DID provisioning & porting), Emergency Services, and Network APIs for private interconnects and edge connectivity. Build, scale, and manage voice, messaging, and data networks with Telnyx's carrier-grade global infrastructure and API-first platform.
title: Telnyx Access Tokens Embeddings API
version: 2.0.0
x-endpoint-cost: light
servers:
- description: Version 2.0.0 of the Telnyx API
url: https://api.telnyx.com/v2
security:
- bearerAuth: []
tags:
- description: Embed documents and perform text searches
name: Embeddings
paths:
/ai/embeddings:
get:
description: Retrieve tasks for the user that are either `queued`, `processing`, `failed`, `success` or `partial_success` based on the query string. Defaults to `queued` and `processing`.
operationId: GetTasksByStatus
parameters:
- description: List of task statuses i.e. `status=queued&status=processing`
in: query
name: status
required: false
schema:
default:
- processing
- queued
description: List of task statuses i.e. `status=queued&status=processing`
items:
type: string
title: Status
type: array
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/BackgroundTasksQueryResponseData'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Get Tasks by Status
tags:
- Embeddings
x-latency-category: responsive
post:
description: "Perform embedding on a Telnyx Storage Bucket using the a embedding model.\nThe current supported file types are:\n- PDF\n- HTML\n- txt/unstructured text files\n- json\n- csv\n- audio / video (mp3, mp4, mpeg, mpga, m4a, wav, or webm ) - Max of 100mb file size.\n\nAny files not matching the above types will be attempted to be embedded as unstructured text.\n\nThis process can be slow, so it runs in the background and the user can check\nthe status of the task using the endpoint `/ai/embeddings/{task_id}`.\n\n **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.\n\nYou can also specify a custom `loader` param. Currently the only supported loader value is\n`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/)\nThis loader will split each article into paragraphs and save additional parameters relevant to Intercom docs, such as\n`article_url` and `heading`. These values will be returned by the `/v2/ai/embeddings/similarity-search` endpoint in the `loader_metadata` field."
operationId: PostEmbedding
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EmbeddingBucketRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/EmbeddingResponse'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Embed documents
tags:
- Embeddings
x-latency-category: responsive
/ai/embeddings/buckets:
get:
description: Get all embedding buckets for a user.
operationId: GetEmbeddingBuckets
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/UserEmbeddedBucketsData'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: List embedded buckets
tags:
- Embeddings
x-latency-category: responsive
/ai/embeddings/buckets/{bucket_name}:
delete:
description: Deletes an entire bucket's embeddings and disables the bucket for AI-use, returning it to normal storage pricing.
operationId: embedding_bucket_files_public_embedding_buckets__bucket_name__delete
parameters:
- in: path
name: bucket_name
required: true
schema:
title: Bucket Name
type: string
responses:
'200':
description: Bucket Embeddings Deleted Successfully
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/BucketNotFoundError'
description: Bucket Not Found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Disable AI for an Embedded Bucket
tags:
- Embeddings
x-latency-category: responsive
get:
description: Get all embedded files for a given user bucket, including their processing status.
operationId: GetBucketName
parameters:
- in: path
name: bucket_name
required: true
schema:
title: Bucket Name
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/EmbeddingsBucketFilesData'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Get file-level embedding statuses for a bucket
tags:
- Embeddings
x-latency-category: responsive
/ai/embeddings/similarity-search:
post:
description: "Perform a similarity search on a Telnyx Storage Bucket, returning the most similar `num_docs` document chunks to the query.\n\nCurrently the only available distance metric is cosine similarity which will return a `distance` between 0 and 1.\nThe lower the distance, the more similar the returned document chunks are to the query.\nA `certainty` will also be returned, which is a value between 0 and 1 where the higher the certainty, the more similar the document.\nYou can read more about Weaviate distance metrics here: [Weaviate Docs](https://weaviate.io/developers/weaviate/config-refs/distances)\n\nIf a bucket was embedded using a custom loader, such as `intercom`, the additional metadata will be returned in the \n`loader_metadata` field."
operationId: PostEmbeddingSimilaritySearch
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EmbeddingSimilaritySearchRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/EmbeddingSimilaritySearchResponse'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Search for documents
tags:
- Embeddings
x-latency-category: responsive
/ai/embeddings/url:
post:
description: Embed website content from a specified URL, including child pages up to 5 levels deep within the same domain. The process crawls and loads content from the main URL and its linked pages into a Telnyx Cloud Storage bucket. As soon as each webpage is added to the bucket, its content is immediately processed for embeddings, that can be used for [similarity search](https://developers.telnyx.com/api-reference/embeddings/search-for-documents) and [clustering](https://developers.telnyx.com/docs/inference/clusters).
operationId: PostEmbeddingUrl
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EmbeddingUrlRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/EmbeddingResponse'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Embed URL content
tags:
- Embeddings
x-latency-category: responsive
/ai/embeddings/{task_id}:
get:
description: 'Check the status of a current embedding task. Will be one of the following:
- `queued` - Task is waiting to be picked up by a worker
- `processing` - The embedding task is running
- `success` - Task completed successfully and the bucket is embedded
- `failure` - Task failed and no files were embedded successfully
- `partial_success` - Some files were embedded successfully, but at least one failed'
operationId: GetEmbeddingTask
parameters:
- in: path
name: task_id
required: true
schema:
title: Task Id
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TaskStatusResponse'
description: Successful Response
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
description: Validation Error
summary: Get an embedding task's status
tags:
- Embeddings
x-latency-category: responsive
components:
schemas:
SupportedEmbeddingModels:
description: Supported models to vectorize and embed documents.
enum:
- thenlper/gte-large
- intfloat/multilingual-e5-large
title: SupportedEmbeddingModels
type: string
BucketNotFoundError:
properties:
detail:
items:
$ref: '#/components/schemas/NotFoundError'
title: Detail
type: array
title: HTTPValidationError
type: object
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
title: Location
type: array
msg:
title: Message
type: string
type:
title: Error Type
type: string
required:
- loc
- msg
- type
title: ValidationError
type: object
EmbeddingMetadata:
properties:
certainty:
title: Certainty
type: number
checksum:
title: Checksum
type: string
embedding:
title: Embedding
type: string
filename:
title: Filename
type: string
loader_metadata:
additionalProperties: true
title: Loader Metadata
type: object
source:
title: Source
type: string
required:
- source
- checksum
- embedding
- filename
title: EmbeddingMetadata
type: object
BackgroundTaskStatus:
description: Status of an embeddings task.
enum:
- queued
- processing
- success
- failure
- partial_success
title: BackgroundTaskStatus
type: string
EmbeddingSimilaritySearchDocument:
description: "Example document response from embedding service\n{\n \"document_chunk\": \"your status? This is Vanessa Bloome...\",\n \"distance\": 0.18607724,\n \"metadata\": {\n \"source\": \"https://us-central-1.telnyxstorage.com/scripts/bee_movie_script.txt\",\n \"checksum\": \"343054dd19bab39bbf6761a3d20f1daa\",\n \"embedding\": \"openai/text-embedding-ada-002\",\n \"filename\": \"bee_movie_script.txt\",\n \"certainty\": 0.9069613814353943,\n \"loader_metadata\": {}\n }\n}"
properties:
distance:
title: Distance
type: number
document_chunk:
title: Document Chunk
type: string
metadata:
$ref: '#/components/schemas/EmbeddingMetadata'
required:
- document_chunk
- distance
- metadata
title: EmbeddingSimilaritySearchDocument
type: object
SupportedEmbeddingLoaders:
description: Supported types of custom document loaders for embeddings.
enum:
- default
- intercom
title: SupportedEmbeddingLoaders
type: string
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
title: Detail
type: array
title: HTTPValidationError
type: object
UserEmbeddedBucketsData:
properties:
data:
$ref: '#/components/schemas/UserEmbeddedBuckets'
required:
- data
title: UserEmbeddedBucketsData
type: object
TaskStatusResponse:
properties:
data:
properties:
created_at:
title: Created At
type: string
finished_at:
title: Finished At
type: string
status:
$ref: '#/components/schemas/BackgroundTaskStatus'
task_id:
format: uuid
title: Task ID
type: string
task_name:
title: Task Name
type: string
type: object
required:
- data
title: TaskStatusResponse
type: object
UserEmbeddedBuckets:
properties:
buckets:
items:
type: string
title: Buckets
type: array
required:
- buckets
title: UserEmbeddedBuckets
type: object
BackgroundTasksQueryResponseData:
properties:
data:
items:
$ref: '#/components/schemas/BackgroundTasksQueryResponse'
title: Data
type: array
required:
- data
title: BackgroundTasksQueryResponseData
type: object
BackgroundTasksQueryResponse:
properties:
bucket:
title: Bucket
type: string
created_at:
format: date-time
title: Created At
type: string
finished_at:
format: date-time
title: Finished At
type: string
status:
$ref: '#/components/schemas/BackgroundTaskStatus'
task_id:
title: Task Id
type: string
task_name:
title: Task Name
type: string
user_id:
title: User Id
type: string
required:
- user_id
- task_id
- task_name
- status
- created_at
title: BackgroundTasksQueryResponse
type: object
NotFoundError:
properties:
code:
title: Telnyx error code
type: string
detail:
title: Error details
type: string
title:
title: Error title
type: string
required:
- detail
title: NotFoundError
type: object
EmbeddingsBucketFiles:
properties:
created_at:
format: date-time
title: Created At
type: string
error_reason:
title: Error Reason
type: string
filename:
title: Filename
type: string
last_embedded_at:
format: date-time
title: Last Embedded At
type: string
status:
title: Status
type: string
updated_at:
format: date-time
title: Updated At
type: string
required:
- filename
- status
- created_at
title: EmbeddingsBucketFiles
type: object
EmbeddingUrlRequest:
properties:
bucket_name:
description: Name of the bucket to store the embeddings. This bucket must already exist.
title: Bucket Name
type: string
url:
description: The URL of the webpage to embed
title: URL
type: string
required:
- url
- bucket_name
title: EmbeddingUrlRequest
type: object
EmbeddingSimilaritySearchResponse:
properties:
data:
items:
$ref: '#/components/schemas/EmbeddingSimilaritySearchDocument'
title: Data
type: array
required:
- data
title: EmbeddingSimilaritySearchResponse
type: object
EmbeddingSimilaritySearchRequest:
properties:
bucket_name:
title: Bucket Name
type: string
num_of_docs:
default: 3
title: Num Of Docs
type: integer
query:
title: Query
type: string
required:
- bucket_name
- query
title: EmbeddingSimilaritySearchRequest
type: object
EmbeddingsBucketFilesData:
properties:
data:
items:
$ref: '#/components/schemas/EmbeddingsBucketFiles'
title: Data
type: array
required:
- data
title: EmbeddingsBucketFilesData
type: object
EmbeddingBucketRequest:
properties:
bucket_name:
title: Bucket Name
type: string
document_chunk_overlap_size:
default: 512
title: Document Chunk Overlap Size
type: integer
document_chunk_size:
default: 1024
title: Document Chunk Size
type: integer
embedding_model:
allOf:
- $ref: '#/components/schemas/SupportedEmbeddingModels'
default: thenlper/gte-large
loader:
allOf:
- $ref: '#/components/schemas/SupportedEmbeddingLoaders'
default: default
required:
- bucket_name
title: EmbeddingBucketRequest
type: object
EmbeddingResponse:
properties:
data:
properties:
created_at:
title: Created At
type: string
finished_at:
title: Finished At
type:
- string
- 'null'
status:
title: Status
type: string
task_id:
format: uuid
title: Task ID
type: string
task_name:
title: Task Name
type: string
user_id:
format: uuid
title: User ID
type: string
type: object
required:
- data
title: EmbeddingResponse
type: object
securitySchemes:
bearerAuth:
scheme: bearer
type: http
branded-calling_bearerAuth:
description: API key passed as a Bearer token in the Authorization header
scheme: bearer
type: http
oauthClientAuth:
description: OAuth 2.0 authentication for Telnyx API and MCP integrations
flows:
authorizationCode:
authorizationUrl: https://api.telnyx.com/v2/oauth/authorize
refreshUrl: https://api.telnyx.com/v2/oauth/token
scopes:
admin: Administrative access to Telnyx resources
tokenUrl: https://api.telnyx.com/v2/oauth/token
clientCredentials:
scopes:
admin: Administrative access to Telnyx resources
tokenUrl: https://api.telnyx.com/v2/oauth/token
type: oauth2
outbound-voice-profiles_bearerAuth:
bearerFormat: JWT
scheme: bearer
type: http
pronunciation-dicts_bearerAuth:
description: Telnyx API v2 key. Obtain from https://portal.telnyx.com
scheme: bearer
type: http
stored-payment-transactions_bearerAuth:
bearerFormat: JWT
scheme: bearer
type: http