Skip to content

Get the network setup of a VPS

GET /api/v2/vps/{id}/network

Returns the network interfaces of a VPS with their IP addresses and reverse DNS. It also lists the free addresses the VPS can take and its private networks. Read it before changing anything with POST /api/v2/vps/{id}/network. It holds the IDs and interface names those calls need. actions says what is allowed now. ipChangePolicy gives the price of the next IPv4 change and any change still waiting for payment. guestNetwork.status is mismatch when the running server does not use the addresses assigned to it. guestNetwork.actions.canRepair says whether the repair_guest_network action can fix that.

Authentication: An API key with the scopes read:vm and read:network and read:services. About keys and scopes

Request

Path parameters

idstringrequired
The VPS ID (vps_…).

Example

GET /api/v2/vps/{id}/network
curl "https://cloud.hostup.se/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/network" \
-H "Authorization: Bearer $HOSTUP_API_KEY"

Responses

200 The network setup of the VPS.

Response 200
{
"interfaces": [
{
"id": "net0",
"model": "virtio",
"mac": "52:54:00:12:34:56",
"bridge": "vmbr0",
"vlan": 112,
"firewallEnabled": true,
"linkDown": false,
"ip": [
{
"id": "ip_01hxa3b4c5d6e7f8g9h0j1k2m3",
"type": "ipv4",
"ip": "203.0.113.42",
"mask": "24",
"main": true,
"isPrivate": false,
"revdns": "app-01.example.com",
"rdnsAvailable": true,
"vlan": 112,
"subnet": {
"id": null,
"name": null,
"parentCidr": "203.0.113.0/24",
"gateway": "203.0.113.1"
}
}
]
}
],
"availableIPv4": [
{
"id": "ip_01hxa3b4c5d6e7f8g9h0j1k2m3",
"type": "ipv4",
"ip": "203.0.113.10",
"status": "available",
"mask": "24",
"main": false,
"isPrivate": false,
"vlan": null,
"subnet": {
"id": null,
"name": null,
"parentCidr": "203.0.113.0/24",
"gateway": "203.0.113.1"
}
}
],
"availableIPv6": [],
"ipv4Limit": 1,
"ipv6Limit": 0,
"reservedPublicIpv4Count": 1,
"reservedPublicIpv6Count": 0,
"limits": {
"ipv4": {
"total": 1,
"used": 1,
"available": 0
},
"ipv6": {
"total": 0,
"used": 0,
"available": 0
}
},
"primaryIP": "203.0.113.42",
"primaryIPrDNS": "app-01.example.com",
"primaryRdnsAvailable": true,
"primaryNetwork": {
"id": null,
"name": null,
"parentCidr": "203.0.113.0/24",
"gateway": "203.0.113.1"
},
"guestNetwork": {
"checked": true,
"available": true,
"vmRunning": true,
"status": "mismatch",
"reason": null,
"interfaces": [
{
"name": "eth0",
"mac": "52:54:00:12:34:56",
"ip": [
{
"ip": "198.51.100.23",
"type": "ipv4",
"prefix": 24
}
]
}
],
"checks": [
{
"interfaceName": "net0",
"mac": "52:54:00:12:34:56",
"guestInterfaceName": "eth0",
"expectedIps": [
"203.0.113.42"
],
"observedIps": [
"198.51.100.23"
],
"missingIps": [
"203.0.113.42"
],
"unexpectedIps": [
"198.51.100.23"
],
"status": "mismatch",
"actions": {
"canRepair": {
"allowed": true,
"reason": null
}
}
}
],
"mismatches": [
{
"interfaceName": "net0",
"mac": "52:54:00:12:34:56",
"guestInterfaceName": "eth0",
"expectedIps": [
"203.0.113.42"
],
"observedIps": [
"198.51.100.23"
],
"missingIps": [
"203.0.113.42"
],
"unexpectedIps": [
"198.51.100.23"
],
"status": "mismatch",
"actions": {
"canRepair": {
"allowed": true,
"reason": null
}
}
}
],
"expectedIps": [
"203.0.113.42"
],
"observedIps": [
"198.51.100.23"
],
"missingIps": [
"203.0.113.42"
],
"unexpectedIps": [
"198.51.100.23"
],
"actions": {
"canRepair": {
"allowed": true,
"reason": null
}
}
},
"nativeNetwork": true,
"ipAvailability": {
"ipv4": {
"availableCount": 0,
"currentNetworkAvailableCount": 0,
"currentNetworkKnown": true,
"reason": null
},
"ipv6": {
"availableCount": 91,
"currentNetworkAvailableCount": 0,
"currentNetworkKnown": false,
"reason": "No IPv6 subnet is currently attached to this VPS."
}
},
"vlanTag": 112,
"ipv6UpgradeOption": {
"key": "ipv6Addresses",
"name": "IPv6 addresses",
"min": 0,
"max": 16,
"step": 1,
"monthlyPrice": 0,
"currencyCode": "SEK",
"currentValue": 0
},
"privateNetworks": [
{
"parentCidr": "10.24.0.0/16",
"status": "pending_switch",
"subnets": [
{
"id": "subnet_01hxa3b4c5d6e7f8g9h0j1k2m3",
"subnetCidr": "10.24.10.0/24",
"vlanTag": 220,
"gateway": "10.24.10.1",
"status": "retired",
"usage": {
"assignedIpCount": 1,
"totalIpCount": 250
}
}
]
}
],
"privateNetworkDefaults": {
"vlanRange": {
"min": 200,
"max": 399
}
},
"ipChangePolicy": {
"freeChangeAvailable": false,
"freeChangeExpiresAt": "2026-09-24T18:30:00.000Z",
"price": {
"amount": 2,
"currencyCode": "EUR"
},
"paidPrice": {
"amount": 2,
"currencyCode": "EUR"
},
"paymentHoldHours": 4,
"pausedUnderAttackUntil": null,
"canChangeNow": true,
"blockedReason": null,
"blockedCode": null,
"pendingChange": null
},
"actions": {
"canAddPublicInterface": {
"allowed": false,
"reason": "Your plan's IPv4 limit has been reached."
},
"canAddIpv4": {
"allowed": false,
"reason": "Your plan's IPv4 limit has been reached."
},
"canAddIpv6": {
"allowed": false,
"reason": "No IPv6 subnet is currently attached to this VPS."
},
"canChangeIp": {
"allowed": true,
"reason": null,
"code": null
},
"canUpgradeIPv6": {
"allowed": true,
"reason": null
},
"canCreatePrivateNetwork": {
"allowed": true,
"reason": null
}
}
}
Response fields
interfacesarray of object
Network interfaces of the VPS. net0 is the primary public interface.
idstring or null
Interface name, for example net0. Send it as interfaceName.
modelstring or null
Virtual network card model, for example virtio.
macstring or null
MAC address of the interface.
bridgestring or null
Name of the host bridge the interface is attached to. No call takes it.
vlannumber or null
VLAN tag of the interface. Tags 200 to 399 are private networks.
firewallEnabledboolean
True when the VPS firewall filters this interface.
linkDownboolean
True when the interface is disconnected.
iparray of object
Addresses assigned to the interface.
idstring or null
IP ID (ip_…). Send it as ipId.
typestring or null
ipv4 or ipv6.
ipstring or null
The address.
maskstring or null
Prefix length, for example 24.
mainboolean
True for the primary address of the VPS.
isPrivateboolean
True for an address on a private network.
revdnsstring or null
Reverse DNS hostname of the address. Null when none is set.
rdnsAvailableboolean
True when reverse DNS can be changed for this address.
vlannumber or null
VLAN tag of the address.
subnetobject or null
The public network the address belongs to. Null when it is not known.
availableIPv4array of object
Free IPv4 addresses on the primary interface’s network that can be assigned.
idstring or null
IP ID (ip_…). Send it as ipId.
typestring or null
ipv4 or ipv6.
ipstring or null
The address.
statusstring
available for a free address. assigned_to_account for an address the account already holds, such as a reserved IP. One of available, assigned_to_account.
maskstring or null
Prefix length.
mainboolean
Always false for a free address.
isPrivateboolean
True for an address on a private network.
vlannumber or null
VLAN tag of the address’s network.
subnetobject or null
The public network the address belongs to. Null when it is not known.
availableIPv6array of object
Free IPv6 addresses on the primary interface’s network that can be assigned.
idstring or null
IP ID (ip_…). Send it as ipId.
typestring or null
ipv4 or ipv6.
ipstring or null
The address.
statusstring
available for a free address. assigned_to_account for an address the account already holds, such as a reserved IP. One of available, assigned_to_account.
maskstring or null
Prefix length.
mainboolean
Always false for a free address.
isPrivateboolean
True for an address on a private network.
vlannumber or null
VLAN tag of the address’s network.
subnetobject or null
The public network the address belongs to. Null when it is not known.
ipv4Limitinteger
Number of public IPv4 addresses the plan includes.
ipv6Limitinteger
Number of IPv6 addresses the VPS can have: one per public interface when IPv6 is on, otherwise 0.
reservedPublicIpv4Countinteger
Reserved public IPv4 addresses on the account.
reservedPublicIpv6Countinteger
Reserved public IPv6 addresses on the account.
limitsobject
Public addresses allowed, used and left.
ipv4object
IPv4 addresses on public interfaces.
totalinteger
Addresses allowed.
usedinteger
Addresses in use.
availableinteger
Addresses that can still be added.
ipv6object
IPv6 addresses on public interfaces.
totalinteger
Addresses allowed.
usedinteger
Addresses in use.
availableinteger
Addresses that can still be added.
primaryIPstring or null
The primary IPv4 address of the VPS.
primaryIPrDNSstring or null
Reverse DNS hostname of the primary address.
primaryRdnsAvailableboolean
True when reverse DNS can be changed for the primary address.
primaryNetworkobject or null
The public network of the primary address. Null when it is not known.
guestNetworkobject or null
Compares the addresses assigned to the VPS with the ones the running server uses. Read through the QEMU Guest Agent. Null when it was not checked.
nativeNetworkboolean
True when network changes on this VPS apply without a restart.
ipAvailabilityobject
How many free addresses the VPS can take.
ipv4object
Free IPv4 addresses.
availableCountinteger
Free addresses on every network the VPS may use, also through a new public interface.
currentNetworkAvailableCountinteger or null
The part of availableCount on the primary interface’s network. Null when that network is not known.
currentNetworkKnownboolean
True when the primary interface’s network is known.
reasonstring or null
Why no address can be added, when that is the case.
ipv6object
Free IPv6 addresses.
availableCountinteger
Free addresses on every network the VPS may use, also through a new public interface.
currentNetworkAvailableCountinteger or null
The part of availableCount on the primary interface’s network. Null when that network is not known.
currentNetworkKnownboolean
True when the primary interface’s network is known.
reasonstring or null
Why no address can be added, when that is the case.
vlanTagnumber or null
VLAN tag of the primary public interface.
ipv6UpgradeOptionobject or null
The plan option that turns on IPv6. Null when the plan has none.
privateNetworksarray of object
Private networks of the account.
parentCidrstring or null
The private network range in CIDR notation.
statusstring or null
State of the private network.
subnetsarray of object
Subnets of the private network.
idstring or null
Subnet ID (subnet_…). Send it as subnetId to create_private_interface.
subnetCidrstring or null
The subnet range in CIDR notation.
vlanTagnumber or null
VLAN tag of the subnet.
gatewaystring or null
Gateway address of the subnet.
statusstring or null
State of the subnet. A retired subnet cannot take new interfaces.
usageobject or null
How many addresses of the subnet are used. Null when not known.
privateNetworkDefaultsobject or null
Settings for new private networks. Null when private networks are not available to the VPS.
ipChangePolicyobject or null
Price and state of IPv4 changes. The first change within 72 hours of the order is free. Every later change costs a fee that is invoiced first. The new address is held while the invoice is open and the change is made once it is paid. IPv6 changes cost nothing. Null when it could not be read.
actionsobject
What can be done with the network now.
canAddPublicInterfaceobject
Whether a new public interface can be added with create_public_interface.
allowedboolean
reasonstring or null
codestring or null
A machine-readable code for why the action is blocked.
canAddIpv4object
Whether an IPv4 address can be added.
allowedboolean
reasonstring or null
codestring or null
A machine-readable code for why the action is blocked.
canAddIpv6object
Whether an IPv6 address can be added.
allowedboolean
reasonstring or null
codestring or null
A machine-readable code for why the action is blocked.
canChangeIpobject
Whether an IPv4 address can be changed with change_ip. code is paused_under_attack or price_unavailable when not.
allowedboolean
reasonstring or null
codestring or null
A machine-readable code for why the action is blocked.
canUpgradeIPv6object
Whether IPv6 can be turned on through the plan.
allowedboolean
reasonstring or null
codestring or null
A machine-readable code for why the action is blocked.
canCreatePrivateNetworkobject
Whether private networks are available to the VPS.
allowedboolean
reasonstring or null
codestring or null
A machine-readable code for why the action is blocked.

Errors

Errors are Problem Details with a stable code. Branch on the code, not on the text.

400Invalid request. The response body is an RFC 7807 Problem Details document.
401Unauthorized. Authentication is required.
403Forbidden. The caller lacks a required scope or does not own the resource.
404Not found. The resource does not exist or is not owned by the caller; code is vps_not_found.
429Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers.
500Internal error. Retry later or contact support if the issue persists.