Server

Download schema

Manages Cloud Servers

List Cloud Servers

GET

https://api.upcloud.com

/1.3/server

Returns the most relevant information for Cloud Servers associated with the current account.

List Cloud Servers › query Parameters

label

string

Filter by label key or key-value pair using "key" or "key=value". Repeat the parameter to require all labels.

uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f…

Filter by Cloud Server UUID. Repeat the parameter to match any of up to five UUIDs.

Universally unique identifier

host

serverEncodedHostId · int64 · min: 1

Filter by Private Cloud host ID. Repeat the parameter to match any of up to five hosts.

Encoded Private Cloud host ID

Example: 7653311107

device

string

Filter by attached device using "type=gpu" or "type!=gpu". Repeat the parameter for up to five filters.

state

string · enum

Filter by the current Cloud Server state.

Enum values:

started

stopped

maintenance

error

tag

serverTagList

Filter by tag name. Separate names with commas to match any tag or colons to require all tags.

One or more tag names. Use commas to match any tag, or colons to require all tags.

search

string

Search UUIDs, titles, hostnames, zones, zone descriptions, IP addresses, tags, and template names.

sort_by

string · enum

Field to sort by.

Enum values:

title

zone

size

cores

memory

popularity

order_by

string · enum

Sort direction. Only applied when sort_by is specified.

Enum values:

asc

desc

limit

serverLimit · min: 1 · max: 1000

Maximum number of Cloud Servers to return.

Maximum number of items to return. Default is 25.

Example: 25

offset

serverOffset · min: 0

Number of Cloud Servers to skip.

Number of items to skip before starting to return results. Default is 0.

Example: 0

List Cloud Servers › Responses

Cloud Server list returned successfully.

Schema for the Cloud Server list response.

getServerList

object · required

GET/1.3/server

curl https://api.upcloud.com/1.3/server \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "servers": {
    "server": [
      {
        "core_number": "2",
        "created": 1705320000,
        "hostname": "web-1.example.com",
        "license": "0",
        "memory_amount": "2048",
        "plan": "2xCPU-2GB",
        "labels": {
          "label": [
            {
              "key": "env",
              "value": "production"
            }
          ]
        },
        "plan_ipv4_bytes": "34253332",
        "plan_ipv6_bytes": "0",
        "simple_backup": "0100,dailies",
        "state": "started",
        "tags": {
          "tag": [
            "production",
            "web"
          ]
        },
        "title": "Production web server",
        "uuid": "007bf7bd-e3cf-4a10-bf01-4251dc7f3b65",
        "zone": "fi-hel1"
      }
    ]
  }
}

application/json

Create a new Cloud Server

POST

https://api.upcloud.com

/1.3/server

Creates a new Cloud Server

Create a new Cloud Server › Request Body

Cloud Server creation parameters

createServer

object · required

Create a new Cloud Server › Responses

Created a Cloud Server

Newly created Cloud Server and optional one-time login credentials

createServerResponse

serverDetails · required

Detailed public information about a Cloud Server

POST/1.3/server

curl https://api.upcloud.com/1.3/server \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "server": {
    "hostname": "my-server.example.com",
    "title": "My Server",
    "zone": "fi-hel1",
    "storage_devices": {
      "storage_device": [
        {
          "action": "clone",
          "storage": "01234567-89ab-cdef-0123-456789abcdef",
          "title": "Operating System"
        }
      ]
    }
  }
}'

Example Request Body

{
  "server": {
    "hostname": "my-server.example.com",
    "title": "My Server",
    "zone": "fi-hel1",
    "storage_devices": {
      "storage_device": [
        {
          "action": "clone",
          "storage": "01234567-89ab-cdef-0123-456789abcdef",
          "title": "Operating System"
        }
      ]
    }
  }
}

Example Responses

{
  "server": {
    "core_number": "2",
    "created": 1705320000,
    "hostname": "my-server.example.com",
    "license": "0",
    "memory_amount": "2048",
    "state": "maintenance",
    "title": "My Server",
    "uuid": "007bf7bd-e3cf-4a10-bf01-4251dc7f3b65",
    "zone": "fi-hel1"
  }
}

application/json

GET

https://api.upcloud.com

/1.3/server/firewall_ruleset_relationships/private/{ruleset_uuid}

Return Cloud Servers visible to the authenticated account that are related to a private firewall ruleset, including each Cloud Server's private ruleset relationships.

ruleset_uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Firewall ruleset UUID

Universally unique identifier

Cloud Servers related to the firewall ruleset

Accessible Cloud Servers related to a private firewall ruleset and their private ruleset relationships.

firewallRulesetRelatedServers

object[] · required

Cloud Servers visible to the authenticated account that are related to the ruleset.

GET/1.3/server/firewall_ruleset_relationships/private/{ruleset_uuid}

curl https://api.upcloud.com/1.3/server/firewall_ruleset_relationships/private/:ruleset_uuid \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "servers": [
    {
      "attached_rulesets": [
        {
          "applied_version": "3",
          "created_at": 1787652930,
          "firewall_ruleset_uuid": "190f56d8-4b3f-4a89-9e5f-320fbc3d17c8",
          "last_applied_at": 1787652932,
          "server_uuid": "0077fa3d-32db-4b09-9f5f-30d9e9afb565",
          "type": "private",
          "updated_at": null,
          "version": "3"
        }
      ],
      "firewall": "on",
      "firewall_private": "on",
      "firewall_private_default_incoming_action": "drop",
      "firewall_private_default_outgoing_action": "accept",
      "title": "Application server",
      "uuid": "0077fa3d-32db-4b09-9f5f-30d9e9afb565"
    }
  ]
}

application/json

List Cloud Server labels

GET

https://api.upcloud.com

/1.3/server/labels

Returns the unique label key-value pairs used by Cloud Servers accessible to the current account.

List Cloud Server labels › Responses

Cloud Server labels returned successfully.

serverLabel[]

Unique label key-value pairs used by accessible Cloud Servers, sorted by key and then value. The array may be empty.

A key/value pair to label and categorize resources

serverLabel

key

string · required

Label key used to classify the resource

value

string · required

Value associated with the label key

GET/1.3/server/labels

curl https://api.upcloud.com/1.3/server/labels \
  --header 'Authorization: Bearer <token>'

Example Responses

[
  {
    "key": "env",
    "value": "production"
  },
  {
    "key": "team",
    "value": "platform"
  }
]

application/json

Get Cloud Server details

GET

https://api.upcloud.com

/1.3/server/{uuid}

Returns detailed information about a Cloud Server.

Get Cloud Server details › path Parameters

uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Cloud Server UUID

Universally unique identifier

Get Cloud Server details › Responses

Cloud Server details returned successfully.

Cloud Server object returned in responses

server

serverDetails · required

Detailed public information about a Cloud Server

GET/1.3/server/{uuid}

curl https://api.upcloud.com/1.3/server/:uuid \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "server": {
    "boot_order": "disk",
    "core_number": "12",
    "created": 1705320000,
    "firewall": "on",
    "host": 7653311107,
    "hostname": "server1.example.com",
    "labels": {
      "label": [
        {
          "key": "env",
          "value": "development"
        }
      ]
    },
    "license": "0",
    "memory_amount": "130048",
    "nic_model": "virtio",
    "plan": "GPU-12xCPU-128GB-2xL40S",
    "plan_ipv4_bytes": "3565675343",
    "plan_ipv6_bytes": "4534432",
    "remote_access_enabled": "yes",
    "remote_access_type": "vnc",
    "server_group": "0b3d85b4-b3be-46ca-a1e2-3b5d40d60fb1",
    "simple_backup": "0100,dailies",
    "state": "started",
    "storage_devices": {
      "storage_device": [
        {
          "address": "virtio:0",
          "boot_disk": "1",
          "labels": [],
          "storage": "012580a1-32a1-466e-a323-689ca16f2d43",
          "storage_encrypted": "yes",
          "storage_size": 20,
          "storage_title": "Operating system disk",
          "type": "disk"
        }
      ]
    },
    "tags": {
      "tag": [
        "DEV",
        "Ubuntu"
      ]
    },
    "timezone": "UTC",
    "title": "Development GPU server",
    "uuid": "0077fa3d-32db-4b09-9f5f-30d9e9afb565",
    "video_model": "cirrus",
    "zone": "fi-hel1"
  }
}

application/json

Modify an existing Cloud Server

PUT

https://api.upcloud.com

/1.3/server/{uuid}

Modifies an existing Cloud Server configuration.

Modify an existing Cloud Server › path Parameters

uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Cloud Server UUID

Universally unique identifier

Modify an existing Cloud Server › Request Body

Fields that can be changed on an existing Cloud Server

modifyServer

object · minProps: 1 · required

Modify an existing Cloud Server › Responses

Modified a Cloud Server

Cloud Server object returned in responses

server

serverDetails · required

Detailed public information about a Cloud Server

PUT/1.3/server/{uuid}

curl https://api.upcloud.com/1.3/server/:uuid \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "server": {
    "core_number": 8,
    "memory_amount": 16384,
    "plan": "custom"
  }
}'

Example Request Body

{
  "server": {
    "core_number": 8,
    "memory_amount": 16384,
    "plan": "custom"
  }
}

Example Responses

{
  "server": {
    "boot_order": "disk",
    "core_number": "12",
    "created": 1705320000,
    "firewall": "on",
    "host": 7653311107,
    "hostname": "server1.example.com",
    "labels": {
      "label": [
        {
          "key": "env",
          "value": "development"
        }
      ]
    },
    "license": "0",
    "memory_amount": "130048",
    "nic_model": "virtio",
    "plan": "GPU-12xCPU-128GB-2xL40S",
    "plan_ipv4_bytes": "3565675343",
    "plan_ipv6_bytes": "4534432",
    "remote_access_enabled": "yes",
    "remote_access_type": "vnc",
    "server_group": "0b3d85b4-b3be-46ca-a1e2-3b5d40d60fb1",
    "simple_backup": "0100,dailies",
    "state": "started",
    "storage_devices": {
      "storage_device": [
        {
          "address": "virtio:0",
          "boot_disk": "1",
          "labels": [],
          "storage": "012580a1-32a1-466e-a323-689ca16f2d43",
          "storage_encrypted": "yes",
          "storage_size": 20,
          "storage_title": "Operating system disk",
          "type": "disk"
        }
      ]
    },
    "tags": {
      "tag": [
        "DEV",
        "Ubuntu"
      ]
    },
    "timezone": "UTC",
    "title": "Development GPU server",
    "uuid": "0077fa3d-32db-4b09-9f5f-30d9e9afb565",
    "video_model": "cirrus",
    "zone": "fi-hel1"
  }
}

application/json

Delete a Cloud Server

DELETE

https://api.upcloud.com

/1.3/server/{uuid}

Deletes a stopped Cloud Server and releases its IP addresses. Deleting backups requires deleting the associated storage devices.

Delete a Cloud Server › path Parameters

uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Cloud Server UUID

Universally unique identifier

Delete a Cloud Server › query Parameters

storages

serverLegacyBoolean · enum

Whether to delete attached storage devices.

Boolean value accepted by the legacy API

Enum values:

false

true

yes

backups

string · enum

How to handle backups when deleting storage devices. The delete value is valid only when storages is set to a truthy value.

Enum values:

keep

keep_latest

delete

Delete a Cloud Server › Responses

Cloud Server deleted.

No data returned

DELETE/1.3/server/{uuid}

curl https://api.upcloud.com/1.3/server/:uuid \
  --request DELETE \
  --header 'Authorization: Bearer <token>'

Example Responses

No example specified for this content type

Attach a private firewall ruleset

POST

https://api.upcloud.com

/1.3/server/{uuid}/attach_firewall_ruleset/private

Attach a private, stateful firewall ruleset to a Cloud Server. The latest ruleset version is selected and applied to private network interfaces.

Attach a private firewall ruleset › path Parameters

uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Cloud Server UUID

Universally unique identifier

Attach a private firewall ruleset › Request Body

Parameters for attaching a private firewall ruleset to a Cloud Server.

serverAttachPrivateFirewallRuleset

object · required

Private firewall ruleset to attach.

Attach a private firewall ruleset › Responses

Private firewall ruleset relationship

Relationship between a Cloud Server and a firewall ruleset.

serverFirewallRulesetRelationship

firewall_ruleset_uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Universally unique identifier

server_uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Universally unique identifier

type

string · enum · required

Network interface class to which the ruleset applies.

Enum values:

public

private

POST/1.3/server/{uuid}/attach_firewall_ruleset/private

curl https://api.upcloud.com/1.3/server/:uuid/attach_firewall_ruleset/private \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "firewall_ruleset": {
    "firewall_ruleset_uuid": "190f56d8-4b3f-4a89-9e5f-320fbc3d17c8"
  }
}'

Example Request Body

{
  "firewall_ruleset": {
    "firewall_ruleset_uuid": "190f56d8-4b3f-4a89-9e5f-320fbc3d17c8"
  }
}

Example Responses

{
  "firewall_ruleset_uuid": "190f56d8-4b3f-4a89-9e5f-320fbc3d17c8",
  "server_uuid": "0077fa3d-32db-4b09-9f5f-30d9e9afb565",
  "type": "private"
}

application/json

Cancel a Cloud Server operation

POST

https://api.upcloud.com

/1.3/server/{uuid}/cancel

Cancels an operation while the Cloud Server is in maintenance state.

Cancel a Cloud Server operation › path Parameters

uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Cloud Server UUID

Universally unique identifier

Cancel a Cloud Server operation › Responses

Operation cancelled.

No data returned

POST/1.3/server/{uuid}/cancel

curl https://api.upcloud.com/1.3/server/:uuid/cancel \
  --request POST \
  --header 'Authorization: Bearer <token>'

Example Responses

No example specified for this content type

Eject the CD-ROM image from a Cloud Server

POST

https://api.upcloud.com

/1.3/server/{uuid}/cdrom/eject

Eject the storage from the Cloud Server's attached CD-ROM device.

Eject the CD-ROM image from a Cloud Server › path Parameters

uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Cloud Server UUID

Universally unique identifier

Eject the CD-ROM image from a Cloud Server › Responses

CD-ROM ejected; updated Cloud Server details

Cloud Server object returned in responses

server

serverDetails · required

Detailed public information about a Cloud Server

POST/1.3/server/{uuid}/cdrom/eject

curl https://api.upcloud.com/1.3/server/:uuid/cdrom/eject \
  --request POST \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "server": {
    "boot_order": "disk",
    "core_number": "12",
    "created": 1705320000,
    "firewall": "on",
    "host": 7653311107,
    "hostname": "server1.example.com",
    "labels": {
      "label": [
        {
          "key": "env",
          "value": "development"
        }
      ]
    },
    "license": "0",
    "memory_amount": "130048",
    "nic_model": "virtio",
    "plan": "GPU-12xCPU-128GB-2xL40S",
    "plan_ipv4_bytes": "3565675343",
    "plan_ipv6_bytes": "4534432",
    "remote_access_enabled": "yes",
    "remote_access_type": "vnc",
    "server_group": "0b3d85b4-b3be-46ca-a1e2-3b5d40d60fb1",
    "simple_backup": "0100,dailies",
    "state": "started",
    "storage_devices": {
      "storage_device": [
        {
          "address": "virtio:0",
          "boot_disk": "1",
          "labels": [],
          "storage": "012580a1-32a1-466e-a323-689ca16f2d43",
          "storage_encrypted": "yes",
          "storage_size": 20,
          "storage_title": "Operating system disk",
          "type": "disk"
        }
      ]
    },
    "tags": {
      "tag": [
        "DEV",
        "Ubuntu"
      ]
    },
    "timezone": "UTC",
    "title": "Development GPU server",
    "uuid": "0077fa3d-32db-4b09-9f5f-30d9e9afb565",
    "video_model": "cirrus",
    "zone": "fi-hel1"
  }
}

application/json

Load a CD-ROM image into a Cloud Server

POST

https://api.upcloud.com

/1.3/server/{uuid}/cdrom/load

Load a storage of type normal or cdrom into the Cloud Server's attached CD-ROM device. If media is already loaded, it is ejected first.

Load a CD-ROM image into a Cloud Server › path Parameters

uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Cloud Server UUID

Universally unique identifier

Load a CD-ROM image into a Cloud Server › Request Body

Parameters for loading a storage into a Cloud Server's CD-ROM device.

serverLoadCdrom

object · required

Storage to load into the attached CD-ROM device.

Load a CD-ROM image into a Cloud Server › Responses

CD-ROM image loaded

Cloud Server object returned in responses

server

serverDetails · required

Detailed public information about a Cloud Server

POST/1.3/server/{uuid}/cdrom/load

curl https://api.upcloud.com/1.3/server/:uuid/cdrom/load \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "storage_device": {
    "storage": "01000000-0000-4000-8000-000060010101"
  }
}'

Example Request Body

{
  "storage_device": {
    "storage": "01000000-0000-4000-8000-000060010101"
  }
}

Example Responses

{
  "server": {
    "boot_order": "disk",
    "core_number": "12",
    "created": 1705320000,
    "firewall": "on",
    "host": 7653311107,
    "hostname": "server1.example.com",
    "labels": {
      "label": [
        {
          "key": "env",
          "value": "development"
        }
      ]
    },
    "license": "0",
    "memory_amount": "130048",
    "nic_model": "virtio",
    "plan": "GPU-12xCPU-128GB-2xL40S",
    "plan_ipv4_bytes": "3565675343",
    "plan_ipv6_bytes": "4534432",
    "remote_access_enabled": "yes",
    "remote_access_type": "vnc",
    "server_group": "0b3d85b4-b3be-46ca-a1e2-3b5d40d60fb1",
    "simple_backup": "0100,dailies",
    "state": "started",
    "storage_devices": {
      "storage_device": [
        {
          "address": "virtio:0",
          "boot_disk": "1",
          "labels": [],
          "storage": "012580a1-32a1-466e-a323-689ca16f2d43",
          "storage_encrypted": "yes",
          "storage_size": 20,
          "storage_title": "Operating system disk",
          "type": "disk"
        }
      ]
    },
    "tags": {
      "tag": [
        "DEV",
        "Ubuntu"
      ]
    },
    "timezone": "UTC",
    "title": "Development GPU server",
    "uuid": "0077fa3d-32db-4b09-9f5f-30d9e9afb565",
    "video_model": "cirrus",
    "zone": "fi-hel1"
  }
}

application/json

Detach a private firewall ruleset

POST

https://api.upcloud.com

/1.3/server/{uuid}/detach_firewall_ruleset/private

Detach a private firewall ruleset from a Cloud Server and reapply private-interface firewall rules.

Detach a private firewall ruleset › path Parameters

uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Cloud Server UUID

Universally unique identifier

Detach a private firewall ruleset › Request Body

Parameters for detaching a private firewall ruleset from a Cloud Server.

serverDetachPrivateFirewallRuleset

object · required

Private firewall ruleset to detach.

Detach a private firewall ruleset › Responses

Private firewall ruleset relationship

Relationship between a Cloud Server and a firewall ruleset.

serverFirewallRulesetRelationship

firewall_ruleset_uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Universally unique identifier

server_uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Universally unique identifier

type

string · enum · required

Network interface class to which the ruleset applies.

Enum values:

public

private

POST/1.3/server/{uuid}/detach_firewall_ruleset/private

curl https://api.upcloud.com/1.3/server/:uuid/detach_firewall_ruleset/private \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "firewall_ruleset": {
    "firewall_ruleset_uuid": "190f56d8-4b3f-4a89-9e5f-320fbc3d17c8"
  }
}'

Example Request Body

{
  "firewall_ruleset": {
    "firewall_ruleset_uuid": "190f56d8-4b3f-4a89-9e5f-320fbc3d17c8"
  }
}

Example Responses

{
  "firewall_ruleset_uuid": "190f56d8-4b3f-4a89-9e5f-320fbc3d17c8",
  "server_uuid": "0077fa3d-32db-4b09-9f5f-30d9e9afb565",
  "type": "private"
}

application/json

List firewall rules

GET

https://api.upcloud.com

/1.3/server/{uuid}/firewall_rule

Return the Cloud Server firewall rules in evaluation order. Changes to firewall rules can take 1-2 minutes to take effect.

List firewall rules › path Parameters

uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Cloud Server UUID

Universally unique identifier

List firewall rules › Responses

A list of firewall rules

Ordered firewall rules configured for a Cloud Server.

serverFirewallRules

object · required

GET/1.3/server/{uuid}/firewall_rule

curl https://api.upcloud.com/1.3/server/:uuid/firewall_rule \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "firewall_rules": {
    "firewall_rule": [
      {
        "action": "accept",
        "comment": "Allow SSH from the office network",
        "destination_address_end": "",
        "destination_address_start": "",
        "destination_port_end": "22",
        "destination_port_start": "22",
        "direction": "in",
        "family": "IPv4",
        "icmp_type": "",
        "position": "1",
        "protocol": "tcp",
        "source_address_end": "192.0.2.255",
        "source_address_start": "192.0.2.1",
        "source_port_end": "",
        "source_port_start": ""
      }
    ]
  }
}

application/json

Replace firewall rules

PUT

https://api.upcloud.com

/1.3/server/{uuid}/firewall_rule

Replace the Cloud Server's complete firewall rule chain. Array order determines rule positions. Changes can take 1-2 minutes to take effect.

Replace firewall rules › path Parameters

uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Cloud Server UUID

Universally unique identifier

Replace firewall rules › Request Body

Complete replacement for a Cloud Server's firewall rule chain. Array order determines rule positions.

serverUpdateFirewallRules

object · required

Replace firewall rules › Responses

Firewall rules replaced

No data returned

PUT/1.3/server/{uuid}/firewall_rule

curl https://api.upcloud.com/1.3/server/:uuid/firewall_rule \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "firewall_rules": {
    "firewall_rule": [
      {
        "action": "accept",
        "comment": "Allow SSH",
        "destination_port_end": "22",
        "destination_port_start": "22",
        "direction": "in",
        "family": "IPv4",
        "protocol": "tcp"
      },
      {
        "action": "drop",
        "direction": "in"
      }
    ]
  }
}'

Example Request Body

{
  "firewall_rules": {
    "firewall_rule": [
      {
        "action": "accept",
        "comment": "Allow SSH",
        "destination_port_end": "22",
        "destination_port_start": "22",
        "direction": "in",
        "family": "IPv4",
        "protocol": "tcp"
      },
      {
        "action": "drop",
        "direction": "in"
      }
    ]
  }
}

Example Responses

No example specified for this content type

Create a firewall rule

POST

https://api.upcloud.com

/1.3/server/{uuid}/firewall_rule

Create a firewall rule. Rules are evaluated in position order; if position is omitted, the rule is appended. Changes can take 1-2 minutes to take effect.

Create a firewall rule › path Parameters

uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Cloud Server UUID

Universally unique identifier

Create a firewall rule › Request Body

Parameters for creating a firewall rule.

serverCreateFirewallRule

object · required

Create a firewall rule › Responses

Created firewall rule

A firewall rule with its position in the Cloud Server's rule chain.

serverFirewallRule

serverFirewallRuleResponseItem · required

A firewall rule with its position in the Cloud Server's rule chain.

POST/1.3/server/{uuid}/firewall_rule

curl https://api.upcloud.com/1.3/server/:uuid/firewall_rule \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "firewall_rule": {
    "action": "accept",
    "comment": "Allow SSH from the office network",
    "destination_port_end": "22",
    "destination_port_start": "22",
    "direction": "in",
    "family": "IPv4",
    "position": "1",
    "protocol": "tcp",
    "source_address_end": "192.0.2.255",
    "source_address_start": "192.0.2.1"
  }
}'

Example Request Body

{
  "firewall_rule": {
    "action": "accept",
    "comment": "Allow SSH from the office network",
    "destination_port_end": "22",
    "destination_port_start": "22",
    "direction": "in",
    "family": "IPv4",
    "position": "1",
    "protocol": "tcp",
    "source_address_end": "192.0.2.255",
    "source_address_start": "192.0.2.1"
  }
}

Example Responses

{
  "firewall_rule": {
    "action": "accept",
    "comment": "Allow SSH from the office network",
    "destination_address_end": "",
    "destination_address_start": "",
    "destination_port_end": "22",
    "destination_port_start": "22",
    "direction": "in",
    "family": "IPv4",
    "icmp_type": "",
    "position": "1",
    "protocol": "tcp",
    "source_address_end": "192.0.2.255",
    "source_address_start": "192.0.2.1",
    "source_port_end": "",
    "source_port_start": ""
  }
}

application/json

Get a firewall rule

GET

https://api.upcloud.com

/1.3/server/{uuid}/firewall_rule/{position}

Return the firewall rule at the specified one-based position in the Cloud Server rule chain.

Get a firewall rule › path Parameters

uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Cloud Server UUID

Universally unique identifier

position

integer · int32 · min: 1 · max: 1000 · required

Firewall rule position

Get a firewall rule › Responses

Firewall rule details

A firewall rule with its position in the Cloud Server's rule chain.

serverFirewallRule

serverFirewallRuleResponseItem · required

A firewall rule with its position in the Cloud Server's rule chain.

GET/1.3/server/{uuid}/firewall_rule/{position}

curl https://api.upcloud.com/1.3/server/:uuid/firewall_rule/:position \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "firewall_rule": {
    "action": "accept",
    "comment": "Allow SSH from the office network",
    "destination_address_end": "",
    "destination_address_start": "",
    "destination_port_end": "22",
    "destination_port_start": "22",
    "direction": "in",
    "family": "IPv4",
    "icmp_type": "",
    "position": "1",
    "protocol": "tcp",
    "source_address_end": "192.0.2.255",
    "source_address_start": "192.0.2.1",
    "source_port_end": "",
    "source_port_start": ""
  }
}

application/json

Delete a firewall rule

DELETE

https://api.upcloud.com

/1.3/server/{uuid}/firewall_rule/{position}

Delete the firewall rule at the specified one-based position. Remaining rules are renumbered. Changes can take 1-2 minutes to take effect.

Delete a firewall rule › path Parameters

uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Cloud Server UUID

Universally unique identifier

position

integer · int32 · min: 1 · max: 1000 · required

Firewall rule position

Delete a firewall rule › Responses

Success

No data returned

DELETE/1.3/server/{uuid}/firewall_rule/{position}

curl https://api.upcloud.com/1.3/server/:uuid/firewall_rule/:position \
  --request DELETE \
  --header 'Authorization: Bearer <token>'

Example Responses

No example specified for this content type

List private firewall ruleset relationships for a Cloud Server

GET

https://api.upcloud.com

/1.3/server/{uuid}/firewall_ruleset_relationships/private

Return all private firewall ruleset relationships configured for a Cloud Server.

List private firewall ruleset relationships for a Cloud Server › path Parameters

uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Cloud Server UUID

Universally unique identifier

List private firewall ruleset relationships for a Cloud Server › Responses

Private firewall ruleset relationships

Private firewall ruleset relationships for a Cloud Server.

serverFirewallRulesetRelationships

object · required

GET/1.3/server/{uuid}/firewall_ruleset_relationships/private

curl https://api.upcloud.com/1.3/server/:uuid/firewall_ruleset_relationships/private \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "firewall_ruleset_relationships": {
    "private": [
      {
        "applied_version": "3",
        "created_at": "2026-08-25T10:15:30Z",
        "firewall_ruleset_uuid": "190f56d8-4b3f-4a89-9e5f-320fbc3d17c8",
        "last_applied_at": "2026-08-25T10:15:32Z",
        "server_uuid": "0077fa3d-32db-4b09-9f5f-30d9e9afb565",
        "type": "private",
        "updated_at": null,
        "version": "3"
      }
    ]
  }
}

application/json

List Cloud Server GPUs

GET

https://api.upcloud.com

/1.3/server/{uuid}/gpus

Returns GPUs attached to a Cloud Server.

List Cloud Server GPUs › path Parameters

uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Cloud Server UUID

Universally unique identifier

List Cloud Server GPUs › Responses

GPU list returned successfully.

GPUs attached to a Cloud Server. The array is empty when no GPUs are attached.

serverGpus

object[] · required

GET/1.3/server/{uuid}/gpus

curl https://api.upcloud.com/1.3/server/:uuid/gpus \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "gpus": [
    {
      "cores": 5888,
      "firmware": "92.00.18.00.01",
      "memory_gib": 24,
      "model": "NVIDIA RTX A5000",
      "part": "900-5G132-2500-000",
      "serial": "GPU-01234567"
    }
  ]
}

application/json

Get Cloud Server networking details

GET

https://api.upcloud.com

/1.3/server/{uuid}/networking

Return all network interfaces and IP addresses configured for a Cloud Server.

Get Cloud Server networking details › path Parameters

uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Cloud Server UUID

Universally unique identifier

Get Cloud Server networking details › Responses

Cloud Server networking details

Cloud Server networking response

serverNetworkingResponse

serverNetworking · required

Network interfaces configured for the Cloud Server

GET/1.3/server/{uuid}/networking

curl https://api.upcloud.com/1.3/server/:uuid/networking \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "networking": {
    "interfaces": {
      "interface": [
        {
          "bootable": "no",
          "index": 4,
          "ip_addresses": {
            "ip_address": [
              {
                "address": "10.0.0.20",
                "dhcp_provided": "yes",
                "family": "IPv4",
                "floating": "no",
                "release_policy": "release"
              }
            ]
          },
          "mac": "de:ff:ff:ff:cc:20",
          "network": "0374ce47-4303-4490-987d-32dc96cfd79b",
          "source_ip_filtering": "yes",
          "type": "private"
        }
      ]
    }
  }
}

application/json

Add a network interface

POST

https://api.upcloud.com

/1.3/server/{uuid}/networking/interface

Add a network interface to a stopped Cloud Server. A private interface must identify the SDN network to attach. The combined limit of network interfaces and storage devices is 24.

Add a network interface › path Parameters

uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Cloud Server UUID

Universally unique identifier

Add a network interface › Request Body

Add network interface request

serverAddInterface

object · required

Add a network interface › Responses

Network interface added

Network interface response

serverInterfaceResponse

serverInterface · required

Network interface attached to a Cloud Server

POST/1.3/server/{uuid}/networking/interface

curl https://api.upcloud.com/1.3/server/:uuid/networking/interface \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "interface": {
    "ip_addresses": {
      "ip_address": [
        {
          "address": "10.0.0.20",
          "dhcp_provided": "yes",
          "family": "IPv4"
        }
      ]
    },
    "network": "0374ce47-4303-4490-987d-32dc96cfd79b",
    "source_ip_filtering": "yes",
    "type": "private"
  }
}'

Example Request Body

{
  "interface": {
    "ip_addresses": {
      "ip_address": [
        {
          "address": "10.0.0.20",
          "dhcp_provided": "yes",
          "family": "IPv4"
        }
      ]
    },
    "network": "0374ce47-4303-4490-987d-32dc96cfd79b",
    "source_ip_filtering": "yes",
    "type": "private"
  }
}

Example Responses

{
  "interface": {
    "bootable": "no",
    "index": 4,
    "ip_addresses": {
      "ip_address": [
        {
          "address": "10.0.0.20",
          "dhcp_provided": "yes",
          "family": "IPv4",
          "floating": "no",
          "release_policy": "release"
        }
      ]
    },
    "mac": "de:ff:ff:ff:cc:20",
    "network": "0374ce47-4303-4490-987d-32dc96cfd79b",
    "source_ip_filtering": "yes",
    "type": "private"
  }
}

application/json

Modify a network interface

PUT

https://api.upcloud.com

/1.3/server/{uuid}/networking/interface/{index}

Modify the IP addresses, source IP filtering, boot setting, or index of a network interface on a stopped Cloud Server. Changing the interface network or type is not supported.

Modify a network interface › path Parameters

uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Cloud Server UUID

Universally unique identifier

index

integer · int32 · min: 1 · required

Network interface index

Modify a network interface › Request Body

Modify network interface request

serverModifyInterface

object · minProps: 1 · required

Modify a network interface › Responses

Network interface modified

Network interface response

serverInterfaceResponse

serverInterface · required

Network interface attached to a Cloud Server

PUT/1.3/server/{uuid}/networking/interface/{index}

curl https://api.upcloud.com/1.3/server/:uuid/networking/interface/:index \
  --request PUT \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "interface": {
    "bootable": "yes",
    "index": 5,
    "source_ip_filtering": "no"
  }
}'

Example Request Body

{
  "interface": {
    "bootable": "yes",
    "index": 5,
    "source_ip_filtering": "no"
  }
}

Example Responses

{
  "interface": {
    "bootable": "no",
    "index": 4,
    "ip_addresses": {
      "ip_address": [
        {
          "address": "10.0.0.20",
          "dhcp_provided": "yes",
          "family": "IPv4",
          "floating": "no",
          "release_policy": "release"
        }
      ]
    },
    "mac": "de:ff:ff:ff:cc:20",
    "network": "0374ce47-4303-4490-987d-32dc96cfd79b",
    "source_ip_filtering": "yes",
    "type": "private"
  }
}

application/json

Delete a network interface

DELETE

https://api.upcloud.com

/1.3/server/{uuid}/networking/interface/{index}

Delete a network interface from a stopped Cloud Server. IP addresses attached to the interface are released according to their release policies.

Delete a network interface › path Parameters

uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Cloud Server UUID

Universally unique identifier

index

integer · int32 · min: 1 · required

Network interface index

Delete a network interface › Responses

Success

No data returned

DELETE/1.3/server/{uuid}/networking/interface/{index}

curl https://api.upcloud.com/1.3/server/:uuid/networking/interface/:index \
  --request DELETE \
  --header 'Authorization: Bearer <token>'

Example Responses

No example specified for this content type

Add an IP address to a network interface

POST

https://api.upcloud.com

/1.3/server/{uuid}/networking/interface/{index}/ip_address

Add an IPv4 or IPv6 address to a private network interface. The interface cannot contain addresses from both families and can have at most five addresses.

Add an IP address to a network interface › path Parameters

uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Cloud Server UUID

Universally unique identifier

index

integer · int32 · min: 1 · required

Network interface index

Add an IP address to a network interface › query Parameters

force

serverBooleanYesno · enum

Move the address from another interface when that interface can retain its required minimum number of addresses

Boolean value represented as yes/no

Enum values:

yes

Add an IP address to a network interface › Request Body

Add IP address to a network interface request

serverAddIpAddress

object · required

Add an IP address to a network interface › Responses

IP address added

IP address response for a network interface

serverIpAddressInterfaceResponse

serverInterfaceIpAddress · required

Network interface IP address

POST/1.3/server/{uuid}/networking/interface/{index}/ip_address

curl https://api.upcloud.com/1.3/server/:uuid/networking/interface/:index/ip_address \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "ip_address": {
    "address": "10.0.0.30",
    "family": "IPv4"
  }
}'

Example Request Body

{
  "ip_address": {
    "address": "10.0.0.30",
    "family": "IPv4"
  }
}

Example Responses

{
  "ip_address": {
    "address": "10.0.0.30",
    "dhcp_provided": "no",
    "family": "IPv4"
  }
}

application/json

Delete an IP address from a network interface

DELETE

https://api.upcloud.com

/1.3/server/{uuid}/networking/interface/{index}/ip_address/{ip}

Delete an IP address from a private network interface. At least one IP address must remain attached to the interface.

Delete an IP address from a network interface › path Parameters

uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Cloud Server UUID

Universally unique identifier

index

integer · int32 · min: 1 · required

Network interface index

ip

serverIpAddress · required

IP address to delete

IP address

Delete an IP address from a network interface › Responses

Success

No data returned

DELETE/1.3/server/{uuid}/networking/interface/{index}/ip_address/{ip}

curl https://api.upcloud.com/1.3/server/:uuid/networking/interface/:index/ip_address/:ip \
  --request DELETE \
  --header 'Authorization: Bearer <token>'

Example Responses

No example specified for this content type

Rebuild a Cloud Server

POST

https://api.upcloud.com

/1.3/server/{uuid}/rebuild

Reinstalls a stopped Cloud Server from a public template.

Rebuild a Cloud Server › path Parameters

uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Cloud Server UUID

Universally unique identifier

Rebuild a Cloud Server › Request Body

Rebuild Cloud Server request

serverRebuild

object · required

Rebuild a Cloud Server › Responses

Cloud Server rebuild initiated.

Cloud Server object returned in responses

server

serverDetails · required

Detailed public information about a Cloud Server

POST/1.3/server/{uuid}/rebuild

curl https://api.upcloud.com/1.3/server/:uuid/rebuild \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "server_rebuild": {
    "clone_source": "01000000-0000-4000-8000-000020050100",
    "delete_detached_disk": "yes",
    "detach_disk": "0169b4f8-051c-4a86-9484-f5b798249949",
    "encrypted": "yes",
    "login_user": {
      "create_password": "no",
      "ssh_keys": {
        "ssh_key": [
          "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIEexamplekey user@example"
        ]
      },
      "username": "debian"
    },
    "password_delivery": "none",
    "storage_title": "Rebuilt system disk"
  }
}'

Example Request Body

{
  "server_rebuild": {
    "clone_source": "01000000-0000-4000-8000-000020050100",
    "delete_detached_disk": "yes",
    "detach_disk": "0169b4f8-051c-4a86-9484-f5b798249949",
    "encrypted": "yes",
    "login_user": {
      "create_password": "no",
      "ssh_keys": {
        "ssh_key": [
          "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIEexamplekey user@example"
        ]
      },
      "username": "debian"
    },
    "password_delivery": "none",
    "storage_title": "Rebuilt system disk"
  }
}

Example Responses

{
  "server": {
    "boot_order": "disk",
    "core_number": "12",
    "created": 1705320000,
    "firewall": "on",
    "host": 7653311107,
    "hostname": "server1.example.com",
    "labels": {
      "label": [
        {
          "key": "env",
          "value": "development"
        }
      ]
    },
    "license": "0",
    "memory_amount": "130048",
    "nic_model": "virtio",
    "plan": "GPU-12xCPU-128GB-2xL40S",
    "plan_ipv4_bytes": "3565675343",
    "plan_ipv6_bytes": "4534432",
    "remote_access_enabled": "yes",
    "remote_access_type": "vnc",
    "server_group": "0b3d85b4-b3be-46ca-a1e2-3b5d40d60fb1",
    "simple_backup": "0100,dailies",
    "state": "started",
    "storage_devices": {
      "storage_device": [
        {
          "address": "virtio:0",
          "boot_disk": "1",
          "labels": [],
          "storage": "012580a1-32a1-466e-a323-689ca16f2d43",
          "storage_encrypted": "yes",
          "storage_size": 20,
          "storage_title": "Operating system disk",
          "type": "disk"
        }
      ]
    },
    "tags": {
      "tag": [
        "DEV",
        "Ubuntu"
      ]
    },
    "timezone": "UTC",
    "title": "Development GPU server",
    "uuid": "0077fa3d-32db-4b09-9f5f-30d9e9afb565",
    "video_model": "cirrus",
    "zone": "fi-hel1"
  }
}

application/json

Relocate a Cloud Server to another zone

POST

https://api.upcloud.com

/1.3/server/{uuid}/relocate

Relocates a stopped Cloud Server to another zone in the same physical location (datacenter).

Relocate a Cloud Server to another zone › path Parameters

uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Cloud Server UUID

Universally unique identifier

Relocate a Cloud Server to another zone › Request Body

Relocate Cloud Server request

relocateServer

zone

serverZone · minLength: 2 · maxLength: 15 · pattern: ^[a-z][a-z0-9-]{0,14… · required

Zone identifier

Example: fi-hel1

Relocate a Cloud Server to another zone › Responses

Cloud Server relocated.

Cloud Server object returned in responses

server

serverDetails · required

Detailed public information about a Cloud Server

POST/1.3/server/{uuid}/relocate

curl https://api.upcloud.com/1.3/server/:uuid/relocate \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "zone": "fi-hel2"
}'

Example Request Body

{
  "zone": "fi-hel2"
}

Example Responses

{
  "server": {
    "boot_order": "disk",
    "core_number": "12",
    "created": 1705320000,
    "firewall": "on",
    "host": 7653311107,
    "hostname": "server1.example.com",
    "labels": {
      "label": [
        {
          "key": "env",
          "value": "development"
        }
      ]
    },
    "license": "0",
    "memory_amount": "130048",
    "nic_model": "virtio",
    "plan": "GPU-12xCPU-128GB-2xL40S",
    "plan_ipv4_bytes": "3565675343",
    "plan_ipv6_bytes": "4534432",
    "remote_access_enabled": "yes",
    "remote_access_type": "vnc",
    "server_group": "0b3d85b4-b3be-46ca-a1e2-3b5d40d60fb1",
    "simple_backup": "0100,dailies",
    "state": "started",
    "storage_devices": {
      "storage_device": [
        {
          "address": "virtio:0",
          "boot_disk": "1",
          "labels": [],
          "storage": "012580a1-32a1-466e-a323-689ca16f2d43",
          "storage_encrypted": "yes",
          "storage_size": 20,
          "storage_title": "Operating system disk",
          "type": "disk"
        }
      ]
    },
    "tags": {
      "tag": [
        "DEV",
        "Ubuntu"
      ]
    },
    "timezone": "UTC",
    "title": "Development GPU server",
    "uuid": "0077fa3d-32db-4b09-9f5f-30d9e9afb565",
    "video_model": "cirrus",
    "zone": "fi-hel1"
  }
}

application/json

Get remote access connection details

GET

https://api.upcloud.com

/1.3/server/{uuid}/remote_access_details

Returns remote access settings and VNC connection details for a Cloud Server.

Get remote access connection details › path Parameters

uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Cloud Server UUID

Universally unique identifier

Get remote access connection details › Responses

Remote access details returned.

Remote access settings and VNC connection details for a Cloud Server

serverRemoteAccessDetails

object · required

GET/1.3/server/{uuid}/remote_access_details

curl https://api.upcloud.com/1.3/server/:uuid/remote_access_details \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "server": {
    "remote_access_enabled": "yes",
    "remote_access_password": "A1b2C3d4",
    "remote_access_type": "vnc",
    "state": "started",
    "vnc_host": "94.237.1.20",
    "vnc_password": "A1b2C3d4",
    "vnc_port": 5901
  }
}

application/json

Restart a Cloud Server

POST

https://api.upcloud.com

/1.3/server/{uuid}/restart

Stops and starts a Cloud Server in started state.

Restart a Cloud Server › path Parameters

uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Cloud Server UUID

Universally unique identifier

Restart a Cloud Server › Request Body

Restart Cloud Server request

restartServer

object · required

Restart a Cloud Server › Responses

Cloud Server restart initiated.

Cloud Server object returned in responses

server

serverDetails · required

Detailed public information about a Cloud Server

POST/1.3/server/{uuid}/restart

curl https://api.upcloud.com/1.3/server/:uuid/restart \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "restart_server": {
    "stop_type": "soft",
    "timeout": "60",
    "timeout_action": "destroy"
  }
}'

Example Request Body

{
  "restart_server": {
    "stop_type": "soft",
    "timeout": "60",
    "timeout_action": "destroy"
  }
}

Example Responses

{
  "server": {
    "boot_order": "disk",
    "core_number": "12",
    "created": 1705320000,
    "firewall": "on",
    "host": 7653311107,
    "hostname": "server1.example.com",
    "labels": {
      "label": [
        {
          "key": "env",
          "value": "development"
        }
      ]
    },
    "license": "0",
    "memory_amount": "130048",
    "nic_model": "virtio",
    "plan": "GPU-12xCPU-128GB-2xL40S",
    "plan_ipv4_bytes": "3565675343",
    "plan_ipv6_bytes": "4534432",
    "remote_access_enabled": "yes",
    "remote_access_type": "vnc",
    "server_group": "0b3d85b4-b3be-46ca-a1e2-3b5d40d60fb1",
    "simple_backup": "0100,dailies",
    "state": "started",
    "storage_devices": {
      "storage_device": [
        {
          "address": "virtio:0",
          "boot_disk": "1",
          "labels": [],
          "storage": "012580a1-32a1-466e-a323-689ca16f2d43",
          "storage_encrypted": "yes",
          "storage_size": 20,
          "storage_title": "Operating system disk",
          "type": "disk"
        }
      ]
    },
    "tags": {
      "tag": [
        "DEV",
        "Ubuntu"
      ]
    },
    "timezone": "UTC",
    "title": "Development GPU server",
    "uuid": "0077fa3d-32db-4b09-9f5f-30d9e9afb565",
    "video_model": "cirrus",
    "zone": "fi-hel1"
  }
}

application/json

Start a Cloud Server

POST

https://api.upcloud.com

/1.3/server/{uuid}/start

Starts a Cloud Server in stopped state.

Start a Cloud Server › path Parameters

uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Cloud Server UUID

Universally unique identifier

Start a Cloud Server › Request Body

Start Cloud Server request

startServer

object · required

Start a Cloud Server › Responses

Cloud Server start initiated.

Cloud Server object returned in responses

server

serverDetails · required

Detailed public information about a Cloud Server

POST/1.3/server/{uuid}/start

curl https://api.upcloud.com/1.3/server/:uuid/start \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "server": {
    "host": 8055964291,
    "start_type": "sync"
  }
}'

Example Request Body

{
  "server": {
    "host": 8055964291,
    "start_type": "sync"
  }
}

Example Responses

{
  "server": {
    "boot_order": "disk",
    "core_number": "12",
    "created": 1705320000,
    "firewall": "on",
    "host": 7653311107,
    "hostname": "server1.example.com",
    "labels": {
      "label": [
        {
          "key": "env",
          "value": "development"
        }
      ]
    },
    "license": "0",
    "memory_amount": "130048",
    "nic_model": "virtio",
    "plan": "GPU-12xCPU-128GB-2xL40S",
    "plan_ipv4_bytes": "3565675343",
    "plan_ipv6_bytes": "4534432",
    "remote_access_enabled": "yes",
    "remote_access_type": "vnc",
    "server_group": "0b3d85b4-b3be-46ca-a1e2-3b5d40d60fb1",
    "simple_backup": "0100,dailies",
    "state": "started",
    "storage_devices": {
      "storage_device": [
        {
          "address": "virtio:0",
          "boot_disk": "1",
          "labels": [],
          "storage": "012580a1-32a1-466e-a323-689ca16f2d43",
          "storage_encrypted": "yes",
          "storage_size": 20,
          "storage_title": "Operating system disk",
          "type": "disk"
        }
      ]
    },
    "tags": {
      "tag": [
        "DEV",
        "Ubuntu"
      ]
    },
    "timezone": "UTC",
    "title": "Development GPU server",
    "uuid": "0077fa3d-32db-4b09-9f5f-30d9e9afb565",
    "video_model": "cirrus",
    "zone": "fi-hel1"
  }
}

application/json

Get Cloud Server CPU statistics

GET

https://api.upcloud.com

/1.3/server/{uuid}/stats/cpu

Returns CPU usage statistics for all supported periods.

Get Cloud Server CPU statistics › path Parameters

uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Cloud Server UUID

Universally unique identifier

Get Cloud Server CPU statistics › Responses

CPU statistics returned.

CPU usage statistics grouped by period

serverCpuStats

object · minProps: 1 · required

GET/1.3/server/{uuid}/stats/cpu

curl https://api.upcloud.com/1.3/server/:uuid/stats/cpu \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "stats": {
    "daily": {
      "summary": {
        "variable": [
          {
            "average": "12 %",
            "current": "8 %",
            "maximum": "37 %",
            "title": "CPU usage %",
            "total": "51 seconds"
          }
        ]
      }
    }
  }
}

application/json

Get Cloud Server CPU statistics by period

GET

https://api.upcloud.com

/1.3/server/{uuid}/stats/cpu/{period}

Returns CPU usage statistics for the selected period.

Get Cloud Server CPU statistics by period › path Parameters

uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Cloud Server UUID

Universally unique identifier

period

serverStatsPeriod · enum · required

Statistics period.

The period for which statistics are calculated.

Enum values:

daily

weekly

monthly

yearly

Get Cloud Server CPU statistics by period › Responses

CPU statistics returned.

CPU usage statistics grouped by period

serverCpuStats

object · minProps: 1 · required

GET/1.3/server/{uuid}/stats/cpu/{period}

curl https://api.upcloud.com/1.3/server/:uuid/stats/cpu/:period \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "stats": {
    "daily": {
      "summary": {
        "variable": [
          {
            "average": "12 %",
            "current": "8 %",
            "maximum": "37 %",
            "title": "CPU usage %",
            "total": "51 seconds"
          }
        ]
      }
    }
  }
}

application/json

Get Cloud Server disk statistics

GET

https://api.upcloud.com

/1.3/server/{uuid}/stats/disk/{type}

Returns aggregate disk read and write statistics for all supported periods.

Get Cloud Server disk statistics › path Parameters

uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Cloud Server UUID

Universally unique identifier

type

string · enum · required

Measure disk activity as transferred bytes or I/O requests.

Enum values:

bytes

requests

Get Cloud Server disk statistics › Responses

Disk statistics returned.

Aggregate disk read and write statistics grouped by period

serverDiskStats

object · minProps: 1 · required

GET/1.3/server/{uuid}/stats/disk/{type}

curl https://api.upcloud.com/1.3/server/:uuid/stats/disk/:type \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "stats": {
    "daily": {
      "summary": {
        "variable": [
          {
            "average": "1.5 MiBps",
            "current": "2.0 MiBps",
            "maximum": "4.0 MiBps",
            "title": "Read",
            "total": "8.0 GiB"
          }
        ]
      }
    }
  }
}

application/json

Get Cloud Server disk statistics by period

GET

https://api.upcloud.com

/1.3/server/{uuid}/stats/disk/{type}/{period}

Returns aggregate disk read and write statistics for the selected period.

Get Cloud Server disk statistics by period › path Parameters

uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Cloud Server UUID

Universally unique identifier

type

string · enum · required

Measure disk activity as transferred bytes or I/O requests.

Enum values:

bytes

requests

period

serverStatsPeriod · enum · required

Statistics period.

The period for which statistics are calculated.

Enum values:

daily

weekly

monthly

yearly

Get Cloud Server disk statistics by period › Responses

Disk statistics returned.

Aggregate disk read and write statistics grouped by period

serverDiskStats

object · minProps: 1 · required

GET/1.3/server/{uuid}/stats/disk/{type}/{period}

curl https://api.upcloud.com/1.3/server/:uuid/stats/disk/:type/:period \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "stats": {
    "daily": {
      "summary": {
        "variable": [
          {
            "average": "1.5 MiBps",
            "current": "2.0 MiBps",
            "maximum": "4.0 MiBps",
            "title": "Read",
            "total": "8.0 GiB"
          }
        ]
      }
    }
  }
}

application/json

Get Cloud Server network statistics

GET

https://api.upcloud.com

/1.3/server/{uuid}/stats/network/{type}

Returns aggregate inbound and outbound network statistics for all interfaces and periods.

Get Cloud Server network statistics › path Parameters

uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Cloud Server UUID

Universally unique identifier

type

serverStatsNetworkType · enum · required

Measure network activity as transferred bytes or packets.

Unit used to measure network activity.

Enum values:

bytes

packets

Get Cloud Server network statistics › Responses

Network statistics returned.

Aggregate inbound and outbound network statistics grouped by period

serverNetworkStats

object · minProps: 1 · required

GET/1.3/server/{uuid}/stats/network/{type}

curl https://api.upcloud.com/1.3/server/:uuid/stats/network/:type \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "stats": {
    "daily": {
      "summary": {
        "variable": [
          {
            "average": "12 Mbps",
            "current": "8.5 Mbps",
            "maximum": "24 Mbps",
            "title": "In",
            "total": "8.0 GiB"
          }
        ]
      }
    }
  }
}

application/json

Get Cloud Server network statistics by network type

GET

https://api.upcloud.com

/1.3/server/{uuid}/stats/network/{type}/{network}

Returns inbound and outbound network statistics for the selected network type and all periods.

Get Cloud Server network statistics by network type › path Parameters

uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Cloud Server UUID

Universally unique identifier

type

serverStatsNetworkType · enum · required

Measure network activity as transferred bytes or packets.

Unit used to measure network activity.

Enum values:

bytes

packets

network

serverNetworkType · enum · required

Network access type to aggregate.

Network access type

Enum values:

public

utility

private

Get Cloud Server network statistics by network type › Responses

Network statistics returned.

Aggregate inbound and outbound network statistics grouped by period

serverNetworkStats

object · minProps: 1 · required

GET/1.3/server/{uuid}/stats/network/{type}/{network}

curl https://api.upcloud.com/1.3/server/:uuid/stats/network/:type/:network \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "stats": {
    "daily": {
      "summary": {
        "variable": [
          {
            "average": "12 Mbps",
            "current": "8.5 Mbps",
            "maximum": "24 Mbps",
            "title": "In",
            "total": "8.0 GiB"
          }
        ]
      }
    }
  }
}

application/json

Get Cloud Server network statistics by network type and period

GET

https://api.upcloud.com

/1.3/server/{uuid}/stats/network/{type}/{network}/{period}

Returns inbound and outbound network statistics for the selected network type and period.

Get Cloud Server network statistics by network type and period › path Parameters

uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Cloud Server UUID

Universally unique identifier

type

serverStatsNetworkType · enum · required

Measure network activity as transferred bytes or packets.

Unit used to measure network activity.

Enum values:

bytes

packets

network

serverNetworkType · enum · required

Network access type to aggregate.

Network access type

Enum values:

public

utility

private

period

serverStatsPeriod · enum · required

Statistics period.

The period for which statistics are calculated.

Enum values:

daily

weekly

monthly

yearly

Get Cloud Server network statistics by network type and period › Responses

Network statistics returned.

Aggregate inbound and outbound network statistics grouped by period

serverNetworkStats

object · minProps: 1 · required

GET/1.3/server/{uuid}/stats/network/{type}/{network}/{period}

curl https://api.upcloud.com/1.3/server/:uuid/stats/network/:type/:network/:period \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "stats": {
    "daily": {
      "summary": {
        "variable": [
          {
            "average": "12 Mbps",
            "current": "8.5 Mbps",
            "maximum": "24 Mbps",
            "title": "In",
            "total": "8.0 GiB"
          }
        ]
      }
    }
  }
}

application/json

Stop a Cloud Server

POST

https://api.upcloud.com

/1.3/server/{uuid}/stop

Stops a Cloud Server in started state.

Stop a Cloud Server › path Parameters

uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Cloud Server UUID

Universally unique identifier

Stop a Cloud Server › Request Body

Stop Cloud Server request

stopServer

object · required

Stop a Cloud Server › Responses

Cloud Server stop initiated.

Cloud Server object returned in responses

server

serverDetails · required

Detailed public information about a Cloud Server

POST/1.3/server/{uuid}/stop

curl https://api.upcloud.com/1.3/server/:uuid/stop \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "stop_server": {
    "stop_type": "soft",
    "timeout": "60"
  }
}'

Example Request Body

{
  "stop_server": {
    "stop_type": "soft",
    "timeout": "60"
  }
}

Example Responses

{
  "server": {
    "boot_order": "disk",
    "core_number": "12",
    "created": 1705320000,
    "firewall": "on",
    "host": 7653311107,
    "hostname": "server1.example.com",
    "labels": {
      "label": [
        {
          "key": "env",
          "value": "development"
        }
      ]
    },
    "license": "0",
    "memory_amount": "130048",
    "nic_model": "virtio",
    "plan": "GPU-12xCPU-128GB-2xL40S",
    "plan_ipv4_bytes": "3565675343",
    "plan_ipv6_bytes": "4534432",
    "remote_access_enabled": "yes",
    "remote_access_type": "vnc",
    "server_group": "0b3d85b4-b3be-46ca-a1e2-3b5d40d60fb1",
    "simple_backup": "0100,dailies",
    "state": "started",
    "storage_devices": {
      "storage_device": [
        {
          "address": "virtio:0",
          "boot_disk": "1",
          "labels": [],
          "storage": "012580a1-32a1-466e-a323-689ca16f2d43",
          "storage_encrypted": "yes",
          "storage_size": 20,
          "storage_title": "Operating system disk",
          "type": "disk"
        }
      ]
    },
    "tags": {
      "tag": [
        "DEV",
        "Ubuntu"
      ]
    },
    "timezone": "UTC",
    "title": "Development GPU server",
    "uuid": "0077fa3d-32db-4b09-9f5f-30d9e9afb565",
    "video_model": "cirrus",
    "zone": "fi-hel1"
  }
}

application/json

Attach a storage device to a Cloud Server

POST

https://api.upcloud.com

/1.3/server/{uuid}/storage/attach

Attach a storage resource as a disk or CD-ROM device to a Cloud Server. SCSI and virtio disks can be attached while the Cloud Server is started; IDE and CD-ROM devices require a stopped Cloud Server. An empty CD-ROM device can be attached without specifying a storage resource.

Attach a storage device to a Cloud Server › path Parameters

uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Cloud Server UUID

Universally unique identifier

Attach a storage device to a Cloud Server › Request Body

Parameters for attaching a storage device to a Cloud Server.

serverAttachStorage

object · required

Storage device to attach.

Attach a storage device to a Cloud Server › Responses

Storage device attached

Cloud Server object returned in responses

server

serverDetails · required

Detailed public information about a Cloud Server

POST/1.3/server/{uuid}/storage/attach

curl https://api.upcloud.com/1.3/server/:uuid/storage/attach \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "storage_device": {
    "address": "virtio:0",
    "boot_disk": 1,
    "storage": "012580a1-32a1-466e-a323-689ca16f2d43",
    "type": "disk"
  }
}'

Example Request Body

{
  "storage_device": {
    "address": "virtio:0",
    "boot_disk": 1,
    "storage": "012580a1-32a1-466e-a323-689ca16f2d43",
    "type": "disk"
  }
}

Example Responses

{
  "server": {
    "boot_order": "disk",
    "core_number": "12",
    "created": 1705320000,
    "firewall": "on",
    "host": 7653311107,
    "hostname": "server1.example.com",
    "labels": {
      "label": [
        {
          "key": "env",
          "value": "development"
        }
      ]
    },
    "license": "0",
    "memory_amount": "130048",
    "nic_model": "virtio",
    "plan": "GPU-12xCPU-128GB-2xL40S",
    "plan_ipv4_bytes": "3565675343",
    "plan_ipv6_bytes": "4534432",
    "remote_access_enabled": "yes",
    "remote_access_type": "vnc",
    "server_group": "0b3d85b4-b3be-46ca-a1e2-3b5d40d60fb1",
    "simple_backup": "0100,dailies",
    "state": "started",
    "storage_devices": {
      "storage_device": [
        {
          "address": "virtio:0",
          "boot_disk": "1",
          "labels": [],
          "storage": "012580a1-32a1-466e-a323-689ca16f2d43",
          "storage_encrypted": "yes",
          "storage_size": 20,
          "storage_title": "Operating system disk",
          "type": "disk"
        }
      ]
    },
    "tags": {
      "tag": [
        "DEV",
        "Ubuntu"
      ]
    },
    "timezone": "UTC",
    "title": "Development GPU server",
    "uuid": "0077fa3d-32db-4b09-9f5f-30d9e9afb565",
    "video_model": "cirrus",
    "zone": "fi-hel1"
  }
}

application/json

Detach a storage device from a Cloud Server

POST

https://api.upcloud.com

/1.3/server/{uuid}/storage/detach

Detach a storage device identified by its device address or storage resource UUID. IDE and CD-ROM devices cannot be detached while the Cloud Server is started.

Detach a storage device from a Cloud Server › path Parameters

uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Cloud Server UUID

Universally unique identifier

Detach a storage device from a Cloud Server › Request Body

Parameters for detaching a storage device from a Cloud Server.

serverDetachStorage

object · required

Storage device to detach, identified by either its device address or storage resource UUID.

Detach a storage device from a Cloud Server › Responses

Storage device detached

Cloud Server object returned in responses

server

serverDetails · required

Detailed public information about a Cloud Server

POST/1.3/server/{uuid}/storage/detach

curl https://api.upcloud.com/1.3/server/:uuid/storage/detach \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "storage_device": {
    "address": "virtio:0"
  }
}'

Example Request Body

{
  "storage_device": {
    "address": "virtio:0"
  }
}

Example Responses

{
  "server": {
    "boot_order": "disk",
    "core_number": "12",
    "created": 1705320000,
    "firewall": "on",
    "host": 7653311107,
    "hostname": "server1.example.com",
    "labels": {
      "label": [
        {
          "key": "env",
          "value": "development"
        }
      ]
    },
    "license": "0",
    "memory_amount": "130048",
    "nic_model": "virtio",
    "plan": "GPU-12xCPU-128GB-2xL40S",
    "plan_ipv4_bytes": "3565675343",
    "plan_ipv6_bytes": "4534432",
    "remote_access_enabled": "yes",
    "remote_access_type": "vnc",
    "server_group": "0b3d85b4-b3be-46ca-a1e2-3b5d40d60fb1",
    "simple_backup": "0100,dailies",
    "state": "started",
    "storage_devices": {
      "storage_device": [
        {
          "address": "virtio:0",
          "boot_disk": "1",
          "labels": [],
          "storage": "012580a1-32a1-466e-a323-689ca16f2d43",
          "storage_encrypted": "yes",
          "storage_size": 20,
          "storage_title": "Operating system disk",
          "type": "disk"
        }
      ]
    },
    "tags": {
      "tag": [
        "DEV",
        "Ubuntu"
      ]
    },
    "timezone": "UTC",
    "title": "Development GPU server",
    "uuid": "0077fa3d-32db-4b09-9f5f-30d9e9afb565",
    "video_model": "cirrus",
    "zone": "fi-hel1"
  }
}

application/json

Get VNC connection details

GET

https://api.upcloud.com

/1.3/server/{uuid}/vnc_details

Returns VNC connection details and remote access settings for a Cloud Server.

Get VNC connection details › path Parameters

uuid

serverUuid · uuid · pattern: ^[0-9a-f]{8}-[0-9a-f… · required

Cloud Server UUID

Universally unique identifier

Get VNC connection details › Responses

VNC connection details returned.

Remote access settings and VNC connection details for a Cloud Server

serverRemoteAccessDetails

object · required

GET/1.3/server/{uuid}/vnc_details

curl https://api.upcloud.com/1.3/server/:uuid/vnc_details \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "server": {
    "remote_access_enabled": "yes",
    "remote_access_password": "A1b2C3d4",
    "remote_access_type": "vnc",
    "state": "started",
    "vnc_host": "94.237.1.20",
    "vnc_password": "A1b2C3d4",
    "vnc_port": 5901
  }
}

application/json

Getting Started Server Group

Server

List Cloud Servers

List Cloud Servers › query Parameters

List Cloud Servers › Responses

Create a new Cloud Server

Create a new Cloud Server › Request Body

Create a new Cloud Server › Responses

List Cloud Servers related to a private firewall ruleset

List Cloud Servers related to a private firewall ruleset › path Parameters

List Cloud Servers related to a private firewall ruleset › Responses

List Cloud Server labels

List Cloud Server labels › Responses

Get Cloud Server details

Get Cloud Server details › path Parameters

Get Cloud Server details › Responses

Modify an existing Cloud Server

Modify an existing Cloud Server › path Parameters

Modify an existing Cloud Server › Request Body

Modify an existing Cloud Server › Responses

Delete a Cloud Server

Delete a Cloud Server › path Parameters

Delete a Cloud Server › query Parameters

Delete a Cloud Server › Responses

Attach a private firewall ruleset

Attach a private firewall ruleset › path Parameters

Attach a private firewall ruleset › Request Body

Attach a private firewall ruleset › Responses

Cancel a Cloud Server operation

Cancel a Cloud Server operation › path Parameters

Cancel a Cloud Server operation › Responses

Eject the CD-ROM image from a Cloud Server

Eject the CD-ROM image from a Cloud Server › path Parameters

Eject the CD-ROM image from a Cloud Server › Responses

Load a CD-ROM image into a Cloud Server

Load a CD-ROM image into a Cloud Server › path Parameters

Load a CD-ROM image into a Cloud Server › Request Body

Load a CD-ROM image into a Cloud Server › Responses

Detach a private firewall ruleset

Detach a private firewall ruleset › path Parameters

Detach a private firewall ruleset › Request Body

Detach a private firewall ruleset › Responses

List firewall rules

List firewall rules › path Parameters

List firewall rules › Responses

Replace firewall rules

Replace firewall rules › path Parameters

Replace firewall rules › Request Body

Replace firewall rules › Responses

Create a firewall rule

Create a firewall rule › path Parameters

Create a firewall rule › Request Body

Create a firewall rule › Responses

Get a firewall rule

Get a firewall rule › path Parameters

Get a firewall rule › Responses

Delete a firewall rule

Delete a firewall rule › path Parameters

Delete a firewall rule › Responses

List private firewall ruleset relationships for a Cloud Server

List private firewall ruleset relationships for a Cloud Server › path Parameters

List private firewall ruleset relationships for a Cloud Server › Responses

List Cloud Server GPUs

List Cloud Server GPUs › path Parameters

List Cloud Server GPUs › Responses

Get Cloud Server networking details

Get Cloud Server networking details › path Parameters

Get Cloud Server networking details › Responses

Add a network interface

Add a network interface › path Parameters

Add a network interface › Request Body

Add a network interface › Responses

Modify a network interface

Modify a network interface › path Parameters

Modify a network interface › Request Body

Modify a network interface › Responses

Delete a network interface

Delete a network interface › path Parameters

Delete a network interface › Responses

Add an IP address to a network interface

Add an IP address to a network interface › path Parameters