Network Peering

Network peering management

List peerings

GET

https://api.upcloud.com

/1.3/network-peering

Get a list of all peerings within the current account. Only peerings that refer to a network that the current account has access are returned.

It is also possible to filter network peering with label URL parameters, e.g. ?label=env or ?label=env%3Dprod. The URL parameter can be given multiple times to add more filters (e.g. ?label=env%3Dprod&label=v2), where only network peering that match all labels are returned. Label keys are matched case insensitively.

List peerings › query Parameters

uuid

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

Filter by network peering UUID.

Universally unique identifier

network_uuid_local

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

Filter by local network uuid.

Universally unique identifier

network_uuid_peer

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

Filter by peer network uuid.

Universally unique identifier

label

string

Label filter in the form key=value. Can be specified multiple times to filter by multiple labels.

List peerings › Responses

A list of network peerings.

Network peerings

networkPeerings

object · required

Create peering

POST

https://api.upcloud.com

/1.3/network-peering

Network peerings are used to enable traffic between two networks that can be on different main accounts. The peering must be established both ways before it's considered as active. Peering is only supported between networks of type private.

Note: you should only create peering between accounts and networks you trust. There is no limits on what traffic can flow. The server firewall has no effect for private type networks.

It is required that both networks have a Router attached to the network.

Create peering › Request Body

Describes the mutable properties when creating a network-peering between two networks

networkPeeringCreate

name

string · required

object · required

Describes the local side of the peering

object · required

Describes the peer side of the peering

configured_status

string · enum

Enum values:

active

disabled

Default: active

Create peering › Responses

The network peering was successfully created.

Network peering object describes a peering relationship between two networks

networkPeering

configured_status

string · enum

Enum values:

active

disabled

name

networkPeeringName · minLength: 1 · maxLength: 255

Name of a network peering relationship.

object

Describes the local side of the peering

object

Describes the peer side of the peering

state

networkPeeringState · enum

Current lifecycle state of a network peering.

Enum values:

active

pending-peer

provisioning

conflict-subnet

missing-local-router

missing-peer-router

deleted-peer-network

disabled

uuid

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

Universally unique identifier

When the network peering was created

When the network peering was last updated. Null until the first modification.

POST/1.3/network-peering

curl https://api.upcloud.com/1.3/network-peering \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "configured_status": "active",
  "name": "Peering A->B",
  "network": {
    "uuid": "03126dc1-a69f-4bc2-8b24-e31c22d64712"
  },
  "peer_network": {
    "uuid": "03585987-bf7d-4544-8e9b-5a1b4d74a333"
  }
}'

Example Request Body

{
  "configured_status": "active",
  "name": "Peering A->B",
  "network": {
    "uuid": "03126dc1-a69f-4bc2-8b24-e31c22d64712"
  },
  "peer_network": {
    "uuid": "03585987-bf7d-4544-8e9b-5a1b4d74a333"
  }
}

json

Example Responses

{
  "configured_status": "active",
  "name": "Peering A->B",
  "network": {
    "ip_networks": {
      "ip_network": [
        {
          "address": "192.168.0.0/24",
          "family": "IPv4"
        },
        {
          "address": "fc02:c4f3::/64",
          "family": "IPv6"
        }
      ]
    },
    "uuid": "03126dc1-a69f-4bc2-8b24-e31c22d64712"
  },
  "peer_network": {
    "ip_networks": {
      "ip_network": [
        {
          "address": "192.168.99.0/24",
          "family": "IPv4"
        },
        {
          "address": "fc02:c4f3:99::/64",
          "family": "IPv6"
        }
      ]
    },
    "uuid": "03585987-bf7d-4544-8e9b-5a1b4d74a333"
  },
  "state": "active",
  "uuid": "0f7984bc-5d72-4aaf-b587-90e6a8f32efc",
  "created_at": "2026-07-01T00:00:00Z"
}

json

application/json

Get peering

GET

https://api.upcloud.com

/1.3/network-peering/{peering_uuid}

Returns the state of an existing network peering.

Note that the peer_network field only contains the network details if the peering has been defined by both accounts.

Get peering › path Parameters

peering_uuid

string · uuid · required

The network peering identifier.

Get peering › Responses

Details of the specified network peering.

Network peering object describes a peering relationship between two networks

networkPeering

configured_status

string · enum

Enum values:

active

disabled

name

networkPeeringName · minLength: 1 · maxLength: 255

Name of a network peering relationship.

object

Describes the local side of the peering

object

Describes the peer side of the peering

state

networkPeeringState · enum

Current lifecycle state of a network peering.

Enum values:

active

pending-peer

provisioning

conflict-subnet

missing-local-router

missing-peer-router

deleted-peer-network

disabled

uuid

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

Universally unique identifier

When the network peering was created

When the network peering was last updated. Null until the first modification.

GET/1.3/network-peering/{peering_uuid}

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

Example Responses

{
  "configured_status": "active",
  "name": "Peering A->B",
  "network": {
    "ip_networks": {
      "ip_network": [
        {
          "address": "192.168.0.0/24",
          "family": "IPv4"
        },
        {
          "address": "fc02:c4f3::/64",
          "family": "IPv6"
        }
      ]
    },
    "uuid": "03126dc1-a69f-4bc2-8b24-e31c22d64712"
  },
  "peer_network": {
    "ip_networks": {
      "ip_network": [
        {
          "address": "192.168.99.0/24",
          "family": "IPv4"
        },
        {
          "address": "fc02:c4f3:99::/64",
          "family": "IPv6"
        }
      ]
    },
    "uuid": "03585987-bf7d-4544-8e9b-5a1b4d74a333"
  },
  "state": "active",
  "uuid": "0f7984bc-5d72-4aaf-b587-90e6a8f32efc",
  "created_at": "2026-07-01T00:00:00Z"
}

json

application/json

Delete peering

DELETE

https://api.upcloud.com

/1.3/network-peering/{peering_uuid}

Deletes a network peering. It is required that the peering is in disabled state before delete is possible.

Delete peering › path Parameters

peering_uuid

string · uuid · required

The network peering identifier.

Delete peering › Responses

The network peering was successfully deleted.

No data returned

Modify peering

PATCH

https://api.upcloud.com

/1.3/network-peering/{peering_uuid}

Modifies attributes of an existing network peering.

Modify peering › path Parameters

peering_uuid

string · uuid · required

The network peering identifier.

Modify peering › Request Body

Describes the mutable properties when modifying a network-peering

networkPeeringModify

configured_status

enum

Enum values:

active

disabled

name

string

Modify peering › Responses

The network peering was successfully modified.

Network peering object describes a peering relationship between two networks

networkPeering

configured_status

string · enum

Enum values:

active

disabled

name

networkPeeringName · minLength: 1 · maxLength: 255

Name of a network peering relationship.

object

Describes the local side of the peering

object

Describes the peer side of the peering

state

networkPeeringState · enum

Current lifecycle state of a network peering.

Enum values:

active

pending-peer

provisioning

conflict-subnet

missing-local-router

missing-peer-router

deleted-peer-network

disabled

uuid

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

Universally unique identifier

When the network peering was created

When the network peering was last updated. Null until the first modification.

PATCH/1.3/network-peering/{peering_uuid}

curl https://api.upcloud.com/1.3/network-peering/:peering_uuid \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "configured_status": "disabled",
  "name": "Peering A->B modified"
}'

Example Request Body

{
  "configured_status": "disabled",
  "name": "Peering A->B modified"
}

json

Example Responses

{
  "configured_status": "active",
  "name": "Peering A->B",
  "network": {
    "ip_networks": {
      "ip_network": [
        {
          "address": "192.168.0.0/24",
          "family": "IPv4"
        },
        {
          "address": "fc02:c4f3::/64",
          "family": "IPv6"
        }
      ]
    },
    "uuid": "03126dc1-a69f-4bc2-8b24-e31c22d64712"
  },
  "peer_network": {
    "ip_networks": {
      "ip_network": [
        {
          "address": "192.168.99.0/24",
          "family": "IPv4"
        },
        {
          "address": "fc02:c4f3:99::/64",
          "family": "IPv6"
        }
      ]
    },
    "uuid": "03585987-bf7d-4544-8e9b-5a1b4d74a333"
  },
  "state": "active",
  "uuid": "0f7984bc-5d72-4aaf-b587-90e6a8f32efc",
  "created_at": "2026-07-01T00:00:00Z"
}

json

application/json

Network IP Address

List peerings

GET

https://api.upcloud.com

/1.3/network-peering

Get a list of all peerings within the current account. Only peerings that refer to a network that the current account has access are returned.

List peerings › query Parameters

uuid

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

Filter by network peering UUID.

Universally unique identifier

network_uuid_local

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

Filter by local network uuid.

Universally unique identifier

network_uuid_peer

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

Filter by peer network uuid.

Universally unique identifier

label

string

Label filter in the form key=value. Can be specified multiple times to filter by multiple labels.

List peerings › Responses

A list of network peerings.

Network peerings

networkPeerings

object · required

Create peering

POST

https://api.upcloud.com

/1.3/network-peering

Note: you should only create peering between accounts and networks you trust. There is no limits on what traffic can flow. The server firewall has no effect for private type networks.

It is required that both networks have a Router attached to the network.

Create peering › Request Body

Describes the mutable properties when creating a network-peering between two networks

networkPeeringCreate

name

string · required

object · required

Describes the local side of the peering

object · required

Describes the peer side of the peering

configured_status

string · enum

Enum values:

active

disabled

Default: active

Create peering › Responses

The network peering was successfully created.

Network peering object describes a peering relationship between two networks

networkPeering

configured_status

string · enum

Enum values:

active

disabled

name

networkPeeringName · minLength: 1 · maxLength: 255

Name of a network peering relationship.

object

Describes the local side of the peering

object

Describes the peer side of the peering

state

networkPeeringState · enum

Current lifecycle state of a network peering.

Enum values:

active

pending-peer

provisioning

conflict-subnet

missing-local-router

missing-peer-router

deleted-peer-network

disabled

uuid

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

Universally unique identifier

When the network peering was created

When the network peering was last updated. Null until the first modification.

Get peering

GET

https://api.upcloud.com

/1.3/network-peering/{peering_uuid}

Returns the state of an existing network peering.

Note that the peer_network field only contains the network details if the peering has been defined by both accounts.

Get peering › path Parameters

peering_uuid

string · uuid · required

The network peering identifier.

Get peering › Responses

Details of the specified network peering.

Network peering object describes a peering relationship between two networks

networkPeering

configured_status

string · enum

Enum values:

active

disabled

name

networkPeeringName · minLength: 1 · maxLength: 255

Name of a network peering relationship.

object

Describes the local side of the peering

object

Describes the peer side of the peering

state

networkPeeringState · enum

Current lifecycle state of a network peering.

Enum values:

active

pending-peer

provisioning

conflict-subnet

missing-local-router

missing-peer-router

deleted-peer-network

disabled

uuid

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

Universally unique identifier

When the network peering was created

When the network peering was last updated. Null until the first modification.

Delete peering

DELETE

https://api.upcloud.com

/1.3/network-peering/{peering_uuid}

Deletes a network peering. It is required that the peering is in disabled state before delete is possible.

Delete peering › path Parameters

peering_uuid

string · uuid · required

The network peering identifier.

Delete peering › Responses

The network peering was successfully deleted.

No data returned

Modify peering

PATCH

https://api.upcloud.com

/1.3/network-peering/{peering_uuid}

Modifies attributes of an existing network peering.

Modify peering › path Parameters

peering_uuid

string · uuid · required

The network peering identifier.

Modify peering › Request Body

Describes the mutable properties when modifying a network-peering

networkPeeringModify

configured_status

enum

Enum values:

active

disabled

name

string

Modify peering › Responses

The network peering was successfully modified.

Network peering object describes a peering relationship between two networks

networkPeering

configured_status

string · enum

Enum values:

active

disabled

name

networkPeeringName · minLength: 1 · maxLength: 255

Name of a network peering relationship.

object

Describes the local side of the peering

object

Describes the peer side of the peering

state

networkPeeringState · enum

Current lifecycle state of a network peering.

Enum values:

active

pending-peer

provisioning

conflict-subnet

missing-local-router

missing-peer-router

deleted-peer-network

disabled

uuid

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

Universally unique identifier

When the network peering was created

When the network peering was last updated. Null until the first modification.