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