Cloud API Upgrade Documentation


IONOS offers multiple application programming interfaces (APIs) for interacting with and managing services in the public cloud ecosystem. One of the most prominent APIs is the IONOS CloudAPI which facilitates virtual data center resources. The latest generation of CloudAPI is version 6, which contains all features and serves as the baseline forfuture products and updates.
Note: Older versions of IONOS CloudAPI (version 1 through version 5) are announced for End of Life. The endpoints will be deprecated by September 30, 2023, and CloudAPI Version 6 will remain operational.
Users running CloudAPI versions older than version 6 are advised to upgrade to the most recent version.
This documentation shall describe the procedure for upgrading from an older version to CloudAPI version 6. Furthermore, it contains information on which additional features became available in each version as well as breaking changes that require further modifications if respective API resources were used in earlier versions.

IONOS SDKs and Configuration Management Tools

IONOS provides access to various software development kits (SDKs) and configuration management tools. These applications have already been updated to run on CloudAPI version 6.
However, if you are using an IONOS-provided SDK or configuration management tool, you must use the most recent version to ensure that your SDK or configuration management tool interacts with the most recent CloudAPI. More information can be found in the respective GitHub repositories or configuration management tool hubs.
If you don't update older SDKs or configuration management tools, your integration will stop working when CloudAPI versions 1 through 5 are terminated.

API Upgrade Basics

Note: An update of your CloudAPI version will not result in a change to your provisioned services or virtual resources. The virtual resources will continue to run without any service interruption.
You can schedule the transition from old CloudAPI versions to new CloudAPI versions according to your business needs, but it must be completed by September 30, 2023. Following that, IONOS will deactivate all CloudAPI endpoints for all legacy versions, leaving only CloudAPI version 6 operational.
During the transition, you can use multiple versions concurrently because most API resources are compatible across CloudAPI versions. There are a few incompatible changes, which are detailed in the version description below. Based on this compatibility, you can apply updates to your implementation in a sequential and step-by-step manner (e.g. API resource by API resource or per individual REST operation).
If you are unsatisfied with the results, you can revert to the previous, older CloudAPI version and make further changes until it meets your requirements.
Your CloudAPI authentication routine remains unchanged, and all authentication options are forward and backward-compatible across all CloudAPI versions.

Backwards-compatible changes

IONOS' CloudAPI is based on previous versions. In most cases, new CloudAPI versions have added major features. Newer versions of CloudAPI are extensions of older versions.
However, in a small number of cases, breaking changes are applied to new CloudAPI versions as well, requiring adaptations to your implementations if your implementation references respective API resources and payloads. These incompatible changes will be highlighted explicitly in the CloudAPI version listed below.

Upgrading your API version

If you’re running an older version of the API, upgrade to the latest version to take advantage of new functionality or to streamline responses so the API is faster for you. In most cases, upgrading your API version should be simple:
All CloudAPI http methods contain the version tag in the URL.

Example of old CloudAPI Verion (e.g. V2)

  • Scope of API Call: Create a new virtual data center by using CloudAPI Version 2
  • HTTP Method: POST
  • Note: Request payload to be added and not provided here for better readability.
For upgrading to the latest version of CloudAPI you need to change the version tag within the http call. Based on the previous example the http call would need to look like:

Example of latest CloudAPI Verion (V6)

  • Scope of API Call: Create a new virtual data center by using CloudAPI Version 6
  • HTTP Method: POST
  • Note: Request payload to be added and not provided here for better readability.
In most cases, neither the request nor the response payload changes, but it is possible that the value options of a request or response property may have been expanded due to the ongoing growth of services. Please confirm by consulting the CloudAPI Version 6 documentation.

Rolling back your API version

Until the expiration date of CloudAPI version 1 - version 5, you can continue to use all versions of CloudAPI, giving you flexibility in your migration strategy. It is not required to migrate the entirety of your implementation to a single CloudAPI version at once. If necessary, you can run an implementation with different versions of the CloudAPI and plan the transition in iterations.
This concept makes it possible to revert to previous CloudAPI versions. Please note that you may be required to undo incompatible changes across CloudAPI versions.
Note: Any change to the CloudAPI version will not result in any changes to the configuration of your virtual infrastructure or services. They will maintain their previous configuration and status.

API versions

This section provides a summary of important changes in to each CloudAPI version. If a particular CloudAPI version has introduced incompatible changes then they apply to all previous CloudAPI versions.
It is possible to upgrade from any older CloudAPI version to the latest version 6. It is not required to iterate the upgrade process through all versions.
The following section will summarize the changes of each version. However, each CloudAPI version documentation is available in the API Documentation portal. You will find a drop down box at the left top of the documentation website which allows you to select the CloudAPI version of your choice for further consultation.

CloudAPI V6

CloudAPI Version 6 is the latest version and will remain active. It will receive further functionalities, features but also improvements and bug fixes in future.
Added features since CloudAPI V5
  • Added the optional server property type used to provision a Compute Engine or IONOS Cubes (if the property is not provided, the default is ENTERPRISE, which resolves to a Compute Engine).
  • Added the template server property, which is required when provisioning a CUBE server.
  • Added the /template resource for retrieving a list of all available CUBE templates. This template does not apply to ENTERPRISE servers.
  • Added the volume type DAS (direct attached storage based on NVMe), which is automatically applied to every CUBE. This volume type cannot be provisioned independently, meaning you cannot have multiple direct-attached storages per CUBE or mount direct-attached storage volumes on ENTERPRISE server types.
  • Added volume type expansion for the introduction of SSD Performance classes. SSD is still possible but will resolve to the highest SSD performance class, which the volume type SSD_PREMIUM can explicitly provision. To order an SSD performance class from the lower tier, the volume type must be SSD_STANDARD. No performance class has been introduced for volumes of type HDD or DAS.
  • Added the volume property userData, which enables cloud-init configuration injection into public Linux images.
  • Added /flowlogs as a subresource of network interface cards, Managed NAT Gateways, Managed Application Load Balancers, and Managed Network Load Balancers. It specifies which network traffic will be recorded and the S3 bucket where the recordings will be stored.
  • Added the /natgateways resource to the API, a Managed Network Load Balancer service (TCP/IP Layer 3 load balancer according to the OSI model).
  • Added the API resource /networkloadbalancers, a Managed Network Load Balancer service (TCP/IP Layer 3 load balancer according to the OSI model).
  • Added the API resource /applicationloadbalancers, a Managed Application Load Balancer service (an HTTP/HTTPS Layer 7 load balancer in accordance with the OSI model).
  • Added the API resource /targetgroups, required for configuring the Managed Application Load Balancer.
  • Added support for bi-directional firewall configuration on network interface cards with CIDR masks.
  • Added exposure of PCI slot positioning of network interface cards and block storage devices for easier identification within the VM operating system.
  • Added the API resource /targetgroups required for configuring the Managed Application Load Balancer.
Further other resources or properties may be visible in the documentation or in the CloudAPI V6 swagger file but are not listed here as they are not active yet.
Deprecated/ Removed features or incompatible changes since CloudAPI V5
CloudAPI V6 is fully compatible to CloudAPI V5 and has introduced new resources, optional properties as well as property values. Furthermore, no feature was deprecated from CloudAPI V5.
Note: S3 Key Management has been documented separately in the CloudAPI V6 documentation and the corresponding swagger JSON file, but neither the resource path nor its properties have changed. This revision is made solely for documentation purposes.

CloudAPI V5

Added features since CloudAPI V4
  • Added the API resource /k8s for managing Kubernetes clusters and node pools.
  • Added the API resource /backupUnits for managing Backup groups.
  • Added the volume property backupUnits to define the target of storage volume backup.
  • Added the API resource /s3keys as a subresource of User Management for managing individual S3 Keys of your user and other users (depending on user role).
  • Added the functionality to retrieve and manage user information (depending on user role).
  • Added the meta attributes createdByUserId and lastModifiedByUserId to several resources, such as data centers, servers, volumes, etc., to help track ownership and change history by the user.
  • Add the API resource /labels to manage labels and associate them with specific resources (data centers, servers, volumes, snapshots, IP blocks).
Deprecated/ Removed features or incompatible changes since CloudAPI V4
  • Removed the volume property allowReboot of type boolean and indicated whether or not a VM may be rebooted to apply a specific change. When a configuration change to a virtual resource is made that requires a reboot, the VM must be automatically restarted for service reasons. In CloudAPI versions greater than V4, if this property is still set, the CloudAPI will return a parser error.
  • Incompatibly by changing a required header attribute for resellers from PB-Contract-Number to X-Contract-Number. This header field is required only for resellers who can interact on behalf of their respective customers in customer contracts. This field must be used to uniquely identify a contract from which a reseller wishes to retrieve information or make modifications.

CloudAPI V4

Added features since CloudAPI V3
  • Added the API resource /um for user management, including management of privileges and permissions.
  • Added query filter options to CloudAPI resources to apply server-side filtering (e.g., GET all servers of a certain CPU family that are in the state DEALLOCATED).
  • Added the /contracts extension to the response payload, which contains information about contract resource limits and current resource utilization.
  • Added the volume property imageAlias, which allows the assignment of public images via an alias instead of a uuid.
  • Added the /locations extension to the response payload, which contains information about which image aliases are available in each location.
  • Added the LAN property ipFailover to prepare failover routines by configuring the same public IP on multiple NICs within a LAN.
Deprecated/ Removed features or incompatible changes since CloudAPI V3
CloudAPI V4 is fully compatible to CloudAPI V3 and has introduced new resources, optional properties as well as property values. Furthermore, no feature was deprecated from CloudAPI V3.

CloudAPI V3

Added features since CloudAPI V2
  • Added the option to download the CloudAPI version swagger file.
  • Added the volume property availabilityZone to create affinity or anti-affinity of HDD or SSD volumes. This property will not be supported on volumes of type DAS introduced with CloudAPI V6 (see above).
  • Added REST content types for standard data representation.
Deprecated/ Removed features or incompatible changes since CloudAPI V3
  • Deprecated custom REST content types for data representation. Providing the custom REST content types in any CloudAPI version higher than V2 will result in an error due as these types are not known by the API anymore.

CloudAPI V2

Added features since CloudAPI V1
  • Added the volume property sshKeys (only for public Linux images) and imagePassword (for all public images) to define root access to the operating system following the provisioning of a new operating system. One of both options must be defined when creating a new volume with a public image provided by IONOS.
  • Added the volume type SSD in addition to the existing type HDD. Please note that in CloudAPI V2, the SSD Performance Classes option has not yet been implemented, and the corresponding property values are not supported/will result in an error.
Deprecated/ Removed features or incompatible changes since CloudAPI V1
CloudAPI V2 is fully compatible to CloudAPI V1 and has introduced new resources, optional properties as well as property values. Furthermore, no feature was deprecated from CloudAPI V1.

CloudAPI V1

CloudAPI V1 was the first released RESTful API for interacting with IONOS public cloud services. Therefore, there is no change log or compatibility issues to be listed. As mentioned before, all CloudAPI versions are following its predecessor.


Do I need to modify my user account or contract to use the most recent version of CloudAPI?

No. You can use any version of the CloudAPI anytime without modifying your user account or contract yourself or through the IONOS support team.

Will my infrastructure change when I upgrade to the latest version of CloudAPI?

No. All services in your infrastructure will continue to work in the exact configuration you set them up. The upgrade will only change the interface towards IONOS that allows you to manage your infrastructure and services.

What will happen if I do not upgrade or will not complete my upgrade to the latest version of CloudAPI until 30.09.2023?

After September 30, 2023, IONOS will deactivate the CloudAPI endpoints for version 1 up to version 5. Any API call to these versions will not return an error and the respective API call does not get processed. Your infrastructure will continue to operate in the exact configuration you set them up but you cannot add, retrieve, modify, delete any resource anymore. As an alternative, you can use the Data Center Designer (DCD) to continue managing your infrastructure and services until you have completed your upgrade process.

Can I upgrade in small steps or do I need to upgrade all API calls at once?

You can upgrade iteratively and even interact with your resources with different CloudAPI versions. For example, you may pool the status of your VM via the latest CloudAPI version already while you still manage the VM with an earlier version. You can define your upgrade schedule according to your technical needs.

Will there be any price changes or changes to service levels?

Upgrading to the latest version of CloudAPI will not change any prices or service level conditions. These are independent of using any interface (DCD, API, SDKs or Configuration Management Tools).

Will I get charged for additional resources provisioned while doing the upgrade?

Yes. All resources that will get provisioned through any interface in any version will get charged. IONOS cannot determine when you are about to upgrade or work in any particular version productively. From the perspective of IONOS, you are ordering resources that could be used for any workload and, as such, must be billed. Upgrading the CloudAPI requires minimal resources; you can delete any provisioned resource in seconds. You also can execute the upgrade without creating any resource and therefore do not create any cost to your account.

I am using an IONOS SDK or Configuration Management Tool - what shall I do?

Configuration Management Tools are typically built on top of an SDK, and the SDK uses the CloudAPI. All IONOS SDKs and Configuration Management Tools have already been updated to use the most recent version of CloudAPI. As a result, you will need to make sure you are using the most current version of the relevant SDK or Configuration Management Tool. You can find more information in the respective GitHub repository or Release Documentation Hub. The relevant documentation links are provided on the overview page.

I am using the latest version of CloudAPI already - is there anything I need to consider?

Awesome. There is no further action required.

CloudAPI V6 is "currently" the latest version. Will there be new versions in the future?

Yes! IONOS will introduce changes to the current CloudAPI V6 as long as they do not cause breaking changes or incompatibilities. When this occurs, IONOS will release a new CloudAPI version. CloudAPI V6 will not be phased out immediately. IONOS will provide a timeline and information on whether the older API version will be continued or discontinued. You can be confident that IONOS will ensure that any transition is smooth and with adequate lead time. You may have noticed that IONOS has launched certain services in decoupled endpoints, allowing separate services to establish individual life cycles.

Can IONOS do the upgrade for me?

No. However, we may be able to assist by referring IONOS partners who can provide such services. You should contact your sales representative or key account manager about possible options.

I have questions - what shall I do?

Please contact the IONOS support team that will be available for further assistance.


In most cases, the upgrade will be relatively seamless, as the most significant change is made to the URL of your HTTP calls while the request and response payloads remain unchanged. Nevertheless, you may encounter difficulties. Here are some suggestions you may find helpful for initial analysis:
  • Check the HTTP error code; if it is 404, your basepath, including its version, is incorrect. Make sure it is If there are additional HTTP error codes, it may be necessary to verify your credentials.
  • Check your firewall settings; according to IONOS support experience, applying specific restrictive configurations that define the complete API path, including the version tag is not recommended. Ensure that the API endpoint and API version provide unrestricted access to the base path. This permits access to all IONOS APIs.
  • Check the error response message you received; it could be that your HTTP request is valid, but there is an issue with the request payload (in the case of POST calls). Check to see if a property that must be set has been introduced or if a property has been modified. You may wish to consult the CloudAPI Version 6 documentation to determine the correct payload. We hope that all material changes have been listed. Notify the IONOS support team to receive immediate assistance if this is not the case, and the documentation will be updated accordingly.
  • Check your resource limits; you can test your upgraded scripts before deploying them in production. Keep in mind that this will also consume resources for a brief duration. This counts against your resource limits and may leave your contract without additional resources. You should ensure that you have the sufficient capacity by deleting additional resources. If your contract is short on resources, please contact support to increase your resource limits to meet your needs. IONOS does not offer a sandbox mode for its APIs.
Feel free to contact the IONOS support team if you encounter any other trouble during the upgrade.