Networks

UpCloud SDN (Software Defined Networking) provides flexible and customizable network configurations for your cloud infrastructure. You can create private networks, connect them with routers, and peer networks across zones.

Network types

Name
public
Description
Public networks provide internet connectivity. They are automatically added when public IP addresses are assigned to servers.
Name
utility
Description
Shared private network for internal communication within a zone. All servers in the same zone share the same utility network.
Name
private
Description
SDN private networks provide isolated, customizable network segments with full control over IP addressing and routing.

Available IP subnets

For private networks, you can use any global unicast address. Recommended private ranges:

10.0.0.0/8
172.16.0.0/12
192.168.0.0/16

Subnet prefix length: minimum 8 bits, maximum 29 bits.

GET/1.3/network

List networks

Returns a list of all networks accessible to the account. Can be filtered by zone or labels.

Query parameters

Name
zone
Type
string
Description
Filter by zone (e.g., ?zone=fi-hel1).
Name
label
Type
string
Description
Filter by label (e.g., ?label=env=prod).

Request

GET

/1.3/network

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

GET/1.3/network/{uuid}

Get network details

Returns detailed information about a specific network including IP configuration and attached servers.

Request

GET

/1.3/network/{uuid}

curl -X GET https://api.upcloud.com/1.3/network/034c12bc-cf15-4b19-97b2-0ab4e51bb98d \
  -u your_username:your_password

POST/1.3/network

Create network

Creates a new SDN private network in the specified zone.

Attributes

Name
name
Type
string
Description
Network name. Required.
Name
zone
Type
string
Description
Zone identifier. Required.
Name
router
Type
string
Description
Router UUID to attach the network to.
Name
ip_networks
Type
object
Description
IP network configuration. Required.
Name
labels
Type
array
Description
Labels for classification.

IP network attributes

Name
address
Type
string
Description
Network address in CIDR notation (e.g., "10.0.0.0/24"). Required.
Name
dhcp
Type
string
Description
Enable DHCP: "yes" or "no". Default: "yes".
Name
dhcp_default_route
Type
string
Description
Provide default route via DHCP: "yes" or "no".
Name
dhcp_dns
Type
array
Description
DNS servers to provide via DHCP.
Name
family
Type
string
Description
Address family: "IPv4". Required.
Name
gateway
Type
string
Description
Gateway IP address.

Request

POST

/1.3/network

curl -X POST https://api.upcloud.com/1.3/network \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "network": {
      "name": "My Private Network",
      "zone": "fi-hel1",
      "ip_networks": {
        "ip_network": [
          {
            "address": "10.0.0.0/24",
            "dhcp": "yes",
            "dhcp_default_route": "no",
            "dhcp_dns": ["10.0.0.10"],
            "family": "IPv4",
            "gateway": "10.0.0.1"
          }
        ]
      },
      "labels": [
        {"key": "env", "value": "prod"}
      ]
    }
  }'

PUT/1.3/network/{uuid}

Modify network

Modifies an existing SDN private network. Utility and public networks cannot be modified.

Networks can be attached to a router by specifying the router UUID.

Request

PUT

/1.3/network/{uuid}

curl -X PUT https://api.upcloud.com/1.3/network/034c12bc-cf15-4b19-97b2-0ab4e51bb98d \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "network": {
      "name": "Updated Network Name",
      "router": "04c0df35-2658-4b0c-8ac7-962090f4e92a",
      "ip_networks": {
        "ip_network": [
          {
            "address": "10.0.0.0/24",
            "dhcp": "yes",
            "dhcp_default_route": "yes",
            "family": "IPv4",
            "gateway": "10.0.0.1"
          }
        ]
      }
    }
  }'

DELETE/1.3/network/{uuid}

Delete network

Deletes an SDN private network. All servers must be detached before the network can be deleted.

Request

DELETE

/1.3/network/{uuid}

curl -X DELETE https://api.upcloud.com/1.3/network/034c12bc-cf15-4b19-97b2-0ab4e51bb98d \
  -u your_username:your_password

GET/1.3/server/{uuid}/networking

List server networks

Returns all network interfaces attached to a specific server.

Request

GET

/1.3/server/{uuid}/networking

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

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

Create network interface

Creates a new network interface on a server. The server must be stopped.

Attributes

Name
type
Type
string
Description
Interface type: "public", "utility", or "private". Required.
Name
network
Type
string
Description
Network UUID (required for private networks).
Name
ip_addresses
Type
object
Description
IP address configuration.
Name
source_ip_filtering
Type
string
Description
Enable source IP filtering: "yes" or "no". Default: "yes".
Name
bootable
Type
string
Description
Enable network boot: "yes" or "no". Default: "no".

Request

POST

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

curl -X POST https://api.upcloud.com/1.3/server/00798b85-efdc-41ca-8021-f6ef457b8531/networking/interface \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "interface": {
      "type": "private",
      "network": "034c12bc-cf15-4b19-97b2-0ab4e51bb98d",
      "ip_addresses": {
        "ip_address": [
          {
            "family": "IPv4",
            "address": "10.0.0.10"
          }
        ]
      },
      "source_ip_filtering": "yes"
    }
  }'

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

Modify network interface

Modifies an existing network interface. The server must be stopped for most changes.

Request

PUT

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

curl -X PUT https://api.upcloud.com/1.3/server/00798b85-efdc-41ca-8021-f6ef457b8531/networking/interface/3 \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "interface": {
      "source_ip_filtering": "no"
    }
  }'

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

Delete network interface

Removes a network interface from a server. The server must be stopped.

Request

DELETE

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

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