Telnyx Virtual Cross Connects API
Virtual Cross Connect operations
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 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