Create a private network subnet
POST /api/v2/private-networks
Add a private /24 subnet for your VPSes. The first call also creates the account’s private network, a /21 range that holds all its subnets. Later calls add another /24 to that same network. Each subnet gets its own VLAN tag. Private networks span the whole Hostup network. VPSes in any location can join.
Private networking has a one-time setup fee. Until it is paid, the call returns 402 private_network_setup_required. Start the setup with POST /api/v2/private-networks/access. Each subnet that is not retired counts toward the account’s subnet quota. The quota is one subnet unless a higher limit was granted. Request a higher limit in the client area under Network. A full quota returns 409 network_limit_reached.
The new subnet starts as provisioning while the network is set up. The response is the whole private network with all its subnets. An existing network keeps its ID and name.
Authentication: An API key with the scope write:network. About keys and scopes
Request
Body
namestringrequiredregionstringdeprecatedGET /api/v2/private-networks does not list.descriptionstring or nullparentCidrstringExample
curl -X POST "https://cloud.hostup.se/api/v2/private-networks" \ -H "Authorization: Bearer $HOSTUP_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "production-private", "description": "Private backend network" }'curl -X POST "https://cloud.hostup.se/api/v2/private-networks" \ -H "Authorization: Bearer $HOSTUP_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "production-private", "parentCidr": "10.201.64.0/21" }'Responses
201 The subnet is created and is being set up. Returns the private network with all its subnets.
{ "id": "pnet_01hxa3b4c5d6e7f8g9h0j1k2m3", "name": "production-private", "parentCidr": "10.201.64.0/21", "region": "dc1r28", "status": "provisioning", "subnetCount": 1, "attachedVpsCount": 0, "subnets": [ { "id": "subnet_01hxa3b4c5d6e7f8g9h0j1k2m3", "subnetCidr": "10.201.64.0/24", "vlanTag": 253, "gateway": "10.201.64.1", "status": "provisioning" } ], "attachedVps": [], "actions": { "canAddSubnet": { "allowed": false, "reason": "Private network limit reached." } }, "createdAt": "2026-04-27T12:00:00.000Z", "unusedAddressReservationCount": 0}Response fields
idstringpnet_…).namestringparentCidr when it has none.parentCidrstringregionstringdeprecatedstatusstringprovisioning: being set up on the network. active: ready. deprovisioning: being removed. retired: no longer in use. unknown: the state could not be read. One of provisioning, active, deprovisioning, retired, unknown.subnetCountintegerattachedVpsCountintegersubnetsarray of objectidstringsubnet_…).subnetCidrstringvlanTaginteger or nullnull until one is assigned.gatewaystring or nullnull when not known yet.statusstringprovisioning: being set up on the network. active: ready. deprovisioning: being removed. retired: no longer in use. unknown: the state could not be read. One of provisioning, active, deprovisioning, retired, unknown.attachedVpsarray of objectidstringvps_…).namestringGET /api/v2/private-networks/{id} returns its hostname.primaryIpstring or nullnull in this response. GET /api/v2/private-networks/{id} returns it.actionsobjectcanAddSubnetobjectPOST /api/v2/private-networks can add another subnet now. allowed is false with a reason when the subnet quota is full.allowedbooleanreasonstring or nullnull when allowed is true.createdAtstring or nullunusedAddressReservationCountinteger0 in this response. GET /api/v2/private-networks/{id} returns the real count.Errors
Errors are Problem Details with a stable code. Branch on the code, not on the text.
| 400 | invalid_request: name is missing or longer than 100 characters. invalid_cidr: parentCidr is not an aligned /21 inside 10.200.0.0/14. |
| 401 | Unauthorized. Authentication is required. |
| 402 | Private networking is not set up for the account. code is private_network_setup_required. When a setup invoice exists, invoice names it. Pay it and send the request again. |
| 403 | Forbidden. The caller lacks a required scope or does not own the resource. |
| 404 | Not found. The resource does not exist or is not owned by the caller. |
| 409 | No subnet was created. network_limit_reached: the subnet quota is full. parent_cidr_mismatch: parentCidr differs from the account’s existing range. Omit it. cidr_overlap: the requested range is taken or no free /21 is left. subnet_pool_exhausted: the network has no free /24 left. no_vlan_available: no VLAN tag is free. network_deprovisioning: the network is being removed. |
| 429 | Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers. |
| 500 | Internal error. Retry later or contact support if the issue persists. |
| 502 | upstream_failed: the subnet could not be set up. Retry later. |