Servers

Servers are the core compute resource in UpCloud. Each server has dedicated CPU cores, memory, and attached storage devices. Servers can be freely scaled and configured with various operating systems.

Server states

Servers can be in one of the following states:

Name
started
Description
The server is running and accessible.
Name
stopped
Description
The server is powered off and not consuming compute resources.
Name
maintenance
Description
The server is being maintained and is temporarily unavailable.
Name
error
Description
The server has encountered an error state.

GET/1.3/server_size

List server configurations

Returns a list of available server configurations. These define valid combinations of CPU cores and memory amounts.

Response fields

Name
core_number
Type
integer
Description
Number of CPU cores.
Name
memory_amount
Type
integer
Description
Memory amount in MiB.

Request

GET

/1.3/server_size

curl -X GET https://api.upcloud.com/1.3/server_size \
  -u your_username:your_password

GET/1.3/server

List servers

Returns a list of all servers associated with the current account. Results can be filtered, ordered, and paginated.

Query parameters

Name
label
Type
string
Description
Filter by label key-value pair (e.g., env=prod).
Name
limit
Type
integer
Description
Number of results to return (for pagination).
Name
offset
Type
integer
Description
Starting offset for pagination.

Request

GET

/1.3/server

curl -X GET https://api.upcloud.com/1.3/server \
  -u your_username:your_password

GET/1.3/server/{uuid}

Get server details

Returns detailed information about a specific server, including networking, storage devices, and configuration.

Response fields

Name
uuid
Type
string
Description
Unique server identifier.
Name
hostname
Type
string
Description
Server hostname.
Name
state
Type
string
Description
Current server state.
Name
plan
Type
string
Description
Pricing plan or "custom".
Name
core_number
Type
integer
Description
Number of CPU cores.
Name
memory_amount
Type
integer
Description
Memory in MiB.
Name
storage_devices
Type
object
Description
Attached storage devices.
Name
networking
Type
object
Description
Network interfaces configuration.

Request

GET

/1.3/server/{uuid}

curl -X GET https://api.upcloud.com/1.3/server/00798b85-efdc-41ca-8021-f6ef457b8531 \
  -u your_username:your_password

GET/1.3/server/{uuid}/gpus

Get server GPUs

Returns a list of all GPUs attached to a server. Only applicable for GPU-enabled server plans.

Response fields

Name
model
Type
string
Description
GPU model name (e.g., "NVIDIA L40S").
Name
type
Type
string
Description
Device type ("gpu").
Name
serial
Type
string
Description
GPU serial number.
Name
metadata
Type
object
Description
Additional GPU metadata including cores and memory.

Request

GET

/1.3/server/{uuid}/gpus

curl -X GET https://api.upcloud.com/1.3/server/00798b85-efdc-41ca-8021-f6ef457b8531/gpus \
  -u your_username:your_password

POST/1.3/server

Create server

Creates a new server. Servers can be created from templates, by cloning existing servers, or from scratch.

Required attributes

Name
zone
Type
string
Description
Zone identifier (e.g., "fi-hel1").
Name
title
Type
string
Description
Server title (0-255 characters).
Name
hostname
Type
string
Description
Valid hostname (max 128 characters).
Name
storage_devices
Type
object
Description
Storage configuration with 1-16 devices.
Name
networking
Type
object
Description
Network interfaces configuration.

Optional attributes

Name
plan
Type
string
Description
Plan name or "custom" (default: smallest).
Name
core_number
Type
integer
Description
CPU cores (required if plan is "custom").
Name
memory_amount
Type
integer
Description
Memory in MiB (required if plan is "custom").
Name
login_user
Type
object
Description
Login user configuration with SSH keys.
Name
firewall
Type
string
Description
Firewall state: "on" or "off" (default: "on").
Name
metadata
Type
string
Description
Enable metadata service: "yes" or "no".
Name
timezone
Type
string
Description
Timezone identifier (default: "UTC").

Request

POST

/1.3/server

curl -X POST https://api.upcloud.com/1.3/server \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "server": {
      "zone": "fi-hel1",
      "title": "My Debian server",
      "hostname": "debian.example.com",
      "plan": "2xCPU-4GB",
      "storage_devices": {
        "storage_device": [
          {
            "action": "clone",
            "storage": "01000000-0000-4000-8000-000020030100",
            "title": "Debian from template",
            "size": 50,
            "tier": "maxiops"
          }
        ]
      },
      "networking": {
        "interfaces": {
          "interface": [
            {
              "type": "public",
              "ip_addresses": {
                "ip_address": [{"family": "IPv4"}]
              }
            },
            {
              "type": "utility",
              "ip_addresses": {
                "ip_address": [{"family": "IPv4"}]
              }
            }
          ]
        }
      },
      "login_user": {
        "username": "admin",
        "ssh_keys": {
          "ssh_key": ["ssh-rsa AAAAB3Nz..."]
        }
      }
    }
  }'

POST/1.3/server/{uuid}/rebuild

Rebuild server

Rebuilds a server by replacing its primary storage with a new clone from a template. The server must be stopped before rebuilding.

Attributes

Name
clone_source
Type
string
Description
UUID of the storage template to clone from. Required.
Name
detach_disk
Type
string
Description
UUID of the storage device to detach.
Name
delete_detached_disk
Type
string
Description
Delete the detached storage: "yes" or "no".
Name
storage_title
Type
string
Description
Title for the new storage (0-255 characters).
Name
encrypted
Type
string
Description
Encrypt the new storage: "yes" or "no".
Name
password_delivery
Type
string
Description
Password delivery method: "none", "email", or "sms".
Name
login_user
Type
object
Description
Login user configuration with SSH keys.

Request

POST

/1.3/server/{uuid}/rebuild

curl -X POST https://api.upcloud.com/1.3/server/00798b85-efdc-41ca-8021-f6ef457b8531/rebuild \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "rebuild": {
      "clone_source": "01000000-0000-4000-8000-000020030100",
      "detach_disk": "012580a1-32a1-466e-a323-689ca16f2d43",
      "delete_detached_disk": "yes",
      "storage_title": "Rebuilt Debian server",
      "encrypted": "yes",
      "login_user": {
        "username": "admin",
        "ssh_keys": {
          "ssh_key": ["ssh-rsa AAAAB3Nz..."]
        }
      }
    }
  }'

PUT/1.3/server/{uuid}

Modify server

Modifies an existing server's configuration. Some changes require the server to be stopped.

Modifiable attributes

Name
title
Type
string
Description
Server title.
Name
hostname
Type
string
Description
Server hostname.
Name
plan
Type
string
Description
Pricing plan (changing may require stop/start).
Name
core_number
Type
integer
Description
CPU cores (hot-resize if enabled).
Name
memory_amount
Type
integer
Description
Memory amount (hot-resize if enabled).
Name
firewall
Type
string
Description
Firewall state.
Name
simple_backup
Type
string
Description
Backup schedule (e.g., "0100,dailies").

Request

PUT

/1.3/server/{uuid}

curl -X PUT https://api.upcloud.com/1.3/server/00798b85-efdc-41ca-8021-f6ef457b8531 \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "server": {
      "title": "Updated server title",
      "core_number": 4,
      "memory_amount": 8192
    }
  }'

POST/1.3/server/{uuid}/start

Start server

Starts a stopped server.

Optional attributes

Name
start_type
Type
string
Description
Start type: "async" or "sync" (default: "sync").
Name
host
Type
integer
Description
Specific host ID (private cloud only).
Name
avoid_host
Type
integer
Description
Host ID to avoid (for HA setups).

Request

POST

/1.3/server/{uuid}/start

curl -X POST https://api.upcloud.com/1.3/server/00798b85-efdc-41ca-8021-f6ef457b8531/start \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "server": {
      "start_type": "async"
    }
  }'

POST/1.3/server/{uuid}/stop

Stop server

Stops a running server.

Optional attributes

Name
stop_type
Type
string
Description
Stop type: "soft" (graceful) or "hard" (immediate). Default: "soft".
Name
timeout
Type
integer
Description
Timeout in seconds (1-600) before hard stop.

Request

POST

/1.3/server/{uuid}/stop

curl -X POST https://api.upcloud.com/1.3/server/00798b85-efdc-41ca-8021-f6ef457b8531/stop \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "stop_server": {
      "stop_type": "soft",
      "timeout": 60
    }
  }'

POST/1.3/server/{uuid}/restart

Restart server

Restarts a running server.

Attributes

Name
stop_type
Type
string
Description
Restart type: "soft" or "hard" (default: "soft").
Name
timeout
Type
integer
Description
Timeout in seconds (required for soft restart).
Name
timeout_action
Type
string
Description
Action if timeout exceeded: "destroy" or "ignore" (default: "ignore").

Request

POST

/1.3/server/{uuid}/restart

curl -X POST https://api.upcloud.com/1.3/server/00798b85-efdc-41ca-8021-f6ef457b8531/restart \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "restart_server": {
      "stop_type": "soft",
      "timeout": 60,
      "timeout_action": "ignore"
    }
  }'

POST/1.3/server/{uuid}/cancel

Cancel server operation

Cancels an ongoing server operation. Only certain operations can be cancelled, such as server creation or storage cloning.

Error codes

Name
SERVER_STATE_ILLEGAL
Description
The server is in a state where operations cannot be cancelled.
Name
UNABLE_TO_CANCEL
Description
The cancellation was not successful.

Request

POST

/1.3/server/{uuid}/cancel

curl -X POST https://api.upcloud.com/1.3/server/00798b85-efdc-41ca-8021-f6ef457b8531/cancel \
  -u your_username:your_password

DELETE/1.3/server/{uuid}

Delete server

Deletes a server. The server must be stopped before deletion.

Query parameters

Name
storages
Type
string
Description
Storage deletion policy: "0" (keep), "1" (delete all). Default: "0".
Name
backups
Type
string
Description
Backup deletion policy: "keep", "keep_latest", or "delete".

Request

DELETE

/1.3/server/{uuid}

curl -X DELETE "https://api.upcloud.com/1.3/server/00798b85-efdc-41ca-8021-f6ef457b8531?storages=1&backups=delete" \
  -u your_username:your_password

POST/1.3/server/{uuid}/relocate

Relocate server

Relocates a server to a different zone. The server must be stopped before relocation. All attached storages will be cloned to the new zone.

Attributes

Name
zone
Type
string
Description
Target zone identifier (e.g., "de-fra1"). Required.

Request

POST

/1.3/server/{uuid}/relocate

curl -X POST https://api.upcloud.com/1.3/server/00798b85-efdc-41ca-8021-f6ef457b8531/relocate \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "relocate": {
      "zone": "de-fra1"
    }
  }'