Skip to content

Change the network setup of a VPS

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

Makes one network change on a VPS. action picks the change. Each action accepts only its own fields and rejects any other. Read GET /api/v2/vps/{id}/network first for the interface names, IP IDs and the actions gates.

  • update_rdns sets reverse DNS for an address of the VPS. The hostname must already resolve to that address. Send an empty string to reset reverse DNS to the default hostname.
  • get_available_subnets requires ipType and lists free public addresses grouped by network. It returns { subnets } synchronously.
  • assign_ip attaches one available or reserved public IP and requires ipId or ipAddress. assign_ips attaches several to one interface. IPv6 must be assigned to an existing public interface that already has IPv4.
  • remove_ip takes an extra address off an interface. The primary IPv4 address cannot be removed. The number of addresses the plan includes stays the same.
  • change_ip replaces an address with a free one. The first IPv4 change within 72 hours of the order is free. A later IPv4 change is invoiced first and made once the invoice is paid. IPv6 changes are free. reserveOldIp: true keeps the previous public IP as a reserved IP.
  • create_public_interface creates a public interface with a selected IPv4 address. IPv6-only public interfaces are not supported.
  • create_private_interface connects the VPS to a subnet of a private network.
  • delete_interface removes an extra interface. delete_primary_interface removes the primary public interface and needs confirm: true.
  • repair_guest_network writes the assigned addresses into the running server when guestNetwork.status is mismatch.

A change that is done at once returns 200 with operation.status completed and operation.pollUrl null. A change that needs a restart returns 202. Follow it with operation.pollUrl (see Jobs). A paid IPv4 change returns 202 with operation.status pending, no poll URL and a pendingChange with the invoice to pay. The address is held for ipChangePolicy.paymentHoldHours hours. If the invoice is not paid by then, it is cancelled and the address is released.

After a DDoS attack on the VPS, IPv4 changes are paused for a while (409 paused_under_attack). When the VPS has used up its bandwidth, every action except get_available_subnets and repair_guest_network returns 403.

Authentication: An API key with the scope read:vm. Also read:network: needed for every action. write:network includes it. Also read:services: needed for every action. write:services includes it. Also write:vm: only for actions other than get_available_subnets. Also write:network: only for actions other than get_available_subnets. Also write:services: only for actions other than get_available_subnets. About keys and scopes

Request

Path parameters

idstringrequired
The VPS ID (vps_…).

Body

actionstringrequired
The change to make. One of assign_ip, assign_ips, remove_ip, change_ip, update_rdns, get_available_subnets, repair_guest_network, create_public_interface, create_private_interface, delete_interface, delete_primary_interface.
ipIdstring or null
IP ID (ip_…) of the address to use, from GET /api/v2/vps/{id}/network or get_available_subnets. Takes priority over ipAddress.
ipTypestring or null
ipv4 or ipv6. Required for get_available_subnets and remove_ip. Optional for assign_ip and change_ip, where the address sets it. One of ipv4, ipv6.
interfaceNamestring or null
Interface name, for example net0. Used by the IP actions, repair_guest_network and delete_interface. For get_available_subnets it picks the interface isCurrentNetwork refers to, default net0. Leave it out for create_private_interface to use the next free interface.
subnetIdstring or null
Subnet ID (subnet_…). For create_private_interface it picks the private subnet. For the other actions it checks that the address belongs to that network. subnetId alone does not choose an IP.
ipAddressstring or null
The address itself, when no ipId is known. For create_private_interface, a free IPv4 address in the subnet.
reserveOldIpboolean
Only for change_ip. true keeps the previous public IP on the account as a reserved IP. Default false.
cancelPendingChangeboolean
Only for change_ip. true cancels an IPv4 change still waiting for payment (its invoice is cancelled and its address released) before this one is made. Without it, the request returns 409 ip_change_awaiting_payment.
requestIdstring
Only for change_ip. A new UUID for this change. Required for an IPv4 change. Send the same value again when retrying the same change.
expectedPriceobject
Only for change_ip. The ipChangePolicy.price object from GET /api/v2/vps/{id}/network, unchanged. Required for an IPv4 change. A price that no longer matches returns 409.
amountnumberrequired
Amount, 0 for the free change.
currencyCodestringrequired
ISO 4217 currency code.
ipsarray of object
Only for assign_ips. The addresses to attach to interfaceName.
ipIdstring or nullrequired
IP ID (ip_…).
ipAddressstring or nullrequired
The address.
ipTypestring or nullrequired
ipv4 or ipv6.
ipstring or null
Only for update_rdns. The address of the VPS whose reverse DNS changes.
rdnsstring or null
Only for update_rdns. The hostname, which must resolve to ip (A record for IPv4, AAAA for IPv6). Send an empty string to reset reverse DNS to the default hostname.
vlannumber or null
Only for create_private_interface. VLAN tag. Leave it out to use the subnet’s tag.
confirmboolean
Only for delete_primary_interface. Must be true.

Example

POST /api/v2/vps/{id}/network
curl -X POST "https://cloud.hostup.se/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/network" \
-H "Authorization: Bearer $HOSTUP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"action": "update_rdns",
"ip": "203.0.113.42",
"rdns": "app-01.example.com"
}'

Responses

200 The change is done. For get_available_subnets, the free addresses.

{
"subnets": [
{
"id": "subnet_01hxa3b4c5d6e7f8g9h0j1k2m3",
"parentCidr": "203.0.113.0/24",
"isCurrentNetwork": true,
"availableCount": 1,
"ips": [
{
"id": "ip_01hxa3b4c5d6e7f8g9h0j1k2m3",
"ip": "203.0.113.10",
"status": "available",
"subnet": {
"id": "subnet_01hxa3b4c5d6e7f8g9h0j1k2m3",
"parentCidr": "203.0.113.0/24"
}
}
]
}
]
}
Response fields
subnetsarray of object
Free public addresses grouped by network.
idstring or null
Subnet ID (subnet_…).
parentCidrstring or null
The network range in CIDR notation.
isCurrentNetworkboolean
True when the network is the one interfaceName (default net0) is on.
availableCountinteger
Number of free addresses in ips.
ipsarray of object
The free addresses.
idstring or null
IP ID (ip_…). Send it as ipId.
ipstring
The address.
statusstring
Always available.
subnetobject or null
The network of the address.

202 The change was queued. A paid IPv4 change instead waits for its invoice to be paid.

{
"operation": {
"status": "queued",
"jobId": "job_01hxa3b4c5d6e7f8g9h0j1k2m3",
"pollUrl": "/api/jobs/job_01hxa3b4c5d6e7f8g9h0j1k2m3"
}
}
Response fields
operationobject
statusstring
Where the job is. A 202 Accepted response only has pending, queued or in_progress. completed and failed appear when you poll pollUrl. They also appear in a 200 OK response when the action finished during the request. One of pending, queued, in_progress, completed, failed.
jobIdstring
pollUrlstring or null
Where to poll the job while it runs. null when status is already completed or failed.
pendingChangeobject
The IPv4 change waiting for payment. Only on a paid change_ip.
requestIdstring or null
The requestId of the change.
statusstring or null
awaiting_payment, paid or apply_failed.
oldIpstring or null
The address being replaced.
newIpstring or null
The new address, held for the VPS.
interfaceNamestring or null
The interface being changed.
chargeobject or null
The fee, excluding VAT.
holdExpiresAtstring or null
When the held address is released if the invoice is unpaid.
paidAtstring or null
When the invoice was paid.
invoiceobject or null
The invoice to pay. Null until it is ready.

Errors

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

400The body is invalid. detail and errors[].pointer name the field. For update_rdns, reasonCode says why the hostname does not resolve to the address.
401Unauthorized. Authentication is required.
402create_private_interface only: private networking has a setup fee that is not paid. code is payment_required.
403The key lacks a scope. For update_rdns, the address may not be on this VPS (rdns_ip_not_on_vps). Every action except get_available_subnets and repair_guest_network also returns 403 when the bandwidth is used up.
404Not found. The resource does not exist or is not owned by the caller; code is vps_not_found.
409

The change cannot be made now. code says why:

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.