Telnyx

Telnyx Clusters API

Identify common themes and patterns in your embedded documents

Documentation GitHub OpenAPI

Operations 5

GET /ai/clusters List all clusters #

POST /ai/clusters Compute new clusters #

DELETE /ai/clusters/{task_id} Delete a cluster #

GET /ai/clusters/{task_id} Fetch a cluster #

GET /ai/clusters/{task_id}/graph Fetch a cluster visualization #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/telnyx:telnyx-clusters-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: Telnyx Clusters API
  version: 2.0.0
  contact:
    email: support@telnyx.com
  x-endpoint-cost: light
  x-refined-note:
  - x-latency-category differs across the merged source definitions and was not carried
  description: 'Operations tagged Clusters across 3 of this provider''s published API definitions: telnyx-openapi.json, telnyx-openapi.yml, telnyx-openapi_2.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.telnyx.com/v2
  description: Version 2.0.0 of the Telnyx API
security:
- bearerAuth: []
tags:
- name: Clusters
  description: Identify common themes and patterns in your embedded documents
paths:
  /ai/clusters:
    get:
      tags:
      - Clusters
      summary: List all clusters
      operationId: list_all_requested_clusters_public_text_clusters_get
      parameters:
      - name: page
        in: query
        style: deepObject
        explode: true
        description: 'Consolidated page parameter (deepObject style). Originally: page[number], page[size]'
        schema:
          type: object
          properties:
            number:
              type: integer
              default: 0
              title: Page[Number]
            size:
              type: integer
              default: 20
              title: Page[Size]
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClusteringRequestInfoData'
              example:
                data:
                - task_id: string
                  status: completed
                  bucket: string
                  created_at: '2024-01-23T18:10:02.574Z'
                  finished_at: '2024-01-23T18:12:45.000Z'
                  min_cluster_size: 0
                  min_subcluster_size: 0
                meta:
                  total_pages: 0
                  total_results: 0
                  page_number: 0
                  page_size: 0
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: Retrieve a paginated list of clustering tasks and their statuses.
    post:
      tags:
      - Clusters
      summary: Compute new clusters
      description: Starts a background task to compute how the data in an embedded storage bucket is clustered. This helps identify common themes and patterns in the data.
      operationId: compute_new_cluster_public_text_clusters_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicTextClusteringRequest'
            example:
              bucket: string
              prefix: string
              files:
              - string
              min_cluster_size: 25
              min_subcluster_size: 5
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TextClusteringResponseData'
              example:
                data:
                  task_id: string
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    servers:
    - url: https://api.telnyx.com/v2
      description: Version 2.0.0 of the Telnyx API
  /ai/clusters/{task_id}:
    delete:
      tags:
      - Clusters
      summary: Delete a cluster
      operationId: delete_cluster_by_task_id_public_text_clusters__task_id__delete
      parameters:
      - name: task_id
        in: path
        description: Unique identifier of the task.
        required: true
        schema:
          type: string
          title: Task Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
              example:
                detail:
                - loc:
                  - string
                  msg: Message
                  type: Error Type
      description: Delete a clustering task and its computed results.
    get:
      tags:
      - Clusters
      summary: Fetch a cluster
      operationId: fetch_cluster_by_task_id_public_text_clusters__task_id__get
      parameters:
      - name: task_id
        in: path
        description: Unique identifier of the task.
        required: true
        schema:
          type: string
          title: Task Id
      - name: top_n_nodes
        in: query
        description: The number of nodes in the cluster to return in the response. Nodes will be sorted by their centrality within the cluster.
        required: false
        schema:
          type: integer
          default: 0
          title: Top N Nodes
      - name: show_subclusters
        in: query
        description: Whether or not to include subclusters and their nodes in the response.
        required: false
        schema:
          type: boolean
          default: false
          title: Show Subclusters
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClusteringStatusResponseData'
              example:
                data:
                  status: pending
                  bucket: string
                  clusters:
                  - cluster_id: string
                    cluster_header: string
                    cluster_summary: string
                    nodes:
                    - filename: string
                      text: string
                    total_number_of_nodes: 0
                    subclusters:
                    - cluster_id: string
                      cluster_header: string
                      cluster_summary: string
                      nodes:
                      - filename: string
                        text: string
                      total_number_of_nodes: 0
                      subclusters:
                      - cluster_id: string
                        cluster_header: string
                        cluster_summary: string
                        nodes:
                        - filename: string
                          text: string
                        total_number_of_nodes: 0
                        subclusters:
                        - cluster_id: string
                          cluster_header: string
                          cluster_summary: string
                          nodes:
                          - filename: string
                            text: string
                          total_number_of_nodes: 0
                          subclusters:
                          - cluster_id: string
                            cluster_header: string
                            cluster_summary: string
                            nodes: []
                            total_number_of_nodes: 0
                            subclusters: []
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: Fetch the results of a clustering task, including the discovered clusters.
    servers:
    - url: https://api.telnyx.com/v2
      description: Version 2.0.0 of the Telnyx API
  /ai/clusters/{task_id}/graph:
    get:
      tags:
      - Clusters
      summary: Fetch a cluster visualization
      operationId: GetClusterImage
      parameters:
      - name: task_id
        in: path
        description: Unique identifier of the task.
        required: true
        schema:
          type: string
          title: Task Id
      - name: cluster_id
        in: query
        description: Filter results by cluster id.
        required: false
        schema:
          type: integer
          title: Cluster Id
      responses:
        '200':
          description: Successful Response - Returns a PNG image of the cluster visualization.
          content:
            image/png:
              schema:
                type: string
                format: binary
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      description: Fetch a visualization image of the clusters computed by a clustering task.
    servers:
    - url: https://api.telnyx.com/v2
      description: Version 2.0.0 of the Telnyx API
components:
  schemas:
    ClusterNode:
      properties:
        filename:
          type: string
          description: The corresponding source file of your embedded storage bucket that the node is from.
        text:
          type: string
          description: The text of the node.
      type: object
      required:
      - filename
      - text
      title: ClusterNode
    RecursiveCluster:
      properties:
        cluster_id:
          type: string
        cluster_header:
          type: string
        cluster_summary:
          type: string
        nodes:
          items:
            $ref: '#/components/schemas/ClusterNode'
          type: array
        total_number_of_nodes:
          type: integer
        subclusters:
          items:
            type: object
            title: RecursiveCluster
            description: 'Recursive reference to RecursiveCluster. Nesting is elided here so every $ref chain stays finite for function-calling tooling; see #/components/schemas/RecursiveCluster for the full structure.'
            additionalProperties: true
          type: array
      type: object
      required:
      - cluster_id
      - cluster_summary
      - total_number_of_nodes
      title: RecursiveCluster
    ClusteringStatusResponse:
      properties:
        status:
          $ref: '#/components/schemas/TaskStatus'
        bucket:
          type: string
        clusters:
          items:
            $ref: '#/components/schemas/RecursiveCluster'
          type: array
      type: object
      required:
      - status
      - bucket
      - clusters
      title: ClusteringStatusResponse
    TextClusteringResponseData:
      properties:
        data:
          $ref: '#/components/schemas/TextClusteringResponse'
      type: object
      required:
      - data
      title: TextClusteringResponseData
    ValidationError:
      title: ValidationError
      required:
      - loc
      - msg
      - type
      type: object
      properties:
        loc:
          title: Location
          type: array
          items:
            anyOf:
            - type: string
            - type: integer
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
    ClusteringStatusResponseData:
      properties:
        data:
          $ref: '#/components/schemas/ClusteringStatusResponse'
      type: object
      required:
      - data
      title: ClusteringStatusResponseData
    PublicTextClusteringRequest:
      properties:
        bucket:
          type: string
          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).
        prefix:
          type: string
          description: Prefix to filter whcih files in the buckets are included.
        files:
          items:
            type: string
          type: array
          description: Array of files to filter which are included.
        min_cluster_size:
          type: integer
          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.
          default: 25
        min_subcluster_size:
          type: integer
          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.
          default: 5
      type: object
      required:
      - bucket
      title: PublicTextClusteringRequest
    TaskStatus:
      type: string
      enum:
      - pending
      - starting
      - running
      - completed
      - failed
      title: TaskStatus
    ClusteringRequestInfoData:
      properties:
        data:
          items:
            $ref: '#/components/schemas/ClusteringRequestInfo'
          type: array
        meta:
          $ref: '#/components/schemas/Meta'
      type: object
      required:
      - data
      - meta
      title: ClusteringRequestInfoData
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
      example:
        detail:
        - loc:
          - body
          - name
          msg: Field required
          type: missing
    ClusteringRequestInfo:
      properties:
        task_id:
          type: string
        status:
          $ref: '#/components/schemas/TaskStatus'
        bucket:
          type: string
        created_at:
          type: string
          format: date-time
        finished_at:
          type: string
          format: date-time
        min_cluster_size:
          type: integer
        min_subcluster_size:
          type: integer
      type: object
      required:
      - task_id
      - status
      - bucket
      - created_at
      - finished_at
      - min_cluster_size
      - min_subcluster_size
      title: ClusteringRequestInfo
    Meta:
      properties:
        total_pages:
          type: integer
        total_results:
          type: integer
        page_number:
          type: integer
        page_size:
          type: integer
      type: object
      required:
      - total_pages
      - total_results
      - page_number
      - page_size
      title: Meta
    TextClusteringResponse:
      properties:
        task_id:
          type: string
      type: object
      required:
      - task_id
      title: TextClusteringResponse
    RecursiveCluster_2:
      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_2'
          type: array
        total_number_of_nodes:
          type: integer
      required:
      - cluster_id
      - cluster_summary
      - total_number_of_nodes
      title: RecursiveCluster
      type: object
    HTTPValidationError_2:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: 'Telnyx API key supplied as `Authorization: Bearer <token>`. In production, auth may be validated by the API gateway and forwarded via Telnyx auth headers.'
    Payment:
      type: apiKey
      in: header
      name: Authorization
      description: 'Machine Payment Protocol credential used on paid retries, sent as `Authorization: Payment ...`. Obtained by paying a challenge returned in the `WWW-Authenticate` header of a 402 response. This is not a Telnyx API key; initial challenge requests use standard bearer authentication instead.'
    agent-memory_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key
    bearerAuth:
      type: http
      scheme: bearer
    branded-calling_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys.
    collections_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Collections and results are automatically scoped to the authenticated user's organization.
    number-reputation_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Generate one at https://portal.telnyx.com/#/app/api-keys.
    oauthClientAuth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
        authorizationCode:
          authorizationUrl: https://api.telnyx.com/v2/oauth/authorize
          tokenUrl: https://api.telnyx.com/v2/oauth/token
          refreshUrl: https://api.telnyx.com/v2/oauth/token
          scopes:
            admin: Administrative access to Telnyx resources
      description: OAuth 2.0 authentication for Telnyx API and MCP integrations
    outbound-voice-profiles_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    pronunciation-dicts_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API v2 key. Obtain from https://portal.telnyx.com
    rcs-registration_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
    stored-payment-transactions_bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    transcriptions-search_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key. Results are automatically scoped to the authenticated user's organization.
    web-search_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key
    pay-connectors_bearerAuth:
      type: http
      scheme: bearer
      description: Telnyx API key, not the processor bearer token.
    telnyxApiKey:
      type: http
      scheme: bearer
      description: Management-only Telnyx account credential.
x-refined-from:
- telnyx-openapi.json
- telnyx-openapi.yml
- telnyx-openapi_2.json
x-service-info:
  categories:
  - communication
  - developer-tools
  docs:
    apiReference: https://developers.telnyx.com
    homepage: https://telnyx.com
    llms: https://telnyx.com/llms.txt