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 scaling and downscaling servers
- migrating servers to different geographical locations
- IPv4 and IPv6 public addresses, IPv4 floating IPs and IPv4 private addresses
- a 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 of any programming language.
Version history
Version 1.3
| Date | Note |
|---|---|
| Apr 03, 2025 | Added Managed Load Balancer floating IP addresses support. |
| Apr 03, 2025 | Add public IPv4 addresses release policy and service delegation support. |
| Apr 03, 2025 | Added note about internally managed user, and role for Managed Object Storage. |
| Mar 31, 2025 | Minor fixes for Managed Object Storage. |
| Mar 14, 2025 | Added docs for database read-only replicas. |
| Mar 07, 2025 | Added server relocation endpoint. |
| Mar 05, 2025 | Updated examples for Managed Kubernetes. |
| Jan 29, 2025 | Added node progress updates visibility in service details for Managed Databases. |
| Jan 27, 2025 | Added force query parameter to service delete endpoint for Managed Object Storage. |
| Jan 17, 2025 | Added state_messages field and related message codes table for Managed Object Storage. |
| Jan 10, 2025 | Added a note of disabled Object Storage (EOL) create API endpoint. |
| Jan 07, 2025 | Added clearer constraints on bucket name creation for Managed Object Storage. |
| Dec 19, 2024 | Stopped maintaining separate API documentation patch version. |
| Dec 17, 2024 | Added new billing summary endpoint. |
| Dec 16, 2024 | Trial resource limits for accounts have been replaced with normal resource limits. |
| Nov 25, 2024 | Added Managed Object Storage Jobs endpoint. |
| Nov 20, 2024 | Added Partner API documentation. |
| Nov 13, 2024 | Fixed wrong endpoint listed in group inline policies. |
| Nov 12, 2024 | Added backup optional boolean field to Load Balancer backend member. |
| Nov 12, 2024 | Added rule's redirect action desired http status code field to Managed Load Balancer. |
| Nov 12, 2024 | Added docs for group inline policies, and user tags, permissions boundary, and inline policies. |
| Oct 22, 2024 | Added Valkey Managed Database documentation and dropping support for Redis® Managed Databases. |
| Oct 22, 2024 | Added Managed Databases logs integration support. |
| Oct 22, 2024 | Added Audit Logs Export endpoint documentation. |
| Oct 07, 2024 | Added IAM docs for inline-policies, tags, assume-role-policy, and permissions-boundary for Managed Object Storage. |
| Oct 01, 2024 | Added IAM role docs for Managed Object Storage. |
| Sep 03, 2024 | Add total count & pagination documentation for Audit Logs. |
| Sep 03, 2024 | Added new Standard block storage tier |
| Aug 29, 2024 | Added create bucket documentation for Managed Object Storage. |
| Aug 22, 2024 | Added additional warning message in delete bucket for Managed Object Storage. |
| Aug 13, 2024 | Added custom domains support for Managed Object Storage |
| Aug 6, 2024 | New LB rule matchers: http_status, request_header, response_header. Matchers boolean operator can be selected with matching_condition field. |
| Aug 5, 2024 | Added docs for bucket deletion. |
| Jul 30, 2024 | Remove Audit Logs "current_state" and "previous_state". A new separate endpoint will be provided. |
| Jul 1, 2024 | Server creation now defaults storage tier to plan config. |
| May 29, 2024 | Add labels support for Managed Databases. |
| May 16, 2024 | Add Audit Logs documentation. |
| May 10, 2024 | Temporarily removed Modify Policy endpoint. |
| Apr 26, 2024 | Added IAM Groups documentation. |
| Apr 26, 2024 | Added IAM Policy Version documentation. |
| Mar 28, 2024 | Add Network Peering documentation. |
| Mar 20, 2024 | Add Managed Databases alerts support on account and service level. |
| Mar 14, 2024 | Limit remote_access_password length to the maximum length allowed by VNC protocol instead of silently clipping. |
| Mar 11, 2024 | Removed SPICE support |
| Feb 28, 2024 | Add SDN support for Managed Databases. |
| Feb 28, 2024 | The version contains Managed Object Storage API breaking changes. The users field is not allowed in service payload for POST/PUT/PATCH requests. Also added new policies endpoint. |
| Jan 18, 2024 | Reflect Managed Object Storage /metrics/buckets to /buckets endpoint path change. |
| Dec 21, 2023 | Added section describing available IP subnets in Private virtual LANs. |
| Dec 19, 2023 | Update Managed Object Storage users documentation, changed name field to be required and uniq within customer account. |
| Dec 05, 2023 | Update Managed Object Storage users documentation, added optional name field. |
| Nov 24, 2023 | Update Managed Object Storage list services documentation, added sort at created_at column. |
| Nov 23, 2023 | Update Managed Object Storage users documentation, change example username to valid. |
| Nov 22, 2023 | Added Managed Object Storage service metrics series endpoint. |
| Nov 15, 2023 | Added Managed Kubernetes zone se-sto1. |
| Nov 13, 2023 | Updated permission documentation to include Managed Object Storage. |
| Sep 27, 2023 | Added OpenSearch Security management support. |
| Sep 18, 2023 | Managed Object Storage API documentation added. |
| Sep 18, 2023 | Added filter query parameters supported by List certificate bundles endpoint and label query param to List services endpoint. |
| Sep 12, 2023 | Change minimum port to 1 for Load Balancer frontend. |
| Sep 12, 2023 | Added Managed Load Balancer HTTP/2 support. |
| Sep 12, 2023 | Added Managed Kubernetes control plane IP filtering support. |
| Sep 8, 2023 | Add OpenSearch Managed Database documentation. |
| Sep 4, 2023 | Change number of networks required for service creation. |
| Jul 27, 2023 | Added Managed Load Balancer Backend TLS support. |
| Jul 14, 2023 | Added Kubernetes private node groups and node group specific utility network access. |
| Jul 12, 2023 | Added new backend property shutdown-sessions in uplb |
| Jul 6, 2023 | Added Managed Kubernetes zones nl-ams1, sg-sin1, uk-lon1 & us-chi1 |
| Jun 26, 2023 | Added load_balancers field to account resource_limits. |
| Jun 07, 2023 | Updated Managed Load Balancer health check url description |
| May 22, 2023 | Added Managed Load Balancer headers actions. |
| Apr 26, 2023 | Added Managed Load Balancer maintenance window. |
| Mar 15, 2023 | Add Managed Kubernetes beta. |
| Feb 28, 2023 | Deprecate Managed Database connections endpoint and add the new sessions endpoint. |
| Feb 13, 2023 | Support Labels in storages. |
| Jan 16, 2023 | Support Labels in Managed Loadbalancers, support JSON Merge Patch semantics for Managed Loadbalancers. |
| Jan 10, 2023 | Labels implementation across different resources (servers, server groups, networks, routers, accounts), amount of attached storage devices raised from 8 to 16. |
| Jan 4, 2023 | Add Redis® Managed Database documentation. |
| Jan 1, 2023 | Added daily simple backup option. |
| Dec 19, 2022 | Update Minimum size of storage from 10GB to 1GB. |
| Nov 17, 2022 | Update Managed Database service task endpoint and added external migration notice. |
| Oct 27, 2022 | Added server interface ip address endpoint and dhcp_provided field to ip address structure. |
| Oct 7, 2022 | Managed Database service task and migration status endpoint added. |
| Oct 4, 2022 | Added Managed Load Balancer multiple networks support. |
| Sep 12, 2022 | Added Managed Load Balancer matcher inverse flag. |
| Aug 30, 2022 | Managed Database maintenance updates endpoint added. |
| Jul 6, 2022 | Managed Load Balancer metrics endpoint added. |
| Jul 5, 2022 | Permissions added. |
| Feb 11, 2022 | Managed Load Balancer API documentation added. |
| Jan 27, 2022 | Managed Database API documentation added. |
| Apr 26, 2021 | More flexible storage attach/detach options. |
| Apr 19, 2021 | Backup deletion parameters when deleting servers or storages added. |
| Jan 13, 2021 | Support selectable ip addresses in ip addresses and networks API endpoints. |
| Nov 16, 2020 | Account network transfer usage API added, storage tier added to server responses. |
| Oct 22, 2020 | Object Storage API added. Servers can be started asynchronously. |
| Aug 7, 2020 | Editorial changes, minor error corrections. |
| Apr 3, 2020 | Subaccount management API added. |
| Mar 30, 2020 | Metadata service for servers added. |
| Mar 12, 2020 | Simple backup feature added. |
| Jan 23, 2020 | The accounts endpoint now includes resource limits in effect for the calling account. Network boot feature added. |
| 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. |
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.
Version 1.2
Documentation for version 1.2 can be found here.
| Date | Note |
|---|---|
| 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. |
| 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. |
| 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. |
| Jun 20, 2017 | Server attributes plan_ipv4_bytes and plan_ipv6_bytesadded for server details. New storage operation cancel added. |
| Jul 4, 2016 | Firewall rule attribute comment added. |
| Apr 28, 2016 | Server creation attributes login_user and user_data added. |
| Jul 20, 2015 | Server attribute plan added for new pricing options. Also new attributes in storage output. Support for server tags. |
| 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. |
| 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. |
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.
Versions 1.0 and 1.1
| Date | Note |
|---|---|
| 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. |
| Oct 3, 2012 | Added the new storage resource backup features. |
| Jul 9, 2012 | Added the error code CDROM_EJECT_FAILED to the Eject CD-ROM operation. |
| Apr 27, 2012 | First version of this document. |