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_rdnssets 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_subnetsrequiresipTypeand lists free public addresses grouped by network. It returns{ subnets }synchronously.assign_ipattaches one available or reserved public IP and requiresipIdoripAddress.assign_ipsattaches several to one interface. IPv6 must be assigned to an existing public interface that already has IPv4.remove_iptakes an extra address off an interface. The primary IPv4 address cannot be removed. The number of addresses the plan includes stays the same.change_ipreplaces 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: truekeeps the previous public IP as a reserved IP.create_public_interfacecreates a public interface with a selected IPv4 address. IPv6-only public interfaces are not supported.create_private_interfaceconnects the VPS to a subnet of a private network.delete_interfaceremoves an extra interface.delete_primary_interfaceremoves the primary public interface and needsconfirm: true.repair_guest_networkwrites the assigned addresses into the running server whenguestNetwork.statusismismatch.
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
idstringrequiredvps_…).Body
actionstringrequiredassign_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 nullip_…) of the address to use, from GET /api/v2/vps/{id}/network or get_available_subnets. Takes priority over ipAddress.ipTypestring or nullipv4 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 nullnet0. 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 nullsubnet_…). 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 nullipId is known. For create_private_interface, a free IPv4 address in the subnet.reserveOldIpbooleanchange_ip. true keeps the previous public IP on the account as a reserved IP. Default false.cancelPendingChangebooleanchange_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.requestIdstringchange_ip. A new UUID for this change. Required for an IPv4 change. Send the same value again when retrying the same change.expectedPriceobjectchange_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.amountnumberrequiredcurrencyCodestringrequiredipsarray of objectassign_ips. The addresses to attach to interfaceName.ipIdstring or nullrequiredip_…).ipAddressstring or nullrequiredipTypestring or nullrequiredipv4 or ipv6.ipstring or nullupdate_rdns. The address of the VPS whose reverse DNS changes.rdnsstring or nullupdate_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 nullcreate_private_interface. VLAN tag. Leave it out to use the subnet’s tag.confirmbooleandelete_primary_interface. Must be true.Example
- Set reverse DNS
- Reset reverse DNS to the default hostname
- Assign one public IPv4 address
- Assign multiple IP addresses
- Remove an assigned IP address
- Change an IPv4 address and keep the old one
- Change IPv4 after selecting an IP from a requested subnet
- Get available public IPv4 subnets
- Write the assigned addresses into the running server
- Create a public interface with IPv4
- Create a private network interface
- Delete an extra interface
- Delete the primary public interface
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" }'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": "" }'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": "assign_ip", "ipId": "ip_01hxa3b4c5d6e7f8g9h0j1k2m3", "ipType": "ipv4", "interfaceName": "net0" }'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": "assign_ips", "interfaceName": "net0", "ips": [ { "ipId": "ip_01hxa3b4c5d6e7f8g9h0j1k2m3", "ipAddress": "203.0.113.10", "ipType": "ipv4" }, { "ipId": "ip_01hxa3b4c5d6e7f8g9h0j1k2m4", "ipAddress": "2001:db8::10", "ipType": "ipv6" } ] }'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": "remove_ip", "ipId": "ip_01hxa3b4c5d6e7f8g9h0j1k2m3", "ipType": "ipv4", "interfaceName": "net0" }'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": "change_ip", "ipId": "ip_01hxa3b4c5d6e7f8g9h0j1k2m3", "interfaceName": "net0", "subnetId": "subnet_01hxa3b4c5d6e7f8g9h0j1k2m3", "reserveOldIp": true, "requestId": "5f6f2c1e-8b1a-4c8e-9d2a-7c1f0e6b2a11", "expectedPrice": { "amount": 2, "currencyCode": "EUR" } }'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": "change_ip", "ipId": "ip_01hxa3b4c5d6e7f8g9h0j1k2m4", "interfaceName": "net0", "requestId": "0b8e7d4c-3f2a-4e61-9a5b-2c7d8e9f0a12", "expectedPrice": { "amount": 0, "currencyCode": "EUR" } }'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": "get_available_subnets", "ipType": "ipv4" }'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": "repair_guest_network", "interfaceName": "net0" }'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": "create_public_interface", "ipId": "ip_01hxa3b4c5d6e7f8g9h0j1k2m3", "subnetId": "subnet_01hxa3b4c5d6e7f8g9h0j1k2m3" }'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": "create_private_interface", "subnetId": "subnet_01hxa3b4c5d6e7f8g9h0j1k2m4", "ipAddress": "10.42.0.10" }'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": "delete_interface", "interfaceName": "net1" }'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": "delete_primary_interface", "confirm": true }'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" } } ] } ]}{ "operation": { "status": "completed", "jobId": "job_01hxa3b4c5d6e7f8g9h0j1k2m3", "pollUrl": null }}Response fields
subnetsarray of objectidstring or nullsubnet_…).parentCidrstring or nullisCurrentNetworkbooleaninterfaceName (default net0) is on.availableCountintegerips.ipsarray of objectidstring or nullip_…). Send it as ipId.ipstringstatusstringavailable.subnetobject or null202 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" }}{ "operation": { "status": "pending", "jobId": "job_01hxa3b4c5d6e7f8g9h0j1k2m4", "pollUrl": null }, "pendingChange": { "requestId": "5f6f2c1e-8b1a-4c8e-9d2a-7c1f0e6b2a11", "status": "awaiting_payment", "oldIp": "203.0.113.42", "newIp": "198.51.100.20", "interfaceName": "net0", "charge": { "amount": 2, "currencyCode": "EUR" }, "holdExpiresAt": "2026-11-02T16:00:00.000Z", "paidAt": null, "invoice": { "id": "inv_01hxa3b4c5d6e7f8g9h0j1k2m3", "number": "202600123", "paymentUrl": "/billing?invoice=202600123" } }}Response fields
operationobjectstatusstring202 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.jobIdstringpollUrlstring or nullnull when status is already completed or failed.pendingChangeobjectchange_ip.requestIdstring or nullrequestId of the change.statusstring or nullawaiting_payment, paid or apply_failed.oldIpstring or nullnewIpstring or nullinterfaceNamestring or nullchargeobject or nullholdExpiresAtstring or nullpaidAtstring or nullinvoiceobject or nullErrors
Errors are Problem Details with a stable code. Branch on the code, not on the text.
| 400 | The body is invalid. detail and errors[].pointer name the field. For update_rdns, reasonCode says why the hostname does not resolve to the address. |
| 401 | Unauthorized. Authentication is required. |
| 402 | create_private_interface only: private networking has a setup fee that is not paid. code is payment_required. |
| 403 | The 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. |
| 404 | Not 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.
|
| 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. |