Change VPS network state

Read full description Hide full description

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, 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 using ipId when possible; assign_ips attaches multiple IPs to one interface using ips[]; remove_ip removes one assigned IP from an interface and requires ipType; 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). 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

Use Authorization: Bearer <token> for API keys. Dashboard sessions may also use hostup_session.

Context

Related endpoints

GET /api/v2/vps/{id}/network Get VPS network state GET /api/v2/vps/{id} Get VPS details GET /api/v2/vps/{id}/iso List VPS ISO media

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

Accept Example

Content-Type Example

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

create_public_interface

create_private_interface

delete_interface

delete_primary_interface

ipId stringnull · Example: ip_01hxa3b4c5d6e7f8g9h0j1k2m3

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

ipType stringnull · 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 stringnull · Example: net0

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

subnetId stringnull · 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 stringnull · 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

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

ip stringnull · Example: 203.0.113.42

Assigned IP address whose reverse DNS should change for `update_rdns`.

rdns stringnull · Example: app-01.example.com

Reverse DNS hostname for `update_rdns`. The hostname must pass upstream reverse-DNS validation.

vlan numbernull · 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.

subnets array<object> required

subnets[].id stringnull required · Example: subnet_01hxa3b4c5d6e7f8g9h0j1k2m3

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

subnets[].isCurrentNetwork boolean required · Example: true

subnets[].availableCount integer required · Example: 2

subnets[].ips array<object> required

subnets[].ips[].id stringnull required · Example: ip_01hxa3b4c5d6e7f8g9h0j1k2m3

subnets[].ips[].ip string required · Example: 203.0.113.10

subnets[].ips[].status string required · Example: available

subnets[].ips[].subnet objectnull required · Example: null

202 Network action queued and should be polled.

operation object

operation.status string · enum required · Example: queued

pending

queued

in_progress

completed

failed

operation.jobId string required · Example: job_01hxa3b4c5d6e7f8g9h0j1k2m3

operation.pollUrl string required · Example: /api/jobs/job_01hxa3b4c5d6e7f8g9h0j1k2m3

operation.result objectnull · Example: null

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

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

Scenario

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": null
        }
      ]
    }
  ]
}

{
  "type": "object",
  "properties": {
    "subnets": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": [
              "string",
              "null"
            ]
          },
          "parentCidr": {
            "type": [
              "string",
              "null"
            ]
          },
          "isCurrentNetwork": {
            "type": "boolean"
          },
          "availableCount": {
            "type": "integer"
          },
          "ips": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "ip": {
                  "type": "string"
                },
                "status": {
                  "type": "string"
                },
                "subnet": {
                  "type": [
                    "object",
                    "null"
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}

Request Body Set reverse DNS

{
  "action": "update_rdns",
  "ip": "203.0.113.42",
  "rdns": "app-01.example.com"
}