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 Virtual Cross Connects 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: Virtual Cross Connect operations
  name: Virtual Cross Connects
paths:
  /virtual_cross_connects:
    get:
      description: List all Virtual Cross Connects.
      operationId: ListVirtualCrossConnects
      parameters:
      - description: 'Consolidated filter parameter (deepObject style). Originally: filter[network_id]'
        explode: true
        in: query
        name: filter
        schema:
          properties:
            network_id:
              description: The associated network id to filter on.
              example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58
              type: string
          type: object
        style: deepObject
      - $ref: '#/components/parameters/PageConsolidated'
      responses:
        '200':
          $ref: '#/components/responses/VirtualCrossConnectListResponse'
        '422':
          $ref: '#/components/responses/netapps_GenericErrorResponse'
        default:
          $ref: '#/components/responses/netapps_GenericErrorResponse'
      summary: List all Virtual Cross Connects
      tags:
      - Virtual Cross Connects
      x-latency-category: responsive
    post:
      description: Create a new Virtual Cross Connect.<br /><br />For AWS and GCE, you have the option of creating the primary connection first and the secondary connection later. You also have the option of disabling the primary and/or secondary connections at any time and later re-enabling them. With Azure, you do not have this option. Azure requires both the primary and secondary connections to be created at the same time and they can not be independantly disabled.
      operationId: CreateVirtualCrossConnect
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VirtualCrossConnectCreate'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/VirtualCrossConnectResponse'
        '422':
          $ref: '#/components/responses/netapps_UnprocessableEntity'
        default:
          $ref: '#/components/responses/netapps_GenericErrorResponse'
      summary: Create a Virtual Cross Connect
      tags:
      - Virtual Cross Connects
      x-latency-category: responsive
  /virtual_cross_connects/{id}:
    delete:
      description: Delete a Virtual Cross Connect.
      operationId: DeleteVirtualCrossConnect
      parameters:
      - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          $ref: '#/components/responses/VirtualCrossConnectResponse'
        '422':
          $ref: '#/components/responses/netapps_GenericErrorResponse'
        default:
          $ref: '#/components/responses/netapps_GenericErrorResponse'
      summary: Delete a Virtual Cross Connect
      tags:
      - Virtual Cross Connects
      x-latency-category: responsive
    get:
      description: Retrieve a Virtual Cross Connect.
      operationId: GetVirtualCrossConnect
      parameters:
      - $ref: '#/components/parameters/ResourceId'
      responses:
        '200':
          $ref: '#/components/responses/VirtualCrossConnectResponse'
        '422':
          $ref: '#/components/responses/netapps_GenericErrorResponse'
        default:
          $ref: '#/components/responses/netapps_GenericErrorResponse'
      summary: Retrieve a Virtual Cross Connect
      tags:
      - Virtual Cross Connects
      x-latency-category: responsive
    patch:
      description: Update the Virtual Cross Connect.<br /><br />Cloud IPs can only be patched during the `created` state, as GCE will only inform you of your generated IP once the pending connection requested has been accepted. Once the Virtual Cross Connect has moved to `provisioning`, the IPs can no longer be patched.<br /><br />Once the Virtual Cross Connect has moved to `provisioned` and you are ready to enable routing, you can toggle the routing announcements to `true`.
      operationId: UpdateVirtualCrossConnect
      parameters:
      - $ref: '#/components/parameters/ResourceId'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VirtualCrossConnectPatch'
        required: true
      responses:
        '200':
          $ref: '#/components/responses/VirtualCrossConnectResponse'
        '422':
          $ref: '#/components/responses/netapps_UnprocessableEntity'
        default:
          $ref: '#/components/responses/netapps_GenericErrorResponse'
      summary: Update the Virtual Cross Connect
      tags:
      - Virtual Cross Connects
      x-latency-category: responsive
  /virtual_cross_connects_coverage:
    get:
      description: List Virtual Cross Connects Cloud Coverage.<br /><br />This endpoint shows which cloud regions are available for the `location_code` your Virtual Cross Connect will be provisioned in.
      operationId: ListVirtualCrossConnectCoverage
      parameters:
      - description: 'Consolidated filters parameter (deepObject style). Originally: filters[available_bandwidth][contains]'
        explode: true
        in: query
        name: filters
        schema:
          additionalProperties: false
          properties:
            available_bandwidth:
              oneOf:
              - description: Filter by exact available bandwidth match
                type: integer
              - additionalProperties: false
                description: Available bandwidth filtering operations
                properties:
                  contains:
                    description: Filter by available bandwidth containing the specified value
                    type: integer
                type: object
          type: object
        style: deepObject
      - description: 'Consolidated filter parameter (deepObject style). Originally: filter[cloud_provider], filter[cloud_provider_region], filter[location.region], filter[location.site], filter[location.pop], filter[location.code]'
        explode: true
        in: query
        name: filter
        schema:
          properties:
            cloud_provider:
              description: The Virtual Private Cloud provider.
              enum:
              - aws
              - azure
              - gce
              example: aws
              type: string
            cloud_provider_region:
              description: The region of specific cloud provider.
              example: us-east-1
              type: string
            location.code:
              description: The code of associated location to filter on.
              example: silicon_valley-ca
              type: string
            location.pop:
              description: The POP of associated location to filter on.
              example: SV1
              type: string
            location.region:
              description: The region of associated location to filter on.
              example: AMER
              type: string
            location.site:
              description: The site of associated location to filter on.
              example: SJC
              type: string
          type: object
        style: deepObject
      - $ref: '#/components/parameters/PageConsolidated'
      responses:
        '200':
          $ref: '#/components/responses/VirtualCrossConnectCoverageListResponse'
        '422':
          $ref: '#/components/responses/netapps_GenericErrorResponse'
        default:
          $ref: '#/components/responses/netapps_GenericErrorResponse'
      summary: List Virtual Cross Connect Cloud Coverage
      tags:
      - Virtual Cross Connects
      x-latency-category: responsive
components:
  schemas:
    netapps_Errors:
      properties:
        errors:
          items:
            $ref: '#/components/schemas/netapps_Error'
          type: array
      type: object
    VirtualCrossConnectPatch:
      allOf:
      - properties:
          primary_cloud_ip:
            description: The IP address assigned for your side of the Virtual Cross Connect.<br /><br />If none is provided, one will be generated for you.<br /><br />This value can not be patched once the VXC has bene provisioned.
            example: 169.254.0.2
            type: string
          primary_enabled:
            description: Indicates whether the primary circuit is enabled. Setting this to `false` will disable the circuit.
            example: true
            type: boolean
          primary_routing_announcement:
            description: Whether the primary BGP route is being announced.
            example: false
            type: boolean
          secondary_cloud_ip:
            description: The IP address assigned for your side of the Virtual Cross Connect.<br /><br />If none is provided, one will be generated for you.<br /><br />This value can not be patched once the VXC has bene provisioned.
            example: 169.254.0.4
            type: string
          secondary_enabled:
            description: Indicates whether the secondary circuit is enabled. Setting this to `false` will disable the circuit.
            example: true
            type: boolean
          secondary_routing_announcement:
            description: Whether the secondary BGP route is being announced.
            example: false
            type: boolean
        title: VirtualCrossConnectPatch
        type: object
    VirtualCrossConnectCombined:
      allOf:
      - $ref: '#/components/schemas/VirtualCrossConnectCreate'
      - $ref: '#/components/schemas/VirtualCrossConnectPatch'
      - $ref: '#/components/schemas/RegionOut'
    VirtualCrossConnect:
      allOf:
      - $ref: '#/components/schemas/Record'
      - $ref: '#/components/schemas/Interface'
      - properties:
          bandwidth_mbps:
            description: The desired throughput in Megabits per Second (Mbps) for your Virtual Cross Connect.<br /><br />The available bandwidths can be found using the /virtual_cross_connect_regions endpoint.
            example: 50
            type: number
          bgp_asn:
            description: The Border Gateway Protocol (BGP) Autonomous System Number (ASN). If null, value will be assigned by Telnyx.
            example: 1234
            type: number
          cloud_provider:
            description: The Virtual Private Cloud with which you would like to establish a cross connect.
            enum:
            - aws
            - azure
            - gce
            example: aws
            type: string
          cloud_provider_region:
            description: The region where your Virtual Private Cloud hosts are located.<br /><br />The available regions can be found using the /virtual_cross_connect_regions endpoint.
            example: us-east-1
            type: string
          primary_bgp_key:
            description: The authentication key for BGP peer configuration.
            example: yFV4wEPtPVPfDUGLWiyQzwga
            type: string
          primary_cloud_account_id:
            description: The identifier for your Virtual Private Cloud. The number will be different based upon your Cloud provider.
            example: '123456789012'
            type: string
          primary_cloud_ip:
            description: The IP address assigned for your side of the Virtual Cross Connect.<br /><br />If none is provided, one will be generated for you.<br /><br />This value should be null for GCE as Google will only inform you of your assigned IP once the connection has been accepted.
            example: 169.254.0.2
            type: string
          primary_enabled:
            description: Indicates whether the primary circuit is enabled. Setting this to `false` will disable the circuit.
            example: true
            readOnly: true
            type: boolean
          primary_telnyx_ip:
            description: The IP address assigned to the Telnyx side of the Virtual Cross Connect.<br /><br />If none is provided, one will be generated for you.<br /><br />This value should be null for GCE as Google will only inform you of your assigned IP once the connection has been accepted.
            example: 169.254.0.1
            type: string
          record_type:
            description: Identifies the type of the resource.
            example: virtual_cross_connect
            readOnly: true
            type: string
          secondary_bgp_key:
            description: The authentication key for BGP peer configuration.
            example: ge1lONeK9RcA83uuWaw9DvZy
            type: string
          secondary_cloud_account_id:
            description: The identifier for your Virtual Private Cloud. The number will be different based upon your Cloud provider.<br /><br />This attribute is only necessary for GCE.
            example: ''
            type: string
          secondary_cloud_ip:
            description: The IP address assigned for your side of the Virtual Cross Connect.<br /><br />If none is provided, one will be generated for you.<br /><br />This value should be null for GCE as Google will only inform you of your assigned IP once the connection has been accepted.
            example: 169.254.0.4
            type: string
          secondary_enabled:
            description: Indicates whether the secondary circuit is enabled. Setting this to `false` will disable the circuit.
            example: true
            readOnly: true
            type: boolean
          secondary_telnyx_ip:
            description: The IP address assigned to the Telnyx side of the Virtual Cross Connect.<br /><br />If none is provided, one will be generated for you.<br /><br />This value should be null for GCE as Google will only inform you of your assigned IP once the connection has been accepted.
            example: 169.254.0.3
            type: string
        title: VirtualCrossConnect
        type: object
    RegionOut:
      properties:
        region:
          properties:
            code:
              description: Region code of the interface.
              example: ashburn-va
              type: string
            name:
              description: Region name of the interface.
              example: Ashburn
              type: string
            record_type:
              description: Identifies the type of the resource.
              example: region
              readOnly: true
              type: string
          type: object
        region_code:
          description: The region interface is deployed to.
          example: ashburn-va
          type: string
      type: object
    InterfaceStatus:
      description: The current status of the interface deployment.
      enum:
      - created
      - provisioning
      - provisioned
      - deleting
      example: provisioned
      readOnly: true
      type: string
    VirtualCrossConnectCoverage:
      allOf:
      - properties:
          available_bandwidth:
            description: The available throughput in Megabits per Second (Mbps) for your Virtual Cross Connect.
            example:
            - 50
            - 100
            - 200
            - 500
            items:
              type: number
            type: array
          cloud_provider:
            description: The Virtual Private Cloud with which you would like to establish a cross connect.
            enum:
            - aws
            - azure
            - gce
            example: aws
            type: string
          cloud_provider_region:
            description: The region where your Virtual Private Cloud hosts are located. Should be identical to how the cloud provider names region, i.e. us-east-1 for AWS but Frankfurt for Azure
            example: us-east-1
            type: string
          location:
            $ref: '#/components/schemas/netapps_Location'
          record_type:
            description: Identifies the type of the resource.
            example: virtual_cross_connects_coverage
            readOnly: true
            type: string
        title: VirtualCrossConnectCoverage
        type: object
    Record:
      properties:
        created_at:
          description: ISO 8601 formatted date-time indicating when the resource was created.
          example: '2018-02-02T22:25:27.521Z'
          readOnly: true
          type: string
        id:
          description: Identifies the resource.
          example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58
          format: uuid
          readOnly: true
          type: string
        record_type:
          description: Identifies the type of the resource.
          example: sample_record_type
          readOnly: true
          type: string
        updated_at:
          description: ISO 8601 formatted date-time indicating when the resource was updated.
          example: '2018-02-02T22:25:27.521Z'
          readOnly: true
          type: string
      type: object
    netapps_Error:
      properties:
        code:
          type: string
        detail:
          type: string
        meta:
          additionalProperties: true
          type: object
        source:
          properties:
            parameter:
              description: Indicates which query parameter caused the error.
              type: string
            pointer:
              description: JSON pointer (RFC6901) to the offending entity.
              type: string
          type: object
        title:
          type: string
      required:
      - code
      - title
      type: object
    PaginationMeta:
      properties:
        page_number:
          example: 2
          type: integer
        page_size:
          example: 25
          type: integer
        total_pages:
          example: 3
          type: integer
        total_results:
          example: 55
          type: integer
      type: object
    netapps_Location:
      properties:
        code:
          description: Location code.
          example: chicago-il
          type: string
        name:
          description: Human readable name of location.
          example: Chicago IL, US
          type: string
        pop:
          description: Point of presence of location.
          example: CH1
          type: string
        region:
          description: Identifies the geographical region of location.
          example: AMER
          type: string
        site:
          description: Site of location.
          example: ORD
          type: string
      title: Location
      type: object
    VirtualCrossConnectCreate:
      allOf:
      - $ref: '#/components/schemas/VirtualCrossConnect'
      - $ref: '#/components/schemas/RegionIn'
      - required:
        - network_id
        - region_code
        - cloud_provider
        - cloud_provider_region
        - bgp_asn
        - primary_cloud_account_id
        title: VirtualCrossConnectCreate
        type: object
    RegionIn:
      properties:
        region_code:
          description: The region the interface should be deployed to.
          example: ashburn-va
          type: string
      type: object
    Interface:
      properties:
        name:
          description: A user specified name for the interface.
          example: test interface
          type: string
        network_id:
          description: The id of the network associated with the interface.
          example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58
          format: uuid
          type: string
        status:
          $ref: '#/components/schemas/InterfaceStatus'
      type: object
  parameters:
    PageConsolidated:
      description: 'Consolidated page parameter (deepObject style). Originally: page[number], page[size]'
      explode: true
      in: query
      name: page
      schema:
        properties:
          number:
            default: 1
            description: The page number to load
            minimum: 1
            type: integer
          size:
            default: 20
            description: The size of the page
            maximum: 250
            minimum: 1
            type: integer
        type: object
      style: deepObject
    ResourceId:
      description: Identifies the resource.
      in: path
      name: id
      required: true
      schema:
        example: 6a09cdc3-8948-47f0-aa62-74ac943d6c58
        format: uuid
        type: string
  responses:
    VirtualCrossConnectCoverageListResponse:
      content:
        application/json:
          schema:
            properties:
              data:
                items:
                  $ref: '#/components/schemas/VirtualCrossConnectCoverage'
                type: array
              meta:
                $ref: '#/components/schemas/PaginationMeta'
            type: object
      description: Successful response
    VirtualCrossConnectListResponse:
      content:
        application/json:
          schema:
            properties:
              data:
                items:
                  $ref: '#/components/schemas/VirtualCrossConnectCombined'
                type: array
              meta:
                $ref: '#/components/schemas/PaginationMeta'
            type: object
      description: Successful response
    netapps_GenericErrorResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/netapps_Errors'
      description: Unexpected error
    VirtualCrossConnectResponse:
      content:
        application/json:
          schema:
            properties:
              data:
                $ref: '#/components/schemas/VirtualCrossConnectCombined'
            type: object
      description: Successful response
    netapps_UnprocessableEntity:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/netapps_Errors'
      description: Unprocessable entity. Check the 'detail' field in response for details.
  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