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 Clusters 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: Identify common themes and patterns in your embedded documents
  name: Clusters
paths:
  /ai/clusters:
    get:
      operationId: list_all_requested_clusters_public_text_clusters_get
      parameters:
      - description: 'Consolidated page parameter (deepObject style). Originally: page[number], page[size]'
        explode: true
        in: query
        name: page
        schema:
          properties:
            number:
              default: 0
              title: Page[Number]
              type: integer
            size:
              default: 20
              title: Page[Size]
              type: integer
          type: object
        style: deepObject
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClusteringRequestInfoData'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: List all clusters
      tags:
      - Clusters
      x-latency-category: responsive
    post:
      description: Starts a background task to compute how the data in an [embedded storage bucket](https://developers.telnyx.com/api-reference/embeddings/embed-documents) is clustered. This helps identify common themes and patterns in the data.
      operationId: compute_new_cluster_public_text_clusters_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicTextClusteringRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TextClusteringResponseData'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Compute new clusters
      tags:
      - Clusters
      x-latency-category: responsive
  /ai/clusters/{task_id}:
    delete:
      operationId: delete_cluster_by_task_id_public_text_clusters__task_id__delete
      parameters:
      - in: path
        name: task_id
        required: true
        schema:
          title: Task Id
          type: string
      responses:
        '204':
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Delete a cluster
      tags:
      - Clusters
      x-latency-category: responsive
    get:
      operationId: fetch_cluster_by_task_id_public_text_clusters__task_id__get
      parameters:
      - in: path
        name: task_id
        required: true
        schema:
          title: Task Id
          type: string
      - description: The number of nodes in the cluster to return in the response. Nodes will be sorted by their centrality within the cluster.
        in: query
        name: top_n_nodes
        required: false
        schema:
          default: 0
          title: Top N Nodes
          type: integer
      - description: Whether or not to include subclusters and their nodes in the response.
        in: query
        name: show_subclusters
        required: false
        schema:
          default: false
          title: Show Subclusters
          type: boolean
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClusteringStatusResponseData'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Fetch a cluster
      tags:
      - Clusters
      x-latency-category: responsive
  /ai/clusters/{task_id}/graph:
    get:
      operationId: fetch_cluster_image_by_task_id_public_text_clusters__task_id__image_get
      parameters:
      - in: path
        name: task_id
        required: true
        schema:
          title: Task Id
          type: string
      - in: query
        name: cluster_id
        required: false
        schema:
          title: Cluster Id
          type: integer
      responses:
        '200':
          content:
            image/png:
              schema:
                format: binary
                type: string
          description: Successful Response - Returns a PNG image of the cluster visualization.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      summary: Fetch a cluster visualization
      tags:
      - Clusters
      x-latency-category: responsive
components:
  schemas:
    TaskStatus:
      enum:
      - pending
      - starting
      - running
      - completed
      - failed
      title: TaskStatus
      type: string
    ClusterNode:
      properties:
        filename:
          description: The corresponding source file of your embedded storage bucket that the node is from.
          type: string
        text:
          description: The text of the node.
          type: string
      required:
      - filename
      - text
      title: ClusterNode
      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
    ClusteringStatusResponseData:
      properties:
        data:
          $ref: '#/components/schemas/ClusteringStatusResponse'
      required:
      - data
      title: ClusteringStatusResponseData
      type: object
    RecursiveCluster:
      properties:
        cluster_header:
          type: string
        cluster_id:
          type: string
        cluster_summary:
          type: string
        nodes:
          items:
            $ref: '#/components/schemas/ClusterNode'
          type: array
        subclusters:
          items:
            $ref: '#/components/schemas/RecursiveCluster'
          type: array
        total_number_of_nodes:
          type: integer
      required:
      - cluster_id
      - cluster_summary
      - total_number_of_nodes
      title: RecursiveCluster
      type: object
    ClusteringRequestInfo:
      properties:
        bucket:
          type: string
        created_at:
          format: date-time
          type: string
        finished_at:
          format: date-time
          type: string
        min_cluster_size:
          type: integer
        min_subcluster_size:
          type: integer
        status:
          $ref: '#/components/schemas/TaskStatus'
        task_id:
          type: string
      required:
      - task_id
      - status
      - bucket
      - created_at
      - finished_at
      - min_cluster_size
      - min_subcluster_size
      title: ClusteringRequestInfo
      type: object
    Meta:
      properties:
        page_number:
          type: integer
        page_size:
          type: integer
        total_pages:
          type: integer
        total_results:
          type: integer
      required:
      - total_pages
      - total_results
      - page_number
      - page_size
      title: Meta
      type: object
    TextClusteringResponse:
      properties:
        task_id:
          type: string
      required:
      - task_id
      title: TextClusteringResponse
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    TextClusteringResponseData:
      properties:
        data:
          $ref: '#/components/schemas/TextClusteringResponse'
      required:
      - data
      title: TextClusteringResponseData
      type: object
    ClusteringStatusResponse:
      properties:
        bucket:
          type: string
        clusters:
          items:
            $ref: '#/components/schemas/RecursiveCluster'
          type: array
        status:
          $ref: '#/components/schemas/TaskStatus'
      required:
      - status
      - bucket
      - clusters
      title: ClusteringStatusResponse
      type: object
    PublicTextClusteringRequest:
      properties:
        bucket:
          description: The embedded storage bucket to compute the clusters from. The bucket must already be [embedded](https://developers.telnyx.com/api-reference/embeddings/embed-documents).
          type: string
        files:
          description: Array of files to filter which are included.
          items:
            type: string
          type: array
        min_cluster_size:
          default: 25
          description: Smallest number of related text chunks to qualify as a cluster. Top-level clusters should be thought of as identifying broad themes in your data.
          type: integer
        min_subcluster_size:
          default: 5
          description: Smallest number of related text chunks to qualify as a sub-cluster. Sub-clusters should be thought of as identifying more specific topics within a broader theme.
          type: integer
        prefix:
          description: Prefix to filter whcih files in the buckets are included.
          type: string
      required:
      - bucket
      title: PublicTextClusteringRequest
      type: object
    ClusteringRequestInfoData:
      properties:
        data:
          items:
            $ref: '#/components/schemas/ClusteringRequestInfo'
          type: array
        meta:
          $ref: '#/components/schemas/Meta'
      required:
      - data
      - meta
      title: ClusteringRequestInfoData
      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