Skip to content

vps

Manage VPS

Boot

Input parameters

ParameterTypeRequiredDetails
os_template
OS template
Resource no
mount_root_dataset
Rootfs mountpoint
String no

Default: null

Output parameters

No parameters.

Clone

Input parameters

ParameterTypeRequiredDetails
environment
Environment
Resource no

Clone to environment

location
Location
Resource no

Clone to location

node
Node
Resource no

Clone to node

user
User
Resource no

The owner of the cloned VPS

address_location
Address location
Resource no

Location to select IP addresses from

platform
Platform
String no

Default: same

Validation rules
RuleDetails
Include

Allowed values:

  • same
  • vpsadminos

Validation error message: %{value} cannot be used

dataset_plans
Dataset plans
Boolean no

Default: true

resources
Resources
Boolean no

Clone resources such as memory and CPU

Default: true

features
Features
Boolean no

Default: true

hostname
Hostname
String no

Default: null

Validation rules
RuleDetails
Format

Must match this regular expression:

\A[a-zA-Z0-9][a-zA-Z\-_.0-9]{0,62}[a-zA-Z0-9]\z

null

Validation error message: bad format

stop
Shutdown
Boolean no

Do a consistent clone - original VPS is shut down before making a snapshot

Default: true

keep_snapshots
Keep snapshots
Boolean no

Keep snapshots created during the cloning process

Default: false

Output parameters

ParameterTypeDescription
id
VPS id
Integer
user
User
Resource VPS owner
hostname
Hostname
String VPS hostname
manage_hostname
Manage hostname
Boolean Determines whether vpsAdmin sets VPS hostname or not
os_template
OS template
Resource
cgroup_version
Cgroup_version
String
map_mode
Map mode
String
info
Info
String VPS description
dns_resolver
DNS resolver
Resource DNS resolver the VPS will use
node
Node
Resource Node VPS will run on
user_namespace_map
UID/GID mapping
Resource
autostart_enable
Auto-start
Boolean Start VPS on node boot?
autostart_priority
Auto-start priority
Integer 0 is the highest priority, greater numbers have lower priority
onstartall
On start all
Boolean Start VPS on start all action?
config
Config
String Custom configuration options
cpu_limit
CPU limit
Integer Limit of maximum CPU usage
start_menu_timeout
Start menu timeout
Integer Number of seconds the start menu waits for the user
allow_admin_modifications
Allow admin modifications
Boolean
enable_os_template_auto_update
Enable OS template auto update
Boolean
enable_network
Enable network
Boolean
dataset
Dataset
Resource Dataset the VPS resides in
pool
Pool
Resource Storage pool the VPS resides in
created_at
Created at
Datetime
implicit_oom_report_rule_hit_count
Implicit_oom_report_rule_hit_count
Integer
cpu
CPU
Integer Minimally 1, maximally 1024, step size is 1
diskspace
Disk space
Integer Minimally 1024, maximally 1048576, step size is 1
memory
Memory
Integer Minimally 128, maximally 1048576, step size is 1
swap
Swap
Integer Minimally 0, maximally 1048576, step size is 1
is_running
Running
Boolean
in_rescue_mode
In rescue mode
Boolean
uptime
Uptime
Integer
loadavg1
Loadavg1
Float
loadavg5
Loadavg5
Float
loadavg15
Loadavg15
Float
process_count
Process count
Integer
cpu_user
Cpu_user
Float
cpu_nice
Cpu_nice
Float
cpu_system
Cpu_system
Float
cpu_idle
Cpu_idle
Float
cpu_iowait
Cpu_iowait
Float
cpu_irq
Cpu_irq
Float
cpu_softirq
Cpu_softirq
Float
used_memory
Used memory
Integer in MB
used_swap
Used swap
Integer in MB
used_diskspace
Used disk space
Integer in MB

Create

Input parameters

ParameterTypeRequiredDetails
environment
Environment
Resource no

Environment in which to create the VPS, for non-admins

location
Location
Resource no

Location in which to create the VPS, for non-admins

address_location
Address location
Resource no

Location to select IP addresses from

user
User
Resource no

VPS owner

hostname
Hostname
String yes

VPS hostname

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

Format

Must match this regular expression:

\A[a-zA-Z0-9][a-zA-Z\-_.0-9]{0,62}[a-zA-Z0-9]\z

null

Validation error message: bad format

os_template
OS template
Resource no
cgroup_version
Cgroup_version
String no

Default: cgroup_any

Validation rules
RuleDetails
Include

Allowed values:

  • cgroup_any
  • cgroup_v1
  • cgroup_v2

Validation error message: %{value} cannot be used

map_mode
Map mode
String no

Default: native

Validation rules
RuleDetails
Include

Allowed values:

  • native
  • zfs

Validation error message: %{value} cannot be used

info
Info
String no

VPS description

Default: null

dns_resolver
DNS resolver
Resource no

DNS resolver the VPS will use

node
Node
Resource no

Node VPS will run on

user_namespace_map
UID/GID mapping
Resource no
autostart_enable
Auto-start
Boolean no

Start VPS on node boot?

Default: null

autostart_priority
Auto-start priority
Integer no

0 is the highest priority, greater numbers have lower priority

Default: 1000

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

Validation error message: must be at least 0

onstartall
On start all
Boolean no

Start VPS on start all action?

Default: true

config
Config
String no

Custom configuration options

Default: ""

cpu_limit
CPU limit
Integer no

Limit of maximum CPU usage

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

start_menu_timeout
Start menu timeout
Integer no

Number of seconds the start menu waits for the user

Default: null

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

Validation error message: must be between 0 and 86400

allow_admin_modifications
Allow admin modifications
Boolean no

Default: null

enable_os_template_auto_update
Enable OS template auto update
Boolean no

Default: null

enable_network
Enable network
Boolean no

Default: null

cpu
CPU
Integer no

Minimally 1, maximally 1024, step size is 1

Default: null

diskspace
Disk space
Integer no

Minimally 1024, maximally 1048576, step size is 1

Default: null

memory
Memory
Integer no

Minimally 128, maximally 1048576, step size is 1

Default: null

swap
Swap
Integer no

Minimally 0, maximally 1048576, step size is 1

Default: null

ipv4
IPv4
Integer no

Default: 1

ipv6
IPv6
Integer no

Default: 1

ipv4_private
Private IPv4
Integer no

Default: 0

start
Start VPS
Boolean no

Start thew new VPS

Default: true

vps_user_data
User data
Resource no
user_data_format
User data format
String no

Default: null

Validation rules
RuleDetails
Include

Allowed values:

  • script
  • cloudinit_config
  • cloudinit_script
  • nixos_configuration
  • nixos_flake_configuration
  • nixos_flake_uri

Validation error message: %{value} cannot be used

user_data_content
User data content
Text no

Default: null

Output parameters

ParameterTypeDescription
id
VPS id
Integer
user
User
Resource VPS owner
hostname
Hostname
String VPS hostname
manage_hostname
Manage hostname
Boolean Determines whether vpsAdmin sets VPS hostname or not
os_template
OS template
Resource
cgroup_version
Cgroup_version
String
map_mode
Map mode
String
info
Info
String VPS description
dns_resolver
DNS resolver
Resource DNS resolver the VPS will use
node
Node
Resource Node VPS will run on
user_namespace_map
UID/GID mapping
Resource
autostart_enable
Auto-start
Boolean Start VPS on node boot?
autostart_priority
Auto-start priority
Integer 0 is the highest priority, greater numbers have lower priority
onstartall
On start all
Boolean Start VPS on start all action?
config
Config
String Custom configuration options
cpu_limit
CPU limit
Integer Limit of maximum CPU usage
start_menu_timeout
Start menu timeout
Integer Number of seconds the start menu waits for the user
allow_admin_modifications
Allow admin modifications
Boolean
enable_os_template_auto_update
Enable OS template auto update
Boolean
enable_network
Enable network
Boolean
dataset
Dataset
Resource Dataset the VPS resides in
pool
Pool
Resource Storage pool the VPS resides in
created_at
Created at
Datetime
implicit_oom_report_rule_hit_count
Implicit_oom_report_rule_hit_count
Integer
cpu
CPU
Integer Minimally 1, maximally 1024, step size is 1
diskspace
Disk space
Integer Minimally 1024, maximally 1048576, step size is 1
memory
Memory
Integer Minimally 128, maximally 1048576, step size is 1
swap
Swap
Integer Minimally 0, maximally 1048576, step size is 1
is_running
Running
Boolean
in_rescue_mode
In rescue mode
Boolean
uptime
Uptime
Integer
loadavg1
Loadavg1
Float
loadavg5
Loadavg5
Float
loadavg15
Loadavg15
Float
process_count
Process count
Integer
cpu_user
Cpu_user
Float
cpu_nice
Cpu_nice
Float
cpu_system
Cpu_system
Float
cpu_idle
Cpu_idle
Float
cpu_iowait
Cpu_iowait
Float
cpu_irq
Cpu_irq
Float
cpu_softirq
Cpu_softirq
Float
used_memory
Used memory
Integer in MB
used_swap
Used swap
Integer in MB
used_diskspace
Used disk space
Integer in MB
object_state
Object state
String
expiration_date
Expiration
Datetime A date after which the state will progress
remind_after_date
Remind after
Datetime Mail warnings are silenced until this date

Examples

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

Create vps

Create VPS owned by user with ID 1, template ID 1 and DNS resolver ID 1. VPS will be created on node ID 1. Action returns ID of newly created VPS.

Ruby · Simple
reply = api.vps.create({user: 1,
 hostname: "my-vps",
 os_template: 1,
 info: "",
 dns_resolver: 1,
 node: 1,
 onstartall: true})

# reply is an instance of HaveAPI::Client::ResourceInstance
# reply.id = 150
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.vps.create({user: 1,
   hostname: "my-vps",
   os_template: 1,
   info: "",
   dns_resolver: 1,
   node: 1,
   onstartall: true})

  # reply is an instance of HaveAPI::Client::ResourceInstance
  # reply.id = 150
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, ["vps"]);
const action = CallbackClient.findAction(resource, "create");
action.directInvoke({
  params: {["user"]: 1, ["hostname"]: "my-vps", ["os_template"]: 1, ["info"]: "", ["dns_resolver"]: 1, ["node"]: 1, ["onstartall"]: true},
  onReply: (owner, reply) => {
    if (!reply.isOk()) {
      console.error(reply.message(), reply.envelope.errors);
      return;
    }
    console.log(reply.response());
  }
});
// This prints the initial response; use its action-state metadata to monitor completion.
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, ["vps"]);
    const action = CallbackClient.findAction(resource, "create");
    action.directInvoke({
      params: {["user"]: 1, ["hostname"]: "my-vps", ["os_template"]: 1, ["info"]: "", ["dns_resolver"]: 1, ["node"]: 1, ["onstartall"]: true},
      onReply: (owner, reply) => {
        if (!reply.isOk()) {
          console.error(reply.message(), reply.envelope.errors);
          return;
        }
        console.log(reply.response());
        console.log(reply.meta());
      }
    });
    // This prints the initial response; use its action-state metadata to monitor completion.
  } catch (error) {
    console.error(error);
  }
});
JavaScript (async) · Simple
const result = await api.resource("vps").action("create")({params: {["user"]: 1, ["hostname"]: "my-vps", ["os_template"]: 1, ["info"]: "", ["dns_resolver"]: 1, ["node"]: 1, ["onstartall"]: true}});
console.log(result.value);
// Request success alone does not establish operation completion.
const completed = await api.waitForCompletion(result, {timeoutMs: 300000});
console.log(completed.state);
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("vps").action("create")({params: {["user"]: 1, ["hostname"]: "my-vps", ["os_template"]: 1, ["info"]: "", ["dns_resolver"]: 1, ["node"]: 1, ["onstartall"]: true}});
    console.log(result.value);
    console.log(result.response.meta);
    // Request success alone does not establish operation completion.
    const completed = await api.waitForCompletion(result, {timeoutMs: 300000});
    console.log(completed.state);
  } 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, ["vps"]);
const action = CallbackClient.findAction(resource, "create");
action.directInvoke({
  params: {["user"]: 1, ["hostname"]: "my-vps", ["os_template"]: 1, ["info"]: "", ["dns_resolver"]: 1, ["node"]: 1, ["onstartall"]: true},
  onReply: (owner, reply) => {
    if (!reply.isOk()) {
      console.error(reply.message(), reply.envelope.errors);
      return;
    }
    console.log(reply.response());
  }
});
// This prints the initial response; use its action-state metadata to monitor completion.
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, ["vps"]);
    const action = CallbackClient.findAction(resource, "create");
    action.directInvoke({
      params: {["user"]: 1, ["hostname"]: "my-vps", ["os_template"]: 1, ["info"]: "", ["dns_resolver"]: 1, ["node"]: 1, ["onstartall"]: true},
      onReply: (owner, reply) => {
        if (!reply.isOk()) {
          console.error(reply.message(), reply.envelope.errors);
          return;
        }
        console.log(reply.response());
        console.log(reply.meta());
      }
    });
    // This prints the initial response; use its action-state metadata to monitor completion.
  } catch (error) {
    console.error(error);
  }
});
TypeScript (async) · Simple
const result = await api.resource("vps").action("create")({params: {["user"]: 1, ["hostname"]: "my-vps", ["os_template"]: 1, ["info"]: "", ["dns_resolver"]: 1, ["node"]: 1, ["onstartall"]: true}});
console.log(result.value);
// Request success alone does not establish operation completion.
const completed = await api.waitForCompletion(result, {timeoutMs: 300000});
console.log(completed.state);
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("vps").action("create")({params: {["user"]: 1, ["hostname"]: "my-vps", ["os_template"]: 1, ["info"]: "", ["dns_resolver"]: 1, ["node"]: 1, ["onstartall"]: true}});
    console.log(result.value);
    console.log(result.response.meta);
    // Request success alone does not establish operation completion.
    const completed = await api.waitForCompletion(result, {timeoutMs: 300000});
    console.log(completed.state);
  } 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["vps"].actions["create"].call(params={"user": 1, "hostname": "my-vps", "os_template": 1, "info": "", "dns_resolver": 1, "node": 1, "onstartall": True})
print(response.data)
# A request timeout does not cancel a server operation.
if response.operation is not None:
    completed = response.operation.wait(timeout=300, interval=1)
    print(completed)
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["vps"].actions["create"].call(params={"user": 1, "hostname": "my-vps", "os_template": 1, "info": "", "dns_resolver": 1, "node": 1, "onstartall": True})
        print(response.data)
        print(response.meta)
        # A request timeout does not cancel a server operation.
        if response.operation is not None:
            completed = response.operation.wait(timeout=300, interval=1)
            print(completed)
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["vps"].actions["create"].call(params={"user": 1, "hostname": "my-vps", "os_template": 1, "info": "", "dns_resolver": 1, "node": 1, "onstartall": True})
print(response.data)
# A request timeout does not cancel a server operation.
if response.operation is not None:
    completed = await response.operation.wait(timeout=300, interval=1)
    print(completed)
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["vps"].actions["create"].call(params={"user": 1, "hostname": "my-vps", "os_template": 1, "info": "", "dns_resolver": 1, "node": 1, "onstartall": True})
            print(response.data)
            print(response.meta)
            # A request timeout does not cancel a server operation.
            if response.operation is not None:
                completed = await response.operation.wait(timeout=300, interval=1)
                print(completed)
    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.Vps.Create.Prepare()
input := invocation.NewInput().SelectParameters()
input.SetUser(1)
input.SetHostname("my-vps")
input.SetOsTemplate(1)
input.SetInfo("")
input.SetDnsResolver(1)
input.SetNode(1)
input.SetOnstartall(true)
response, err := invocation.Call()
if err != nil {
	fmt.Println(err)
	return
}
if !response.Status {
	fmt.Println(response.Message, response.Errors)
	return
}
if response.Output != nil {
	fmt.Println(response.Output.Id)
}
// Request success does not establish operation completion.
Go API client · With error handling
// go get github.com/vpsfreecz/vpsadmin-go-client/client@latest
package main

import (
	"fmt"

	client "github.com/vpsfreecz/vpsadmin-go-client/client"
)

func main() {
	api := client.New("https://api.vpsfree.cz")
	invocation := api.Vps.Create.Prepare()
	input := invocation.NewInput().SelectParameters()
	input.SetUser(1)
	input.SetHostname("my-vps")
	input.SetOsTemplate(1)
	input.SetInfo("")
	input.SetDnsResolver(1)
	input.SetNode(1)
	input.SetOnstartall(true)
	// To supply advertised global metadata, select only the fields you set:
	// metadata := invocation.NewMetaInput().SelectParameters()
	// metadata.SetIncludes(value) // value has type string
	// metadata.SetNo(value) // value has type bool
	response, err := invocation.Call()
	if err != nil {
		fmt.Println(err)
		return
	}
	if !response.Status {
		fmt.Println(response.Message, response.Errors)
		return
	}
	if response.Output != nil {
		fmt.Println(response.Output.Id)
	}
	if response.IsBlocking() {
		state, err := response.OperationStatus()
		if err != nil {
			fmt.Println(err)
			return
		}
		if !state.Status {
			fmt.Println(state.Message, state.Errors)
			return
		}
		// Inspect the operation status using its documented output fields.
	}
	// Request success does not establish operation completion.
}
Rust API client (async) · Simple
// Use inside an async function returning Result<(), Box<dyn std::error::Error>>.
let response = api.vps().create().user(1_i64).hostname("my-vps".to_owned()).os_template(1_i64).info("".to_owned()).dns_resolver(1_i64).node(1_i64).onstartall(true).send().await?;
println!("{:?}", &response.output.id);
// Request success or a timeout does not establish completion of a server-side operation.
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.vps().create().user(1_i64).hostname("my-vps".to_owned()).os_template(1_i64).info("".to_owned()).dns_resolver(1_i64).node(1_i64).onstartall(true).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;
    println!("{:?}", &response.output.id);
    // Request success or a timeout does not establish completion of a server-side operation.
    // Use only the separately documented action-state action; this API client has no automatic wait helper.
    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.vps().create().user(1_i64).hostname("my-vps".to_owned()).os_template(1_i64).info("".to_owned()).dns_resolver(1_i64).node(1_i64).onstartall(true).send()?;
println!("{:?}", &response.output.id);
// Request success or a timeout does not establish completion of a server-side operation.
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.vps().create().user(1_i64).hostname("my-vps".to_owned()).os_template(1_i64).info("".to_owned()).dns_resolver(1_i64).node(1_i64).onstartall(true).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;
    println!("{:?}", &response.output.id);
    // Request success or a timeout does not establish completion of a server-side operation.
    // Use only the separately documented action-state action; this API client has no automatic wait helper.
    Ok(())
}
TypeScript API client · Simple
// Requires an initialized api and an async context.
const result = await api.vps.create({ "params": { "user": 1, "hostname": "my-vps", "os_template": 1, "info": "", "dns_resolver": 1, "node": 1, "onstartall": true } });
console.log(result.data.id);
// Request success does not establish completion of a server-side operation.
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.vps.create({ "params": { "user": 1, "hostname": "my-vps", "os_template": 1, "info": "", "dns_resolver": 1, "node": 1, "onstartall": true } });
    void [result.data, result.meta, result.envelope, result.httpStatus];
    const item = result.data;
    const value0: unknown = item.id;
    if (value0 !== null && value0 !== undefined) console.log(value0);
    // Request success does not establish completion of a server-side operation.
  } 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->vps->create([
    'user' => 1,
    'hostname' => 'my-vps',
    'os_template' => 1,
    'info' => '',
    'dns_resolver' => 1,
    'node' => 1,
    'onstartall' => true
]);

// $reply is an instance of \HaveAPI\Client\ResourceInstance
// $reply->id = 150
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->vps->create([
        'user' => 1,
        'hostname' => 'my-vps',
        'os_template' => 1,
        'info' => '',
        'dns_resolver' => 1,
        'node' => 1,
        'onstartall' => true
    ]);

    // $reply is an instance of \HaveAPI\Client\ResourceInstance
    // $reply->id = 150
} 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 vps create -- \
              --user 1 \
              --hostname my-vps \
              --os-template 1 \
              --info '' \
              --dns-resolver 1 \
              --node 1 \
              --onstartall
#                              VPS id:  150
#                                User:  -
#                            Hostname:  -
#                     Manage hostname:  -
#                         OS template:  -
#                      Cgroup_version:  -
#                            Map mode:  -
#                                Info:  -
#                        DNS resolver:  -
#                                Node:  -
#                     UID/GID mapping:  -
#                          Auto-start:  -
#                 Auto-start priority:  -
#                        On start all:  -
#                              Config:  -
#                           CPU limit:  -
#                  Start menu timeout:  -
#           Allow admin modifications:  -
#      Enable OS template auto update:  -
#                      Enable network:  -
#                             Dataset:  -
#                                Pool:  -
#                          Created at:  -
#  Implicit_oom_report_rule_hit_count:  -
#                                 CPU:  -
#                          Disk space:  -
#                              Memory:  -
#                                Swap:  -
#                             Running:  -
#                      In rescue mode:  -
#                              Uptime:  -
#                            Loadavg1:  -
#                            Loadavg5:  -
#                           Loadavg15:  -
#                       Process count:  -
#                            Cpu_user:  -
#                            Cpu_nice:  -
#                          Cpu_system:  -
#                            Cpu_idle:  -
#                          Cpu_iowait:  -
#                             Cpu_irq:  -
#                         Cpu_softirq:  -
#                         Used memory:  -
#                           Used swap:  -
#                     Used disk space:  -
#                        Object state:  -
#                          Expiration:  -
#                        Remind after:  -
# 
curl · Simple
$ curl --request POST \
       --data-binary \{\"vps\":\{\"user\":1,\"hostname\":\"my-vps\",\"os_template\":1,\"info\":\"\",\"dns_resolver\":1,\"node\":1,\"onstartall\":true\}\} \
       https://api.vpsfree.cz/v7.0/vpses

# {
#   "status": true,
#   "message": null,
#   "response": {
#     "vps": {
#       "id": 150
#     }
#   },
#   "errors": null
# }
HTTP · Simple
POST /v7.0/vpses HTTP/1.1
Host: api.vpsfree.cz
Content-Type: application/json

{
  "vps": {
    "user": 1,
    "hostname": "my-vps",
    "os_template": 1,
    "info": "",
    "dns_resolver": 1,
    "node": 1,
    "onstartall": true
  }
}

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

{
  "status": true,
  "message": null,
  "response": {
    "vps": {
      "id": 150
    }
  },
  "errors": null
}

Delete

Input parameters

ParameterTypeRequiredDetails
lazy
Lazy delete
Boolean no

Only mark VPS as deleted

Default: true

object_state
Object state
String no

Default: soft_delete

Validation rules
RuleDetails
Include

Allowed values:

  • soft_delete
  • hard_delete
  • deleted

Validation error message: %{value} cannot be used

expiration_date
Expiration
Datetime no

A date after which the state will progress

Default: null

remind_after_date
Remind after
Datetime no

Mail warnings are silenced until this date

Default: null

change_reason
Reason
String no

Reason for the state change. May be mailed to the user.

Default: null

Output parameters

No parameters.

Deploy_public_key

Input parameters

ParameterTypeRequiredDetails
public_key
Public key
Resource yes

Output parameters

No parameters.

Index

Input parameters

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

user
User
Resource no

Filter by owner

node
Node
Resource no

Filter by node

location
Location
Resource no

Filter by location

environment
Environment
Resource no

Filter by environment

user_namespace_map
UID/GID mapping
Resource no
os_template
OS template
Resource no
hostname_any
Hostname_any
String no

Default: null

hostname_exact
Hostname_exact
String no

Default: null

object_state
Object state
String no

Default: null

Validation rules
RuleDetails
Include

Allowed values:

  • active: Active
  • suspended: Suspended
  • soft_delete: Soft delete
  • hard_delete: Hard delete
  • deleted: Deleted

Validation error message: %{value} cannot be used

Output parameters

ParameterTypeDescription
id
VPS id
Integer
user
User
Resource VPS owner
hostname
Hostname
String VPS hostname
manage_hostname
Manage hostname
Boolean Determines whether vpsAdmin sets VPS hostname or not
os_template
OS template
Resource
cgroup_version
Cgroup_version
String
map_mode
Map mode
String
info
Info
String VPS description
dns_resolver
DNS resolver
Resource DNS resolver the VPS will use
node
Node
Resource Node VPS will run on
user_namespace_map
UID/GID mapping
Resource
autostart_enable
Auto-start
Boolean Start VPS on node boot?
autostart_priority
Auto-start priority
Integer 0 is the highest priority, greater numbers have lower priority
onstartall
On start all
Boolean Start VPS on start all action?
config
Config
String Custom configuration options
cpu_limit
CPU limit
Integer Limit of maximum CPU usage
start_menu_timeout
Start menu timeout
Integer Number of seconds the start menu waits for the user
allow_admin_modifications
Allow admin modifications
Boolean
enable_os_template_auto_update
Enable OS template auto update
Boolean
enable_network
Enable network
Boolean
dataset
Dataset
Resource Dataset the VPS resides in
pool
Pool
Resource Storage pool the VPS resides in
created_at
Created at
Datetime
implicit_oom_report_rule_hit_count
Implicit_oom_report_rule_hit_count
Integer
cpu
CPU
Integer Minimally 1, maximally 1024, step size is 1
diskspace
Disk space
Integer Minimally 1024, maximally 1048576, step size is 1
memory
Memory
Integer Minimally 128, maximally 1048576, step size is 1
swap
Swap
Integer Minimally 0, maximally 1048576, step size is 1
is_running
Running
Boolean
in_rescue_mode
In rescue mode
Boolean
uptime
Uptime
Integer
loadavg1
Loadavg1
Float
loadavg5
Loadavg5
Float
loadavg15
Loadavg15
Float
process_count
Process count
Integer
cpu_user
Cpu_user
Float
cpu_nice
Cpu_nice
Float
cpu_system
Cpu_system
Float
cpu_idle
Cpu_idle
Float
cpu_iowait
Cpu_iowait
Float
cpu_irq
Cpu_irq
Float
cpu_softirq
Cpu_softirq
Float
used_memory
Used memory
Integer in MB
used_swap
Used swap
Integer in MB
used_diskspace
Used disk space
Integer in MB
maintenance_lock
Maintenance lock
String
maintenance_lock_reason
Maintenance reason
String
object_state
Object state
String
expiration_date
Expiration
Datetime A date after which the state will progress
remind_after_date
Remind after
Datetime Mail warnings are silenced until this date

Examples

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

Example #0

Ruby · Simple
reply = api.vps.index

# 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.vps.index

  # 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, ["vps"]);
const action = CallbackClient.findAction(resource, "index");
action.directInvoke({
  params: {},
  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, ["vps"]);
    const action = CallbackClient.findAction(resource, "index");
    action.directInvoke({
      params: {},
      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("vps").action("index")({params: {}});
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("vps").action("index")({params: {}});
    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, ["vps"]);
const action = CallbackClient.findAction(resource, "index");
action.directInvoke({
  params: {},
  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, ["vps"]);
    const action = CallbackClient.findAction(resource, "index");
    action.directInvoke({
      params: {},
      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("vps").action("index")({params: {}});
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("vps").action("index")({params: {}});
    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["vps"].actions["index"].call(params={})
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["vps"].actions["index"].call(params={})
        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["vps"].actions["index"].call(params={})
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["vps"].actions["index"].call(params={})
            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.Vps.Index.Prepare()
invocation.NewInput().SelectParameters()
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.User != nil {
			fmt.Println(item.User.Id)
			fmt.Println(item.User.Login)
		}
		fmt.Println(item.Hostname)
		if item.OsTemplate != nil {
			fmt.Println(item.OsTemplate.Id)
			fmt.Println(item.OsTemplate.Label)
		}
		fmt.Println(item.Info)
		if item.DnsResolver != nil {
			fmt.Println(item.DnsResolver.Id)
		}
		if item.Node != nil {
			fmt.Println(item.Node.Id)
			fmt.Println(item.Node.Name)
		}
		fmt.Println(item.Onstartall)
	}
}
Rust API client (async) · Simple
// Use inside an async function returning Result<(), Box<dyn std::error::Error>>.
let response = api.vps().index().send().await?;
for item in &response.output {
    println!("{:?}", &item.id);
    println!("{:?}", &item.user);
    println!("{:?}", &item.hostname);
    println!("{:?}", &item.os_template);
    println!("{:?}", &item.info);
    println!("{:?}", &item.dns_resolver);
    println!("{:?}", &item.node);
    println!("{:?}", &item.onstartall);
}
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.vps().index().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.user);
        println!("{:?}", &item.hostname);
        println!("{:?}", &item.os_template);
        println!("{:?}", &item.info);
        println!("{:?}", &item.dns_resolver);
        println!("{:?}", &item.node);
        println!("{:?}", &item.onstartall);
    }
    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.vps().index().send()?;
for item in &response.output {
    println!("{:?}", &item.id);
    println!("{:?}", &item.user);
    println!("{:?}", &item.hostname);
    println!("{:?}", &item.os_template);
    println!("{:?}", &item.info);
    println!("{:?}", &item.dns_resolver);
    println!("{:?}", &item.node);
    println!("{:?}", &item.onstartall);
}
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.vps().index().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.user);
        println!("{:?}", &item.hostname);
        println!("{:?}", &item.os_template);
        println!("{:?}", &item.info);
        println!("{:?}", &item.dns_resolver);
        println!("{:?}", &item.node);
        println!("{:?}", &item.onstartall);
    }
    Ok(())
}
TypeScript API client · Simple
// Requires an initialized api and an async context.
const result = await api.vps.index();
for (const item of result.data) {
  console.log(item.id);
  console.log(item.user);
  console.log(item.hostname);
  console.log(item.os_template);
  console.log(item.info);
  console.log(item.dns_resolver);
  console.log(item.node);
  console.log(item.onstartall);
}
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.vps.index();
    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.user;
      if (value1 !== null && value1 !== undefined) console.log(value1);
      const value2: unknown = item.hostname;
      if (value2 !== null && value2 !== undefined) console.log(value2);
      const value3: unknown = item.os_template;
      if (value3 !== null && value3 !== undefined) console.log(value3);
      const value4: unknown = item.info;
      if (value4 !== null && value4 !== undefined) console.log(value4);
      const value5: unknown = item.dns_resolver;
      if (value5 !== null && value5 !== undefined) console.log(value5);
      const value6: unknown = item.node;
      if (value6 !== null && value6 !== undefined) console.log(value6);
      const value7: unknown = item.onstartall;
      if (value7 !== null && value7 !== undefined) console.log(value7);
    }
  } 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->vps->index();

// $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->vps->index();

    // $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 vps index
#                              VPS id:  150
#                                User:  somebody (#1)
#                            Hostname:  thehostname
#                     Manage hostname:  -
#                         OS template:  Scientific Linux 6 (#1)
#                      Cgroup_version:  -
#                            Map mode:  -
#                                Info:  My very important VPS
#                        DNS resolver:   (#1)
#                                Node:   (#1)
#                     UID/GID mapping:  -
#                          Auto-start:  -
#                 Auto-start priority:  -
#                        On start all:  true
#                              Config:  -
#                           CPU limit:  -
#                  Start menu timeout:  -
#           Allow admin modifications:  -
#      Enable OS template auto update:  -
#                      Enable network:  -
#                             Dataset:  -
#                                Pool:  -
#                          Created at:  -
#  Implicit_oom_report_rule_hit_count:  -
#                                 CPU:  -
#                          Disk space:  -
#                              Memory:  -
#                                Swap:  -
#                             Running:  -
#                      In rescue mode:  -
#                              Uptime:  -
#                            Loadavg1:  -
#                            Loadavg5:  -
#                           Loadavg15:  -
#                       Process count:  -
#                            Cpu_user:  -
#                            Cpu_nice:  -
#                          Cpu_system:  -
#                            Cpu_idle:  -
#                          Cpu_iowait:  -
#                             Cpu_irq:  -
#                         Cpu_softirq:  -
#                         Used memory:  -
#                           Used swap:  -
#                     Used disk space:  -
#                    Maintenance lock:  -
#                  Maintenance reason:  -
#                        Object state:  -
#                          Expiration:  -
#                        Remind after:  -
# 
curl · Simple
$ curl --request GET \
       --data-binary \{\"vps\":\{\}\} \
       https://api.vpsfree.cz/v7.0/vpses

# {
#   "status": true,
#   "message": null,
#   "response": {
#     "vpses": [
#       {
#         "id": 150,
#         "user": {
#           "id": 1,
#           "login": "somebody"
#         },
#         "hostname": "thehostname",
#         "os_template": {
#           "id": 1,
#           "label": "Scientific Linux 6"
#         },
#         "info": "My very important VPS",
#         "dns_resolver": {
#           "id": 1
#         },
#         "node": {
#           "id": 1,
#           "name": "node1"
#         },
#         "onstartall": true
#       }
#     ]
#   },
#   "errors": null
# }
HTTP · Simple
GET /v7.0/vpses 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: 539

{
  "status": true,
  "message": null,
  "response": {
    "vpses": [
      {
        "id": 150,
        "user": {
          "id": 1,
          "login": "somebody"
        },
        "hostname": "thehostname",
        "os_template": {
          "id": 1,
          "label": "Scientific Linux 6"
        },
        "info": "My very important VPS",
        "dns_resolver": {
          "id": 1
        },
        "node": {
          "id": 1,
          "name": "node1"
        },
        "onstartall": true
      }
    ]
  },
  "errors": null
}

Migrate

Input parameters

ParameterTypeRequiredDetails
node
Node
Resource yes
replace_ip_addresses
Replace IP addresses
Boolean no

When migrating to another location, current IP addresses are replaced by addresses from the new location

Default: null

transfer_ip_addresses
Transfer IP addresses
Boolean no

If possible, keep IP addresses and recharge them to a different environment or location

Default: null

swap
Swap
String no

Minimally 0, maximally 1048576, step size is 1

Default: enforce

Validation rules
RuleDetails
Include

Allowed values:

  • enforce

Validation error message: %{value} cannot be used

maintenance_window
Maintenance window
Boolean no

Migrate the VPS within the nearest maintenance window

Default: true

finish_weekday
Finish weekday
Integer no

Prepare the migration and finish it on this day

Default: null

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

Validation error message: must be between 0 and 6

finish_minutes
Finish minutes
Integer no

Number of minutes from midnight of start_weekday after which the migration is done

Default: null

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

Validation error message: must be between 0 and 1410

cleanup_data
Cleanup data
Boolean no

Remove VPS dataset from the source node

Default: true

no_start
No start
Boolean no

Do not start the VPS on the target node

Default: false

skip_start
Skip start
Boolean no

Continue even if the VPS fails to start on the target node

Default: false

send_mail
Send e-mails
Boolean no

Inform the VPS owner about migration progress

Default: true

reason
Reason
String no

Default: null

Output parameters

No parameters.

Passwd

Input parameters

ParameterTypeRequiredDetails
type
Type
String no

node, storage or mailer

Default: secure

Validation rules
RuleDetails
Include

Allowed values:

  • secure
  • simple

Validation error message: %{value} cannot be used

Output parameters

ParameterTypeDescription
password
Password
String Auto-generated password

Reinstall

Input parameters

ParameterTypeRequiredDetails
os_template
OS template
Resource no
vps_user_data
User data
Resource no
user_data_format
User data format
String no

Default: null

Validation rules
RuleDetails
Include

Allowed values:

  • script
  • cloudinit_config
  • cloudinit_script
  • nixos_configuration
  • nixos_flake_configuration
  • nixos_flake_uri

Validation error message: %{value} cannot be used

user_data_content
User data content
Text no

Default: null

Output parameters

No parameters.

Replace

Input parameters

ParameterTypeRequiredDetails
node
Node
Resource no

Clone to node

expiration_date
Expiration_date
Datetime no

How long should the original VPS be kept

Default: null

start
Start
Boolean no

Start thew new VPS

Default: true

preserve_backups
Preserve backups
Boolean no

Move existing backup datasets to the replacement VPS

Default: true

preserve_backup_history
Preserve backup history
Boolean no

Back up a replacement snapshot so future backups can continue incrementally

Default: true

reason
Reason
Text no

Default: null

Output parameters

ParameterTypeDescription
id
VPS id
Integer
user
User
Resource VPS owner
hostname
Hostname
String VPS hostname
manage_hostname
Manage hostname
Boolean Determines whether vpsAdmin sets VPS hostname or not
os_template
OS template
Resource
cgroup_version
Cgroup_version
String
map_mode
Map mode
String
info
Info
String VPS description
dns_resolver
DNS resolver
Resource DNS resolver the VPS will use
node
Node
Resource Node VPS will run on
user_namespace_map
UID/GID mapping
Resource
autostart_enable
Auto-start
Boolean Start VPS on node boot?
autostart_priority
Auto-start priority
Integer 0 is the highest priority, greater numbers have lower priority
onstartall
On start all
Boolean Start VPS on start all action?
config
Config
String Custom configuration options
cpu_limit
CPU limit
Integer Limit of maximum CPU usage
start_menu_timeout
Start menu timeout
Integer Number of seconds the start menu waits for the user
allow_admin_modifications
Allow admin modifications
Boolean
enable_os_template_auto_update
Enable OS template auto update
Boolean
enable_network
Enable network
Boolean
dataset
Dataset
Resource Dataset the VPS resides in
pool
Pool
Resource Storage pool the VPS resides in
created_at
Created at
Datetime
implicit_oom_report_rule_hit_count
Implicit_oom_report_rule_hit_count
Integer
cpu
CPU
Integer Minimally 1, maximally 1024, step size is 1
diskspace
Disk space
Integer Minimally 1024, maximally 1048576, step size is 1
memory
Memory
Integer Minimally 128, maximally 1048576, step size is 1
swap
Swap
Integer Minimally 0, maximally 1048576, step size is 1
is_running
Running
Boolean
in_rescue_mode
In rescue mode
Boolean
uptime
Uptime
Integer
loadavg1
Loadavg1
Float
loadavg5
Loadavg5
Float
loadavg15
Loadavg15
Float
process_count
Process count
Integer
cpu_user
Cpu_user
Float
cpu_nice
Cpu_nice
Float
cpu_system
Cpu_system
Float
cpu_idle
Cpu_idle
Float
cpu_iowait
Cpu_iowait
Float
cpu_irq
Cpu_irq
Float
cpu_softirq
Cpu_softirq
Float
used_memory
Used memory
Integer in MB
used_swap
Used swap
Integer in MB
used_diskspace
Used disk space
Integer in MB

Restart

Input parameters

ParameterTypeRequiredDetails
force
Force restart
Boolean no

Delete the DNS resolver even it is in use. Affected VPSes get a new DNS resolver.

Default: false

Output parameters

No parameters.

Set_maintenance

Input parameters

ParameterTypeRequiredDetails
lock
Lock
Boolean yes

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

reason
Reason
String no

Default: ""

Output parameters

No parameters.

Show

Input parameters

No parameters.

Output parameters

ParameterTypeDescription
id
VPS id
Integer
user
User
Resource VPS owner
hostname
Hostname
String VPS hostname
manage_hostname
Manage hostname
Boolean Determines whether vpsAdmin sets VPS hostname or not
os_template
OS template
Resource
cgroup_version
Cgroup_version
String
map_mode
Map mode
String
info
Info
String VPS description
dns_resolver
DNS resolver
Resource DNS resolver the VPS will use
node
Node
Resource Node VPS will run on
user_namespace_map
UID/GID mapping
Resource
autostart_enable
Auto-start
Boolean Start VPS on node boot?
autostart_priority
Auto-start priority
Integer 0 is the highest priority, greater numbers have lower priority
onstartall
On start all
Boolean Start VPS on start all action?
config
Config
String Custom configuration options
cpu_limit
CPU limit
Integer Limit of maximum CPU usage
start_menu_timeout
Start menu timeout
Integer Number of seconds the start menu waits for the user
allow_admin_modifications
Allow admin modifications
Boolean
enable_os_template_auto_update
Enable OS template auto update
Boolean
enable_network
Enable network
Boolean
dataset
Dataset
Resource Dataset the VPS resides in
pool
Pool
Resource Storage pool the VPS resides in
created_at
Created at
Datetime
implicit_oom_report_rule_hit_count
Implicit_oom_report_rule_hit_count
Integer
cpu
CPU
Integer Minimally 1, maximally 1024, step size is 1
diskspace
Disk space
Integer Minimally 1024, maximally 1048576, step size is 1
memory
Memory
Integer Minimally 128, maximally 1048576, step size is 1
swap
Swap
Integer Minimally 0, maximally 1048576, step size is 1
is_running
Running
Boolean
in_rescue_mode
In rescue mode
Boolean
uptime
Uptime
Integer
loadavg1
Loadavg1
Float
loadavg5
Loadavg5
Float
loadavg15
Loadavg15
Float
process_count
Process count
Integer
cpu_user
Cpu_user
Float
cpu_nice
Cpu_nice
Float
cpu_system
Cpu_system
Float
cpu_idle
Cpu_idle
Float
cpu_iowait
Cpu_iowait
Float
cpu_irq
Cpu_irq
Float
cpu_softirq
Cpu_softirq
Float
used_memory
Used memory
Integer in MB
used_swap
Used swap
Integer in MB
used_diskspace
Used disk space
Integer in MB
maintenance_lock
Maintenance lock
String
maintenance_lock_reason
Maintenance reason
String
object_state
Object state
String
expiration_date
Expiration
Datetime A date after which the state will progress
remind_after_date
Remind after
Datetime Mail warnings are silenced until this date

Start

Input parameters

No parameters.

Output parameters

No parameters.

Stop

Input parameters

ParameterTypeRequiredDetails
force
Poweroff
Boolean no

Delete the DNS resolver even it is in use. Affected VPSes get a new DNS resolver.

Default: false

Output parameters

No parameters.

Swap_with

Input parameters

ParameterTypeRequiredDetails
vps
VPS
Resource yes

Swap with this VPS

resources
Resources
Boolean no

Swap resources (CPU, memory and swap, not disk space)

Default: null

hostname
Hostname
Boolean no

Swap hostname

Default: null

expirations
Expirations
Boolean no

Swap expirations

Default: null

Output parameters

No parameters.

Update

Input parameters

ParameterTypeRequiredDetails
user
User
Resource no

VPS owner

hostname
Hostname
String no

VPS hostname

Default: null

Validation rules
RuleDetails
Format

Must match this regular expression:

\A[a-zA-Z0-9][a-zA-Z\-_.0-9]{0,62}[a-zA-Z0-9]\z

null

Validation error message: bad format

manage_hostname
Manage hostname
Boolean no

Determines whether vpsAdmin sets VPS hostname or not

Default: null

os_template
OS template
Resource no
cgroup_version
Cgroup_version
String no

Default: cgroup_any

Validation rules
RuleDetails
Include

Allowed values:

  • cgroup_any
  • cgroup_v1
  • cgroup_v2

Validation error message: %{value} cannot be used

map_mode
Map mode
String no

Default: native

Validation rules
RuleDetails
Include

Allowed values:

  • native
  • zfs

Validation error message: %{value} cannot be used

info
Info
String no

VPS description

Default: null

dns_resolver
DNS resolver
Resource no

DNS resolver the VPS will use

node
Node
Resource no

Node VPS will run on

user_namespace_map
UID/GID mapping
Resource no
autostart_enable
Auto-start
Boolean no

Start VPS on node boot?

Default: null

autostart_priority
Auto-start priority
Integer no

0 is the highest priority, greater numbers have lower priority

Default: 1000

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

Validation error message: must be at least 0

onstartall
On start all
Boolean no

Start VPS on start all action?

Default: true

config
Config
String no

Custom configuration options

Default: ""

cpu_limit
CPU limit
Integer no

Limit of maximum CPU usage

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

start_menu_timeout
Start menu timeout
Integer no

Number of seconds the start menu waits for the user

Default: null

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

Validation error message: must be between 0 and 86400

allow_admin_modifications
Allow admin modifications
Boolean no

Default: null

enable_os_template_auto_update
Enable OS template auto update
Boolean no

Default: null

enable_network
Enable network
Boolean no

Default: null

cpu
CPU
Integer no

Minimally 1, maximally 1024, step size is 1

Default: null

memory
Memory
Integer no

Minimally 128, maximally 1048576, step size is 1

Default: null

swap
Swap
Integer no

Minimally 0, maximally 1048576, step size is 1

Default: null

change_reason
Change reason
Text no

If filled, it is send to VPS owner in an email

Default: null

admin_override
Admin override
Boolean no

Make it possible to assign more resource than the user actually has

Default: null

admin_lock_type
Admin lock type
String no

How is the admin lock enforced

Default: null

Validation rules
RuleDetails
Include

Allowed values:

  • no_lock
  • absolute
  • not_less
  • not_more

Validation error message: %{value} cannot be used

object_state
Object state
String no

Default: null

Validation rules
RuleDetails
Include

Allowed values:

  • active: Active
  • suspended: Suspended
  • soft_delete: Soft delete
  • hard_delete: Hard delete
  • deleted: Deleted

Validation error message: %{value} cannot be used

expiration_date
Expiration
Datetime no

A date after which the state will progress

Default: null

remind_after_date
Remind after
Datetime no

Mail warnings are silenced until this date

Default: null

Output parameters

No parameters.

Subresources