Change VPS network state

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

Perform one whitelisted network operation for a VPS.

Read GET /api/v2/vps/{id}/network first to get interface names, assigned IP IDs, available IP IDs, subnet IDs, private-network choices, guest-network status, and action gates.

action selects exactly one operation; send only the fields listed for that action because unknown fields are rejected.

Action guide: update_rdns sets reverse DNS for an assigned IP using ip and rdns; assign_ip attaches one available or reserved public IP and requires ipId or ipAddress for one concrete available IP; do not call assign_ip with only ipType or only subnetId.

assign_ips attaches multiple IPs to one interface using ips[]; remove_ip detaches one non-primary assigned IP from an interface and requires ipType; it releases the address assignment but does not reduce the VPS's configured or purchased IP capacity; get_available_subnets requires ipType (ipv4 or ipv6) and returns sanitized public subnet groups immediately; change_ip replaces an assigned IP and requires ipId or ipAddress for one concrete available IP.

To satisfy a request such as "change my VPS to 64.112.125.0/24 or another IPv4 from a different /24", first call get_available_subnets with { "action": "get_available_subnets", "ipType": "ipv4" }, filter the returned subnets[] by parentCidr when the user named a subnet, choose one returned subnets[].ips[].id, then call change_ip with that ipId and interfaceName (usually net0).

For assign_ip, use the same discovery pattern when no direct available IP ID is already known: call get_available_subnets, choose one returned subnets[].ips[].id, then retry assign_ip with that ipId.

repair_guest_network applies the assigned addresses inside the running server and removes stale observed addresses when guestNetwork.status is mismatch and guestNetwork.actions.canRepair.allowed is true; send interfaceName from the mismatch row, usually net0.

reserveOldIp: true keeps the previous public IP as a reserved public IP instead of returning it to the pool.

ipType is optional for change_ip because the server infers the family from the selected address, and subnetId may be sent with ipId/ipAddress to prove the selected IP came from the chosen subnet.

subnetId alone does not choose an IP, and confirm is not a valid change_ip field.

create_public_interface creates a public interface with a selected public IP; create_private_interface creates a private-network interface from a private subnet; delete_interface removes a non-primary interface by interfaceName; delete_primary_interface removes the primary public interface only when confirm: true and the network state allows it.

Mutating actions return an operation envelope.

If the operation completed inline, operation.status is completed and operation.pollUrl is null; if a restart/reconfigure job was queued, the response is 202 with a poll URL.

get_available_subnets is read-style and returns { subnets } synchronously.

VPS Services Networking

Authentication

Required API scopes: write:vmwrite:network

Authenticate with an API key in the Authorization: Bearer <token> header.

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

Authorization Bearer <token>
Accept application/json
Content-Type application/json

Body

required
application/json
action string · enum required · Example: update_rdns

Network action to perform. Each action accepts only its documented fields; unknown fields are rejected.

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
ipId string · nullable · Example: ip_01hxa3b4c5d6e7f8g9h0j1k2m3

Public IP address ID from GET /api/v2/vps/{id}/network availableIPv4[].id, availableIPv6[].id, or interface ip[].id. Prefer this over ipAddress when both are available.

ipType string · nullable · enum · Example: ipv4

IP family. Required for get_available_subnets and remove_ip; optional for assign_ip and change_ip when ipId or ipAddress identifies an address.

ipv4
ipv6
interfaceName string · nullable · Example: net0

Interface name from GET /api/v2/vps/{id}/network interfaces[].id or guestNetwork.mismatches[].interfaceName. Required when assigning/removing/changing IPs, repairing guest network settings, or deleting an interface. For private-interface creation, omit it unless the network state tells you to use a specific name.

subnetId string · nullable · Example: subnet_01hxa3b4c5d6e7f8g9h0j1k2m3

Subnet ID from network availability results. Accepted by assign_ip, create_public_interface, create_private_interface, and by change_ip only together with ipId or ipAddress to validate the selected IP. It does not choose an IP by itself.

ipAddress string · nullable · Example: 203.0.113.10

Raw IP address fallback when no ipId is available. Prefer ipId for public IP operations.

reserveOldIp boolean · Example: true

Only accepted for change_ip. When true, the old public IP is kept as a reserved public IP instead of being returned to the pool.

ips array<object>

Batch assignment list for assign_ips. Each item identifies one IP to attach to the same interface.

ips[].ipId string · nullable required · Example: ip_01hxa3b4c5d6e7f8g9h0j1k2m3

Nullable: may be null when not applicable.

ips[].ipAddress string · nullable required · Example: 203.0.113.10

Nullable: may be null when not applicable.

ips[].ipType string · nullable required · Example: ipv4

Nullable: may be null when not applicable.

ip string · nullable · Example: 203.0.113.42

Assigned IP address whose reverse DNS should change for update_rdns.

rdns string · nullable · Example: app-01.example.com

Reverse DNS hostname for update_rdns. Non-empty values must be public hostnames that pass forward-DNS validation. Send an empty string to reset reverse DNS to the default hostname for the IP.

vlan number · nullable · Example: 220

Optional VLAN tag for create_private_interface. Usually omit this and use the subnet/private-network defaults from the network state.

confirm boolean · Example: true

Required and must be true only for delete_primary_interface.

Responses

200 Network action completed or subnet availability returned.
OperationEnvelope
operation object required
operation.status string · enum required · Example: queued

Operation status. 202 Accepted responses only carry pending, queued, or in_progress; the terminal completed and failed values appear only in 200 OK responses for operations that finished within the request, or when polling pollUrl.

pending
queued
in_progress
completed
failed
operation.jobId string required · Example: job_01hxa3b4c5d6e7f8g9h0j1k2m3
operation.pollUrl string · nullable required · Example: /api/jobs/job_01hxa3b4c5d6e7f8g9h0j1k2m3

URL to poll for progress while the operation is in flight. null when status is already terminal (completed or failed), so there is nothing left to poll.

Variant 2
subnets array<object> required
subnets[].id string · nullable required · Example: subnet_01hxa3b4c5d6e7f8g9h0j1k2m3

Nullable: may be null when not applicable.

subnets[].parentCidr string · nullable required · Example: 203.0.113.0/24

Nullable: may be null when not applicable.

subnets[].isCurrentNetwork boolean required · Example: true
subnets[].availableCount integer required · Example: 2
subnets[].ips array<object> required
subnets[].ips[].id string · nullable required · Example: ip_01hxa3b4c5d6e7f8g9h0j1k2m3

Nullable: may be null when not applicable.

subnets[].ips[].ip string required · Example: 203.0.113.10
subnets[].ips[].status string required · Example: available
subnets[].ips[].subnet object · nullable required · Example: null

Nullable: may be null when not applicable.

202 Network action queued and should be polled.
operation object
operation.status string · enum required · Example: queued

Operation status. 202 Accepted responses only carry pending, queued, or in_progress; the terminal completed and failed values appear only in 200 OK responses for operations that finished within the request, or when polling pollUrl.

pending
queued
in_progress
completed
failed
operation.jobId string required · Example: job_01hxa3b4c5d6e7f8g9h0j1k2m3
operation.pollUrl string · nullable required · Example: /api/jobs/job_01hxa3b4c5d6e7f8g9h0j1k2m3

URL to poll for progress while the operation is in flight. null when status is already terminal (completed or failed), so there is nothing left to poll.

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
409 The VPS is busy applying another change (for example a previous network update, restart, or migration is still in progress). Wait a moment and retry the same request.
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
POST https://cloud.hostup.se/api/v2/vps/{id}/network
For AI assistants
View as Markdown
cURL 
curl -X POST "https://cloud.hostup.se/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/network" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "update_rdns",
    "ip": "203.0.113.42",
    "rdns": "app-01.example.com"
  }'
Response 
{
  "subnets": [
    {
      "id": "subnet_01hxa3b4c5d6e7f8g9h0j1k2m3",
      "parentCidr": "203.0.113.0/24",
      "isCurrentNetwork": true,
      "availableCount": 2,
      "ips": [
        {
          "id": "ip_01hxa3b4c5d6e7f8g9h0j1k2m3",
          "ip": "203.0.113.10",
          "status": "available",
          "subnet": {
            "id": "subnet_01hxa3b4c5d6e7f8g9h0j1k2m3",
            "parentCidr": "203.0.113.0/24"
          }
        }
      ]
    }
  ]
}
Request Body Set reverse DNS 
{
  "action": "update_rdns",
  "ip": "203.0.113.42",
  "rdns": "app-01.example.com"
}