Skip to content

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

namestringrequired
Name of the new subnet, up to 100 characters. On the first call it also names the private network.
regionstringdeprecated
Deprecated. Omit it. Private networks span the whole Hostup network. Another value creates a network that GET /api/v2/private-networks does not list.
descriptionstring or null
Optional note stored with the subnet. Longer text is cut at 255 characters.
parentCidrstring
Optional /21 range for a new private network, aligned inside 10.200.0.0/14. Omit it to get a free range. When the account already has a network, omit it or send that network’s range.

Example

POST /api/v2/private-networks
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"
}'

Responses

201 The subnet is created and is being set up. Returns the private network with all its subnets.

Response 201
{
"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
idstring
The private network ID (pnet_…).
namestring
Name given when the network was created. parentCidr when it has none.
parentCidrstring
The network’s IPv4 range, a /21. Each subnet is a /24 inside it.
regionstringdeprecated
Deprecated. Location slug of the network. Private networks span the whole Hostup network. You can ignore it.
statusstring
provisioning: 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.
subnetCountinteger
Number of subnets that are not retired.
attachedVpsCountinteger
Number of VPSes with an interface in one of the subnets.
subnetsarray of object
Every subnet in the network, retired ones included.
idstring
The subnet ID (subnet_…).
subnetCidrstring
The subnet’s range, a /24.
vlanTaginteger or null
VLAN tag of the subnet. null until one is assigned.
gatewaystring or null
First usable address in the subnet. null when not known yet.
statusstring
provisioning: 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 object
VPSes with an interface in one of the subnets.
idstring
The VPS ID (vps_…).
namestring
Generic name of the VPS. GET /api/v2/private-networks/{id} returns its hostname.
primaryIpstring or null
Always null in this response. GET /api/v2/private-networks/{id} returns it.
actionsobject
canAddSubnetobject
Whether POST /api/v2/private-networks can add another subnet now. allowed is false with a reason when the subnet quota is full.
allowedboolean
reasonstring or null
Why no subnet can be added. null when allowed is true.
createdAtstring or null
When the network was created.
unusedAddressReservationCountinteger
Always 0 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.

400invalid_request: name is missing or longer than 100 characters. invalid_cidr: parentCidr is not an aligned /21 inside 10.200.0.0/14.
401Unauthorized. Authentication is required.
402Private 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.
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.
409No 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.
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.
502upstream_failed: the subnet could not be set up. Retry later.