Get VPS network state

Return network interfaces, assigned addresses, available public addresses, private-network context, reverse DNS state, IP-change limits, and action gates for one VPS. Get {id} from GET /api/v2/vps data[].id. Use this before network writes so the agent can choose ipId, subnetId, interfaceName, and understand blockers without frontend inference.

VPS Services Networking

Authentication

Required API scope: read:vm

Use Authorization: Bearer <token> for API keys. Dashboard sessions may also use hostup_session.

Context

Path Parameters

id string required Example: vps_01hxa3b4c5d6e7f8g9h0j1k2m3

Public VPS ID from `GET /api/v2/vps` `data[].id`. Do not invent this value; use the exact ID returned by the referenced API response.

Headers

Accept Example
Content-Type Example

Responses

200 VPS network state.
interfaces array<object> required
interfaces[].id stringnull required · Example: net0
interfaces[].model stringnull required · Example: virtio
interfaces[].mac stringnull required · Example: 52:54:00:12:34:56
interfaces[].bridge stringnull required · Example: vmbr0
interfaces[].vlan numbernull required · Example: null
interfaces[].firewallEnabled boolean required · Example: true
interfaces[].linkDown boolean required · Example: false
interfaces[].ip array<object> required
interfaces[].ip[].id stringnull required · Example: ip_01hxa3b4c5d6e7f8g9h0j1k2m3
interfaces[].ip[].type stringnull required · Example: ipv4
interfaces[].ip[].ip stringnull required · Example: 203.0.113.42
interfaces[].ip[].mask stringnull required · Example: 24
interfaces[].ip[].main boolean required · Example: true
interfaces[].ip[].isPrivate boolean required · Example: false
interfaces[].ip[].revdns stringnull required · Example: app-01.example.com
interfaces[].ip[].rdnsAvailable boolean required · Example: true
interfaces[].ip[].vlan numbernull required · Example: null
interfaces[].ip[].subnet objectnull required · Example: null
availableIPv4 array<object> required
availableIPv4[].id stringnull required · Example: ip_01hxa3b4c5d6e7f8g9h0j1k2m3
availableIPv4[].type stringnull required · Example: ipv4
availableIPv4[].ip stringnull required · Example: 203.0.113.10
availableIPv4[].status string · enum required · Example: available
available
assigned_to_account
availableIPv4[].mask stringnull required · Example: 24
availableIPv4[].main boolean required · Example: false
availableIPv4[].isPrivate boolean required · Example: false
availableIPv4[].vlan numbernull required · Example: null
availableIPv4[].subnet objectnull required · Example: null
availableIPv6 array<object> required
availableIPv6[].id stringnull required · Example: ip_01hxa3b4c5d6e7f8g9h0j1k2m3
availableIPv6[].type stringnull required · Example: ipv6
availableIPv6[].ip stringnull required · Example: 2001:db8:100::10
availableIPv6[].status string · enum required · Example: available
available
assigned_to_account
availableIPv6[].mask stringnull required · Example: 64
availableIPv6[].main boolean required · Example: false
availableIPv6[].isPrivate boolean required · Example: false
availableIPv6[].vlan numbernull required · Example: null
availableIPv6[].subnet objectnull required · Example: null
ipv4Limit integer required · Example: 2
ipv6Limit integer required · Example: 1
reservedPublicIpv4Count integer required · Example: 1
reservedPublicIpv6Count integer required · Example: 0
limits object required
limits.ipv4 object required
limits.ipv4.total integer required · Example: 2
limits.ipv4.used integer required · Example: 1
limits.ipv4.available integer required · Example: 1
limits.ipv6 object required
limits.ipv6.total integer required · Example: 1
limits.ipv6.used integer required · Example: 0
limits.ipv6.available integer required · Example: 1
primaryIP stringnull required · Example: 203.0.113.42
primaryIPrDNS stringnull required · Example: app-01.example.com
primaryRdnsAvailable boolean required · Example: true
primaryNetwork objectnull required · Example: null
ipAvailability object required
ipAvailability.ipv4 object required
ipAvailability.ipv4.availableCount integer required · Example: 1
ipAvailability.ipv4.currentNetworkAvailableCount integernull required · Example: 1
ipAvailability.ipv4.currentNetworkKnown boolean required · Example: true
ipAvailability.ipv4.reason stringnull required · Example: null
ipAvailability.ipv6 object required
ipAvailability.ipv6.availableCount integer required · Example: 1
ipAvailability.ipv6.currentNetworkAvailableCount integernull required · Example: 1
ipAvailability.ipv6.currentNetworkKnown boolean required · Example: true
ipAvailability.ipv6.reason stringnull required · Example: null
vlanTag numbernull required · Example: null
ipv6UpgradeOption objectnull required · Example: null
privateNetworks array<object> required
privateNetworks[].parentCidr stringnull required · Example: 10.24.0.0/16
privateNetworks[].status stringnull required · Example: pending_switch
privateNetworks[].subnets array<object> required
privateNetworks[].subnets[].id stringnull required · Example: subnet_01hxa3b4c5d6e7f8g9h0j1k2m3
privateNetworks[].subnets[].subnetCidr stringnull required · Example: 10.24.10.0/24
privateNetworks[].subnets[].vlanTag numbernull required · Example: 220
privateNetworks[].subnets[].gateway stringnull required · Example: 10.24.10.1
privateNetworks[].subnets[].status stringnull required · Example: retired
privateNetworks[].subnets[].usage objectnull required · Example: null
privateNetworkDefaults objectnull required · Example: null
ipChangePolicy objectnull required · Example: null
actions object required
actions.canAddPublicInterface object required
actions.canAddPublicInterface.allowed boolean required · Example: true
actions.canAddPublicInterface.reason stringnull required · Example: null
actions.canAddPublicInterface.code stringnull · Example: pending_order

Machine-readable reason code when an action is blocked.

actions.canAddIpv4 object required
actions.canAddIpv4.allowed boolean required · Example: true
actions.canAddIpv4.reason stringnull required · Example: null
actions.canAddIpv4.code stringnull · Example: pending_order

Machine-readable reason code when an action is blocked.

actions.canAddIpv6 object required
actions.canAddIpv6.allowed boolean required · Example: true
actions.canAddIpv6.reason stringnull required · Example: null
actions.canAddIpv6.code stringnull · Example: pending_order

Machine-readable reason code when an action is blocked.

actions.canChangeIp object required
actions.canChangeIp.allowed boolean required · Example: true
actions.canChangeIp.reason stringnull required · Example: null
actions.canChangeIp.code stringnull · Example: pending_order

Machine-readable reason code when an action is blocked.

actions.canUpgradeIPv6 object required
actions.canUpgradeIPv6.allowed boolean required · Example: true
actions.canUpgradeIPv6.reason stringnull required · Example: null
actions.canUpgradeIPv6.code stringnull · Example: pending_order

Machine-readable reason code when an action is blocked.

actions.canCreatePrivateNetwork object required
actions.canCreatePrivateNetwork.allowed boolean required · Example: true
actions.canCreatePrivateNetwork.reason stringnull required · Example: null
actions.canCreatePrivateNetwork.code stringnull · Example: pending_order

Machine-readable reason code when an action is blocked.

400 Invalid request. The response body is an RFC 7807 Problem Details document.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on `detail`.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when `code` is `invalid_request`.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
401 Unauthorized. Authentication is required.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on `detail`.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when `code` is `invalid_request`.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
403 Forbidden. The caller lacks a required scope or does not own the resource.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on `detail`.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when `code` is `invalid_request`.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
404 Not found. The resource does not exist or is not owned by the caller.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on `detail`.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when `code` is `invalid_request`.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
429 Rate limited. Retry after the limit resets. 429 responses include `Retry-After` seconds plus `X-RateLimit-*` headers.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on `detail`.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when `code` is `invalid_request`.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
500 Internal error. Retry later or contact support if the issue persists.
type string · Example: https://developer.hostup.se/errors/invalid_request
title string · Example: Validation failed
status integer · Example: 400
detail string · Example: The request body failed validation.
code string · Example: invalid_request

Stable machine-readable code. Branch on this field, not on `detail`.

instance string · Example: /api/v2/orders
requestId string · Example: req_01hxa3b4c5d6e7f8g9h0j1k2m3
timestamp string · Example: 2026-04-27T12:34:56.000Z
errors array<object>

Field-level validation errors when `code` is `invalid_request`.

errors[].pointer string required · Example: /items/0/eppCode
errors[].detail string required · Example: `eppCode` is required for this transfer.
errors[].code string required · Example: missing_required
extensions object
GET https://cloud.hostup.se/api/v2/vps/{id}/network
For AI assistants
View as Markdown
cURL 
curl -X GET "https://cloud.hostup.se/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/network" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
Response 
{
  "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"
  },
  "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": {
    "monthlyLimit": 1,
    "usedThisPeriod": 0,
    "remaining": 1,
    "periodStart": "2026-04-01",
    "nextReset": "2026-05-01",
    "lastUsedAt": null,
    "canChangeNow": true,
    "blockedReason": null
  },
  "actions": {
    "canAddPublicInterface": {
      "allowed": false,
      "reason": "Your IPv4 limit has been reached. Enable IPv6 to add an IPv6 public interface."
    },
    "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
    },
    "canUpgradeIPv6": {
      "allowed": true,
      "reason": null
    },
    "canCreatePrivateNetwork": {
      "allowed": true,
      "reason": null
    }
  }
}