1. Introduction
UpCloud is a cloud hosting platform used to run virtual servers. UpCloud provides:
- easy creation and hosting of virtual server instances
- management of hosting resources such as servers, storages and IP addresses efficiently
- quickly upscaling and downscaling servers
- migrating servers to different geographical locations
- IPv4 and IPv6 public addresses, IPv4 floating IPs and IPv4 private addresses
- utility network privately connecting all your servers around the globe
- private networks for communication between servers
- firewall services
The billing of resources is done by the hour on a usage basis.
This document describes the Application Programming Interface (API) to UpCloud. It gives information on how to use the API to build applications to control resources such as servers and storages on UpCloud. API client applications can be used to automate regular tasks on the cloud such as creating new servers and to abstract the end user from the cloud service.
This technical document is intended for developers building applications using the UpCloud API. Basic knowledge in programming is required to use the API. The API is independent from any programming language.
Older versions
Documentation for older API version 1.2 (currently 1.2.8) can be found here.
Version history
| API version | Date | Note |
|---|---|---|
| 1.0.0 | Apr 27, 2012 | First version of this document. |
| 1.0.1 | Jul 9, 2012 | Added the error code CDROM_EJECT_FAILED to the Eject CD-ROM operation. |
| 1.0.2 | Oct 3, 2012 | Added the new storage resource backup features. |
| 1.0.3, 1.1.1 | Aug 7, 2013 | Added the Modify IP address operation for modifying PTR records. Storages are divided into two tiers: hdd and ssd. Modified server operations to support the new VNC connection method. |
| 1.2.0 | Mar 30, 2015 | Storage tier maxiops added (replacing ssd). Added the family attribute to IP address and Firewall rule operations to support IPv6. Several other minor updates. |
| 1.2.1 | Apr 29, 2015 | Server attribute host added for server details and avoid_host for more control on what host machine VMs should or should not reside on. |
| 1.2.2 | Jul 20, 2015 | Server attribute plan added for new pricing options. Also new attributes in storage output. Support for server tags. |
| 1.2.3 | Apr 28, 2016 | Server creation attributes login_user and user_data added. |
| 1.2.4 | Jul 4, 2016 | Firewall rule attribute comment added. |
| 1.2.5 | Jun 20, 2017 | Server attributes plan_ipv4_bytes and plan_ipv6_bytesadded for server details. New storage operation cancel added. |
| 1.2.6 | Jan 2, 2018 | Server operation cancellation added. reject removed from accepted firewall rule actions. SERVER_CREATING_LIMIT_REACHED error code added. Numerous minor and editorial corrections and clarifications. |
| 1.2.7 | Mar 1, 2018 | Flag for setting storages as boot disks and TOO_MANY_BOOT_DISKS error code added. Clarified use and syntax of storage device addresses. Updated examples to use current plan names and resource amounts. Various other minor and editorial corrections and clarifications. |
| 1.2.8 | Mar 1, 2019 | Storages can now be removed during server deletion by adding ?storages=1 to the end of server deletion URI. The platform may rate-limit non-virtio network devices. Other smaller fixes and clarifications. |
| 1.3.0 | Oct 15, 2019 | New software-defined networking stack is now available, allowing custom networks with different features. These can be found from the Networks section, with new features such as API-controlled floating IPs. Private cloud server and host APIs have been introduced. Additionally, server remote access has been revamped, allowing for SPICE connections in addition to older VNC ones. |
| 1.3.1 | Jan 23, 2020 | The accounts endpoint now includes resource limits in effect for the calling account. Network boot feature added. |
| 1.3.2 | Mar 12, 2020 | Simple backup feature added. |
| 1.3.3 | Mar 30, 2020 | Metadata service for servers added. |
| 1.3.4 | Apr 3, 2020 | Subaccount management API added. |
| 1.3.5 | Aug 7, 2020 | Editorial changes, minor error corrections. |
| 1.3.6 | Oct 22, 2020 | Object Storage API added. Servers can be started asynchronously. |
| 1.3.7 | Nov 16, 2020 | Account network transfer usage API added, storage tier added to server responses. |
| 1.3.8 | Jan 13, 2021 | Support selectable ip addresses in ip addresses and networks API endpoints. |
| 1.3.9 | Apr 19, 2021 | Backup deletion parameters when deleting servers or storages added. |
| 1.3.10 | Apr 26, 2021 | More flexible storage attach/detach options. |
| 1.3.11 | Jan 27, 2022 | Managed Database API documentation added. |
| 1.3.12 | Feb 11, 2022 | Managed Load Balancer API documentation added. |
| 1.3.13 | Jul 5, 2022 | Permissions added. |
| 1.3.14 | Jul 6, 2022 | Managed Load Balancer metrics endpoint added. |
| 1.3.15 | Aug 30, 2022 | Managed Database maintenance updates endpoint added. |
| 1.3.16 | Sep 12, 2022 | Added Managed Load Balancer matcher inverse flag. |
| 1.3.17 | Oct 4, 2022 | Added Managed Load Balancer multiple networks support. |
| 1.3.18 | Oct 7, 2022 | Managed Database service task and migration status endpoint added. |
| 1.3.19 | Oct 27, 2022 | Added server interface ip address endpoint and dhcp_provided field to ip address structure. |
| 1.3.20 | Nov 17, 2022 | Update Managed Database service task endpoint and added external migration notice. |
| 1.3.21 | Dec 19, 2022 | Update Minimum size of storage from 10GB to 1GB. |
| 1.3.22 | Jan 1, 2023 | Added daily simple backup option. |
| 1.3.23 | Jan 4, 2023 | Add Redis Managed Database documentation. |
| 1.3.24 | Jan 10, 2023 | Labels implementation across different resources (servers, server groups, networks, routers, accounts), amount of attached storage devices raised from 8 to 16. |
| 1.3.25 | Jan 16, 2023 | Support Labels in Managed Loadbalancers, support JSON Merge Patch semantics for Managed Loadbalancers. |
| 1.3.26 | Feb 13, 2023 | Support Labels in storages. |
| 1.3.27 | Feb 28, 2023 | Deprecate Managed Database connections endpoint and add the new sessions endpoint. |
| 1.3.28 | Mar 15, 2023 | Add Managed Kubernetes beta. |
| 1.3.29 | Apr 26, 2023 | Added Managed Load Balancer maintenance window. |
Changes from version 1.2
List of incompatible changes from version 1.2
- VNC attributes in server creation, modification and viewing have been replaced by remote access attributes. See 8. Servers for more details.
- The
privateIP address type now refers to the new SDN enabled private networks. The previous semantics of theprivateaddress type are now referred to asutility.
Changes from version 1.1
List of incompatible changes from version 1.1
- IP address and Firewall Rule operations now require
familyattribute. - Customers can now configure servers to avoid certain hosts for added redundancy of environments.