Skip to content

ip_address

Manage IP addresses

Assign

Path
POST /v7.0/ip_addresses/{ip_address_id}/assign
Description
Route the address to an interface
Authentication required
yes
Scope
ip_address#assign
Aliases
Blocking
yes

Input parameters

Layout
object
Namespace
ip_address
ParameterTypeRequiredDetails
network_interface
NetworkInterface
 Resource yes
route_via
Route_via
 Resource no

Output parameters

Layout
object
Namespace
ip_address
ParameterTypeDescription
id
ID
 Integer IP address ID
network_interface
NetworkInterface
 Resource
network
Network
 Resource
user
User
 Resource Filter by owner
addr
Address
 String Address itself
prefix
Prefix
 Integer
size
Size
 Integer
route_via
Route_via
 Resource
charged_environment
Charged environment
 Resource

Assign_with_host_address

Path
POST /v7.0/ip_addresses/{ip_address_id}/assign_with_host_address
Description
Route the address to an interface
Authentication required
yes
Scope
ip_address#assign_with_host_address
Aliases
Blocking
yes

Input parameters

Layout
object
Namespace
ip_address
ParameterTypeRequiredDetails
network_interface
NetworkInterface
 Resource yes
host_ip_address
HostIpAddress
 Resource no

Host address to assign to the interface, defaults to the first address

Output parameters

Layout
object
Namespace
ip_address
ParameterTypeDescription
id
ID
 Integer IP address ID
network_interface
NetworkInterface
 Resource
network
Network
 Resource
user
User
 Resource Filter by owner
addr
Address
 String Address itself
prefix
Prefix
 Integer
size
Size
 Integer
route_via
Route_via
 Resource
charged_environment
Charged environment
 Resource

Create

Path
POST /v7.0/ip_addresses
Description
Add an IP address
Authentication required
yes
Scope
ip_address#create
Aliases
new
Blocking
no

Input parameters

Layout
object
Namespace
ip_address
ParameterTypeRequiredDetails
network_interface
NetworkInterface
 Resource no
network
Network
 Resource yes
user
User
 Resource no

Filter by owner
addr
Address
 String yes

Address itself

Default: null

Validation rules
RuleDetails
Present

Must be supplied and cannot be null. Must not be empty; strings must contain a non-whitespace character.

Validation error message: must be present and non-empty
prefix
Prefix
 Integer no

Default: null
size
Size
 Integer no

Default: null
route_via
Route_via
 Resource no
location
Location
 Resource no

Location this IP address is available in

Output parameters

Layout
object
Namespace
ip_address
ParameterTypeDescription
id
ID
 Integer IP address ID
network_interface
NetworkInterface
 Resource
network
Network
 Resource
user
User
 Resource Filter by owner
addr
Address
 String Address itself
prefix
Prefix
 Integer
size
Size
 Integer
route_via
Route_via
 Resource
charged_environment
Charged environment
 Resource

Free

Path
POST /v7.0/ip_addresses/{ip_address_id}/free
Description
Remove the route from an interface
Authentication required
yes
Scope
ip_address#free
Aliases
Blocking
yes

Input parameters

No parameters.

Output parameters

Layout
object
Namespace
ip_address
ParameterTypeDescription
id
ID
 Integer IP address ID
network_interface
NetworkInterface
 Resource
network
Network
 Resource
user
User
 Resource Filter by owner
addr
Address
 String Address itself
prefix
Prefix
 Integer
size
Size
 Integer
route_via
Route_via
 Resource
charged_environment
Charged environment
 Resource

Index

Path
GET /v7.0/ip_addresses
Description
List IP addresses
Authentication required
yes
Scope
ip_address#index
Aliases
list
Blocking
no

Input parameters

Layout
object
Namespace
ip_address
ParameterTypeRequiredDetails
from_id
From ID
 Integer no

List objects with IDs greater or lower than this value

Default: null

Validation rules
RuleDetails
Number
  • Must be a number after parameter type conversion.
  • Minimum: 0 (inclusive).

Validation error message: must be at least 0
limit
Limit
 Integer no

Number of objects to retrieve

Default: null

Validation rules
RuleDetails
Number
  • Must be a number after parameter type conversion.
  • Minimum: 0 (inclusive).
  • Maximum: 1000 (inclusive).

Validation error message: must be between 0 and 1000
network_interface
NetworkInterface
 Resource no
vps
VPS
 Resource no

VPS this IP is assigned to, can be null
version
IP version
 Integer no

4 or 6

Default: null
network
Network
 Resource no
location
Location
 Resource no

Location this IP address is available in
user
User
 Resource no

Filter by owner
assigned_to_interface
Assigned to interface
 Boolean no

Default: null
network_enabled
Network enabled
 Boolean no

Default: null
role
Role
 String no

Show only datasets of certain role

Default: null

Validation rules
RuleDetails
Include

Allowed values:

  • public_access
  • private_access

Validation error message: %{value} cannot be used
purpose
Purpose
 String no

Default: null

Validation rules
RuleDetails
Include

Allowed values:

  • any
  • vps
  • export

Validation error message: %{value} cannot be used
usable_for
Usable for
 String no

Filter by compatible network purpose, including networks with purpose any

Default: null

Validation rules
RuleDetails
Include

Allowed values:

  • vps
  • export

Validation error message: %{value} cannot be used
addr
Address
 String no

Address itself

Default: null
prefix
Prefix
 Integer no

Default: null
size
Size
 Integer no

Default: null
order
Order
 String no

Template order

Default: asc

Validation rules
RuleDetails
Include

Allowed values:

  • asc
  • interface

Validation error message: %{value} cannot be used

Output parameters

Layout
object_list
Namespace
ip_addresses
ParameterTypeDescription
id
ID
 Integer IP address ID
network_interface
NetworkInterface
 Resource
network
Network
 Resource
user
User
 Resource Filter by owner
addr
Address
 String Address itself
prefix
Prefix
 Integer
size
Size
 Integer
route_via
Route_via
 Resource
charged_environment
Charged environment
 Resource

Examples

Examples use an initialized api client, authenticated when required. See initialization and authentication.

Example #0

List IP addresses assigned to VPS with ID 101.

Ruby · Simple 
reply = api.ip_address.index({vps: 101})

# reply is an instance of HaveAPI::Client::ResourceInstanceList,
# which is a subclass of Array
Ruby · With error handling 
begin
  require 'haveapi/client'

  api = HaveAPI::Client.new("https://api.vpsfree.cz/", version: "7.0")
  api.setup

  api.authenticate(:token, token: 'example-token')

  reply = api.ip_address.index({vps: 101})

  # reply is an instance of HaveAPI::Client::ResourceInstanceList,
  # which is a subclass of Array
rescue HaveAPI::Client::ValidationError => error
  warn error.message
  warn error.errors.inspect
rescue HaveAPI::Client::ActionFailed => error
  warn error.message
  warn error.response.errors.inspect if error.response.is_a?(HaveAPI::Client::Response)
rescue HaveAPI::Client::Authentication::AuthenticationFailed, HaveAPI::Client::ProtocolError,
       RestClient::Exception, JSON::ParserError => error
  warn error.message
end
JavaScript (callback) · Simple 
const resource = CallbackClient.findResource(api, ["ip_address"]);
const action = CallbackClient.findAction(resource, "index");
action.directInvoke({
  params: {["vps"]: 101},
  onReply: (owner, reply) => {
    if (!reply.isOk()) {
      console.error(reply.message(), reply.envelope.errors);
      return;
    }
    console.log(reply.response());
  }
});
JavaScript (callback) · With error handling 
import { CallbackClient } from "haveapi-client";

const api = new CallbackClient("https://api.vpsfree.cz/", {version: "7.0"});

api.authenticate("token", {token: "example-token"}, (api, ready) => {
  if (!ready) {
    console.error("Discovery or authentication failed");
    return;
  }
  try {
    const resource = CallbackClient.findResource(api, ["ip_address"]);
    const action = CallbackClient.findAction(resource, "index");
    action.directInvoke({
      params: {["vps"]: 101},
      onReply: (owner, reply) => {
        if (!reply.isOk()) {
          console.error(reply.message(), reply.envelope.errors);
          return;
        }
        console.log(reply.response());
        console.log(reply.meta());
      }
    });
  } catch (error) {
    console.error(error);
  }
});
JavaScript (async) · Simple 
const result = await api.resource("ip_address").action("index")({params: {["vps"]: 101}});
console.log(result.value);
JavaScript (async) · With error handling 
import { AsyncClient, AsyncError } from "haveapi-client";

async function main() {
  const api = new AsyncClient("https://api.vpsfree.cz/", {version: "7.0"});
  try {
    await api.authenticate("token", {token: "example-token"});
    const result = await api.resource("ip_address").action("index")({params: {["vps"]: 101}});
    console.log(result.value);
    console.log(result.response.meta);
  } catch (error) {
    if (error instanceof AsyncError) {
      console.error(error.kind, error.message, error.errors);
    } else {
      throw error;
    }
  }
}
main().catch(error => console.error(error));
TypeScript (callback) · Simple 
const resource = CallbackClient.findResource(api, ["ip_address"]);
const action = CallbackClient.findAction(resource, "index");
action.directInvoke({
  params: {["vps"]: 101},
  onReply: (owner, reply) => {
    if (!reply.isOk()) {
      console.error(reply.message(), reply.envelope.errors);
      return;
    }
    console.log(reply.response());
  }
});
TypeScript (callback) · With error handling 
import { CallbackClient } from "haveapi-client";

const api = new CallbackClient("https://api.vpsfree.cz/", {version: "7.0"});

api.authenticate("token", {token: "example-token"}, (api, ready) => {
  if (!ready) {
    console.error("Discovery or authentication failed");
    return;
  }
  try {
    const resource = CallbackClient.findResource(api, ["ip_address"]);
    const action = CallbackClient.findAction(resource, "index");
    action.directInvoke({
      params: {["vps"]: 101},
      onReply: (owner, reply) => {
        if (!reply.isOk()) {
          console.error(reply.message(), reply.envelope.errors);
          return;
        }
        console.log(reply.response());
        console.log(reply.meta());
      }
    });
  } catch (error) {
    console.error(error);
  }
});
TypeScript (async) · Simple 
const result = await api.resource("ip_address").action("index")({params: {["vps"]: 101}});
console.log(result.value);
TypeScript (async) · With error handling 
import { AsyncClient, AsyncError } from "haveapi-client";

async function main(): Promise<void> {
  const api = new AsyncClient("https://api.vpsfree.cz/", {version: "7.0"});
  try {
    await api.authenticate("token", {token: "example-token"});
    const result = await api.resource("ip_address").action("index")({params: {["vps"]: 101}});
    console.log(result.value);
    console.log(result.response.meta);
  } catch (error) {
    if (error instanceof AsyncError) {
      console.error(error.kind, error.message, error.errors);
    } else {
      throw error;
    }
  }
}
main().catch(error => console.error(error));
Python (sync) · Simple 
response = api.resources["ip_address"].actions["index"].call(params={"vps": 101})
print(response.data)
Python (sync) · With error handling 
from haveapi_client import Client, ActionError, HaveAPIError, TokenAuth

try:
    with Client("https://api.vpsfree.cz/", version="7.0", auth=TokenAuth("example-token")) as api:
        response = api.resources["ip_address"].actions["index"].call(params={"vps": 101})
        print(response.data)
        print(response.meta)
except ActionError as error:
    print(error.message, error.errors)
except HaveAPIError as error:
    print(error.message, error.status_code)
Python (async) · Simple 
# Run inside an async function after initializing api.
response = await api.resources["ip_address"].actions["index"].call(params={"vps": 101})
print(response.data)
Python (async) · With error handling 
import asyncio

from haveapi_client import AsyncClient, ActionError, HaveAPIError, TokenAuth


async def main() -> None:
    try:
        async with AsyncClient("https://api.vpsfree.cz/", version="7.0", auth=TokenAuth("example-token")) as api:
            response = await api.resources["ip_address"].actions["index"].call(params={"vps": 101})
            print(response.data)
            print(response.meta)
    except ActionError as error:
        print(error.message, error.errors)
    except HaveAPIError as error:
        print(error.message, error.status_code)


asyncio.run(main())
Go API client · Simple 
invocation := api.IpAddress.Index.Prepare()
input := invocation.NewInput().SelectParameters()
input.SetVps(101)
response, err := invocation.Call()
if err != nil {
	fmt.Println(err)
	return
}
if !response.Status {
	fmt.Println(response.Message, response.Errors)
	return
}
for _, item := range response.Output {
	if item != nil {
		fmt.Println(item.Id)
		if item.NetworkInterface != nil {
			fmt.Println(item.NetworkInterface.Id)
			fmt.Println(item.NetworkInterface.Name)
		}
		if item.Network != nil {
			fmt.Println(item.Network.Id)
			fmt.Println(item.Network.Address)
		}
		fmt.Println(item.Addr)
		fmt.Println(item.Prefix)
	}
}
Rust API client (async) · Simple 
// Use inside an async function returning Result<(), Box<dyn std::error::Error>>.
let response = api.ip_address().index().vps(101_i64).send().await?;
for item in &response.output {
    println!("{:?}", &item.id);
    println!("{:?}", &item.network_interface);
    println!("{:?}", &item.network);
    println!("{:?}", &item.addr);
    println!("{:?}", &item.prefix);
}
Rust API client (async) · With error handling 
// cargo add vpsadmin-client
// cargo add tokio --features macros,rt-multi-thread
// cargo add serde_json
use vpsadmin_client::Client;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api = match Client::builder("https://api.vpsfree.cz/")
        .basic_auth("user", "secret")
        .build() {
        Ok(api) => api,
        Err(error) => {
            eprintln!("Client configuration failed: {}", error);
            eprintln!("HTTP status: {:?}; timeout: {}", error.http_status(), error.is_timeout());
            return Err(error.into());
        }
    };
    let response = match api.ip_address().index().vps(101_i64).send().await {
        Ok(response) => response,
        Err(error) => {
            eprintln!("Request failed: {}", error);
            eprintln!("HTTP status: {:?}; timeout: {}", error.http_status(), error.is_timeout());
            return Err(error.into());
        }
    };
    let _ = response.http_status;
    let _ = &response.meta;
    for item in &response.output {
        println!("{:?}", &item.id);
        println!("{:?}", &item.network_interface);
        println!("{:?}", &item.network);
        println!("{:?}", &item.addr);
        println!("{:?}", &item.prefix);
    }
    Ok(())
}
Rust API client (blocking) · Simple 
// Use inside a synchronous function outside async runtime threads returning Result<(), Box<dyn std::error::Error>>.
let response = api.ip_address().index().vps(101_i64).send()?;
for item in &response.output {
    println!("{:?}", &item.id);
    println!("{:?}", &item.network_interface);
    println!("{:?}", &item.network);
    println!("{:?}", &item.addr);
    println!("{:?}", &item.prefix);
}
Rust API client (blocking) · With error handling 
// cargo add vpsadmin-client --features blocking
// cargo add serde_json
// Construct, use and drop this blocking client outside async runtime threads.
use vpsadmin_client::blocking::Client;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api = match Client::builder("https://api.vpsfree.cz/")
        .basic_auth("user", "secret")
        .build() {
        Ok(api) => api,
        Err(error) => {
            eprintln!("Client configuration failed: {}", error);
            eprintln!("HTTP status: {:?}; timeout: {}", error.http_status(), error.is_timeout());
            return Err(error.into());
        }
    };
    let response = match api.ip_address().index().vps(101_i64).send() {
        Ok(response) => response,
        Err(error) => {
            eprintln!("Request failed: {}", error);
            eprintln!("HTTP status: {:?}; timeout: {}", error.http_status(), error.is_timeout());
            return Err(error.into());
        }
    };
    let _ = response.http_status;
    let _ = &response.meta;
    for item in &response.output {
        println!("{:?}", &item.id);
        println!("{:?}", &item.network_interface);
        println!("{:?}", &item.network);
        println!("{:?}", &item.addr);
        println!("{:?}", &item.prefix);
    }
    Ok(())
}
TypeScript API client · Simple 
// Requires an initialized api and an async context.
const result = await api.ip_address.index({ "params": { "vps": 101 } });
for (const item of result.data) {
  console.log(item.id);
  console.log(item.network_interface);
  console.log(item.network);
  console.log(item.addr);
  console.log(item.prefix);
}
TypeScript API client · With error handling 
// Configured API client: vpsadmin-typescript-client.
import { AsyncClient, AsyncError } from "haveapi-client";
import { createClient } from "vpsadmin-typescript-client";

async function main(): Promise<void> {
  try {
    const runtime = new AsyncClient("https://api.vpsfree.cz/v7.0");
    await runtime.authenticate("basic", { user: "user", password: "secret" });
    const api = createClient({ execute: spec => runtime.request(spec) });
    const result = await api.ip_address.index({ "params": { "vps": 101 } });
    void [result.data, result.meta, result.envelope, result.httpStatus];
    for (const item of result.data) {
      const value0: unknown = item.id;
      if (value0 !== null && value0 !== undefined) console.log(value0);
      const value1: unknown = item.network_interface;
      if (value1 !== null && value1 !== undefined) console.log(value1);
      const value2: unknown = item.network;
      if (value2 !== null && value2 !== undefined) console.log(value2);
      const value3: unknown = item.addr;
      if (value3 !== null && value3 !== undefined) console.log(value3);
      const value4: unknown = item.prefix;
      if (value4 !== null && value4 !== undefined) console.log(value4);
    }
  } catch (error) {
    if (!(error instanceof AsyncError)) throw error;
    console.error(error.kind, error.httpStatus);
    throw error;
  }
}

main().catch(error => { throw error; });
PHP · Simple 
$reply = $api->ip_address->index([
    'vps' => 101
]);

// $reply is an instance of \HaveAPI\Client\ResourceInstanceList
PHP · With error handling 
try {
    $api = new \HaveAPI\Client('https://api.vpsfree.cz/', '7.0');
    $api->setup();

    $api->authenticate('token', ['token' => 'example-token']);

    $reply = $api->ip_address->index([
        'vps' => 101
    ]);

    // $reply is an instance of \HaveAPI\Client\ResourceInstanceList
} catch (\HaveAPI\Client\Exception\ValidationError $error) {
    echo $error->getMessage() . "\n";
    print_r($error->getErrors());
} catch (\HaveAPI\Client\Exception\ActionFailed $error) {
    echo $error->getMessage() . "\n";
    print_r($error->getErrors());
} catch (\HaveAPI\Client\Exception\Base $error) {
    echo $error->getMessage() . "\n";
} catch (\Exception $error) {
    // Dependency failures still propagate to the application.
    echo $error->getMessage() . "\n";
    throw $error;
}
CLI · Simple 
$ haveapi-cli -u https://api.vpsfree.cz/ --version 7.0 ip_address index -- \
              --vps 101
#                   ID:  10
#     NetworkInterface:  eth0 (#42)
#              Network:  192.168.0.0 (#1)
#                 User:  -
#              Address:  192.168.0.50
#               Prefix:  24
#                 Size:  -
#            Route_via:  -
#  Charged environment:  -
#
curl · Simple 
$ curl --request GET \
       --data-binary \{\"ip_address\":\{\"vps\":101\}\} \
       https://api.vpsfree.cz/v7.0/ip_addresses\?vps\=101

# {
#   "status": true,
#   "message": null,
#   "response": {
#     "ip_addresses": [
#       {
#         "id": 10,
#         "network_interface": {
#           "id": 42,
#           "name": "eth0"
#         },
#         "network": {
#           "id": 1,
#           "address": "192.168.0.0"
#         },
#         "addr": "192.168.0.50",
#         "prefix": 24
#       }
#     ]
#   },
#   "errors": null
# }
HTTP · Simple 
GET /v7.0/ip_addresses?vps=101 HTTP/1.1
Host: api.vpsfree.cz
Content-Type: application/json



HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
Content-Length: 366

{
  "status": true,
  "message": null,
  "response": {
    "ip_addresses": [
      {
        "id": 10,
        "network_interface": {
          "id": 42,
          "name": "eth0"
        },
        "network": {
          "id": 1,
          "address": "192.168.0.0"
        },
        "addr": "192.168.0.50",
        "prefix": 24
      }
    ]
  },
  "errors": null
}

Show

Path
GET /v7.0/ip_addresses/{ip_address_id}
Description
Show IP address
Authentication required
yes
Scope
ip_address#show
Aliases
find
Blocking
no

Input parameters

No parameters.

Output parameters

Layout
object
Namespace
ip_address
ParameterTypeDescription
id
ID
 Integer IP address ID
network_interface
NetworkInterface
 Resource
network
Network
 Resource
user
User
 Resource Filter by owner
addr
Address
 String Address itself
prefix
Prefix
 Integer
size
Size
 Integer
route_via
Route_via
 Resource
charged_environment
Charged environment
 Resource

Update

Path
PUT /v7.0/ip_addresses/{ip_address_id}
Description
Update IP address
Authentication required
yes
Scope
ip_address#update
Aliases
Blocking
yes

Input parameters

Layout
object
Namespace
ip_address
ParameterTypeRequiredDetails
user
User
 Resource no

Filter by owner
environment
Environment
 Resource no

Output parameters

Layout
object
Namespace
ip_address
ParameterTypeDescription
id
ID
 Integer IP address ID
network_interface
NetworkInterface
 Resource
network
Network
 Resource
user
User
 Resource Filter by owner
addr
Address
 String Address itself
prefix
Prefix
 Integer
size
Size
 Integer
route_via
Route_via
 Resource
charged_environment
Charged environment
 Resource