Megaport API Documentation

Megaport offers a public API for access to all the services available through the Megaport Portal. You can use this API to automate your Megaport provisioning to save time and effort. The Megaport API is based on REST. The API has predictable URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes. In addition to this reference, you can find API tutorials in the [Megaport Documentation](https://docs.megaport.com). # Environments There are two server environments that can be accessed using different URLs: - [https://api.megaport.com](https://api.megaport.com) - this is the live Production environment. You will be liable for any services ordered in this system. - [https://api-staging.megaport.com](https://api-staging.megaport.com) - this is a test Staging environment and is expected to have lower availability requirements. You can test any action in this environment and the API calls and responses mirror the production system, but the services will not be deployed and you will not be billed for any activity. The staging environment is reset (to match the production environment) every 24 hours. You can use the Environments menu in the upper-left corner of this site to toggle the examples between No Environment (which shows `baseUrl`) and Staging ([https://api-staging.megaport.com](https://api-staging.megaport.com)). You can define [environment variables](https://learning.postman.com/docs/sending-requests/managing-environments/) in your Postman collection to automatically populate the `baseUrl` value in API requests and easily switch between staging and production environments. For more information about authenticating users in these environments, see [Megaport Authentication - API Keys](https://dev.megaport.com/#82876b33-a332-4b5d-8bf2-cef672f104b5). # Responses All API responses include standard HTTP response codes: - 200 - OK. A successful request. - 400 - Bad request. This error is typically caused by missing or incorrect request parameters. - 401 - Unauthorized. This error indicates that the request is missing the required authentication credentials. Typically this means a missing or invalid API access token. - 403 - Forbidden. You do not have the required permissions to perform this request. - 500 - Server error. When this occurs, Megaport developers are notified of the error by email by the server. - 503 - Server is unavailable, possibly down for maintenance. A standard response to a request will include a message, plus optionally some data. # Release Notes ## September 2025 **invitationPending field added to /v2/employee** – Added the `invitationPending` field to the GET `/v2/employee` endpoint response to improve employee invitation status visibility. ## August 2025 **Cross Connect Ordering** – In the networkdesign/validate and networkdesign/buy endpoints, the Cross Connect implementation has been updated to use the `addOn` config instead of the `crossConnectRequested` flag. **Partner Resource Limits** – Megaport partners can now configure resource limits for their managed companies via the API. The POST and PUT `/v2/managedCompanies` endpoints now accept a new optional field in the request Body called `resourceLimits`. Example structure: ``` json { ... "resourceLimits": [ { "productType": "MEGAPORT", "limit": 10 }, { "productType": "VXC", "limit": 20 } ], ... } ``` ## June 2025 **Changes for GET /v4/product/mve/images** – These changes have been made to the response Body of this endpoint: - A new field `vendorProductId` has been added. This is a unique identifier generated by concatenating the `product` and `vendor` values. - MVE images are now returned with the most recent (highest `id`) being returned first, per product and vendor. **Service Speed Values in GET /v3/locations** – The `mcrSpeedMps` and `megaportSpeedMbps` array values in the `/v3/locations` endpoint response are now returned in ascending order. ## May 2025 **GET /v3/locations** – The Megaport Portal has been updated to use the new `/v3/locations` API endpoint instead of `/v2/locations`. The `/v2/locations` public API is now deprecated and will be fully decommissioned on 31 July 2025. For more information, see [API Deprecation Notices and Frequently Asked Questions (FAQs)](https://docs.megaport.com/troubleshooting/api-v2-faq/). **Invoice APIs Updated to V3** – The Megaport Portal has been updated to use the new `v3` invoice API endpoints instead of `v2`. Note also that `companyId` has been updated to `companyUid`, and `supplierId` has been added to the URL in the v3 version. The v2 public APIs are now deprecated and will be fully decommissioned on 31 July 2025. For more information, see [API Deprecation Notices and Frequently Asked Questions (FAQs)](https://docs.megaport.com/troubleshooting/api-v2-faq/). **Disallow Service Deletion when Connected VXCs Exist** – Previously, deleting a product in the Megaport Terraform Provider, either explicitly or due to Port speed changes, could inadvertently delete attached VXCs. This caused an issue as the Megaport Terraform Provider was unaware of the deletion, which led to unexpected results. Therefore, a query parameter `safe_delete=true` has been added to delete calls in the Megaport Terraform Provider, which tells the API to return an error when deleting a product if it has attached VXCs. This makes it clear to the user that they need to move the VXC first, or delete it independently of their current operation, without causing issues to the Terraform state. This does not effect existing API or Portal users. ## April 2025 **Jumbo Frame Support on MCR**: A new field `ipMtu` has been added to the following endpoints which allows you to set the largest size (in bytes) of an IP packet that can be sent over the connected VXC. - POST /v3/networkdesign/validate - POST /v3/networkdesign/buy - PUT /v3/product/vxc/{uid} **Invoice Endpoint Improvements**: The invoicing endpoints have been updated to change the Invoice Charge From/To date fields to reflect the time period to which the ETF applies - the ETF duration. **Packet Filtering on MCR Endpoints**: New endpoints have been created to manage MCR packet filters via the API. New fields have also been added to the VXC create/update endpoint data within the interfaces object to define packet filters for a VXC (`packetFilterIn`/ `packetFilterOut`). - GET MCR Packet Filter Details – /v2/product/mcr2/{productUid}/packetFilter/{packetFilterId} - GET MCR Packet Filter Summary List – /v2/product/mcr2/{productUid}/packetFilters - POST Create MCR Packet Filter – /v2/product/mcr2/{productUid}/packetFilter - PUT Update MCR Packet Filter – /v2/product/mcr2/{productUid}/packetFilter/{packetFilterId} - DEL Delete MCR Packet Filter – /v2/product/mcr2/{productUid}/packetFilter/{packetFilterId} **Fixed:** The `/v2/products` endpoint was taking up to 4 minutes to respond for Google inc. This has now reduced significantly to around 50 seconds. ## March 2025 **Updated GET /v3/locations**: These improvements have been made to the `/v3/locations` endpoint: - Added the optional parameter `mveImageId`. When including the mveImageId, the endpoint will return only the locations that have capacity for the mveImageId. If the mveImageId is not passed in, the `mveMaxCpuCoreCount` value will always be null. - Added the MCR speed field (`mcrSpeedMbps`). ## February 2025 **New /v3/notificationPreferences Endpoint**: The `/v3/notificationPreferences` endpoint has been added to allow users to subscribe to individual notifications or notification groups in the Megaport Portal. This endpoint replaces the previous `/v2/notificationPreferences` endpoint. For more information, see [Email Notifications](https://dev.megaport.com/#a79d135b-1c48-4640-95f4-83a207ed01d0). **Removed the PUT /v2/product/cxc/{productUid} Endpoint**: The PUT `/v2/product/cxc` endpoint has been deprecated as all active CXC services have been migrated to VXCs. Users should access the PUT `/v2/product/vxc/{productUid}` endpoint instead. ## January 2025 **Oracle Virtual Circuit ID Now Returned**: Improvements have been made to the public APIs relating to Oracle VXCs. The `virtualCircuitId` field (the VLAN ID on the Oracle side of the VXC) is now returned in the response for these APIs: - GET /v2/product/{uid} - GET /v2/products - POST /v3/networkdesign/validate - POST /v3/networkdesign/buy ## December 2024 **Activity Logging**: Improvements have been made to the account activity information that is logged and displayed in the Megaport Portal. A new API `v3/activity` has also been created that can be used to retrieve activity logs for the logged-in user. ## November 2024 **Deprecate v2 APIs Replaced by v3 APIs**: As previously communicated, some of our v2 APIs have been superseded by v3 versions and were scheduled for deprecation. These v2 APIs have now been officially deprecated and no longer supported by Megaport: - Get MVE Price: GET /v2/pricebook/mve - Get VXC Price: GET /v2/pricebook/vxc - Validate Orders: POST /v2/networkdesign/validate - Buy Services: POST /v2/networkdesign/buy - Update VXC Details: PUT /v2/product/vxc/{productUid} - Delete Services: POST /v2/product/{productUid}/action/{action} For more information, see [API v2 Shutdown FAQs](https://docs.megaport.com/troubleshooting/api-v2-faq/). **Updated Invoice APIs from v2 to v3**: The invoice APIs have been to updated from v2 to v3, and to support companyUid. - GET /v3/company/${companyUid}/invoice/supplierId/{supplierId}?fromDate=${fromDate}&toDate=${toDate} - GET /v3/company/${companyUid}/invoice/${invoiceId} - GET /v3/company/${companyUid}/invoice/${invoiceId}/pdf - GET /v3/company/${companyUid}/invoice/${invoiceId}/csv **Resource Tags Added to Invoice Report**: Resource tags for services have been added to the Invoices report (CSV only). This allows you to export tagging information for external analysis. **Added Diversity Zone in Response for CSPs**: Previously customers who wanted to connect to a CSP were not able to see the diversity zone they were connecting to when reviewing available ports. The diversity zone information has now been added to the response that is returned so customers can determine the diversity zone they are connecting to for a given service. For example, the response that is returned in this request will now include diversity zone: `/v2/secure/google/{pairing_key}`. ## October 2024 **Removed MCR BFD Timer Settings**: Support for maintaining MCR BFD timer settings has been removed from the API. The BFD settings are not editable, the default values configured when BFD is enabled are Transmit Interval: 300 milliseconds, Receive Interval: 300 milliseconds, Multiplier: 3. ## August 2024 **Resource Tagging**: Customers now have the ability to create, modify, and delete resource tags to manage their active services via the Megaport API. Resource tags are key and value pairs that act as metadata for organizing Megaport resources. These tags will appear in the Service Inventory report by default for the company who has implemented the tags providing they own the service the tag is put against. **New Endpoints for MVE**: The new endpoints **GET v3/locations** and **GET v4/product/mve/images** have been added. v3/locations and v4/product/mve/images are intended to replace v2/locations and v3/product/mve/images. The MVE details have moved to v4/product/mve/images. If the v3/locations diversityZones has a value in the mveMaxCpuCoreCount then you can order any MVE from the v4/product/mve/images endpoint as long as the size is less than the maxMaxCpuCoreCount. **Add Max Length Validation to Service Level Reference Field**: Validations have been changed for the Service Level Reference field (costCentre) so that this field now has a maximum value of 255 characters. **Fixed**: API was responding with a 400 error instead of a 404 when querying a product that doesn’t exist. ## July 2024 **Telemetry CSV Download**: The service telemetry APIs can now download utilization data in CSV format as well as text format. For more information, see [Metric Types](https://dev.megaport.com/#54818a50-1bd6-4aad-924e-54bb7921ac0b). **GET /v2/product/{productUid} Speed Improvements**: The performance of this API has been optimised. In some cases, the load time for this API for larger companies has halved. ## June 2024 **Support for Monitoring Maintenance and Outage Events**: The `/ens/v1/status/outage` and `/ens/v1/status/maintenance` public APIs have been created which allow you to monitor maintenance activities and service outages. For more information, see [Maintenance and Outage Events](https://dev.megaport.com/#84d76e8b-b223-4aab-89a6-c97c3970e8e3). **Fixed**: NPE errors were occurring in the `/v2/employment` endpoint because the user did not not have an email address defined. ## May 2024 **Megaport Internet Available in More Countries**: Megaport Internet connections can now also be ordered from Ports and MCRs in New Zealand, Canada, and Singapore, in addition to Australia, UK and the US where it was already available. ## April 2024 **New /v3/login API**: A new `/v3/login` API has been created to replace the soon to be deprecated `/v2/login` API. The v2 API will no longer be supported; please migrate any API integrations you have from the v2 version to the new v3 API version. **GSA/GRA Updated**: Megaport has updated the standard Global Services Agreement (GSA) and Global Reseller Agreement (GRA) terms (in accordance with Clauses 15(a) and 20(a) respectively). As part of this update, the early termination fee (ETF) applied to a service on a contract that is canceled before the term is complete has changed from 50% to 100%. This change took effect in the Megaport Portal on April 15, 2024. ## March 2024 **New Service Inventory API**: A new public API `/v2/secure/inventory/companies/{companyUid}/services/csv` has been created which allows you to download your service inventory, including historical services, in comma-separated values (CSV) file format. You can also return the service inventory in JSON format using the `/v2/secure/inventory/companies/{companyUid}/services` API. For more information, see [Service Inventory Report](https://dev.megaport.com/#96494ff6-b57e-4e9a-ad56-218cec44115e). **Updated GET Available MVE Sizes API**: The GET Available MVE Sizes `/v2/product/mve/variants` API has been updated to remove the `bandwidthMbps` parameter from the response. **MVE validate/buy API Changes to Remove Vendor**: Changes have been made to the following MVE APIs to remove `vendor` as a required parameter. This parameter is no longer required, and if passed it will just be ignored. - /v2/networkdesign/validate - /v3/networkdesign/validate - /v2/networkdesign/buy - /v3/networkdesign/buy ## February 2024 **New Invoice APIs**: To ensure you keep receiving the most accurate, up-to-date and complete invoice data, including credit notes and tax information, you are required to migrate to the new invoice API endpoints. For more information, see [New Invoice APIs FAQs](https://docs.megaport.com/troubleshooting/api-new-invoices/) and [Invoices](https://dev.megaport.com/#3ef5f20b-b6b1-49f3-9e8a-3580b3272349). **MCR and MVE Diversity**: You can now choose a diversity zone when creating MCRs and MVEs. You can pass the `diversityZone` parameter when validating and ordering an MCR and MVE via API. For more information, see [Buy MCR (v3)](https://dev.megaport.com/#291cb695-a0bc-4574-9e1c-1eb0e7346a28) and the Buy MVE (v3) endpoint for the relevant vendor. **VXC Shutdown added to the Create Screen**: The VXC and IX shutdown feature has been expanded so that you can now shut down a VXC and IX service when creating the service. Previously it could be done only when editing the service. You can now pass the `shutdown` parameter in the v2/v3 validate and buy API endpoints. If not passed, it defaults to FALSE (Enabled). ## December 2023 **Terms on VXC**: VXCs can now be put on a 12, 24, or 36 month term. The following APIs have been updated to accept the new optional field: “term” to put a VXC on term: - POST /v3/networkdesign/validate - POST /v3/networkdesign/buy - PUT /v3/product/vxc/{productUid} Acceptable values for “term” are: 1, 12, 24, 36. If “term” is not provided when validating and ordering a VXC, it defaults to 1 (No Minimum Term). If “term” is not provided when updating a VXC, the existing value is not updated. **Improved Telemetry API**: The following enhancements have been made to the Telemetry APIs: - You can now specify a time span in 'days in the past' instead of needing exact dates. - You can ask for multiple metrics in a single request (for example, bit rate + packet rate) to reduce the number of requests needed. For more information, see [Metric Types](https://dev.megaport.com/#54818a50-1bd6-4aad-924e-54bb7921ac0b). **AWS HC Fetch Supported Bandwidths**: A new public API `/v2/secure/awshc` has been created to look up AWS HC ports with supported bandwidth options. ## November 2023 **VXC / IX Shutdown**: Added the shutdown option to VXC/IX validate and buy APIs. ## October 2023 **Reverse DNS for IX Connections**: Enabled the ability to add and edit reverse DNS for IX connections. Updated the Validate, Buy, and Update IX APIs to support the specifying of reverse DNS. For more information, see [PUT Update IX](https://dev.megaport.com/#6ae89dd9-e4bd-4fb5-8533-f8a4a0d02385). **Fixed**: The error ‘A Deal with uid \[None\]’ was showing when trying to order a VXC between an MVE and a Port. ## September 2023 **Support 5x vNICs for an MVE**: - POST `/v3/networkdesign/validate` and POST `/v3/networkdesign/buy` have been updated to accept up to 5 vNICs when ordering an MVE. - GET `/v2/product/{productUid}` and GET `/v2/products` return vNICs information for an MVE. **Updated GET Locations API to dynamically return the list of port speeds available**: The query made by the `/v2/locations` API has been updated to return all three speeds available (1G, 10G, and 100G) at a location. For more information, see [GET Locations](https://dev.megaport.com/#ae411b15-0989-4f7f-ac28-78e385264515). ## August 2023 **Performance Improvements**: Multiple APIs have been updated for speed and performance improvements. **France IX**: GET Partner Megaports now returns France IX ports that you can connect to. These ports have connectType=FRANCEIX. For more information, see [GET Partner Megaports](https://dev.megaport.com/#c276af3b-884e-481a-bb3e-9ad5a22471cc). **MCR Looking Glass Performance Improvements**: MCR Looking Glass APIs have been updated to support asynchronous requests for IP, BGP, and neighbor routes in async mode. A new API called GET MCR IP / BGP BGP Neighbor Routes in Async Mode has also been created to support retrieving these results. For more information, see [MCR Looking Glass](https://dev.megaport.com/#3ccc098c-3d47-4467-8845-5a19a565f3e3). ## July 2023 **Mexico Billing Market**: Four new mandatory TAX Registration fields related to fiscal and legal compliance information are now required when adding or editing the Mexico billing market. These are: Company Type, Tax Regime, Tax Purpose, and RFC Number. For more information, see [POST Set Billing Market](https://dev.megaport.com/#6713863b-f2c4-4fcf-9e7d-81262d8b20ae). **Fixed**: B-End VLAN being overridden by the A-End VLAN in the Service Key VXCs /validate and /buy endpoints. After ordering a Service Key VXC from a Port, MCR or MVE with a defined B-End VLAN, the service returned a different VLAN value from the one sent as part of the payload in both the /validate and /buy APIs. The B-End value the API returned for Service Key VXCs was the VLAN value in the A-End. Now the B-End VLAN value is returned correctly. # API Deprecation Notices From time to time we update, change versions, and deprecate APIs when releasing new functionality. We recommend that you keep up to date with these changes and plan any API integration updates accordingly. For more information, see [API Deprecation Notices and Frequently Asked Questions (FAQs)](https://docs.megaport.com/troubleshooting/api-v2-faq/). # Feedback If you have feedback, suggestions, or corrections for this site and the online documentation, please send an email to: Megaport Tech Pubs