Skip to content

API-Documentation

In this article

invapi.hostkey.com control panels API documentation

We have developed an API to manage all our services. It offers full functionality to daily operations and integrations.

Information

Control panel invapi.hostkey.com is built on top of this API.

Key Features:

  • Search: Search for the server by IP, hostname, location, and tag
  • Order: order standard servers and receive access details in 10-30 minutes
  • Power management: reboot, power on/off, read sensors and power status
  • Networking: view network settings, enable/disable NICs, block/unblock specific IPs. Set DNS RRs.
  • Reinstalls: perform fully automated reinstalls for standard OS: Centos, Ubuntu, Debian, and Windows Server. SSH keys, post-install scripts, and HTTP callbacks are supported.
  • IPMI access: get raw access to the server IPMI, create network pass-through with admin user and manage server directly via a standard DRAC or IPMI interface with HTML5 or Java console
  • Console access: one-click access to HTML5 or Java server console without installing anything locally
  • ISO library access: server may be booted directly from one of our ISO images for installation or troubleshooting
  • Remote hands requests: one-click experience to create remote hands requests to check your server or other common tasks
  • Billing operations: top-up account directly, pay bills directly from the panel. Request cancellations.
  • Statistics: View traffic usage graphs per interface or specific IP. View server performance metrics with the monitoring agent installed.
  • Tags: setup own tags/values for a server, perform search operations, access these tags via API to keep server states and other server-related data like your billing ID
  • Coming soon: hourly billing, create your own users with various permissions, allocate budget limits to users, post-payment for verified customers, server monitoring with notifications. Private IP blocks management.

API Requests

All requests must be made over the HTTPS protocol to ensure transaction encryption.

Unless otherwise specified, all requests should use the POST method.

API examples format

Examples in this documentation are described using a command line HTTP client curl. On computers with Linux and MacOS curl are usually installed by default, and it is available for loading on all popular platforms, including Windows.

Each example is divided into several lines with a symbol of \, which is compatible with bash. A typical example looks like this:

POST request example:
curl -s "https://invapi.hostkey.com/tags.php" -X POST \
--data "action=list" \
--data "token=$HOSTKEY_TOKEN" \
--data "id=Server ID"

The parameter -X sets the request method. For consistency, the method will be indicated in all examples, even if it is clearly not required for GET methods.

Examples for which the JSON object is required in the body of the request, transmit the required data through the --data parameter.

The response to requests takes place in JSON format and is formatted in the documentation for habitability.

Attention

To use the API at the beginning, you need to get an session token. This can be done using API calls auth/login or auth/whmcslogin

Note

To use the above examples, without substituting your token each time, you can add a token once to the environment variables in your console. For example, on Linux this can be done using a command:

HOSTKEY_TOKEN="token"

After that, the token will be automatically substituted in your requests.

Note

Please note that all values in this documentation are examples. Do not rely on identifiers of operating systems, tariffs, etc., used in examples. Use your values of servers/networks/domains to obtain values or before creating resources.

Authorization using an API key

To utilize the API, you must first acquire a session token. This can be achieved by making an API call to auth/login, after obtaining an API key in Invapi, or through the call api_keys/add.

A session token can also be obtained through the auth/whmcslogin call using the account login and password.

To access both the entire account and a specific server, you can obtain authorization through an API key by making a call to auth/login. If the key is found in the database and authorization is successful, the system will return the session token $HOSTKEY_TOKEN.

The token's authority will apply to the entire account if using a shared key or only to a specific server if using a per-server key. This method enables automatic server management and ordering services through our API without requiring login credentials or interactive 2FA verification.

Working with API keys using api_keys calls

To work with API calls and obtain an API key, you will need a session token. The session token can be obtained through the auth/whmcslogin call and is valid for one hour by default. After obtaining the session token, we recommend generating an API key for your account and using it to work with the API. To receive the session token, use the auth/login call.

Resource Action Description
api_keys.php list obtain data on all generated API keys associated with the account
api_keys.php list_for_server obtain data on API keys generated for a specific server
api_keys.php view view information regarding a particular API key
api_keys.php add obtain an API key for an account or server
api_keys.php edit modify the API key parameters
api_keys.php delete delete an API key
api_keys.php history display of API key usage information for a specified time period

api_keys/list

Displays all API keys generated by the account associated with the session token.

HTTP method - POST

Parameter Required Type Value/default Description
action * string list main action - obtain data on all generated API keys associated with the account
token * string session token

POST-request

curl -s "https://invapi.hostkey.com/api_keys.php" -X POST \
--data "action=list" \
--data "token=$HOSTKEY_TOKEN"
Positive response
{
    "result": "OK",
    "module": "api_keys",
    "action": "list",
    "data": [
        {
            "id": 484, //Account API key ID
            "name": "new_api",
            "active": 1,
            "ip": "",
            "server_id": 0,
            "token_view": "0cab",
            "login_notify_method": "none",
            "login_notify_address": null
        },
        { 
            "id": 237, //Server API key ID
            "name": "test_control_panel",
            "active": 1,
            "ip": "",
            "server_id": 39601, //Server ID for the assigned key's server
            "token_view": "b66d",
            "login_notify_method": "none",
            "login_notify_address": null
        }
    ]
}

api_keys/list_for_server

Displays the API keys generated for a particular server.

HTTP method - POST

Parameter Required Type Value/default Description
action * string list_for_server main action - obtain data on API keys generated for a specific server
server_id * int Server ID
token * string session token

POST-request

curl -s "https://invapi.hostkey.com/api_keys.php" -X POST \
--data "action=list_for_server" \
--data "params[server_id]={Server ID}" \ 
--data "token=$HOSTKEY_TOKEN"
Positive response
{
    "result": "OK",
    "module": "api_keys",
    "action": "list_for_server",
    "data": [
        {
            "id": 237,
            "name": "test_control_panel",
            "active": 1,
            "ip": "",
            "server_id": 39601,
            "token_view": "b66d",
            "login_notify_method": "none",
            "login_notify_address": null
        }
    ]
}

api_keys/view

Displays information about a specific API key.

HTTP method - POST

Parameter Required Type Value/default Description
action * string view main action - view information regarding a particular API key
id * int API key ID (can be obtained by calling api_keys/list)
token * string session token

POST-request

curl -s "https://invapi.hostkey.com/api_keys.php" -X POST \
--data "action=view" \
--data "params[id]={API key ID}" \ 
--data "token=$HOSTKEY_TOKEN"
Positive response
{
    "result": "OK",
    "module": "api_keys",
    "action": "view",
    "data": {
        "id": 484,
        "name": "new_api",
        "active": 1,
        "ip": "",
        "server_id": 0,
        "token_view": "0cab",
        "login_notify_method": "none",
        "login_notify_address": null
    }
}

api_keys/add

Allows you to obtain an API key for an account or server.

HTTP method - POST

Parameter Required Type Value/default Description
action * string add main action - obtain an API key for an account or server
name * string key name
server_id int server ID, if the key is not issued for the entire account
ip string provide a list of authorized IP addresses for key usage (for example 10.0.0.2, 10.4.6.3/24)
login_notify_method * string select the notification method for login using the provided API key (none, email, webhook)
login_notify_address string email or notification webhook address will depend on the value set in the login_notify_method
active * int 1 - enable the key, 0 - disable the key
token * string session token

Note

When specifying an API key for the server, make sure to set the login notify method to none.

POST-request

curl -s "https://invapi.hostkey.com/api_keys.php" -X POST \
--data "action=add" \
--data "params[name]={API key name}" \
--data "params[server_id]={Server ID}" \
--data "params[ip]={IP address "white list"} \
--data "params[login_notify_method]={`none`, `email` or `webhook`}" \
--data "params[login_notify_address]=" \
--data "params[active]={1 or 0}" \
--data "token=$HOSTKEY_TOKEN"
Positive response
{
    "result": "OK",
    "module": "api_keys",
    "action": "add",
    "data": {
        "id": 501, //API key ID
        "name": "test key",
        "active": 1,
        "ip": "10.0.0.1 10.3.4.5",
        "server_id": 0,
        "token_view": "d981",
        "login_notify_method": "email",
        "login_notify_address": "[email protected]",
        "api_key": "d9815703f6f41d3f-5d52f141ff7ac755" // Generated API key
    }
}

api_keys/edit

Allows you to modify the API key parameters.

HTTP method - POST

Parameter Required Type Value/default Description
action * string edit main action - modify the API key parameters
id * int API key ID (can be obtained by calling api_keys/list)
name * string key name
ip string provide a list of authorized IP addresses for key usage (for example 10.0.0.2, 10.4.6.3/24)
login_notify_method * string select the notification method for login using the provided API key (none, email, webhook)
login_notify_address string email or notification webhook address will depend on the value set in the login_notify_method
active * int 1 - enable the key, 0 - disable the key
token * string session token

POST-request

curl -s "https://invapi.hostkey.com/api_keys.php" -X POST \
--data "action=edit" \
--data "params[id]={API key ID}" \ 
--data "params[name]={API key name}" \
--data "params[server_id]={Server ID}" \
--data "params[ip]={IP address ACL} \
--data "params[login_notify_method]={`none`, `email` or `webhook`}" \
--data "params[login_notify_address]=" \
--data "params[active]={1 or 0}" \
--data "token=$HOSTKEY_TOKEN"
Positive response
{
    "result": "OK",
    "module": "api_keys",
    "action": "edit",
    "data": {
        "id": 506
    }
}

api_keys/delete

Allows you to delete an API key.

HTTP method - POST

Parameter Required Type Value/default Description
action * string delete main action - delete an API key
id * int API key ID (can be obtained by calling api_keys/list)
token * string session token

POST-request

curl -s "https://invapi.hostkey.com/api_keys.php" -X POST \
--data "action=delete" \
--data "params[id]={API key ID}" \ 
--data "token=$HOSTKEY_TOKEN"
Positive response
{
    "result": "OK",
    "module": "api_keys",
    "action": "delete",
    "data": {
        "id": 506
    }
}

api_keys/history

Allows you to display of API key usage information for a specified time period.

HTTP method - POST

Parameter Required Type Value/default Description
action * string history main action - display of API key usage information for a specified time period
id * int API key ID (can be obtained by calling api_keys/list)
period_from string Date from which to output history in Y-M-D format
period_to string Date to which you want to output the history in the format Y-M-D
token * string session token

POST-request

curl -s "https://invapi.hostkey.com/api_keys.php" -X POST \
--data "action=history" \
--data "params[id]={API key ID}" \ 
--data "params[period_from]={History output start date} \
--data "params[period_from]={History output end date} \
--data "token=$HOSTKEY_TOKEN"
Positive response
{
    "result": "OK",
    "module": "api_keys",
    "action": "history",
    "data": [
        {
            "id": 20818097,
            "date": "2024-02-14 11:14:05",
            "message": "Deleted api_key 506. json:{\"id\":\"506\"}",
            "type": "action",
            **Login**: "[email protected]"
        },
        {
            "id": 20817742,
            "date": "2024-02-14 11:10:45",
            "message": "Changed api_key 506. name from 'test key 2' to 'new_new test', active from '1' to '0', ip from '10.0.0.1 10.3.4.5' to '78.8.8.6', login_notify_method from 'none' to 'email', login_notify_address from '' to '[email protected]'",
            "type": "action",
            **Login**: "[email protected]"
        },
        {
            "id": 20817738,
            "date": "2024-02-14 11:10:45",
            "message": "Updated api_key 506. json:{\"id\":\"506\",\"name\":\"new_new test\",\"ip\":\"78.8.8.6\",\"login_notify_method\":\"email\",\"login_notify_address\":\"[email protected]\",\"active\":\"0\"}",
            "type": "action",
            **Login**: "[email protected]"
        },
        {
            "id": 20816506,
            "date": "2024-02-14 11:03:51",
            "message": "Created new api_key 506. json:{\"name\":\"test key 2\",\"ip\":\" 10.0.0.1, 10.3.4.5\",\"login_notify_method\":\"none\",\"active\":\"1\",\"server_id\":\"34533\"}",
            "type": "action",
            **Login**: "[email protected]"
        }
    ]
}

Authorization

Resource Action Description
auth.php login obtain a session token via API KEY
auth.php whmcslogin obtain a session token from a login/password pair
auth.php logout session token removal
auth.php info obtain complete equipment data
eq.php set_pin set/change PIN Code
eq.php check_pin validate entered PIN

auth/login

Allows you to obtain a session token using an account or server API key.

Note

The most important data is the token (hereafter $HOSTKEY_TOKEN in the examples). All information about the token data and permissions is stored on the API server, the rest of the data helps to build the right web interface for a particular role.

The token is normally valid for 2 hours, if a different token lifetime is required, it can be specified in seconds using the ttl parameter. If the token is requested again within this time, a valid token will be returned. The token is usually bound to the user's IP if not required - the binding can be removed with the fix_ix=0 parameter. If the token is bound to the IP and the IP changes, the system will generate an error and it will be necessary to get the token again.

HTTP method - POST

Parameter Required Type Value/default Description
action * string login Main action - obtains an access token
key * string API access key
ttl int 7200 session duration in seconds, default is 7200 (2 hours)

POST-request

curl -s "https://invapi.hostkey.com/auth.php" -X POST \
--data "action=login" \
--data "key={API key value from Invapi}" \
Positive response
{
    "result": {
        "token": c92e48c4506320873286b84440e74sfd", // SESSION TOKEN
        "role": "Customer billing",
        "role_type": "Customer",
        "whmcs_id": 3172,
        "whmcs_location": "whmcs_com",
        "servers": [
            34533
            32645
            17405
        ],
        "customer_id": 38157,
        "permissions": [ // LIST OF AVAILABLE API CALLS FOR A SPECIFIC ROLE
            "api_keys/edit",
            "api_keys/view",
            "auth/2fa_check",
            "auth/billing_list",
            "auth/flip_tag",
            "auth/sms_send",
            "customers/update_acl",
            "datacenter/list",
            "datacenter/show",
            "eq/add_ipmi_admin",
            "eq/add_ipmi_user",
            "eq/appraise",
            "eq/boot_dev",
            "eq/console",
            "eq/create_pxe",
            "eq/get_ipmi",
            "eq/get_traffic",
            "eq/list",
            "eq/novnc",
            "eq/off",
            "eq/on",
            "eq/order_instance",
            "eq/reboot",
            "eq/reinstall",
            "eq/remove_ipmi_user",
            "eq/sensors",
            "eq/set_pin",
            "eq/show",
            "eq/status",
            "eq/suspend",
            "eq/unit_reset",
            "eq/unsuspend",
            "foreman/get_hostgroup",
            "foreman/get_media",
            "foreman/get_network",
            "foreman/get_os",
            "foreman/get_ptable",
            "ip/get_ip",
            "ip/get_ptr",
            "ip/get_traffic",
            "ip/list_free_ip",
            "ip/set_main",
            "ip/update_ptr",
            "iso/list_iso",
            "iso/mount_iso",
            "iso/unmount_iso",
            "jenkins/call",
            "jenkins/get_tasks",
            "license/list",
            "location/list",
            "location/show",
            "locations/view",
            "nat/add_static_nat",
            "nat/remove_static_nat",
            "net/block_ip",
            "net/get_acl",
            "net/get_bps_in",
            "net/get_bps_out",
            "net/get_port",
            "net/get_pspeed",
            "net/get_snmp",
            "net/get_status",
            "net/ip_chart",
            "net/ip_settings",
            "net/nmap",
            "net/port_off",
            "net/port_on",
            "net/remove_ipv4",
            "net/show_cacti",
            "net/show_ip_graph",
            "net/unblock_ip",
            "os/list",
            "os/search",
            "paypal/check_order",
            "paypal/check_subscription",
            "paypal/create_order",
            "paypal/create_subscription",
            "pdns/add_dns",
            "pdns/add_domain",
            "pdns/add_subdomain",
            "pdns/create_dns",
            "pdns/create_zone",
            "pdns/delete_domain",
            "pdns/delete_zone",
            "pdns/edit",
            "pdns/get_domains",
            "pdns/get_subdomains",
            "pdns/get_zone",
            "pdns/list_domains",
            "pdns/list_servers",
            "pdns/list_subdomains",
            "pdns/view",
            "pdns/view_zone",
            "pdu/get",
            "presets/list",
            "presets/search",
            "soft/list",
            "ssh_keys/add",
            "ssh_keys/delete",
            "ssh_keys/list",
            "stocks/list",
            "stocks/show",
            "sumsub/get_token",
            "tag/add",
            "tag/clear",
            "tag/list",
            "tag/remove",
            "traffic_plans/list",
            "vat/check_vat",
            "vm/create_snapshot",
            "vm/get_engine",
            "vm/get_snapshot",
            "vm/load_stats",
            "vm/remove_snapshot",
            "vm/restore_snapshot",
            "whmcs/add_contact",
            "whmcs/add_os_addon",
            "whmcs/apply_credit",
            "whmcs/cancel_order",
            "whmcs/create_addfunds",
            "whmcs/delete_cancellation_request",
            "whmcs/delete_contact",
            "whmcs/download_invoice",
            "whmcs/generate_due_invoice",
            "whmcs/getcredits",
            "whmcs/getpaymentgw",
            "whmcs/get_billing_data",
            "whmcs/get_cancellation_requests",
            "whmcs/get_client",
            "whmcs/get_contacts",
            "whmcs/get_invoice",
            "whmcs/get_invoices",
            "whmcs/get_related_invoices",
            "whmcs/mass_pay",
            "whmcs/request_cancellation",
            "whmcs/transactions",
            "whmcs/update_client",
            "whmcs/update_contact",
            "whmcs/update_product",
            "whmcs/verify_address",
            "whmcs/verify_email",
            "yookassa/check_payment",
            "yookassa/init"
        ],
        "token_expire": 1702895140,
        "new": 1
    }
}
Failure response
{
    "result": -1,
    "error": "Invalid API key XXXXXXXXXXXXX-XXXXXXXXXXXXXXX"
}

auth/whmcslogin

Allows you to obtain a session token by pairing your account login and password.

HTTP method - POST

Note

Authorization by login/password pair is performed for the entire account and all its servers. If authorization is successful, the system returns a session token $HOSTKEY_TOKEN. You can bind the session token to a specific IP address, then you must retrieve it when logging in from a different IP.

Attention

If you have 2FA enabled, this call will send a request to your 2FA device and you will need to enter an access code.

Parameter Required Type Value/default Description
action * string whmcslogin main action - to obtain a session token
user * string billing login
password * string billing password
fix_ip int fix_ip=0 - do not bind token to address, fix_ip=1 - bind
ttl int 10800 session duration in seconds, default is 3600 (1 hour)

POST-request, cURL

curl -s "https://invapi.hostkey.com/auth.php" -X POST \
--data "action=whmcslogin" \
--data "user={login}" \
--data "password={password}"
Positive response
{
    "result": {
        "token": c92e48c4506320873286b84440e74sfd", // SESSION TOKEN
        { "role": "Customer Billing", // ROLE
        "role_type": "Customer", // ROLE TYPE
        "whmcs_id": 3172, // BILLING ACCOUNT_ID
        "whmcs_location": "whmcs_com", // WHICH BILLING IS USED HERE
        "whmcs_token": null, 
        "permissions": [ // LIST OF API CALLS AVAILABLE FOR A GIVEN ROLE
            "api_keys/edit",
            "api_keys/view",
            "auth/2fa_check",
            "auth/billing_list",
            "auth/flip_tag",
            "auth/sms_send",
            "customers/update_acl",
            "datacenter/list",
            "datacenter/show",
            "eq/add_ipmi_admin",
            "eq/add_ipmi_user",
            "eq/appraise",
            "eq/boot_dev",
            "eq/console",
            "eq/create_pxe",
            "eq/get_ipmi",
            "eq/get_traffic",
            "eq/list",
            "eq/novnc",
            "eq/off",
            "eq/on",
            "eq/order_instance",
            "eq/reboot",
            "eq/reinstall",
            "eq/remove_ipmi_user",
            "eq/sensors",
            "eq/set_pin",
            "eq/show",
            "eq/status",
            "eq/suspend",
            "eq/unit_reset",
            "eq/unsuspend",
            "foreman/get_hostgroup",
            "foreman/get_media",
            "foreman/get_network",
            "foreman/get_os",
            "foreman/get_ptable",
            "ip/get_ip",
            "ip/get_ptr",
            "ip/get_traffic",
            "ip/list_free_ip",
            "ip/set_main",
            "ip/update_ptr",
            "iso/list_iso",
            "iso/mount_iso",
            "iso/unmount_iso",
            "jenkins/call",
            "jenkins/get_tasks",
            "license/list",
            "location/list",
            "location/show",
            "locations/view",
            "nat/add_static_nat",
            "nat/remove_static_nat",
            "net/block_ip",
            "net/get_acl",
            "net/get_bps_in",
            "net/get_bps_out",
            "net/get_port",
            "net/get_pspeed",
            "net/get_snmp",
            "net/get_status",
            "net/ip_chart",
            "net/ip_settings",
            "net/nmap",
            "net/port_off",
            "net/port_on",
            "net/remove_ipv4",
            "net/show_cacti",
            "net/show_ip_graph",
            "net/unblock_ip",
            "os/list",
            "os/search",
            "paypal/check_order",
            "paypal/check_subscription",
            "paypal/create_order",
            "paypal/create_subscription",
            "pdns/add_dns",
            "pdns/add_domain",
            "pdns/add_subdomain",
            "pdns/create_dns",
            "pdns/create_zone",
            "pdns/delete_domain",
            "pdns/delete_zone",
            "pdns/edit",
            "pdns/get_domains",
            "pdns/get_subdomains",
            "pdns/get_zone",
            "pdns/list_domains",
            "pdns/list_servers",
            "pdns/list_subdomains",
            "pdns/view",
            "pdns/view_zone",
            "pdu/get",
            "presets/list",
            "presets/search",
            "soft/list",
            "ssh_keys/add",
            "ssh_keys/delete",
            "ssh_keys/list",
            "stocks/list",
            "stocks/show",
            "sumsub/get_token",
            "tag/add",
            "tag/clear",
            "tag/list",
            "tag/remove",
            "traffic_plans/list",
            "vat/check_vat",
            "vm/create_snapshot",
            "vm/get_engine",
            "vm/get_snapshot",
            "vm/load_stats",
            "vm/remove_snapshot",
            "vm/restore_snapshot",
            "whmcs/add_contact",
            "whmcs/add_os_addon",
            "whmcs/apply_credit",
            "whmcs/cancel_order",
            "whmcs/create_addfunds",
            "whmcs/delete_cancellation_request",
            "whmcs/delete_contact",
            "whmcs/download_invoice",
            "whmcs/generate_due_invoice",
            "whmcs/getcredits",
            "whmcs/getpaymentgw",
            "whmcs/get_billing_data",
            "whmcs/get_cancellation_requests",
            "whmcs/get_client",
            "whmcs/get_contacts",
            "whmcs/get_invoice",
            "whmcs/get_invoices",
            "whmcs/get_related_invoices",
            "whmcs/mass_pay",
            "whmcs/request_cancellation",
            "whmcs/transactions",
            "whmcs/update_client",
            "whmcs/update_contact",
            "whmcs/update_product",
            "whmcs/verify_address",
            "whmcs/verify_email",
            "yookassa/check_payment",
            "yookassa/init"
        ],
        "corporate": 0,
        "verified": null,
        "token_expire": 1703059226,
        "new": 0,
        "billing_options": {
            "location": "NL",
            "company": "HOSTKEY B.V.",
            "active": 1,
            "allowed_payments": [
                "yookassa"
            ],
            "native_endpoint": "invapi.hostkey.com"
        }
    },
    "timings": [ // ???
        {
            "init": 2
        },
        {
            "auth_log_start": 2
        },
        {
            "auth_log_done": 3
        },
        {
            "check_brute_done": 131
        },
        {
            "auth_find_customer_done": 3
        },
        {
            "check_whmcs_user at whmcs_com": 469
        },
        {
            "log_brute_done": 5
        },
        {
            "usleep_done": 84
        },
        {
            "auth_get_hash_done": 2
        },
        {
            "hash_init_done": 5
        },
        {
            "auth_set_token_done": 423
        },
        {
            "auth_get_role_done": 1
        },
        {
            "auth_list_permissions_done": 2
        },
        {
            "auth_check_customer_init": 0
        },
        {
            "auth_check_customer_done": 5
        },
        {
            "auth_add_tags_done": 0
        },
        {
            "auth_log_time": [
                {
                    "add_log": 3
                },
                {
                    "amqp_sendmessage": 28
                }
            ]
        },
        {
            "whmcslogin total": 1166
        }
    ]
}
Failure response
{
    "result": -2,
    "error": "auth: authenthication failure  " // INTERNAL ERROR DESCRIPTION
    "details": // ERROR DETAILS FROM WHMCS
}

auth/logout

Allows you to end a client session.

HTTP method - POST

Parameter Required Type Value/default Description
action * string logout main action - delete the session token from the database. When the session is finished, you should log out of the system. This avoids potential security issues.
token * string removal token

POST-request, cURL

curl -s "https://invapi.hostkey.com/auth.php" -X POST \
--data "action=logout" \
--data "token=$HOSTKEY_TOKEN"

auth/info

Allows you to get user information (available API requests, account type and role, and id servers associated with the account).

HTTP method - POST

Parameter Required Type Value/default Description
action * string info main action - info will return full data about your token including your server's identification numbers when you are logged in.
token * string session token

POST-request, cURL

curl -s "https://invapi.hostkey.com/auth.php" -X POST \
--data "action=info" \
--data "token=$HOSTKEY_TOKEN"
Positive response
{
    "result": {
        "servers": { // ID SERVERS ASSOCIATED WITH THE ACCOUNT
            "34533": "34533"
            "32645": "32645"
            "17405": "17405"
        },
        "show_products": 1,
        "manage_products": 1,
        "show_invoices": 1,
        "manage_orders": 1,
        "email": "[email protected]",
        "token_expire": 1703059020,
        "whmcs_id": "3172",
        "whmcs_location": "whmcs_com",
        "billing_servers": [],
        "deploy_keys": [],
        "permissions": [ // LIST OF AVAILABLE API CALLS FOR A SPECIFIC ROLE
            "api_keys/edit",
            "api_keys/view",
            "auth/2fa_check",
            "auth/billing_list",
            "auth/flip_tag",
            "auth/sms_send",
            "customers/update_acl",
            "datacenter/list",
            "datacenter/show",
            "eq/add_ipmi_admin",
            "eq/add_ipmi_user",
            "eq/appraise",
            "eq/boot_dev",
            "eq/console",
            "eq/create_pxe",
            "eq/get_ipmi",
            "eq/get_traffic",
            "eq/list",
            "eq/novnc",
            "eq/off",
            "eq/on",
            "eq/order_instance",
            "eq/reboot",
            "eq/reinstall",
            "eq/remove_ipmi_user",
            "eq/sensors",
            "eq/set_pin",
            "eq/show",
            "eq/status",
            "eq/suspend",
            "eq/unit_reset",
            "eq/unsuspend",
            "foreman/get_hostgroup",
            "foreman/get_media",
            "foreman/get_network",
            "foreman/get_os",
            "foreman/get_ptable",
            "ip/get_ip",
            "ip/get_ptr",
            "ip/get_traffic",
            "ip/list_free_ip",
            "ip/set_main",
            "ip/update_ptr",
            "iso/list_iso",
            "iso/mount_iso",
            "iso/unmount_iso",
            "jenkins/call",
            "jenkins/get_tasks",
            "license/list",
            "location/list",
            "location/show",
            "locations/view",
            "nat/add_static_nat",
            "nat/remove_static_nat",
            "net/block_ip",
            "net/get_acl",
            "net/get_bps_in",
            "net/get_bps_out",
            "net/get_port",
            "net/get_pspeed",
            "net/get_snmp",
            "net/get_status",
            "net/ip_chart",
            "net/ip_settings",
            "net/nmap",
            "net/port_off",
            "net/port_on",
            "net/remove_ipv4",
            "net/show_cacti",
            "net/show_ip_graph",
            "net/unblock_ip",
            "os/list",
            "os/search",
            "paypal/check_order",
            "paypal/check_subscription",
            "paypal/create_order",
            "paypal/create_subscription",
            "pdns/add_dns",
            "pdns/add_domain",
            "pdns/add_subdomain",
            "pdns/create_dns",
            "pdns/create_zone",
            "pdns/delete_domain",
            "pdns/delete_zone",
            "pdns/edit",
            "pdns/get_domains",
            "pdns/get_subdomains",
            "pdns/get_zone",
            "pdns/list_domains",
            "pdns/list_servers",
            "pdns/list_subdomains",
            "pdns/view",
            "pdns/view_zone",
            "pdu/get",
            "presets/list",
            "presets/search",
            "soft/list",
            "ssh_keys/add",
            "ssh_keys/delete",
            "ssh_keys/list",
            "stocks/list",
            "stocks/show",
            "sumsub/get_token",
            "tag/add",
            "tag/clear",
            "tag/list",
            "tag/remove",
            "traffic_plans/list",
            "vat/check_vat",
            "vm/create_snapshot",
            "vm/get_engine",
            "vm/get_snapshot",
            "vm/load_stats",
            "vm/remove_snapshot",
            "vm/restore_snapshot",
            "whmcs/add_contact",
            "whmcs/add_os_addon",
            "whmcs/apply_credit",
            "whmcs/cancel_order",
            "whmcs/create_addfunds",
            "whmcs/delete_cancellation_request",
            "whmcs/delete_contact",
            "whmcs/download_invoice",
            "whmcs/generate_due_invoice",
            "whmcs/getcredits",
            "whmcs/getpaymentgw",
            "whmcs/get_billing_data",
            "whmcs/get_cancellation_requests",
            "whmcs/get_client",
            "whmcs/get_contacts",
            "whmcs/get_invoice",
            "whmcs/get_invoices",
            "whmcs/get_related_invoices",
            "whmcs/mass_pay",
            "whmcs/request_cancellation",
            "whmcs/transactions",
            "whmcs/update_client",
            "whmcs/update_contact",
            "whmcs/update_product",
            "whmcs/verify_address",
            "whmcs/verify_email",
            "yookassa/check_payment",
            "yookassa/init"
        ],
        "role_type": "Customer",
        "role_name": "Customer billing",
        "verified": null,
        "sumsub_id": null,
        "sumsub_comment": null,
        "corporate": 0,
        "tags": [
            {
                "id": 582523,
                "component": "customers",
                "component_id": 38157,
                "tag": "email_verification",
                "value": "verified",
                "extra": "1699523441",
                "internal": 0
            }
        ],
        "billing_options": {
            "url": "https://billing-itb.hostkey.com/",
            "location": "NL",
            "company": "HOSTKEY B.V.",
            "active": 1,
            "allowed_payments": [
                "paypal"
            ],
            "native_endpoint": "invapi.hostkey.com"
        },
        "client_ip": "185.130.215.70",
        "timing": [
            {
                "auth_validate_token": 0
            },
            {
                "auth_tags": 0
            },
            {
                "auth_get_role": 0
            },
            {
                "whmcs_get_server_raw": 0
            },
            {
                "eq_search": 0
            },
            {
                "add new tags": 0
            },
            {
                "list_permissions": 0
            },
            {
                "private_block": 0
            },
            {
                "auth_log": 0
            }
        ]
    }
}
Failure response
{
    "result": -2,
    "error": "auth: invalid token #13"
}

PIN codes

We are trying to keep our customer's servers safe, even in case of data leaks on the user's devices. The system will ask for a PIN for every critical server's operation.

The PIN is a short password to keep equipment safe and should not be stored anywhere. We could only reset it via manual support request after extra security verification.

Note

  • PIN's hashes are stored very separately from our billing and inventory databases.
  • Most of the management functions will not work without or with an empty PIN. It should be set once.

eq/set_pin

Allows you to set/change the client PIN.

HTTP method - POST/GET

Parameter Required Type Value/default Description
action * string set_pin main action - set/change PIN for the user
token * string session token
old_pin if modified int old PIN code
new_pin * int new PIN code

POST-request, cURL

curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=set_pin" \
--data "token=$HOSTKEY_TOKEN" \
--data "old_pin={CURRENT PIN}" \
--data "new_pin={NEW PIN}"
Positive response
{
    "result": "OK",
    "action": "set_pin",
    "callback": "d4eb60d21f7824a6f33de66060e2f2f5"
}
Failure response
{
"result": "Fail",
"scope": "Invalid PIN/email combination, please check",
"context": {
"action": "set_pin",
"id": "0"
},
"status": "failure",
"created": "2021-05-17 21:07:55",
"debug": null,
"key": "4746d646be54d7805f10e1b6c4f003bb"
}

Note

This action has an asynchronous response.

eq/check_pin

Allows you to confirm the correctness of the entered client PIN.

HTTP method - POST/GET

Parameter Required Type Value/default Description
action * string check_pin main action - validate entered PIN
token * string session token
old_pin if modified int PIN code

POST-request, cURL

curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=check_pin" \
--data "token=$HOSTKEY_TOKEN" \
--data "pin={PIN code}"
Positive response
{
    "result": "OK",
    "action": "check_pin",
    "callback": "85dab623da4d091884a86a33ee05ce41"
}
Failure response

```json

{ "result": "OK", "scope": "Invalid pin code", "context": { "action": "check_pin", "id": "0" }, "debug": "Blocked For Security Purposes", "key": "d862ecc7ea64c5af55f39b132f3b7502" } ```

Note

This action has an asynchronous response.

Attention

After several failures API will return only failed responses with long delays to avoid bruteforce.

Billing interaction

HOSTKEY uses WHMCS as its billing software.

Resource Action Description
whmcs.php get_client customer information acquisition
whmcs.php update_client change customer account details
whmcs.php reset_password reset customer account password
whmcs.php get_contacts retrieve a list of additional contacts
whmcs.php add_contact add another contact to the account
whmcs.php update_contact change details for an additional contact
whmcs.php delete_contact delete additional contact for account
whmcs.php create_addfunds create add funds invoice
whmcs.php getpaymentgw get information how to pay this invoice
whmcs.php get_billing_data retrieve billing information for the server
whmcs.php getcredits get information about the movement of funds on the personal account, all accruals and write-offs of credits
whmcs.php generate_due_invoice create the following invoice for the server
whmcs.php transactions retrieve a list of transactions by client account
whmcs.php mass_pay create a group invoice for payment from multiple invoices
whmcs.php download_invoice download an invoice in PDF format
whmcs.php get_related_invoices get a list of invoices for a specific server
whmcs.php apply_credit pay the invoice with credit balance
whmcs.php create_addfunds create an invoice in order to top up credit balance
whmcs.php get_invoice retrieve invoice data for payment
whmcs.php get_invoices retrieve a complete list of invoices for payment
whmcs.php request_cancellation request a cancellation of the service
whmcs.php delete_cancellation_request delete a request to service cancellation
whmcs.php get_cancellation_requests get an active list of service cancellation requests

whmcs/get_client

Allows you to retrieve the required customer data from the billing system.

HTTP method - POST

Parameter Required Type Value/default Description
action * string get_client main action - customer information acquisition
token * string session token

POST-request, cURL

curl -s "https://invapi.hostkey.com/whmcs.php" -X POST \
--data "action=get_client" \
--data "token=$HOSTKEY_TOKEN" \
Positive response
{
    "result": "success",
    "client": {
        "userid": 3172,
        "id": 3172,
        "uuid": "b6d0bd75-1bd1-4ffc-9ec5-3870668b1ea9",
        "firstname": "John", // NAME
        "lastname": "Hostkey", // SURNAME
        "fullname": "Hostkey", // FULL NAME
        "companyname": "",
        "email": "[email protected]", // CLIENT E-MAIL
        "address1": "Veldweg 111", // CLIENT ADDRESS
        "address2": "",
        "city": "Amsterdam", // CITY
        "fullstate": "",
        "state": "", // STATE/PROVINCE/AREA
        "postcode": "7845 TC", // ZIP CODE
        "countrycode": "NL", // COUNTRY CODE
        "country": "NL", // COUNTRY CODE
        "phonenumber": "79658742356", // PHONE NUMBER
        "tax_id": "",
        "Password": "",
        "email_preferences": {
            "general": 1,
            "invoice": 1,
            "support": 1,
            "product": 1,
            "domain": 1,
            "affiliate": 1
        },
        "statecode": "",
        "countryname": "Netherlands", // COUNTRY NAME
        "phonecc": 7, // COUNTRY CALLING CODE
        "phonenumberformatted": "+31.06-95005645", 
        "telephoneNumber": "06-95005645", // PHONE NUMBER
        "billingcid": 0,
        "twofaenabled": false,
        "currency": 2,
        "defaultgateway": "",
        "groupid": 2,
        "status": "Active",
        "credit": "998.39",
        "taxexempt": false,
        "latefeeoveride": false,
        "overideduenotices": false,
        "separateinvoices": false,
        "disableautocc": false,
        "emailoptout": false,
        "marketing_emails_opt_in": true,
        "overrideautoclose": false,
        "allowSingleSignOn": 1,
        "email_verified": false,
        "language": "",
        "isOptedInToMarketingEmails": true,
        "lastlogin": "Date: 2023/09/11 12:27<br>IP Address: 176.222.34.23<br>Host: 176.222.56.20", // DATE, IP ADDRESS AND HOST IP
        "currency_code": "EUR", // VALUE CODE
        "co_autopayment": {
            "name": "Autopayment enabled",
            "type": "checkbox",
            "required": false,
            "value": ""
        },
        "co_payfirstday": {
            "name": "Services for first day",
            "type": "checkbox",
            "required": false,
            "value": ""
        },
        "co_marktemails": {
            "name": "Marketing e-mails",
            "type": "checkbox",
            "required": false,
            "value": "on"
        },
        "co_subscription": {
            "name": "Autopayments via PayPal",
            "type": "text",
            "size": 40,
            "required": false,
            "value": ""
        },
        "co_marktsms": {
            "name": "Marketing SMS",
            "type": "checkbox",
            "required": false,
            "value": "on"
        },
        "co_smsnum": {
            "name": "SMS number for 2FA and notices",
            "type": "text",
            "size": 26,
            "required": false,
            "placeholder": "+310695005645",
            "value": "310695005645"
        },
        "co_customertype": {
            "name": "Client type",
            "type": "select",
            "options": [
                "Individual",
                "Legal entity"
            ],
            "required": true,
            "value": "Individual"
        },
        "co_regaddress": {
            "name": "Legal address",
            "type": "text",
            "size": 100,
            "required": false,
            "value": ""
        },
        "co_bankdata": {
            "name": "Bank information",
            "type": "text",
            "size": 100,
            "required": false,
            "value": ""
        },
        "co_secret": {
            "name": "Secret word",
            "type": "text",
            "size": 26,
            "required": true,
            "value": "server"
        },
        "co_skype": {
            "name": "Skype/Telegram",
            "type": "text",
            "size": 26,
            "required": false,
            "value": ""
        },
    },
    "billing_location": "whmcs_com",
    "groupdata": {
        "id": 2,
        "groupname": "Customers",
        "groupcolour": "#ffffff",
        "discountpercent": "0.00",
        "susptermexempt": "",
        "separateinvoices": ""
    },
    "internal": {
        "id": 38157,
        "billing": "whmcs_com",
        "account_id": 3172,
        "email": "[email protected]",
        "active_since": "2023-11-09",
        "monthly": null,
        "verified": null,
        "corporate": 0,
        "tags": [
            {
                "id": 582523,
                "component": "customers",
                "component_id": 38157,
                "tag": "email_verification",
                "value": "verified",
                "extra": "1699523441",
                "internal": 0
            }
        ]
    }
}

whmcs/update_client

Allows you to modify customer account details.

HTTP method - POST

Parameter Required Type Value/default Description
action * string update_client main action - change customer account details
token * string session token
billing_status string billing status
billing_firstname string Customer's first name
billing_lastname string Customer's last name
billing_companyname string Company name
billing_email string Customer's email
billing_address1 string Customer address string 1
billing_address2 string Customer address string 2
billing_city string Customer's city
billing_state string Customer's state or region
billing_postcode string Customer's postcode
billing_country string Customer's country
billing_phonenumber string Customer's phonenumber
billing_twofaenabled string Enabling two-factor authorisation (true/false)
billing_currency int Payment currency 1 - , 2 - , 3 -
billing_groupid int (1/0)
billing_taxexempt string (true/false)
billing_latefeeoveride string (true/false)
billing_overideduenotices string (true/false)
billing_separateinvoices string (true/false)
billing_disableautocc string (true/false)
billing_emailoptout string (true/false)
billing_marketingoptin string Subscription to marketing mailings (true/false)
billing_overrideautoclose string (true/false)
billing_allowSingleSignOn int (1/0)
co_autopayment checkbox Activate automatic payments (on/off)
co_payfirstday checkbox Pay on the first of the month (on/off)
co_marktemails checkbox Marketing emails (on/off)
co_subscription string Automatic payments through the service (PayPal, etc)
co_marktsms checkbox Marketing mailing approval (on/off)
co_smsnum string SMS notification or 2FA authentication code number send
co_customertype string Type of customer: Natural person/Legal entity
co_regaddress string Customer's legal address
co_bankdata string Customer's bank details
co_secret string Secret word
co_skype string Skype/Telegram adress

POST-request, cURL

curl -s "https://invapi.hostkey.com/whmcs.php" -X POST \
--data "action=update_client" \
--data "billing_firstname={NAME} \
    ...
--data "co_smsnum=310695005645" \
--data "token=$HOSTKEY_TOKEN"
Positive response
{
    "result": "success",
    "clientid": "3172"
}

whmcs/reset_password

Allows you to reset the access password for the client account.

Attention

The `email' parameter must match the client's email address in the account where the password is being reset.

HTTP method - POST

Parameter Required Type Value/default Description
action * string reset_password main action - reset customer account password
token * string session token
email * string a password reset link will be sent to the email address provided.

POST-request, cURL

curl -s "https://invapi.hostkey.com/whmcs.php" -X POST \
--data "action=reset_password" \
--data "email={Email address to receive a password reset link}" \
--data "token=$HOSTKEY_TOKEN" \
Positive response
{
    "result": "OK",
    "message": "Password reset link was sent to the registred email.",
    "debug": {
        "result": "success"
    }
}
Failure response
{
    "result": -1,
    "message": "Failed to identify the customer's billing, please contact support"
}

whmcs/get_contacts

Lets you retrieve a list of additional contacts for a customer account.

HTTP method - POST

Parameter Required Type Value/default Description
action * string get_contacts main action - retrieve a list of additional contacts
token * string session token

POST-request, cURL

curl -s "https://invapi.hostkey.com/whmcs.php" -X POST \
--data "action=get_contacts" \
--data "token=$HOSTKEY_TOKEN" \
Positive response
{
    "result": "success",
    "contacts": [
        {
            "id": 121, // ADDITIONAL CONTACT ID
            "userid": 3172,
            "firstname": "Dimitry", 
            "lastname": "Servers",
            "companyname": "",
            "email": "[email protected]",
            "address1": "",
            "address2": "",
            "city": "",
            "state": "",
            "postcode": "",
            "country": "NL",
            "phonenumber": "",
            "tax_id": "",
            "subaccount": 1,
            **Password**: "$2y$10$pSlFQ1Vvq0UcKD5eE9dZ2.J5s779skGChaD0fPJB7ooURi1/KnDJm",
            "permissions": "",
            "domainemails": 0,
            "generalemails": 0,
            "invoiceemails": 0,
            "productemails": 0,
            "supportemails": 0,
            "affiliateemails": 0,
            "pwresetkey": "",
            "created_at": "0000-00-00 00:00:00",
            "updated_at": "2023-12-22 11:31:45",
            "pwresetexpiry": "0000-00-00 00:00:00"
        }
    ]
}

whmcs/add_contact

Allows you to add an additional contact to an account.

HTTP method - POST

Parameter Required Type Value/default Description
action * string add_contact main action - add an additional contact to an account
token * string session token

POST-request, cURL

curl -s "https://invapi.hostkey.com/whmcs.php" -X POST \
--data "action=add_contact" \
--data "token=$HOSTKEY_TOKEN" \
Positive response
{
    "result": "success",
    "contactid": 121 // ADDITIONAL CONTACT ID
}

Attention

A new additional contact will be created with a random 'email'. This must always be changed via the INVAPI.

whmcs/update_contact

Allows you to change the details of an additional contact.

HTTP method - POST

Parameter Required Type Value/default Description
action * string update_contact main action - change details for an additional contact
contact_id * int additional Contact ID
email * string additional contact's email for the account
password2 string new password for additional contact
phonenumber int phone number of the additional contact. Adding a number includes 2FA via SMS.
token * string session token

POST-request, cURL

curl -s "https://invapi.hostkey.com/whmcs.php" -X POST \
--data "action=update_contact" \
--data "contact_id=121" \
--data "token=29cfb2b6fb8f1bc838455fe36e032aaa" \
--data "[email protected]" \
--data "phonenumber=+79656754663" \
--data "password2=4321" \
Positive response
    "result": "success",
    "contactid": 121 // ADDITIONAL CONTACT ID

whmcs/delete_contact

Lets you delete an additional contact for an account.

HTTP method - POST

Parameter Required Type Value/default Description
action * string delete_contact main action - delete additional contact for account
contact_id * int additional Contact ID
token * string session token

POST-request, cURL

curl -s "https://invapi.hostkey.com/whmcs.php" -X POST \
--data "action=add_contact" \
--data "contact_id={additional Contact ID}" \
--data "token=$HOSTKEY_TOKEN" \
Positive response
{
    "result": "success",
    "message": "119"
}
Failure response
{
    "result": -1,
    "error": "whmcs/delete_contact: verification failed, subcontact not found"
}

whmcs/getpaymentgw

Provides information on how to pay your invoice.

HTTP method - POST

Parameter Required Type Value/default Description
action * string getpaymentgw main action - get information how to pay this invoice
invoice_id * int invoice ID
token * string session token

POST-request, cURL

curl -s "https://invapi.hostkey.com/whmcs.php" -X POST \
--data "action=getpaymentgw" \
--data "invoice_id={invoice ID}" \
--data "token=$HOSTKEY_TOKEN" \
Positive response
{
"result": "OK",
    "methods": {
        "paypal": {
            "name": "PayPal",
            "call": "<table><tr><td><form target=_blank action=\"https:\/\/www.paypal.com\/cgi-bin\/webscr\" method=\"post\">\n<input type=\"hidden\" name=\"cmd\" value=\"_xclick\">\n<input type=\"hidden\" name=\"business\" value=\"[email protected]\"><input type=\"hidden\" name=\"item_name\" value=\"HOSTKEY - Invoice #"invoice_id"\">\n<input type=\"hidden\" name=\"amount\" value=\"10.00\">\n<input type=\"hidden\" name=\"tax\" value=\"0.00\">\n<input type=\"hidden\" name=\"no_note\" value=\"1\">\n<input type=\"hidden\" name=\"no_shipping\" value=\"1\">\n<input type=\"hidden\" name=\"address_override\" value=\"0\">\n<input type=\"hidden\" name=\"first_name\" value=\""your firstname\">\n<input type=\"hidden\" name=\"last_name\" value=\""your lastname\">\n<input type=\"hidden\" name=\"email\" value=\""your email"\">\n<input type=\"hidden\" name=\"address1\" value=\"your address"\">\n<input type=\"hidden\" name=\"city\" value=\"your city"\">\n<input type=\"hidden\" name=\"state\" value=\"\">\n<input type=\"hidden\" name=\"zip\" value=\"11-111\">\n<input type=\"hidden\" name=\"country\" value=\"PL\">\n<input type=\"hidden\" name=\"night_phone_a\" value=\"48\">\n<input type=\"hidden\" name=\"night_phone_b\" value=\"48512515151\"><input type=\"hidden\" name=\"charset\" value=\"utf-8\">\n<input type=\"hidden\" name=\"currency_code\" value=\"EUR\">\n<input type=\"hidden\" name=\"custom\" value=\"196727\">\n<input type=\"hidden\" name=\"return\" value=\"https:\/\/invapi.hostkey.com?invoice_id=196727&paymentsuccess=true\">\n<input type=\"hidden\" name=\"cancel_return\" value=\"https:\/\/invapi.hostkey.com?invoice_id=196727&paymentfailed=true\">\n<input type=\"hidden\" name=\"notify_url\" value=\"https:\/\/bill.hostkey.com\/modules\/gateways\/callback\/paypal.php\">\n<input type=\"hidden\" name=\"bn\" value=\"WHMCS_ST\">\n<input type=\"hidden\" name=\"rm\" value=\"2\">\n<input type=\"image\" src=\"https:\/\/www.paypal.com\/en_US\/i\/btn\/x-click-but03.gif\" border=\"0\" name=\"submit\" alt=\"Make a one time payment with PayPal\">\n<\/form><\/td><\/tr><\/table>"
        },
        "banktransfer": {
            "name": "Bank Transfer",
            "call": "<span style='text-align:left'>Please wire funds in favor of: <p>HOSTKEY B.V.<br \/>\r\nWillem Frederik Hermansstraat 91, 1011DG<br \/>\r\nAmsterdam, the Netherlands<br \/>\r\nVAT: … KvK: … <br \/>\r\nIBAN: … SWIFT: …<br \/>\r\nBank: Co\u00f6peratieve Rabobank U.A.<br \/>Reference Number: 196727<\/p>"
        },
        "roudiappstripealipay": {
            "name": "Alipay (\u652f\u4ed8\u5b9d)",
            "call": "<!-- MoStripe New buy process -->\n\t<br \/><br \/>\n\t\n\t<script src=\"https:\/\/code.jquery.com\/jquery-1.10.2.min.js\"><\/script>\n\t<script src=\"https:\/\/js.stripe.com\/v3\/\"><\/script>\n\t<p><button id=\"mostripeOBT\" class=\"btn btn-primary\" title=\"moStripe Pay Now\">Pay Now<\/button><\/p>\n\t<p><\/p>\n\t<p id=\"resulterror\"><\/p>\n\t<form target=_blank action=\"#\" method=\"post\" id=\"roudifrm\">\n\t\t<input type=\"hidden\" name=\"invoiceid\" value=\"196727\" \/>\n\t\t<input type=\"hidden\" name=\"alipay_amount\" value=\"1000\" \/>\n\t\t<input type=\"hidden\" name=\"mostripeshakey\" value=\"5f18bcb3057b3a00f233f2cc3ca62a1bf9336b6e\" \/>\n\t\t<input type=\"hidden\" name=\"currency\" value=\"eur\" \/>\n\t\t<input type=\"hidden\" name=\"userid\" value=\"22160\" \/>\n\t\t\n\t<script type=\"text\/javascript\">\n\t\tvar stripe = Stripe( 'pk_live_LBhYzleiKSQfyNixR2vL2zjp');\n\t\t\n\t\tjQuery(function($) {\n\t\t    $('#mostripeOBT').click(function(){\n\t\t\t    stripe.createSource({\n\t\t\t\t  type: 'alipay',\n\t\t\t\t  amount: 1000,\n\t\t\t\t  currency: 'eur',\n\t\t\t\t  metadata: {\n\t\t\t\t  \tuserid: '22160',\n\t\t\t\t  \tinvoiceid: '196727'\n\t\t\t\t  },\n\t\t\t\t  redirect: {\n\t\t\t\t    return_url: 'https:\/\/bill.hostkey.com\/modules\/gateways\/callback\/roudiappstripealipay.php?id=196727&alipay_amount=1000&currency=eur&userid=22160',\n\t\t\t\t  },\n\t\t\t\t}).then(function(result) {\n\t\t\t\t  \/\/ handle result.error or result.source\n\t\t\t\t  if(result.error === 'payment_method_not_available'){\n\t\t\t\t\t  $('#resulterror').html('The payment method is currently not available');\n\t\t\t\t  } else if(result.error === 'processing_error'){\n\t\t\t\t\t  $('#resulterror').html('An unexpected error occurred preventing us from creating your payment.');\n\t\t\t\t  }\n\t\t\t\t  \/\/if successfull\n\t\t\t\t  if(result.source){\n\t\t\t\t\t $(location).attr('href', result.source.redirect.url);\n\t\t\t\t  }\n\t\t\t\t});\n\t\t\t\t\n\t\t\t\treturn false;\n\t\t    });\n\t\t});\n\t<\/script>\n\t<\/form>\n\t<!-- MoStripe New buy process ends -->"
        },
        "paymaster": {
            "name": "Webmoney (WME)",
            "call": "<form target=_blank method=\"post\" action=\"https:\/\/psp.paymaster24.com\/Payment\/Init\">\n     <input type=\"hidden\" name=\"LMI_MERCHANT_ID\" value=\"f8ebdab8-979c-41e6-90e6-69bdba4b5411\" \/>\n\t\t <input type=\"hidden\" name=\"LMI_PAYMENT_DESC_BASE64\" value=\"SE9TVEtFWSAtIEludm9pY2UgIzE5NjcyNw==\" \/>\n\t\t <input type=\"hidden\" name=\"LMI_PAYMENT_NO\" value=\"196727\" \/>\n\t\t <input type=\"hidden\" name=\"LMI_PAYMENT_AMOUNT\" value=\"10.00\" \/>\n\t\t <input type=\"hidden\" name=\"LMI_CURRENCY\" value=\"EUR\" \/>\n\t\t <input type=\"hidden\" name=\"LMI_FAILURE_URL\" value=\"https:\/\/invapi.hostkey.com?invoice_id=196727&paymentfailed=true\" \/>\n\t\t <input type=\"hidden\" name=\"LMI_SUCCESS_URL\" value=\"https:\/\/invapi.hostkey.com?invoice_id=196727&paymentsuccess=true\" \/>\n\t\t <input type=\"hidden\" name=\"LMI_INVOICE_CONFIRMATION_URL\" value=\"https:\/\/bill.hostkey.com\/\/modules\/gateways\/callback\/paymaster.php\" \/>\n\t\t <input type=\"hidden\" name=\"LMI_PAYMENT_CONFIRMATION_URL\" value=\"https:\/\/bill.hostkey.com\/\/modules\/gateways\/callback\/paymaster.php\" \/>\n\t\t <input type=\"hidden\" name=\"LMI_PAYMENT_NOTIFICATION_URL\" value=\"https:\/\/bill.hostkey.com\/\/modules\/gateways\/callback\/paymaster.php\" \/>\n\t\t <input type=\"hidden\" name=\"sign\" value=\"f5c5b30b12f544ce1686a1d69b50df36800acb08\" \/>\n\t\t <input type=\"submit\" value=\"Pay Now\" \/>\n\t\t <\/form>"
        },
        "bitpaycheckout": {
            "name": "Cryptocurrency (BTC, ETH and other)",
            "call": "<form target=_blank action=\"https:\/\/bill.hostkey.com\/modules\/gateways\/bit-pay\/createinvoice.php\" method=\"POST\"><input type=\"hidden\" name=\"invoiceId\" value = \"196727\" \/><input type=\"hidden\" name=\"systemURL\" value = \"https:\/\/bill.hostkey.com\" \/><input type=\"hidden\" name=\"buyerName\" value = \"\" \/><input type=\"hidden\" name=\"buyerAddress1\" value = \"\" \/><input type=\"hidden\" name=\"buyerAddress2\" value = \"\" \/><input type=\"hidden\" name=\"buyerCity\" value = \"warsava\" \/><input type=\"hidden\" name=\"buyerState\" value = \"\" \/><input type=\"hidden\" name=\"buyerZip\" value = \"11-111\" \/><input type=\"hidden\" name=\"buyerEmail\" value = \"[email protected]\" \/><input type=\"hidden\" name=\"buyerPhone\" value = \"48512515151\" \/><input type=\"submit\" value=\"Pay Now\" \/><\/form>"
        }
    }
}

whmcs/get_billing_data

Allows you to retrieve payment information for server rentals or other products.

HTTP Method - POST

Parameter Required Type Value/default Description
action * string get_billing_data main action - retrieve billing information for the server
id * int server ID
token * string session token

POST-request, cURL

curl -s "https://invapi.hostkey.com/whmcs.php" -X POST \
--data "action=get_billing_data" \
--data "token=$HOSTKEY_TOKEN" \
--data "id={Server ID}" \ 
Positive response
{
    "IP": "nl-vmmini", // Hostname/IP from billing
    "client_id": 3172, // Client ID in WHMCS
    "order_id": 5448, // Order ID in WHMCS
    "suspend_reason": "", // Specify the reason why the server was stopped (if such a situation occurred)
    "billing_setupfee": "5.00", // Initial payment amount
    "product_id": 5724, // Product ID in WHMCS
    "whmcs_location": "whmcs_com", // Payment identification
    "billing_status": "Active", // Server billing status
    "reg_date": "2023-12-14", // Service Start Date
    "billing_cycle": "Monthly", // Payment cycle
    "next_due_date": "2024-01-14", // Next payment due date
    "billing_reccuring": "5.00", // Amount of periodic payment
    "billing_name": "Services related to the provision of computing facilities (Instant server NL)",
    "billing_dedicatedip": "176.222.34.23",
    "billing_domain": "nl-vmmini",
    "promoid": 0,
    "terminationdate": null,
    "subscriptionid": "",
    "overideautosuspend": 0,
    "overidesuspenduntil": "0000-00-00",
    "currencyprefix": "", // Currency symbol
    "currencysuffix": "EUR",  // Cuttency name
    "is_company": 0,
    "tax_id": "",
    "groupdata": {
        "id": 2,
        "groupname": "Customers",
        "groupcolour": "#ffffff",
        "discountpercent": "0.00",
        "susptermexempt": "",
        "separateinvoices": ""
    },
    "days_left": 23,
    "customer_name": "John Hostkey", // Client name
    "customer_email": "[email protected]", // Client e-mail
    "result": "OK"
}

whmcs/getcredits

Allows you to get information about the movement of funds on the personal account, all accruals and write-offs of credits.

HTTP Method - POST

Parameter Required Type Value/default Description
action * string getcredit main action - get information about the movement of funds on the personal account, all accruals and write-offs of credits
id * int server ID
token * string session token

POST-request, cURL

curl -s "https://invapi.hostkey.com/whmcs.php" -X POST \
--data "action=getcredits" \
--data "token=$HOSTKEY_TOKEN" \
Positive response
{
    "result": "OK",
    "message": {
        "result": "success",
        "totalresults": 5,
        "clientid": 3172,
        "credits": {
            "credit": [
                {
                    "id": 2526,
                    "date": "2023-11-09",
                    "description": "Credit Applied to Invoice #10116",
                    "amount": "-5.00",
                    "relid": 0
                },
                {
                    "id": 4657,
                    "date": "2023-12-14",
                    "description": "Credit Applied to Invoice #18580",
                    "amount": "-5",
                    "relid": 0
                }
            ]
        }
    }
}

whmcs/generate_due_invoice

Lets you create the following invoice for the server

HTTP Method - POST

Parameter Required Type Value/default Description
action * string generate_due_invoice main action - create the following invoice for the server
id * int server ID
token * string session token

POST-request, cURL

curl -s "https://invapi.hostkey.com/whmcs.php" -X POST \
--data "action=generate_due_invoice" \
--data "token=$HOSTKEY_TOKEN" \
--data "id={Server ID}" \ 
Positive response
{
"result": "OK",
"invoices": 1
}
Failure response
{
"result": -1,
"error": "whmcs/generate_due_invoice: permission denied #3, this is not your server"
}

whmcs/transactions

Allows you to retrieve a list of transactions by client account.

HTTP Method - POST

Parameter Required Type Value/default Description
action * string transactions main action - retrieve a list of transactions by client account
invoice_id int invoice number for which transactions are required
transaction_id int Information transaction
token * string session token

POST-request, cURL

curl -s "https://invapi.hostkey.com/whmcs.php" -X POST \
--data "action=transactions" \
--data "token=$HOSTKEY_TOKEN" \
--data "invoice_id={invoice ID}" \ 
--data "transaction_id={transaction ID}" \    
Positive response
{
    "result": "OK",
    "transactions": []
}

whmcs/mass_pay

Lets you create a group invoice for payment from multiple invoices.

HTTP Method - POST

Parameter Required Type Value/default Description
action * string mass_pay main action - create a group invoice for payment from multiple invoices
invoices[] * array array of account numbers
token * string session token

POST-request, cURL

curl -s "https://invapi.hostkey.com/whmcs.php" -X POST \
--data "action=mass_pay" \
--data "token=$HOSTKEY_TOKEN" \
--data "invoices[]={invoice ID 1}" \
--data "invoices[]={invoice ID 2}" \
...
--data "invoices[]={invoice ID N}" \
Positive response
{
    "result": "OK",
    "invoiceid": 23455
}
Failure response
{
    "result": -1,
    "error": "whmcs/mass_pay: invalid request"
}

whmcs/download_invoice

Allows you to download an invoice in PDF format.

HTTP Method - POST

Parameter Required Type Value/default Description
action * string download_invoice main action - download an invoice in PDF format
invoice_id * int Invoice number for download
token * string session token

POST-request, cURL

curl -s "https://invapi.hostkey.com/whmcs.php" -X POST \
--data "action=download_invoice" \
--data "token=$HOSTKEY_TOKEN" \
--data "invoice_id={invoce ID}" \
Positive response

Invoice ID in PDF

Failure response
{
    "result": -1,
    "error": "whmcs/download_invoice: Invalid invoice ID"
}

Lets you get a list of invoices for a specific server.

HTTP Method - POST

Parameter Required Type Value/default Description
action * string get_related_invoices main action - get a list of invoices for a specific server
id * int server ID
token * string session token

POST-request, cURL

curl -s "https://invapi.hostkey.com/whmcs.php" -X POST \
--data "action=get_related_invoices" \
--data "token=$HOSTKEY_TOKEN" \
--data "id={Server ID}" \
Positive response
{
    "result": "success",
    "invoices": [
        {
            "id": 23451,
            "userid": 3172,
            "invoicenum": "",
            "date": "2023-12-25",
            "duedate": "2024-01-14",
            "datepaid": "0000-00-00 00:00:00",
            "last_capture_attempt": "0000-00-00 00:00:00",
            "date_refunded": "0000-00-00 00:00:00",
            "date_cancelled": "0000-00-00 00:00:00",
            "subtotal": "5.00",
            "credit": "0.00",
            "tax": "0.00",
            "tax2": "0.00",
            "total": "5.00",
            "taxrate": "0.00",
            "taxrate2": "0.00",
            "status": "Unpaid",
            "paymentmethod": "paipal",
            "paymethodid": null,
            "notes": "",
            "created_at": "2023-12-25 11:20:31",
            "updated_at": "2023-12-25 11:20:31"
        },
        {
            "id": 18580,
            "userid": 3172,
            "invoicenum": "",
            "date": "2023-12-14",
            "duedate": "2023-12-29",
            "datepaid": "2023-12-14 05:54:52",
            "last_capture_attempt": "0000-00-00 00:00:00",
            "date_refunded": "0000-00-00 00:00:00",
            "date_cancelled": "0000-00-00 00:00:00",
            "subtotal": "5.00",
            "credit": "5.00",
            "tax": "0.00",
            "tax2": "0.00",
            "total": "0.00",
            "taxrate": "0.00",
            "taxrate2": "0.00",
            "status": "Paid",
            "paymentmethod": "paipal",
            "paymethodid": null,
            "notes": "",
            "created_at": "2023-12-14 05:54:31",
            "updated_at": "2023-12-14 05:54:52"
        }
    ]
}
Failure response
{
    "result": -1,
    "error": "whmcs/get_related_invoices: permission denied #3, this is not your server"
}

whmcs/apply_credit

Allows you to pay a invoice in full or in part from a credit balance.

HTTP Method - POST

Parameter Required Type Value/default Description
action * string apply_credit main action - pay the invoice with credit balance
invoice_id * int invoice number
amount * int replenishment amount
token * string session token

POST-request, cURL

curl -s "https://invapi.hostkey.com/whmcs.php" -X POST \
--data "action=apply_credit" \
--data "token=$HOSTKEY_TOKEN" \
--data "invoice_id={invoice ID}" \
--data "amount={amount to be paid in account currency}" \
Positive response
{
    "result": "success",
    "invoiceid": 23449,
    "amount": 300,
    "invoicepaid": "true"
}
Failure response
{
    "result": -1,
    "error": "whmcs/apply_credit: invalid invoice id"
}

whmcs/create_addfunds

Allows you to create an invoice in order to top up credit balance.

HTTP method - POST

Parameter Required Type Value/default Description
action * string create_addfundst main action - create an invoice in order to top up credit balance
amount * int replenishment amount
token * string session token

POST-request, cURL

curl -s "https://invapi.hostkey.com/whmcs.php" -X POST \
--data "action=create_addfunds" \
--data "amount={Amount to be paid in account currency}" \
--data "token=$HOSTKEY_TOKEN" \
Positive response
Response:
{
"result":"OK",
"invoice":196727,
"message":"Invoice 196727 created"
}

whmcs/get_invoice

Allows you to retrieve invoice data for payment.

HTTP Method - POST

Parameter Required Type Value/default Description
action * string get_invoice main action - retrieve invoice data for payment
invoice_id * int invoice number
token * string session token

POST-request, cURL

curl -s "https://invapi.hostkey.com/whmcs.php" -X POST \
--data "action=get_invoice" \
--data "token=$HOSTKEY_TOKEN" \
--data "invoice_id={invoice ID}" \
Positive response
{
    "result": "success",
    "invoiceid": 23455,
    "invoicenum": "",
    "userid": 3172,
    "date": "2023-12-25",
    "duedate": "2023-12-25",
    "datepaid": "0000-00-00 00:00:00",
    "lastcaptureattempt": "0000-00-00 00:00:00",
    "subtotal": "800.00",
    "credit": "0.00",
    "tax": "0.00",
    "tax2": "0.00",
    "total": "800.00",
    "balance": "8.00",
    "taxrate": "0.00",
    "taxrate2": "0.00",
    "status": "Unpaid",
    "paymentmethod": "paypal",
    "notes": "",
    "ccgateway": false,
    "items": {
        "item": [
            {
                "id": 25727,
                "type": "Invoice",
                "relid": 23449,
                "description": "Invoice #23449",
                "amount": "3.00",
                "taxed": 0,
                "inv_id": -1
            },
            {
                "id": 25731,
                "type": "Invoice",
                "relid": 23451,
                "description": "Invoice #23451",
                "amount": "5.00",
                "taxed": 0,
                "inv_id": -1
            }
        ]
    },
    "transactions": ""
}
Failure response
{
    "result": -1,
    "error": "whmcs/get_invoice: invalid invoice id 23457 at whmcs_com"
}

whmcs/get_invoices

Allows you to retrieve a complete list of invoices for payment.

HTTP Method - POST

Parameter Required Type Value/default Description
action * string get_invoices main action - retrieve a complete list of invoices for payment
token * string session token

POST-request, cURL

curl -s "https://invapi.hostkey.com/whmcs.php" -X POST \
--data "action=get_invoices" \
--data "token=$HOSTKEY_TOKEN" \
Positive response
{
    "result": "success",
    "totalresults": 6,
    "numreturned": 5,
    "invoices": {
        "invoice": [
            {
                "id": 23455,
                "userid": 3172,
                "firstname": "John",
                "lastname": "Hostkey",
                "companyname": "",
                "invoicenum": "",
                "date": "2023-12-25",
                "duedate": "2023-12-25",
                "datepaid": "0000-00-00 00:00:00",
                "last_capture_attempt": "0000-00-00 00:00:00",
                "date_refunded": "0000-00-00 00:00:00",
                "date_cancelled": "0000-00-00 00:00:00",
                "subtotal": "8.00",
                "credit": "0.00",
                "tax": "0.00",
                "tax2": "0.00",
                "total": "8.00",
                "taxrate": "0.00",
                "taxrate2": "0.00",
                "status": "Unpaid",
                "paymentmethod": "paypal",
                "paymethodid": null,
                "notes": "",
                "created_at": "2023-12-25 12:01:27",
                "updated_at": "2023-12-25 12:01:27",
                "currencycode": "EUR",
                "currencyprefix": "",
                "currencysuffix": "EUR"
            },
            {
                "id": 23451,
                "userid": 3172,
                "firstname": "John",
                "lastname": "Hostkey",
                "companyname": "",
                "invoicenum": "",
                "date": "2023-12-25",
                "duedate": "2024-01-14",
                "datepaid": "0000-00-00 00:00:00",
                "last_capture_attempt": "0000-00-00 00:00:00",
                "date_refunded": "0000-00-00 00:00:00",
                "date_cancelled": "0000-00-00 00:00:00",
                "subtotal": "5.00",
                "credit": "0.00",
                "tax": "0.00",
                "tax2": "0.00",
                "total": "5.00",
                "taxrate": "0.00",
                "taxrate2": "0.00",
                "status": "Unpaid",
                "paymentmethod": "paypal",
                "paymethodid": null,
                "notes": "",
                "created_at": "2023-12-25 11:20:31",
                "updated_at": "2023-12-25 11:20:31",
                "currencycode": "EUR",
                "currencyprefix": "",
                "currencysuffix": "EUR"
            },
            {
                "id": 23449,
                "userid": 3172,
                "firstname": "John",
                "lastname": "Hostkey",
                "companyname": "",
                "invoicenum": "",
                "date": "2023-12-25",
                "duedate": "2024-01-09",
                "datepaid": "2023-12-25 13:08:58",
                "last_capture_attempt": "0000-00-00 00:00:00",
                "date_refunded": "0000-00-00 00:00:00",
                "date_cancelled": "0000-00-00 00:00:00",
                "subtotal": "3.00",
                "credit": "3.00",
                "tax": "0.00",
                "tax2": "0.00",
                "total": "0.00",
                "taxrate": "0.00",
                "taxrate2": "0.00",
                "status": "Paid",
                "paymentmethod": "paypal",
                "paymethodid": null,
                "notes": "",
                "created_at": "2023-12-25 11:15:14",
                "updated_at": "2023-12-25 13:08:58",
                "currencycode": "EUR",
                "currencyprefix": "",
                "currencysuffix": "EUR"
            },
            {
                "id": 18580,
                "userid": 3172,
                "firstname": "John",
                "lastname": "Hostkey",
                "companyname": "",
                "invoicenum": "",
                "date": "2023-12-14",
                "duedate": "2023-12-29",
                "datepaid": "2023-12-14 05:54:52",
                "last_capture_attempt": "0000-00-00 00:00:00",
                "date_refunded": "0000-00-00 00:00:00",
                "date_cancelled": "0000-00-00 00:00:00",
                "subtotal": "5.00",
                "credit": "5.00",
                "tax": "0.00",
                "tax2": "0.00",
                "total": "0.00",
                "taxrate": "0.00",
                "taxrate2": "0.00",
                "status": "Paid",
                "paymentmethod": "paypal",
                "paymethodid": null,
                "notes": "",
                "created_at": "2023-12-14 05:54:31",
                "updated_at": "2023-12-14 05:54:52",
                "currencycode": "EUR",
                "currencyprefix": "",
                "currencysuffix": "EUR"
            },
            {
                "id": 10116,
                "userid": 3172,
                "firstname": "John",
                "lastname": "Hostkey",
                "companyname": "",
                "invoicenum": "",
                "date": "2023-11-09",
                "duedate": "2023-11-24",
                "datepaid": "2023-11-09 13:13:37",
                "last_capture_attempt": "0000-00-00 00:00:00",
                "date_refunded": "0000-00-00 00:00:00",
                "date_cancelled": "0000-00-00 00:00:00",
                "subtotal": "2.5.00",
                "credit": "2.5.00",
                "tax": "0.00",
                "tax2": "0.00",
                "total": "0.00",
                "taxrate": "0.00",
                "taxrate2": "0.00",
                "status": "Paid",
                "paymentmethod": "paypal",
                "paymethodid": null,
                "notes": "",
                "created_at": "2023-11-09 12:48:29",
                "updated_at": "2023-11-09 13:13:37",
                "currencycode": "EUR",
                "currencyprefix": "",
                "currencysuffix": "EUR"
            }
        ]
    }
}
Failure response
{
    "result": -2,
    "error": "whmcs/get_invoices: invalid token, logout"
}

whmcs/request_cancellation

Allows you to request a cancellation of the service.

HTTP Method - POST

Parameter Required Type Value/default Description
action * string request_cancellation main action - request a cancellation of the service
id * int server ID
cancellation_type * int 1 - immediate cancellation with partial refund (if possible), 0 - cancellation at the end of the current billing period.
terminate_reason_custom string reason for cancellation
token * string session token

POST-request, cURL

curl -s "https://invapi.hostkey.com/whmcs.php" -X POST \
--data "action=request_cancellation" \
--data "id={Server ID} \
--data "cancelation_type={1 or 0}" \
--data "terminate_reason_custom={reason for cancellation}" \
--data "token=$HOSTKEY_TOKEN" \
Positive response
{
    "result": "OK",
    "action": "request_cancellation",
    "callback": "b36a18f95ce4ac52d5ee18aaf25940cc"
}
Failure response
{
    "result": -1,
    "error": "whmcs/request_cancellation: permission denied #3, this is not your server"
}

whmcs/delete_cancellation_request

Allows you to cancel a request to service cancellation.

HTTP Method - POST

Parameter Required Type Value/default Description
action * string delete_cancellation_request main action - delete a request to service cancellation
id * int server ID
token * string session token

POST-request, cURL

curl -s "https://invapi.hostkey.com/whmcs.php" -X POST \
--data "action=delete_cancellation_request" \
--data "id={Server ID} \
--data "token=$HOSTKEY_TOKEN" \
Positive response
{
    "result": "success",
    "message": [
        "CR deleted",
        "Invoice 23451 reactivated"
    ]
}
Failure response
{
    "result": -1,
    "error": "whmcs/request_cancellation: permission denied #3, this is not your server"
}

whmcs/get_cancellation_requests

Allows you to get an active list of service cancellation requests.

HTTP Method - POST

Parameter Required Type Value/default Description
action * string get_cancellation_requests main action - get an active list of service cancellation requests
id int server ID
token * string session token

POST-request, cURL

curl -s "https://invapi.hostkey.com/whmcs.php" -X POST \
--data "action=get_cancellation_requests" \
--data "id={Server ID} \
--data "token=$HOSTKEY_TOKEN" \
Positive response
{
    "result": "success",
    "message": [
        {
            "id": 507,
            "date": "2023-12-25 13:44:22",
            "relid": 5724,
            "reason": "Not needing for me",
            "type": "End of Billing Period",
            "created_at": "0000-00-00 00:00:00",
            "updated_at": "0000-00-00 00:00:00"
        }
    ]
}
Failure response
{
    "result": -1,
    "error": "whmcs/request_cancellation: permission denied #3, this is not your server"
}

Instant servers

Standard configurations for instant servers include compute (VMs), physical servers, physical servers with GPUs, and vGPU servers (VMs with PCIe-passthrough GPUs). These configurations are pre-built and deployed automatically within 10-20 minutes.

You may order instant servers via this API. All payments for instant servers go from the billing's credit account. You should have the necessary funds on account to place an order.

Resource Action Description
presets.php list get a list of available instances for a region
os.php list get OS list for a specific instance
traffic_plans.php list get appropriate traffic plans for specific instance
eq.php order_instance order a specific instance. The order will be fulfilled upon payment of the invoice or from the credit balance.

The following abbreviations can be used in the response in the name of the instances:

  • BM - bare-metal server;
  • VM - virtual instance (VM);
  • Compute - instance belongs to compute group. Compute group is general use KVM-based virtual servers (VPS);
  • Gpu - GPU server;
  • Vgpu - vGPU server.

presets/list

Allows you to get an up-to-date list of available instances with rental fees. Session token not required.

Information

Currently available instances in Netherlands (ND), USA (US), Finland (FI), Germany (DE), Iceland (IS) and Turkey (TR).

HTTP method - POST

Parameter Required Type Value/default Description
action * string list main action — get a list of available instances for a region
location * string instances location - NL/US/FI/DE/IS/TR (Netherlands, USA, Finland, Germany, Iceland, Turkey)

POST-request, cURL

curl -s "https://invapi.hostkey.com/presets.php" -X POST \
--data "action=list" \
--data "location={Two-letter area code}"
Positive response
{
    "result": "OK",
    "action": "list",
    "presets": [
        {
            "id": 108, // instance ID
            "name": "vm.pico", // instance name
            "active": 1, // active instance
            "monthly_com": 3, // price in EUR without local VAT. For EU customers without VAT ID appropriate local VAT needs to be added.
            "description": "VM instance 1/1/15 SSD", // Description
            "cpu": 1, // CPU cores
            "ram": 1, // RAM amount in Gb
            "hdd": "15", // storage size in Gb
            "gpu": "", // GPU installed, if any
            "locations": "NL,US,FI,DE,IS,TR", // available in locations.
            "virtual": 1, // an indication that the instance is a virtualized instance (VM)
            "price": { // price depends on location
                "NL": {
                    "USD": -1,
                    "EUR": 3,
                },
                "US": {
                    "USD": -1,
                    "EUR": 3,
                },
                "FI": {
                    "USD": -1,
                    "EUR": 3,
                },
                "DE": {
                    "USD": -1,
                    "EUR": 3,
                },
                "IS": {
                    "USD": -1,
                    "EUR": 3,
                },
                "TR": {
                    "USD": -1,
                    "EUR": 3,
                }
            },
            "available": 184, // amount available immediately to order
            "server_type": "Virtual Private Server",
            "tags": [ // set of tags to specify proper UI
                {
                    "id": 312305, // Server ID
                    "component": "presets",
                    "component_id": 108,
                    "tag": "stock",
                    "value": "10",
                    "extra": "",
                    "internal": 0
                },
                {
                    "id": 312306,
                    "component": "presets",
                    "component_id": 108,
                    "tag": "web_group",
                    "value": "General",
                    "extra": "vm",
                    "internal": 0
                },
                {
                    "id": 312307,
                    "component": "presets",
                    "component_id": 108,
                    "tag": "pid_fi",
                    "value": "3216",
                    "extra": "",
                    "internal": 0
                },
                {
                    "id": 346027,
                    "component": "presets",
                    "component_id": 108,
                    "tag": "web_hdd",
                    "value": "SSD",
                    "extra": "",
                    "internal": 0
                },
                {
                    "id": 346292,
                    "component": "presets",
                    "component_id": 108,
                    "tag": "web_storage",
                    "value": "true",
                    "extra": "15GB SSD",
                    "internal": 0
                },
                {
                    "id": 438294,
                    "component": "presets",
                    "component_id": 108,
                    "tag": "pid_de",
                    "value": "3219",
                    "extra": "",
                    "internal": 0
                },
                {
                    "id": 481712,
                    "component": "presets",
                    "component_id": 108,
                    "tag": "web_geekbench_score_max",
                    "value": "11121",
                    "extra": "",
                    "internal": 0
                },
                {
                    "id": 559071,
                    "component": "presets",
                    "component_id": 108,
                    "tag": "pre_order",
                    "value": "true",
                    "extra": "TR",
                    "internal": 0
                },
                {
                    "id": 736612,
                    "component": "presets",
                    "component_id": 108,
                    "tag": "no_increase",
                    "value": "",
                    "extra": "",
                    "internal": 0
                },
                {
                    "id": 312308,
                    "component": "presets",
                    "component_id": 108,
                    "tag": "vm",
                    "value": "true",
                    "extra": "",
                    "internal": 1
                },
                {
                    "id": 312309,
                    "component": "presets",
                    "component_id": 108,
                    "tag": "compute",
                    "value": "1",
                    "extra": "",
                    "internal": 1
                },
                {
                    "id": 312311,
                    "component": "presets",
                    "component_id": 108,
                    "tag": "web_ghz",
                    "value": "2.6",
                    "extra": "",
                    "internal": 1
                },
                {
                    "id": 312312,
                    "component": "presets",
                    "component_id": 108,
                    "tag": "web_addinfo",
                    "value": "true",
                    "extra": "param1=Delivery ETA: from 2-5 minutes param2=Upgrade: No",
                    "internal": 1
                },
                {
                    "id": 312315,
                    "component": "presets",
                    "component_id": 108,
                    "tag": "pid_nl",
                    "value": "3201",
                    "extra": "",
                    "internal": 1
                },
                {
                    "id": 312316,
                    "component": "presets",
                    "component_id": 108,
                    "tag": "pid_us",
                    "value": "3203",
                    "extra": "",
                    "internal": 1
                },
                {
                    "id": 458740,
                    "component": "presets",
                    "component_id": 108,
                    "tag": "web_geekbench_score",
                    "value": "492",
                    "extra": "Performance",
                    "internal": 1
                },
                {
                    "id": 567279,
                    "component": "presets",
                    "component_id": 108,
                    "tag": "web_label",
                    "value": "true",
                    "extra": "[{ &quot;name&quot;: &quot;SSD + Xeon E5-26xx&quot;,&quot;color&quot;: &quot;#E23329&quot;,&quot;number&quot;: 2}]",
                    "internal": 1
                },
                {
                    "id": 580969,
                    "component": "presets",
                    "component_id": 108,
                    "tag": "pid_is",
                    "value": "3221",
                    "extra": "",
                    "internal": 1
                },
                {
                    "id": 581092,
                    "component": "presets",
                    "component_id": 108,
                    "tag": "pid_tr",
                    "value": "3223",
                    "extra": "",
                    "internal": 1
                }
            ]
        } ... , {
            "id": 15,
            "name": "bm.v1-mini",
            "active": 1,
            "monthly_com": 35,
            "description": "BM i3\/8\/240", //  bare-metal server with dual-core i3 processor
            "cpu": 2,
            "ram": 8,
            "hdd": 240,
            "gpu": "",
            "locations": "NL",
            "virtual": 0,
            "tags": [
                {
                    "id": 7130,
                    "tag": "bm", // bare-metal server
                    "value": "true",
                    "extra": "",
                    "internal": 1
                }],
            "available": 3
        }, ... , {
            "id": 8,
            "name": "vgpu.v1-mini",
            "active": 1,
            "monthly_com": 157,
            "description": "vGPU 4\/16\/240 + 1080",
            "cpu": 4,
            "ram": 16,
            "hdd": 240,
            "gpu": "1xGTX1080", // this server is equipped with a GTX 1080 GPU.
            "locations": "NL",
            "virtual": 1,
            "tags": [
                {
                    "id": 7118,
                    "tag": "gpu", // it's a GPU server
                    "value": "1",
                    "extra": "",
                    "internal": 1
                }, 
                {
                    "id": 11428,
                    "tag": "vgpu",  // it's a vGPU server
                    "value": "true",
                    "extra": "",
                    "internal": 1
                }
            ],
            "available": 1
        } ... ]
}

Note

Operating system information and a list of post-installation tasks are required for ordering.

os/list

Returns a list of suitable operating systems for a given instance. All Windows license prices are already calculated. Without specifying an instance id, the call returns available operating systems for all available instances. Session token is not required.

Note

Please note that all prices are only for the purpose of creating a proper user interface. They will be recalculated in the backend at the time of ordering.

HTTP method - POST

Parameter Required Type Value/default Description
action * string list main action — get OS list for a specific instance
instance_id int instance ID (which can be obtained using the presets/list call)

POST-request, cURL

curl -s "https://invapi.hostkey.com/os.php" -X POST \
--data "action=list" \
--data "instance_id={Instance ID}"
Positive response
{
    "result": "OK",
    "action": "list",
    "os_list": [
        {
        "id": 183, // Operation system ID
        "name": "RockyLinux 8",
        "api_enabled": 0,
        "type_login": 1,
        "pxe_os_id": null,
        "active": 1,
        "description": "",
        "tags": [
                {
                    "id": 78797,
                    "tag": "bm",
                    "value": "true",
                    "extra": "",
                    "component_id": 183,
                    "component": "OS",
                    "internal": 0
                },
                {
                    "id": 78798,
                    "tag": "gpu",
                    "value": "true",
                    "extra": "",
                    "component_id": 183,
                    "component": "OS",
                    "internal": 0
                },
                {
                    "id": 78799,
                    "tag": "vgpu",
                    "value": "true",
                    "extra": "",
                    "component_id": 183,
                    "component": "OS",
                    "internal": 0
                },
                {
                    "id": 78800,
                    "tag": "vm",
                    "value": "true",
                    "extra": "",
                    "component_id": 183,
                    "component": "OS",
                    "internal": 0
                },
                {
                    "id": 264231,
                    "tag": "family",
                    "value": "RockyLinux",
                    "extra": "50",
                    "component_id": 183,
                    "component": "OS",
                    "internal": 0
                },
                {
                    "id": 627236,
                    "tag": "vds",
                    "value": "",
                    "extra": "",
                    "component_id": 183,
                    "component": "OS",
                    "internal": 0
                }

        ]
    },  {
        "id": 202,
        "name": "Windows Server 2022 VM",
        "api_enabled": 0,
        "type_login": 1,
        "pxe_os_id": null,
        "active": 0,
        "description": "WS22 DC for VMs",
        "tags": [
                {
                    "id": 241628,
                    "tag": "vm",
                    "value": "true",
                    "extra": "",
                    "component_id": 202,
                    "component": "OS",
                    "internal": 0
                },
                {
                    "id": 241630,
                    "tag": "min_ram", // minimum RAM requirements
                    "value": "4", // 4 Gb
                    "extra": "",
                    "component_id": 202,
                    "component": "OS",
                    "internal": 0
                },
                {
                    "id": 241631,
                    "tag": "min_hdd", // minimum disk space requirements
                    "value": "32", // 32 Gb
                    "extra": "",
                    "component_id": 202,
                    "component": "OS",
                    "internal": 0
                },
                {
                    "id": 241632,
                    "tag": "price_per_core_EUR", // MS license fee for the SPLA product in Euro per core
                    "value": "2",
                    "extra": "",
                    "component_id": 202,
                    "component": "OS",
                    "internal": 0
                },
                {
                    "id": 241634,
                    "tag": "user_name",
                    "value": "Administrator",
                    "extra": "",
                    "component_id": 202,
                    "component": "OS",
                    "internal": 0
                },
                {
                    "id": 264276,
                    "tag": "family",
                    "value": "Windows Server",
                    "extra": "70",
                    "component_id": 202,
                    "component": "OS",
                    "internal": 0
                },
                {
                    "id": 264320,
                    "tag": "short_name",
                    "value": "WS 2022 for VPS",
                    "extra": "",
                    "component_id": 202,
                    "component": "OS",
                    "internal": 0
                }
            ],
            "price_EUR": 2,
            "billing_plan": {
                "EUR": {
                    "1": 2, // the estimated cost of this license in Euro (excluding VAT) depending on the number of cores.
                    "3": 6,
                    "6": 12,
                    "12": 24
                },
            },
            "price_EUR": 2
        }
        ]
}

software/list

Returns a list of available software to install on the server.

Without specifying an instance ID the call will return the available software to install for all available instances. No session token is required.

HTTP method - POST

Parameter Required Type Value/default Description
action * string list main action - get a list of software available for installation on a given instance.
location string instances location - NL/US/FI/DE/IS/TR (Netherlands, USA, Finland, Germany, Iceland, Turkey)
instance_id int instance ID (which can be obtained using the presets/list call)

POST-request, cURL

curl -s "https://invapi.hostkey.com/software.php" -X POST \
--data "action=list" \
--data "location={Two-letter area code}" \
--data "instance_id={instance ID}"
Positive response
{
    "result": "OK",
    "action": "list",
    "software": [
        {
            "id": 26, // software id
            "name": "3X-UI + Shadowsocks/Xray/V2ray VPN server",
            "description": "3X-UI provides a graphical user interface for managing a private VPN server with Shadowsocks, V2ray, Xray, Trojan and other popular protocols.",
            "price": 0,
            "active": 1,
            "icon": "",
            "task": "invapi_external_3x_vpn_ui_install.dsl",
            "tags": [
                {
                    "id": 325472,
                    "tag": "vm",
                    "value": "1",
                    "extra": "",
                    "component_id": 26,
                    "component": "software",
                    "internal": 1
                },
                {
                    "id": 325473,
                    "tag": "bm",
                    "value": "1",
                    "extra": "",
                    "component_id": 26,
                    "component": "software",
                    "internal": 1
                },
                {
                    "id": 325474,
                    "tag": "group",
                    "value": "VPN servers",
                    "extra": "",
                    "component_id": 26,
                    "component": "software",
                    "internal": 0
                },
                {
                    "id": 325475,
                    "tag": "task",
                    "value": "invapi_external_3x_vpn_ui_install.dsl",
                    "extra": "",
                    "component_id": 26,
                    "component": "software",
                    "internal": 1
                },
                {
                    "id": 325476,
                    "tag": "family",
                    "value": "VPN servers",
                    "extra": "120",
                    "component_id": 26,
                    "component": "software",
                    "internal": 0
                },
                {
                    "id": 345944,
                    "tag": "description_en",
                    "value": "",
                    "extra": "Various web-panels and software for a private VPN servers",
                    "component_id": 26,
                    "component": "software",
                    "internal": 0
                },
                {
                    "id": 351007,
                    "tag": "vgpu",
                    "value": "1",
                    "extra": "",
                    "component_id": 26,
                    "component": "software",
                    "internal": 1
                },
                {
                    "id": 353230,
                    "tag": "gpu",
                    "value": "1",
                    "extra": "",
                    "component_id": 26,
                    "component": "software",
                    "internal": 1
                },
                {
                    "id": 356028,
                    "tag": "os",
                    "value": [
                        "160",
                        "183",
                        "184",
                        "157",
                        "180",
                        "144",
                        "187",
                        "193"
                    ],
                    "extra": "U20.4, U22.4, RL8, AL8, D10, D11",
                    "component_id": 26,
                    "component": "software",
                    "internal": 0
                },
                {
                    "id": 538578,
                    "tag": "min_cpu",
                    "value": "1",
                    "extra": "",
                    "component_id": 26,
                    "component": "software",
                    "internal": 0
                },
                {
                    "id": 538579,
                    "tag": "min_ram",
                    "value": "1",
                    "extra": "",
                    "component_id": 26,
                    "component": "software",
                    "internal": 0
                },
                {
                    "id": 611129,
                    "tag": "family_desc_en",
                    "value": "",
                    "extra": "A VPN server is a type of server that enables the hosting and delivery of VPN services. It is a combination of hardware and software technologies that provide a secure connection. Get your ready-to-go VPN server in 15 minutes.",
                    "component_id": 26,
                    "component": "software",
                    "internal": 0
                },
                {
                    "id": 1142361,
                    "tag": "timeout",
                    "value": "600",
                    "extra": "",
                    "component_id": 26,
                    "component": "software",
                    "internal": 1
                }
            ]
        },
...
        {
            "id": 65,
            "name": "Minecraft: Java Edition Server",
            "description": "Minecraft: Java Edition Server is a player-owned or business-owned multiplayer game server software.",
            "price": 0,
            "active": 1,
            "icon": "",
            "task": "invapi_external_minecraft_server_install.dsl",
            "tags": [
                {
                    "id": 856009,
                    "tag": "vm",
                    "value": "1",
                    "extra": "",
                    "component_id": 65,
                    "component": "software",
                    "internal": 1
                },
                {
                    "id": 856011,
                    "tag": "bm",
                    "value": "1",
                    "extra": "",
                    "component_id": 65,
                    "component": "software",
                    "internal": 1
                },
                {
                    "id": 856013,
                    "tag": "vgpu",
                    "value": "1",
                    "extra": "",
                    "component_id": 65,
                    "component": "software",
                    "internal": 1
                },
                {
                    "id": 856016,
                    "tag": "min_cpu",
                    "value": "1",
                    "extra": "",
                    "component_id": 65,
                    "component": "software",
                    "internal": 0
                },
                {
                    "id": 856020,
                    "tag": "min_ram",
                    "value": "1",
                    "extra": "",
                    "component_id": 65,
                    "component": "software",
                    "internal": 0
                },
                {
                    "id": 856023,
                    "tag": "os",
                    "value": [
                        "180",
                        "219",
                        "219",
                        "160",
                        "187",
                        "217"
                    ],
                    "extra": "D11,12 U20,22,23",
                    "component_id": 65,
                    "component": "software",
                    "internal": 1
                },
                {
                    "id": 856063,
                    "tag": "tasks",
                    "value": "invapi_external_minecraft_server_install.dsl",
                    "extra": "",
                    "component_id": 65,
                    "component": "software",
                    "internal": 0
                },
                {
                    "id": 856073,
                    "tag": "docs_en",
                    "value": "",
                    "extra": "https://url.hostkey.com/Minecraft",
                    "component_id": 65,
                    "component": "software",
                    "internal": 0
                },
                {
                    "id": 856076,
                    "tag": "group",
                    "value": "Games",
                    "extra": "",
                    "component_id": 65,
                    "component": "software",
                    "internal": 0
                },
                {
                    "id": 856081,
                    "tag": "family",
                    "value": "Games",
                    "extra": "31",
                    "component_id": 65,
                    "component": "software",
                    "internal": 0
                },
                {
                    "id": 856089,
                    "tag": "family_desc_en",
                    "value": "",
                    "extra": "Game servers are your gateway to hosting and managing online gaming experiences. From multiplayer setups to collaborative gameplay, this category offers server solutions optimized for seamless, high-performance gaming environments. With HOSTKEY you can build your own gaming infrastructure in a few clicks ordering servers with pre-installed games.",
                    "component_id": 65,
                    "component": "software",
                    "internal": 0
                }
            ]
        }
    ]
}

traffic_plans/list

Allows you to get a network traffic map for a specific instance in a specific location. Does not require a session token.

HTTP method - POST

Parameter Required Type Value/default Description
action * string list main action — get appropriate traffic plans for specific instance
location * string instances location - NL/US/FI/DE/IS/TR (Netherlands, USA, Finland, Germany, Iceland, Turkey)
instance_id int instance ID (which can be obtained using the presets/list call)

POST-request, cURL

curl -s "https://invapi.hostkey.com/traffic_plans.php" -X POST \
--data "action=list" \
--data "location={Two-letter area code}" \
--data "instance={Instance ID}" \
Positive response
{
    "result": "OK",
    "action": "list",
    "traffic_plans": [
        {
            "id": 25, // traffic plan ID
            "name": "3Tb traffic (1Gbps) VM", // traffic plan name
            "limit_in": 999, // Incoming limit, Tb
            "limit_out": 3, // Outgoing limit, Tb
            "rate_in": 0, // cost of excessive incoming traffic in Euros/Tb
            "rate_out": 2, // cost of excessive outbound traffic in Euros/Tb
            "bandwidth": 1000, // bandwidth limitation (Mbps)
            "locations": "NL,US,FI,DE,IS,TR,", // server region
            "currency_id": 0, // this plan for Euro, currency id = 0
            "active": 1,
            "web_plan": 0,
            "price": 0, // flat rate, free of charge
            "main_plan": 37,
            "tags": [
                {
                    "id": 11449,
                    "component": "traffic_plans",
                    "component_id": 25,
                    "tag": "vm",
                    "value": "true",
                    "extra": "",
                    "internal": 1
                }
            ]
        },
        {
            "id": 37,
            "name": "3Tb traffic (1Gbps) VM",
            "limit_in": 999,
            "limit_out": 3,
            "rate_in": 0,
            "rate_out": 180,
            "bandwidth": 1000,
            "locations": "NL,US,FI,DE,IS,TR,",
            "currency_id": 0
            "active": 1,
            "web_plan": 0,
            "price": 0,
            "main_plan": 25,
            "tags": [
                {
                    "id": 11471,
                    "component": "traffic_plans",
                    "component_id": 37,
                    "tag": "vm",
                    "value": "true",
                    "extra": "",
                    "internal": 1
                }
            ]
        }
    ]
}
Failure response
{
    "result": -1,
    "error": "traffic_plans/list: error while looking for traffic plans"
}

eq/order_instance

Allows you to order instant or stock servers (instances) with specified parameters, operating system and software defaults.

HTTP method - POST

Parameter Required Type Value/default Description
action * string list main action — order an instance with specified parameters
token * string session token
deploy_period * string month, quarter, 6 months, year (monthly, quarterly, semi-annually, annually)
deploy_notify * string email notification upon successful completion of deployment true/false
pin * int PIN code
preset * string deployment instance name - name from presets/list
location_name * string server location name - NL/US/FI/DE/IS/TR (Netherlands, USA, Finland, Germany, Iceland, Turkey)
os_id * int OS ID from the list of operating systems from the output os/list
soft_id int Software ID from the output software/list
traffic_plan * string ID of the selected traffic plan traffic_plans/list
root_pass * string default root password. The password must be a minimum of 8 characters long and include both uppercase and lowercase Latin letters, as well as at least one special character
hostname string host name of the deployed instance. Defaults to the instance ID
ssh_key string ssh public key for root user
post_install_callback string URL to be invoked after successful deployment
post_install_script string code to run after successful deployment
os_name string OS name
own_os int if set to 1, the instance will be shipped without without OS installation. This call is useful if you plan to install the operating system later
root_size int is the size of the root partition (/) on the disk in percent. If not specified, it is assumed to be 100
jenkins_task string Jenkins task ID to run after deployment. Valid values: 1 - install GPU driver, 2 - GPU driver plus NVIDIA docker, 3 - driver, docker plus IOMMU patch, -1 - do nothing.

POST-request, cURL

curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=order_instance" \
--data "token=$HOSTKEY_TOKEN" \
--data "deploy_period={monthly,quarterly,semi-annually,annually}" \
--data "deploy_notify=true" \
--data "pin={PIN}" \
--data "preset={instance preset name}" \
--data "location_name={Two-letter area code}"
--data "traffic_plan={Traffic plan ID}" \
--data "os_id={operating system ID}" \
--data "soft_id={software ID}" \
--data "root_pass={root password}" \
--data "hostname={host name}" \
--data "ssh_key={public SSH key}" \
--data "post_install_callback=" \
--data "post_install_script=" \
--data "os_name=" \
--data "own_os=" \
--data "root_size=100" \
--data "jenkins_task={Jenkins Task ID, -1, 1, 2, 3}" \
Positive response
{
    "result": "OK",
    "action": "order_instance",
    "invoice": 24016,
    "status": "Paid"
}

Instant Server Ordering Algorithm with eq/order_instance

  1. Generate a client API key;

  2. Choose the location for server ordering from the following options: NL/US/FI/DE/IS/TR (Netherlands, USA, Finland, Germany, Iceland, and Turkey);

  3. To determine the ID of the preset to deploy, use the presets/list prompt.

    This ID will be used further as instance_id or preset. For example, if "id": 108, the values are instance_id=108 and preset=108;

  4. Using the os/list query, determine the os_id of the operating system to be installed, using the instance ID from step 3. For example, for Ubuntu 22.04, this value will be returned in the query response as "id": 187;

    Note

    To deploy the server without installing an operating system, simply specify the own_os=1 parameter at a later time.

  5. Use the software/list query to determine the deployable software for a given instance and get its ID (hereafter parameter soft_id). For example, for CMS Wodrpress the query output will be "id": 20;

    Note

    If desired, the software can be installed during deployment or at a later time.

  6. Use the [traffic_plans/list] query to get the network traffic plan ID for your server. For example, for a 3Tb traffic (1Gbps) VM plan, the call will return the value "id": 25;

  7. Obtain the session token $HOSTKEY_TOKEN by making a request to auth/login.

  8. To order the server, insert the data obtained in steps 2-7 into the eq/order_instance request. Make sure to specify your PIN code (if you haven't set it yet, do so via the eq/set_pin request), root password, and deploy period (monthly, quarterly, 6 months, or yearly). You can choose to receive deployment notifications by mail by setting deploy_notify to true (recommended).

In the eq/order_instance call, you have the option to specify additional parameters.

Here is an example of how to order a server with Wordpress (id=20) on Debian 11 (id=180):

Example POST request for ordering an instant server, cURL

curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=order_instance" \
--data "token=eeee51003b1d81d2eca65660735c0531" \
--data "deploy_period=monthly" \
--data "deploy_notify=true" \
--data "pin=1907" \
--data "preset=108" \
--data "location_name=NL" \
--data "os_id=180" \
--data "soft_id=20" \
--data "traffic_plan=25" \
--data "root_pass=mdLus8Ng" \
Positive response
{
    "result": "OK",
    "action": "order_instance",
    "invoice": 50062,
    "status": "Paid"
}

Upon receiving the request, INVAPI will select/create the appropriate server at a specific location and proceed with its deployment. Prior to any installation, a credit check will be performed (if autopayments from credit is set) or a payment invoice will be issued. If the installation is successful, the new server will be associated with the customer's account. The customer will be notified by email if requested. All paid licenses will be added to the order as add-ons.

Note

Incompatible operating systems and software will result in an error message similar to this:

{
"result": -1,
"error": "reinstall: extra software Odoo (#49) is not compatible with Ubuntu 22.04"
}

To select a different operating system, set a different os_id parameter.

Attention

You may begin using the server once you receive notification of its deployment completion via email or when the server's status changes to Active in the My Servers section of the Invapi control panel . If there is a failure during the server deployment process, you will be notified via email. Please note that deployment may take 20 minutes or longer.

To track the deployment and its status, use asynchronous actions. You can obtain the deploy key by executing the eq/update_servers call.

The installation will be considered successful once you receive an asynchronous action message like this:

Positive response
{
"result": "OK",
"scope": "Autodeploy completed, check VRI-208-64405",
"context": {
    "action": "deploy_vm",
    "id": "32645",
    "location": "NL",
    "ip": "176.222.34.23",
    "ip_ipmi": "0.0.0.0"
},
"debug": "0",
"key": "9889fcb51255146e04224205c04976e8"
}

Reinstall server using eq/order_instance.

To reinstall the server, follow the same steps as for ordering, but include the additional parameter id - the ID of the server to be reinstalled from Invapi - and omit some of the other parameters in eq/order_instance call. You have the option to select a different operating system and pre-installed software, or perform a "clean slate" reinstallation by setting the own_os=1 parameter.

HTTP method - POST

Parameter Required Type Value/default Description
action * string list main action — order an instance with specified parameters
token * string session token
pin * int PIN code
hostname string host name of the deployed instance. Defaults to the instance ID
os_id * int OS ID from the list of operating systems from the output os/list
soft_id int Software ID from the output software/list
root_pass * string default root password. The password must be a minimum of 8 characters long and include both uppercase and lowercase Latin letters, as well as at least one special character
ssh_key string ssh public key for root user
post_install_script string code to run after successful deployment
own_os int if set to 1, the instance will be shipped without without OS installation. This call is useful if you plan to install the operating system later
root_size int is the size of the root partition (/) on the disk in percent. If not specified, it is assumed to be 100
id * int reinstall server ID

Reinstallation POST request, cURL

curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=order_instance" \
--data "token=$HOSTKEY_TOKEN" \
--data "pin={PIN}" \
--data "hostname={host name}" \
--data "os_id={operating system ID}" \
--data "soft_id={software ID}" \
--data "root_pass={root password}" \
--data "ssh_key={public SSH key}" \
--data "post_install_script=" \
--data "os_name=" \
--data "own_os=" \
--data "root_size=100" \
--data "id={Server ID from Invapi}" // Having an ID will initiate the server reinstallation process.

Attention

If you receive a message stating that no server with that ID was found when requesting reinstallation, update the list of servers associated with the session token by executing the eq/update_servers query.

Note

Incompatible operating systems and software will result in an error message similar to this:

{
"result": -1,
"error": "reinstall: extra software Odoo (#49) is not compatible with Ubuntu 22.04"
}

To select a different operating system, set a different os_id parameter.

Attention

Do not begin a new reinstallation until the previous one is complete, or you will receive a warning:

{"result":-1,"error":"another reinstall in progress for XXXXX, please wait"}

To move our server from its current operating system to Rocky Linux 9 (id=205) and Grafana (id=18), please follow these steps:

Example POST request for reinstallation, cURL

curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=order_instance" \
--data "token=5e731472b19f25c7fe61c9eb5c2ea4e3" \
--data "deploy_notify=true" \
--data "pin=1907" \
--data "os_id=205" \
--data "soft_id=18" \
--data "root_pass=mnN48Dl@4" \
--data "id=32645"
Positive response
{
    "result": "OK",
    "action": "order_instance",
    "callback": "e2fbe5f43796d4139983b695271da9aa", // asynchronous key
    "deploy_status": "reinstall",
    "id": 32645,
    "os_name": "RockyLinux 9",
    "soft_name": "Grafana"
}

Attention

No notification of successful reinstallation will be sent to your email when using this method. Please remember and save the new root password or use the old server password. Information about accessing the ordered software can be found in the Marketplace documentation or directly in the server card of the Invapi control panel.

By utilizing the asynchronous key (callback field), we can monitor the reinstallation process through asynchronous actions.

Example of a successful reinstallation response
{
    "result": "OK",
    "scope": "{\"result\":\"deploy_done\"}",
    "context": {
        "action": "reinstall_vm",
        "id": "32645",
        "location": "NL",
        "ip": "176.222.34.23",
        "ip_ipmi": "0.0.0.0",
        "reinstall": 1
    },
    "debug": "",
    "key": "a129bad13781bdf5790746064aba0af6"
}

Stock servers

Stock servers are physical servers with standard configurations that are deployed within one business day, unless otherwise specified.

Stock servers can be ordered through the API.

All payments for stock servers are made from the billing account. To place an order, the required amount must be in the account.

Resource Action Description
stocks.php list get a list of available servers
stocks.php show get detailed information for a single server
eq.php order_instance create an order for stock server deployment in the billing, that will be fulfilled once the invoice is paid

stocks/list

This action will let you retrieve a fresh list of available stock servers with configuration and basic pricing. No access token is required

HTTP method - POST

Parameter Required Type Value/default Description
action * string list main action - get a list of available servers
location * string 'NL','US','FI','DE','IS','TR' server location
group * string 'ALL', '1CPU', '2CPU', 'GPU', 'AMD', 'AMD-MODERN', 'INTEL' server group
  • Currently available instances in Netherlands (ND), USA (US), Finland (FI), Germany (DE), Iceland (IS) and Turkey (TR).
  • Servers are categorized into the following groups: ALL - all servers, 1CPU - single-processor servers, 2CPU - dual-processor servers, GPU - GPU-based servers, AMD - servers with AMD processors, AMD-MODERN - servers with modern AMD Ryzen processors, INTEL - servers with AMD processors. GPU servers are excluded from other groups.
  • Server performance score is shown for its CPU, not GPU.

POST-request, cURL

curl -s "https://invapi.hostkey.com/stocks.php" -X POST \
    --data "action=list" \
    --data "location={Two-letter area code}" \
    --data "group={Server group}"
Positive response
{
    "result": "OK",
    "action": "list",
    "servers": [
        {
            "id": 40514,
            "name": "40514",
            "hardware": {
                "config": "AMD Ryzen 9 5950X 3.4GHz (16 cores)/​128Gb/​1Tb NVMe SSD/​PSU",
                "motherboard_name": "ASRock X570D4U",
                "cpu_name": "AMD Ryzen 9 5950X 3.4GHz (16 cores)",
                "cpu_type": "AMD-MODERN",
                "cpu_count": 1,
                "cpu_cores": 16,
                "cpu_frq": "3.4",
                "ram": 128,
                "ram_type": "ddr4ecc",
                "hdd_count": 1,
                "hdd_groups": [
                    {
                        "name": "1Tb NVMe SSD",
                        "type": "HDD",
                        "count": 1,
                        "size": "1024"
                    }
                ],
                "hdd_pairs": 0,
                "gpu_name": null,
                "gpu_count": 0,
                "raid_levels": [
                    "LVM_HBA"
                ]
            },
            "location": "FI",
            "cpu_count": "1",
            "cpu_perf": 46719,
            "cpu_perflink": "http://www.cpubenchmark.net/cpu_lookup.php?cpu=AMD+Ryzen+9+5950X&id=3862",
            "tags": {
                "ipmi": {
                    "tag": "ipmi",
                    "value": "ami_bmc",
                    "extra": ""
                }
            },
            "deployment_estimate": "auto",
            "billing_plan": {
                "EUR": {
                    "1": 115,
                    "3": 334.65,
                    "6": 648.6,
                    "12": 1214.4
                },
            },
            "server_group": "Dedicated Server"
        },
        {
            "id": 44717,
            "name": "44717 2U",
            "hardware": {
                "config": "2xXeon E5-2680v2 2.8GHz (10 cores)/​128Gb/​960Gb SSD/​2xPSU",
                "motherboard_name": "DELL PE R720 MB (native)",
                "cpu_name": "Xeon E5-2680v2 2.8GHz (10 cores)",
                "cpu_type": "INTEL",
                "cpu_count": 2,
                "cpu_cores": 20,
                "cpu_frq": "2.8",
                "ram": 128,
                "ram_type": "ddr3reg",
                "hdd_count": 1,
                "hdd_groups": [
                    {
                        "name": "960Gb SSD",
                        "type": "HDD",
                        "count": 1,
                        "size": "960"
                    }
                ],
                "hdd_pairs": 0,
                "gpu_name": null,
                "gpu_count": 0,
                "raid_levels": [
                    "LVM_HBA"
                ]
            },
            "location": "FI",
            "cpu_count": "2",
            "cpu_perf": 12615,
            "cpu_perflink": "http://www.cpubenchmark.net/cpu_lookup.php?cpu=Intel+Xeon+E5-2680+v2+%40+2.80GHz&id=2061",
            "tags": {
                "ipmi": {
                    "tag": "ipmi",
                    "value": "dell_idrac9",
                    "extra": ""
                },
                "hwraid": {
                    "tag": "hwraid",
                    "value": "1",
                    "extra": ""
                }
            },
            "deployment_estimate": "auto",
            "billing_plan": {
                "EUR": {
                    "1": 107,
                    "3": 311.37,
                    "6": 603.48,
                    "12": 1129.92
                },
            },
            "server_group": "Dedicated Server"
        }
    ]
}

stocks/show

Allows you to get advanced information about a specific server from the general list of available servers.

HTTP method - POST

Parameter Required Type Value/default Description
action * string show main action - get detailed information for a single server
id * int server ID
eq.php order_instance create an order for a stock server deployment. The order will be executed after the invoice is paid

POST-request, cURL

curl -s "https://invapi.hostkey.com/stocks.php" -X POST \
    --data "action=show" \
    --data "id={Server ID}"
Positive response
{
    "result": "OK",
    "action": "show",
    "server_data": {
        "id": 44717,
        "name": "44717 2U",
        "hardware": {
            "config": "2xXeon E5-2680v2 2.8GHz (10 cores)/​128Gb/​960Gb SSD/​2xPSU",
            "motherboard_name": "DELL PE R720 MB (native)",
            "cpu_name": "Xeon E5-2680v2 2.8GHz (10 cores)",
            "cpu_type": "INTEL",
            "cpu_count": 2,
            "cpu_cores": 20,
            "cpu_frq": "2.8",
            "ram": 128,
            "ram_type": "ddr3reg",
            "hdd_count": 1,
            "hdd_groups": [
                {
                    "name": "960Gb SSD",
                    "type": "HDD",
                    "count": 1,
                    "size": "960"
                }
            ],
            "hdd_pairs": 0,
            "gpu_name": null,
            "gpu_count": 0,
            "raid_levels": [
                "LVM_HBA"
            ]
        },
        "location": {
            "dc_location": "FI",
            "location_id": 4,
            "country": "FI"
        },
        "cpu_count": "2",
        "cpu_perf": 12615,
        "cpu_perflink": "http://www.cpubenchmark.net/cpu_lookup.php?cpu=Intel+Xeon+E5-2680+v2+%40+2.80GHz&id=2061",
        "tags": {
            "ipmi": {
                "tag": "ipmi",
                "value": "dell_idrac9",
                "extra": ""
            },
            "hwraid": {
                "tag": "hwraid",
                "value": "1",
                "extra": ""
            }
        },
        "deployment_estimate": "auto",
        "billing_plan": {
            "EUR": {
                "1": 107,
                "3": 311.37,
                "6": 603.48,
                "12": 1129.92
            },
        }
    }
}

Notable equipment tags

  • ipmi - The server has an IPMI/DRAC/ILO/etc. managing interface. This does not necessarily mean it can be automatically deployed, but some management tasks will be easier to perform;
  • hwraid - The server has a hardware RAID controller installed or identical feature integrated into motherboard. If you want to use this feature, automatic deployment will not be possible, as RAID controller configuration is done by our operations team, usually within the next business day;
  • no_autodeploy - This server can not be deployed using our automation tools. Like with hardware raid setup, it will require involvement of our operations team and will be done during the next business day.

Creating a stock server deployment order

To order a stock server, use the eq/order_instance call with the ID of the stock server.

Remote access

Bare-metal servers

If the server is equipped with IPMI, we could provide direct access there. All our servers have IPMI in the gray IP range. We provide NAT on-demand to external IPs for 2 hours to perform necessary operations.

Asynckeys for all NAT operations should be checked with nat_callback.php:

https://invapi.hostkey.com/nat_callback.php?action=check&key=XXXX

Resource Action Description
nat.php add_static_nat create static DNAT pass-through rule to server's IPMI (public IP to access IPMI of the server)
nat.php remove_static_nat remove static DNAT pass-through to server's IPMI
eq.php add_ipmi_user create temp IPMI user for IPMI web access
eq.php remove_ipmi_user remove temp IPMI user for IPMI web access
eq.php unit_reset reset IPMI module

nat/add_static_nat

Creates a static DNAT pass-through access rule for the IPMI server.

HTTP method - POST

Parameter Required Type Value/default Description
action * string add_static_nat main action - create static DNAT pass-through rule to server's IPMI (public IP to access IPMI of the server)
token * string session token
id * int server ID
pin * int PIN code

POST-request, cURL

curl -s "https://invapi.hostkey.com/nat.php" -X POST \
--data "action=add_static_nat" \
--data "token=$HOSTKEY_TOKEN" \
--data "id={Server ID}" \
--data "pin={PIN code}"
Positive response
{
    "result": "OK",
    "action": "add_static_nat",
    "callback": "7bc29eb23fb1b879b21fce509597f07c" //asynchronous operation key
}
This action has an asynchronous response
{
"result": "OK",
"scope": "5.39.221.32",
"context": {
    "action": "add_static_nat",
    "id": "server ID",
    "location": "NL"
},
"debug": "/ip/firewall/nat/add=action=dst-nat=chain=dstnat=dst-address=5.39.221.32=to-addresses=10.77.21.239=.proplist=chain",
"key": "7bc29eb23fb1b879b21fce509597f07c"
}

nat/remove_static_nat

HTTP method - POST

Removes a static DNAT pass-through to the IPMI server

Parameter Required Type Value/default Description
action * string remove_static_nat main action- remove a static DNAT pass-through to the IPMI server
token * string session token
id * int server ID

POST-request, cURL

curl -s "https://invapi.hostkey.com/nat.php" -X POST \
--data "action=remove_static_nat" \
--data "token=$HOSTKEY_TOKEN" \
--data "id={Server ID}"
Positive response
{
  "result": "OK",
  "action": "remove_static_nat",
  "callback": "f685eaa0f06e47faa2e6bb5002828b00"
}
This action has an asynchronous response
{
  "result": "OK",
  "scope": "5.39.221.32",
  "context": {
    "action": "remove_staticnat",
    "id": "server ID",
    "location": "NL"
  },
  "debug": "/ip/firewall/nat/remove=.id=*42B=.proplist=chain",
  "key": "f685eaa0f06e47faa2e6bb5002828b00"
}

eq/add_ipmi_user

Creates a temporary user for web access to IPMI.

HTTP method - POST

Parameter Required Type Value/default Description
action * string add_ipmi_user main action - create temp IPMI user for IPMI web access
token * string session token
id * int server ID

POST-request, cURL

curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=add_ipmi_user" \
--data "token=$HOSTKEY_TOKEN" \
--data "id={Server ID}"
Positive response
{
"result": "OK",
"action": "add_ipmi_user",
"callback": "f685eaa0f06e47faa2e6bb5002828b00"
}
This action has an asynchronous response
{
"result": "OK",
"scope": "{\"result\":\"OK\",\"message\":\"User added\",\"debug\":\"\"}\n2021/05/17 22:46:55 Set User Password command successful (user 4)\n\n2021/05/17 22:46:55 \n2021/05/17 22:46:56 Set User Access (channel 1 id 4) successful.\n\n2021/05/17 22:46:56 exit status 1\n",
"context": {
    "action": "add_ipmi_user",
    "id": "server ID",
    "location": "NL",
    "User": "uHFxxxxx",
    "Password": "4Djxxxxx"
},
"debug": null,
"key": "f685eaa0f06e47faa2e6bb5002828b00"
}

eq/remove_ipmi_user

Deletes a temporary IPMI user

HTTP method - POST

Parameter Required Type Value/default Description
action * string remove_ipmi_user main action - remove temp IPMI user for IPMI web access
token * string session token
id * int server ID
curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=remove_ipmi_user" \
--data "token=$HOSTKEY_TOKEN" \
--data "id={Server ID}"

POST-request, cURL

{
  "result": "OK",
  "action": "remove_ipmi_user",
  "callback": "f685eaa0f06e47faa2e6bb5002828b00"
}
This action has an asynchronous response
{
  "result": "OK",
  "scope": "2021/05/17 22:50:49  User removed",
  "context": {
    "action": "remove_ipmi_user",
    "id": "Server ID",
    "location": "NL",
    "User": "uHFxxxxx"
  },
  "debug": null,
  "key": "f685eaa0f06e47faa2e6bb5002828b00"
}

eq/unit_reset

Reloads the IPMI module for a specific server.

Attention

In some cases, it may be necessary to reset the IPMI module if it stops responding or fails to perform some operations. Resetting the IPMI controller can help in these situations.

HTTP method - POST

Parameter Required Type Value/default Description
action * string unit_reset main action - reset IPMI module.
token * string session token
id * int server ID
pin * int PIN code

POST-request, cURL

curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=unit_reset" \
--data "token=$HOSTKEY_TOKEN" \
--data "id={Server ID}" \
--data "pin={PIN code}"
Positive response
{
  "result": "OK",
  "action": "unit_reset",
  "callback": "f685eaa0f06e47faa2e6bb5002828b00"
}
This action has an asynchronous response
{
  "result": "OK",
  "scope": "Unit is reset",
  "context": {
    "action": "unit_reset",
    "id": "Server ID",
    "location": "NL"
  },
  "debug": "Sent cold reset command to MC",
  "key": "f685eaa0f06e47faa2e6bb5002828b00"
}

Virtual servers

Remote access actions for Virtual Machines:

Resource Action Description
eq console get access to VM console

eq/console

HTTP method - POST

Parameter Required Type Value/default Description
action * string console main action - get access to VM console
token * string session token
id * int server ID
pin * int PIN code

POST-request, cURL

curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=console" \
--data "token=$HOSTKEY_TOKEN" \
--data "id={Server ID}" \
--data "pin={PIN code}"
Positive response
{
    "result": "OK",
    "action": "console",
    "callback": "f28dfd83fbc1dbb914710774d8e9e30a"
}
This action has an asynchronous response
{
    "result": "OK",
    "scope": "[virt-viewer]\ntype=spice\nhost=146.0.78.94\nport=6194\npassword=HY14U9qL\n# Password is valid for 120 seconds.\ndelete-this-file=1\nfullscreen=0\ntitle=34533:%d\ntoggle-fullscreen=shift+f11\nrelease-cursor=shift+f12\nsecure-attention=ctrl+alt+end\ntls-port=6195\nenable-smartcard=0\nenable-usb-autoshare=0\nusb-filter=null\ntls-ciphers=DEFAULT\nhost-subject=O=infra.hostkey.com,CN=172.18.2.34\nca=-----BEGIN CERTIFICATE-----\\nMIID+jCCAuKgAwIBAgICEAAwDQYJKoZIhvcNAQELBQAwWjELMAkGA1UEBhMCVVMxGTAXBgNVBAoM\\nEGluZnJhLmhvc3RrZXkucnUxMDAuBgNVBAMMJ292ci1ubC1lbmdpbmUwMmEuaW5mcmEuaG9zdGtl\\neS5ydS40NDU2MTAeFw0yMjA2MDUwNjQyNTZaFw00MjA2MDEwNjQyNTZaMFoxCzAJBgNVBAYTAlVT\\nMRkwFwYDVQQKDBBpbmZyYS5ob3N0a2V5LnJ1MTAwLgYDVQQDDCdvdnItbmwtZW5naW5lMDJhLmlu\\nZnJhLmhvc3RrZXkucnUuNDQ1NjEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCmOyY2\\n9SE0+o37Uft2HQjNcUsa/+KFQ+3/Dk9QTb2/wxIRmQLDWA/TleV2tI2rdRE+UfCnbWarP4++luvy\\nrxqKFKYU5qcf1jC1QXyS9ILkD9Akmj76GGxggmfV2YsvYCxEifSRctL6foUfYiztOqHOtj5MxC2Q\\njC/7yns+Mj8U5aM8J6wYZJI7Cv50qFgKOEMLWqguSalPRInPaFiLxb0PR9MM4vI82UBWY13sCaY2\\nUtAItk3LkKEwuJAW9XaBKPR4eP2v8c9FmvfyUK7uyV+FdEitQWsQlA07fz/Dz2AdodObgmlv9NoO\\ncg0O8sTQsVt8GcXsTXOScrylqUuljGthAgMBAAGjgckwgcYwHQYDVR0OBBYEFGZ9uIc9qrUCU7DZ\\niR4k5/OCDdE4MIGDBgNVHSMEfDB6gBRmfbiHPaq1AlOw2YkeJOfzgg3ROKFepFwwWjELMAkGA1UE\\nBhMCVVMxGTAXBgNVBAoMEGluZnJhLmhvc3RrZXkucnUxMDAuBgNVBAMMJ292ci1ubC1lbmdpbmUw\\nMmEuaW5mcmEuaG9zdGtleS5ydS40NDU2MYICEAAwDwYDVR0TAQH/BAUwAwEB/zAOBgNVHQ8BAf8E\\nBAMCAQYwDQYJKoZIhvcNAQELBQADggEBAHcQuHN3LEEdS3bCh41xOfPD3zbR4pcmHp6N5ng0FDCs\\nOZD5sO+PSrIsYP3gegVFxUomjR3AJ9TZojpodZYnzbgzaCCvC1JOb6VT35ekmNinvMfpkMB2WptM\\nPkME6sFJS4oxo6pmoPZvlKINBr3dYLcpLmFv9nYLALvL+LYxGjgnxa8bLokPYI3Pz5LL4JE8TQp0\\nFL9U6cs4DDueN0vwmNeRYb//PdSS8snlcYRhSKRsRdxx0moYSM0+CMOutjuVlXGjDxq3f6clnz1I\\nVY1/VLw1OyJTHOCHez+phC702Oh4Z5/1lMzWbRrKdZMEWweMif3VmIMMXe5JnaluF6lopW4=\\n-----END CERTIFICATE-----\\n\nsecure-channels=main;inputs;cursor;playback;record;display;smartcard;usbredir\nversions=rhev-win64:2.0-160;rhev-win32:2.0-160;rhel8:7.0-3;rhel7:2.0-6;rhel6:99.0-1\nnewer-version-url=http://www.ovirt.org/documentation/admin-guide/virt/console-client-resources\n\n[ovirt]\nhost=ovr-nl-engine02a.infra.hostkey.com:443\nvm-guid=12b720b2-d878-4f6c-a2cc-61a61f200a48\nsso-token=mcHYs92LDliDuVJ2lHKY8nNugkPS49IuTnS3_hpKOtylYX8DbCxAOAAm8J5ib_5-XNoRzoltHvjruHsWAY7fAw\nadmin=1\nca=-----BEGIN CERTIFICATE-----\\nMIID+jCCAuKgAwIBAgICEAAwDQYJKoZIhvcNAQELBQAwWjELMAkGA1UEBhMCVVMxGTAXBgNVBAoM\\nEGluZnJhLmhvc3RrZXkucnUxMDAuBgNVBAMMJ292ci1ubC1lbmdpbmUwMmEuaW5mcmEuaG9zdGtl\\neS5ydS40NDU2MTAeFw0yMjA2MDUwNjQyNTZaFw00MjA2MDEwNjQyNTZaMFoxCzAJBgNVBAYTAlVT\\nMRkwFwYDVQQKDBBpbmZyYS5ob3N0a2V5LnJ1MTAwLgYDVQQDDCdvdnItbmwtZW5naW5lMDJhLmlu\\nZnJhLmhvc3RrZXkucnUuNDQ1NjEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCmOyY2\\n9SE0+o37Uft2HQjNcUsa/+KFQ+3/Dk9QTb2/wxIRmQLDWA/TleV2tI2rdRE+UfCnbWarP4++luvy\\nrxqKFKYU5qcf1jC1QXyS9ILkD9Akmj76GGxggmfV2YsvYCxEifSRctL6foUfYiztOqHOtj5MxC2Q\\njC/7yns+Mj8U5aM8J6wYZJI7Cv50qFgKOEMLWqguSalPRInPaFiLxb0PR9MM4vI82UBWY13sCaY2\\nUtAItk3LkKEwuJAW9XaBKPR4eP2v8c9FmvfyUK7uyV+FdEitQWsQlA07fz/Dz2AdodObgmlv9NoO\\ncg0O8sTQsVt8GcXsTXOScrylqUuljGthAgMBAAGjgckwgcYwHQYDVR0OBBYEFGZ9uIc9qrUCU7DZ\\niR4k5/OCDdE4MIGDBgNVHSMEfDB6gBRmfbiHPaq1AlOw2YkeJOfzgg3ROKFepFwwWjELMAkGA1UE\\nBhMCVVMxGTAXBgNVBAoMEGluZnJhLmhvc3RrZXkucnUxMDAuBgNVBAMMJ292ci1ubC1lbmdpbmUw\\nMmEuaW5mcmEuaG9zdGtleS5ydS40NDU2MYICEAAwDwYDVR0TAQH/BAUwAwEB/zAOBgNVHQ8BAf8E\\nBAMCAQYwDQYJKoZIhvcNAQELBQADggEBAHcQuHN3LEEdS3bCh41xOfPD3zbR4pcmHp6N5ng0FDCs\\nOZD5sO+PSrIsYP3gegVFxUomjR3AJ9TZojpodZYnzbgzaCCvC1JOb6VT35ekmNinvMfpkMB2WptM\\nPkME6sFJS4oxo6pmoPZvlKINBr3dYLcpLmFv9nYLALvL+LYxGjgnxa8bLokPYI3Pz5LL4JE8TQp0\\nFL9U6cs4DDueN0vwmNeRYb//PdSS8snlcYRhSKRsRdxx0moYSM0+CMOutjuVlXGjDxq3f6clnz1I\\nVY1/VLw1OyJTHOCHez+phC702Oh4Z5/1lMzWbRrKdZMEWweMif3VmIMMXe5JnaluF6lopW4=\\n-----END CERTIFICATE-----\\n\n\n",
    "context": {
        "action": "console",
        "id": "34533",
        "location": "NL",
        "ip_ipmi": ""
    },
    "debug": "",
    "key": "f28dfd83fbc1dbb914710774d8e9e30a"
}

Data from scope should be stored in console.vv file for virtual machine viewer or accessed other way via VNC.

Following JS code do this action:

var blob = new Blob([result.scope], {
  type: 'text/octet-stream'
});
var filename = "console.vv";

if (window.navigator.msSaveOrOpenBlob) {
  window.navigator.msSaveBlob(blob, "console.vv");
} else {
  var elem = document.createElement('a');
  elem.href = window.URL.createObjectURL(blob);
  elem.download = filename;
  document.body.appendChild(elem);
  elem.click();
  document.body.removeChild(elem);
}

Server control

Information

Most of the server control actions are part of the eq (equipment) resource.

Resource Action Description
eq.php list get servers list, search for servers
eq.php show get full information about the server
eq.php update_servers refresh the active server's list

eq/list

Searches servers by location, status, hardware, IP, and properties.

HTTP method - POST

Parameter Required Type Value/default Description
action * string list main action - Get servers list, search for servers. The list function returns the server's id which matched search criteria.
default (no extra parameters) (without additional parameters) - return all assigned server's ID
location string Show servers from a specific region. Possible values: NL,US,FI,DE,IS and TR. Example: location=IS,NL (all servers from IS and NL regions)
status string show servers with a specific status. Possible customer's statuses: rent (active server), power_off (suspended for a reason). Example: status=power_off will show all suspended servers.
component string servers with a specific component like CPU or GPU. Usage component=12345,5456,.. where numbers are components ID
ip string server with specific IP address. Example: ip=199.100.7.5
mac string server with specific MAC address. Example: mac=00.00.00.00.00.00
Mini string compact servers with single CPU and IPMI
Storage string servers intended to be used as a storage
Nodes string servers intend to be used as virtualization nodes
Micro string servers with single CPU and without IPMI
VPS string virtual servers
1CPU string servers with single CPU
2CPU string servers with dual CPU's
Dell string Dell branded servers
Gpu string GPU servers
Instances string servers with standard configuration and full remote control
AMD string EPYC and Ryzen based servers

You may request several groups like all servers with groups 1CPU AND AMD:

group=1CPU,AMD

Note

For search inside server's tags API call resource tags, action user_search.

POST-request, cURL

curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=list" \
--data "token=$HOSTKEY_TOKEN" \
Positive response
{
    "servers": [
        34533
        32645
        17405
    ],
    "result": "OK"
}

eq/show

Provides information about a specific server.

HTTP method - POST

Parameter Required Type Value/default Description
action * string show main action - provides information about a specific server.
token * string session token
id * int server ID

POST-request, cURL

curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=show" \
--data "token=$HOSTKEY_TOKEN" \
--data "id={Server ID}"
Positive response
{
    "result": "OK",
    "server_data": {
        "id": 34533,
        "ref_tableName": "VPS",
        "Condition_Component": "rent",
        "account_id": 5724,
        "type_billing": "whmcs_com",
        "is_owner": "Rent",
        "cost_trafficIN": 0,
        "limit_trafficIN": 999,
        "cost_traffic": 180,
        "limit_traffic": 3,
        "new_limit_traffic": 0,
        "limit_bands": 1000,
        "trafficPeriodOut": 0,
        "trafficPeriodIn": 0,
        "trafficPeriodOutBilling": 0,
        "trafficPeriodInBilling": 0,
        "datePeriod": "2024-01-14 00:00:00",
        "IsShape": 1,
        "hwconfig": "4 vCore/​4Gb/​60Gb SSD",
        "status": "rent",
        "type": "VPS",
        "days_left": 18,
        "due_date": "2024-01-14"
    },
    "hardware": {
        "config": "4 vCore/​4Gb/​60Gb SSD",
        "components": [
            {
                "Type": "Platform",
                "Name": "Ovirt VM",
                "Count": 1,
                "hdd_type": "SSD"
            },
            {
                "Type": "CPU",
                "Name": "VPS Core",
                "Count": 4,
                "hdd_type": "SSD",
                "Cores": 4,
                "cpu_type": "INTEL"
            },
            {
                "Type": "RAM",
                "Name": "VPS RAM 1Gb",
                "Count": 4,
                "hdd_type": "SSD",
                "Size": 1
            },
            {
                "Type": "HDD",
                "Name": "VPS HDD 10 Gb",
                "Count": 6,
                "hdd_type": "SSD",
                "Size": 10
            }
        ],
        "tags": {
            "platform_ipmi": [
                "ovirt"
            ],
            "platform_location": [
                "NL,US,FI,IS,DE"
            ],
            "platform_tdp": [
                "1"
            ],
            "platform_blades": [
                "100"
            ],
            "platform_nojava_console": [
                ""
            ],
            "platform_vm": [
                "true"
            ],
            "platform_virt": [
                "1"
            ],
            "cpu_location": [
                "NL,US,FI,IS,TR",
                "NL,US,FI,IS,TR",
                "NL,US,FI,IS,TR",
                "NL,US,FI,IS,TR"
            ],
            "cpu_deprecation": [
                "8",
                "8",
                "8",
                "8"
            ],
            "cpu_production_start": [
                "",
                "",
                "",
                ""
            ],
            "cpu_tdp": [
                "1",
                "1",
                "1",
                "1"
            ],
            "cpu_virt": [
                "1",
                "1",
                "1",
                "1"
            ],
            "cpu_frq": [
                "2.4",
                "2.4",
                "2.4",
                "2.4"
            ],
            "cpu_cores": [
                "1",
                "1",
                "1",
                "1"
            ],
            "ram_vm": [
                "1",
                "1",
                "1",
                "1"
            ],
            "ram_location": [
                "NL,US,FI,IS,TR",
                "NL,US,FI,IS,TR",
                "NL,US,FI,IS,TR",
                "NL,US,FI,IS,TR"
            ],
            "ram_ram_type": [
                "VRAM",
                "VRAM",
                "VRAM",
                "VRAM"
            ],
            "ram_size": [
                "1",
                "1",
                "1",
                "1"
            ],
            "ram_ramtype": [
                "VRAM",
                "VRAM",
                "VRAM",
                "VRAM"
            ],
            "ram_virt": [
                "1",
                "1",
                "1",
                "1"
            ],
            "hdd_location": [
                "NL,US,FI,IS,TR",
                "NL,US,FI,IS,TR",
                "NL,US,FI,IS,TR",
                "NL,US,FI,IS,TR",
                "NL,US,FI,IS,TR",
                "NL,US,FI,IS,TR"
            ],
            "hdd_tdp": [
                "0.01",
                "0.01",
                "0.01",
                "0.01",
                "0.01",
                "0.01"
            ],
            "hdd_size": [
                "10",
                "10",
                "10",
                "10",
                "10",
                "10"
            ],
            "hdd_type": [
                "HDD",
                "HDD",
                "HDD",
                "HDD",
                "HDD",
                "HDD"
            ],
            "hdd_virt": [
                "1",
                "1",
                "1",
                "1",
                "1",
                "1"
            ],
            "hdd_interface": [
                "SATA",
                "SATA",
                "SATA",
                "SATA",
                "SATA",
                "SATA"
            ],
            "hdd_interface_sata": [
                "SATA",
                "SATA",
                "SATA",
                "SATA",
                "SATA",
                "SATA"
            ],
            "eta": 0.07
        },
        "vm": 1,
        "gpu": 0,
        "vds": 0,
        "uefi": 0,
        "hwraid": 0,
        "motherboard_name": "",
        "cpu_name": "vCPU",
        "cpu_type": "vCPU",
        "cpu_count": 4,
        "cpu_cores": 4,
        "cpu_frq": "2.4",
        "ram": 4,
        "ram_type": "vram",
        "hdd": 60,
        "hdd_count": 1,
        "hdd_groups": [
            {
                "name": "60Gb SSD",
                "type": "HDD",
                "count": 1,
                "size": "60"
            }
        ],
        "hdd_pairs": 0,
        "gpu_name": null,
        "gpu_count": 0,
        "raid_levels": [
            "LVM_HBA"
        ]
    },
    "groups": [
        {
            "ID": "26",
            "Code": "Micro",
            "Name": "Micro",
            "active": 0
        },
        {
            "ID": "32",
            "Code": "1CPU",
            "Name": "1CPU",
            "active": 0
        },
        {
            "ID": "33",
            "Code": "2CPU",
            "Name": "2CPU",
            "active": 0
        },
        {
            "ID": "39",
            "Code": "OUT",
            "Name": "OUT",
            "active": 0
        },
        {
            "ID": "41",
            "Code": "Gpu",
            "Name": "Gpu",
            "active": 0
        },
        {
            "ID": "52",
            "Code": "1CPU_OUT_NEW",
            "Name": "1CPU_OUT_NEW",
            "active": 0
        },
        {
            "ID": "53",
            "Code": "Ryzen",
            "Name": "Ryzen",
            "active": 0
        },
        {
            "ID": "54",
            "Code": "5Ghz",
            "Name": "5Ghz",
            "active": 0
        },
        {
            "ID": "55",
            "Code": "2CPU_OUT_NEW",
            "Name": "2CPU_OUT_NEW",
            "active": 0
        },
        {
            "ID": "59",
            "Code": "Promo",
            "Name": "Promo",
            "active": 0
        }
    ],
    "licenses": [
        {
            "id": 124,
            "name": "ISPmanager 6 Lite on IP 31.207.44.105",
            "amount": 1,
            "date_buy": ""
        }
    ],
    "location": {
        "dc_location": "NL",
        "location_id": 1
    },
    "OS": null,
    "IP": [
        {
            "port": "eth0",
            "MAC": "56:6f:ff:5b:08:7b",
            "IP": "31.207.44.105",
            "status": "enable",
            "main_ip": 1,
            "locked": 0,
            "date_block": null,
            "license_id": 124,
            "main_int": 1,
            "vlan": 415,
            "updated": 13,
            "license_name": "ISPmanager",
            "white_ddos": 0,
            "description": ""
        }
    ],
    "interfaces": [
        {
            "id": 122936,
            "type": "eth0",
            "mac": "56:6f:ff:5b:08:7b",
            "upstream_id": null,
            "IsMain": 1,
            "IsVirt": 0,
            "Status": "enable",
            "switch_owner": "",
            "switch_model": "virtual"
        }
    ],
    "IPMI": {
        "model": "ovirt",
        "interfaces": []
    },
    "tags": [
        {
            "id": 799108,
            "component": "Component1",
            "component_id": 34533,
            "tag": "order_origin",
            "value": "invapi",
            "extra": "1",
            "internal": 0
        },
        {
            "id": 799112,
            "component": "Component1",
            "component_id": 34533,
            "tag": "hostname",
            "value": "nl-vmmini",
            "extra": "",
            "internal": 0
        },
        {
            "id": 799116,
            "component": "Component1",
            "component_id": 34533,
            "tag": **Password**,
            "value": "wK5Vjwx_BC",
            "extra": "",
            "internal": 0
        },
        {
            "id": 799128,
            "component": "Component1",
            "component_id": 34533,
            "tag": "OS",
            "value": "Ubuntu 22.04",
            "extra": "",
            "internal": 0
        },
        {
            "id": 799132,
            "component": "Component1",
            "component_id": 34533,
            "tag": "user_name",
            "value": "root",
            "extra": "",
            "internal": 0
        },
        {
            "id": 799137,
            "component": "Component1",
            "component_id": 34533,
            "tag": "webpanel",
            "value": "ispmanager6",
            "extra": "https://isp34533.hostkey.in:1500/ispmgr",
            "internal": 0
        }
    ],
    "preset": "vm.mini",
    "preset_description": "VM instance 4/4/60 SSD"
}

eq/update_servers

Refresh the active server's list. If the customer has ordered or released a server, it's necessary to refresh the server's list. This action will check again inventory and refresh token with the current server's list.

HTTP method - POST

Parameter Required Type Value/default Description
action * string update_servers main action - refresh the active server's list
token * string session token

POST-request, cURL

curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=update_servers" \
--data "token=$HOSTKEY_TOKEN"
Positive response
{
  "result": "OK"
}

Server power control

We manage our bare-metal servers via an out-of-band IPMI module. oVirt VMs are managed via standard API.

Resource Action Description
eq.php status get power status
eq.php sensors get sensors data (bare-metal only)
eq.php on turn power on
eq.php off turn power off
eq.php reboot reboot server

eq/status

Allows you to view the power status of the server.

HTTP method - POST

Parameter Required Type Value/default Description
action * string status main action - get power status
token * string session token
id * int server ID

POST-request, cURL

curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=status" \
--data "token=$HOSTKEY_TOKEN" \
--data "id={Server ID}"
Positive response
{
    "result": "OK",
    "action": "status",
    "callback": "6fae43c4aca5be531a1275307bd094b1"
}
This action has an asynchronous response
{
    "result": "OK",
    "scope": "VM is up now",
    "context": {
        "action": "status",
        "id": "34533",
        "location": "NL",
        "ip_ipmi": ""
    },
    "debug": "debug",
    "key": "6fae43c4aca5be531a1275307bd094b1"
}
{
"result": "OK",
"scope": "Chassis Power is on",
"context": {
    "action": "status",
    "id": "Server ID",
    "location": "NL"
},
"debug": "Chassis Power is on",
"key": "f685eaa0f06e47faa2e6bb5002828b00"
}

eq/sensors (bare-metal only)

Allows you to retrieve data from the bare-metal server's sensors.

HTTP method - POST

Parameter Required Type Value/default Description
action * string sensors main action- get sensors data
token * string session token
id * int server ID

POST-request, cURL

curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=sensors" \
--data "token=$HOSTKEY_TOKEN" \
--data "id={Server ID}"
Positive response
{
  "result": "OK",
  "action": "sensors",
  "callback": "f685eaa0f06e47faa2e6bb5002828b00"
}
This action has an asynchronous response
{
  "result": "OK",
  "scope": "CPU Temp         | 36 degrees C      | ok\nPCH Temp         | 37 degrees C      | ok\nSystem Temp      | 25 degrees C      | ok\nPeripheral Temp  | 33 degrees C      | ok\nVcpuVRM Temp     | 34 degrees C      | ok\nVmemABVRM Temp   | 31 degrees C      | ok\nVmemCDVRM Temp   | 30 degrees C      | ok\nP1-DIMMA1 Temp   | 26 degrees C      | ok\nP1-DIMMB1 Temp   | 26 degrees C      | ok\nP1-DIMMC1 Temp   | no reading        | ns\nP1-DIMMD1 Temp   | no reading        | ns\nFAN              | 3100 RPM          | ok\n12V              | 12.06 Volts       | ok\n5VCC             | 5.08 Volts        | ok\n3.3VCC           | 3.33 Volts        | ok\nVBAT             | 3.00 Volts        | ok\nVcpu             | 1.84 Volts        | ok\nVDIMMAB          | 1.22 Volts        | ok\nVDIMMCD          | 1.22 Volts        | ok\n5VSB             | 5.10 Volts        | ok\n3.3VSB           | 3.27 Volts        | ok\n1.5V PCH         | 1.53 Volts        | ok\n1.2V BMC         | 1.23 Volts        | ok\n1.05V PCH        | 1.06 Volts        | ok\nPS Status        | 0x01              | ok\n",
  "context": {
    "action": "get_sensors",
    "id": "Server ID",
    "location":"NL"
  },
  "debug":"CPU Temp         | 36 degrees C      | okPCH Temp         | 37 degrees C      | okSystem Temp      | 25 degrees C      | okPeripheral Temp  | 33 degrees C      | okVcpuVRM Temp     | 34 degrees C      | okVmemABVRM Temp   | 31 degrees C      | okVmemCDVRM Temp   | 30 degrees C      | okP1-DIMMA1 Temp   | 26 degrees C      | okP1-DIMMB1 Temp   | 26 degrees C      | okP1-DIMMC1 Temp   | no reading        | nsP1-DIMMD1 Temp   | no reading        | nsFAN              | 3100 RPM          | ok12V              | 12.06 Volts       | ok5VCC             | 5.08 Volts        | ok3.3VCC           | 3.33 Volts        | okVBAT             | 3.00 Volts        | okVcpu             | 1.84 Volts        | okVDIMMAB          | 1.22 Volts        | okVDIMMCD          | 1.22 Volts        | ok5VSB             | 5.10 Volts        | ok3.3VSB           | 3.27 Volts        | ok1.5V PCH         | 1.53 Volts        | ok1.2V BMC         | 1.23 Volts        | ok1.05V PCH        | 1.06 Volts        | okPS Status        | 0x01              | ok",
  "key":"f685eaa0f06e47faa2e6bb5002828b00"
}

eq/on

Allows you to power on the server.

HTTP method - POST

Parameter Required Type Value/default Description
action * string on main action - turn power on
token * string session token
id * int server ID
pin * int PIN code

POST-request, cURL

curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=on" \
--data "token=$HOSTKEY_TOKEN" \
--data "id={Server ID}" \
--data "pin={PIN code}"
Positive response
{
    "result": "OK",
    "action": "on",
    "callback": "9f058913338363da1276a003707dc8bd"
}
This action has an asynchronous response
{
    "result": "OK",
    "scope": "VM is up now",
    "context": {
        "action": "on",
        "id": "34533",
        "location": "NL",
        "ip_ipmi": ""
    },
    "debug": "",
    "key": "9f058913338363da1276a003707dc8bd"
}

eq/off

Allows you to turn off power to the server.

HTTP method - POST

Parameter Required Type Value/default Description
action * string off main action - turn power off
token * string session token
id * int server ID
pin * int PIN code

POST-request, cURL

curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=off" \
--data "token=$HOSTKEY_TOKEN" \
--data "id={Server ID}" \
--data "pin={PIN code}"
Positive response
{
    "result": "OK",
    "action": "off",
    "callback": "6ff0b0895a6c25edd31c4069ea009ff7"
}
This action has an asynchronous response
{
    "result": "OK",
    "scope": "VM is down now",
    "context": {
        "action": "off",
        "id": "34533",
        "location": "NL",
        "ip_ipmi": ""
    },
    "debug": "debug",
    "key": "6ff0b0895a6c25edd31c4069ea009ff7"
}

eq/reboot

Allows you to perform a server reboot.

HTTP method - POST

Parameter Required Type Value/default Description
action * string reboot main action - reboot server
token * string session token
id * int server ID
pin * int PIN code

POST-request, cURL

curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=reboot" \
--data "token=$HOSTKEY_TOKEN" \
--data "id={Server ID}" \
--data "pin={PIN code}"
Positive response
{
    "result": "OK",
    "action": "reboot",
    "callback": "9a3751450d879fd9e933fdea92add6e8"
}
This action has an asynchronous response
    "result": "OK",
    "scope": "VM is rebooted",
    "context": {
        "action": "off",
        "id": "34533",
        "location": "NL",
        "ip_ipmi": ""
    },
    "debug": "debug",
    "key": "9a3751450d879fd9e933fdea92add6e8"
}

Reinstall the operating system on the server (second option)

This reinstall option is used for servers that failed to reinstall using the first method.

We are using Foreman to deploy servers via PXE network boot. The installation process goes in several stages:

  1. Create reinstall stage key (optional) via eq/reinstall;
  2. Create PXE config with parameters via eq/create_pxe;
  3. Change server boot order via eq/bootdev. It should run from PXE;
  4. Reboot the server via eq/reboot;
  5. The server will catch the PXE bootloader and OS installation will go on;
  6. OS will report installation stages during install progress:
    1. 1st stage: OS installation was started;
    2. 2nd stage: base OS was installed, proceed with post-install tasks;
    3. 3rd stage: Post-install tasks are completed, running final tasks;
    4. 4th stage: Install is completed, restarting the server;
    5. 5th stage: The server is online;
  7. After installing the operating system, you should change the boot order via eq/bootdev. The server must boot from the HDD;
  8. Run extra Jenkins task on a server (i.e. install GPU drivers);
  9. Remove PXE config via eq/clear_pxe. This action will prevent a sudden reinstallation.
Resource Action Description
eq.php reinstall create master key for reinstall OS
os.php list get a list of OS for a server
jenkins.php list retrieve available Ansible tasks
eq.php create_pxe create PXE config for OS install
eq.php boot_dev set boot order for VM or bare-metal server
eq.php reboot reboot server

eq/reinstall

Allows you to create a $REINSTALL_KEY master key for reinstalling the operating system.

Note

If we need to automate the whole reinstall process, we will need a master key to keep track of different actions. All stage alerts from the OS installer go to this key. As the OS install goes on, it will report stages via async responses via this key. This key will be required for eq/create_pxe.

HTTP method - POST

Parameter Required Type Value/default Description
action string reinstall main action - create master key for reinstall
token * string session token
id * int server ID

POST-request, cURL

curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=reinstall" \
--data "token=$HOSTKEY_TOKEN" \
--data "id={Server ID}" \
Positive response
{
"result":"OK",
"action":"reinstall",
"stage":"create_pxe",
"callback":"aa719bfc59c3626c059950c1dcb4dbfa" \\ $REINSTALL_KEY to get information about installation steps.
}    

Note

For information on all steps of the reinstallation process, call eq_callback/check.

eq_callback/check

Get information about all stages of reinstalling the operating system.

HTTP method - POST

Parameter Required Type Value/default Description
action string check main action - get information about the stage of the OS reinstallation
reinstall_key string $REINSTALL_KEY from eq/reinstall to track reinstallation steps

POST-request, cURL

curl -s "https://invapi.hostkey.com/eq_callback.php" -X POST \
--data "action=check" \
--data "key=$REINSTALL_KEY" \
Positive response
{
"result":"Stage", // Informative message about the progress of the installation process
"scope":" (1\/5) OS installation started", // Stage information
"context":{"action":"reinstall","id":"42253","location":"NL"}, // Installation information (main action, server ID, and location)
"key":"aa719bfc59c3626c059950c1dcb4dbfa" // $REINSTALL_KEY
} 
{
"result":"OK",
"scope":" Deploy completed, Server is online",
"context":{"action":"reinstall",
"id":"42253","location":"NL"},
"debug":null,
"key":"0aacc95ff67f81943519b44f566bedd8"
}

Actions to take before starting the OS installation

Before we start with reinstall, some mandatory information should be collected:

  1. Get the list of operating systems that can be installed by calling os_list

    Attention

    You will also need to select a host name and password before starting the reinstallation.

  2. Select disk partitioning scheme:

    • LVM_RAID0 - create stripe across all disks via LVM;
    • LVM_HBA - install OS on the smallest device, let the rest untouched, applicable if there are more than 1 storage device;
    • LVM_RAID1 - create disk mirror via LVM, applicable if there are two similar storage devices;
    • LVM_RAID10 - create LVM RAID10 across all storage device pairs, minimum 2 pairs of devices required;
    • LVM_RAID10S - create LVM RAID1 on smallest storage devices pairs for OS, create LVM RAID10 on rest of storage devices pars.
  3. Prepare a Public ssh key if you want to set your SSH key for admin login.

  4. Think about Post-install tasks - standardized Ansible tasks that can be run on the server after installation via Jenkins. You can get a list of them by calling jenkins/get_tasks.

jenkins/get_tasks

This will retrieve all possible Ansible tasks with its tags. You could load this data in JS variables and show it for appropriate servers - checking by tags.

HTTP method - POST

Parameter Required Type Value/default Description
action * string get_tasks main action - retrieve available Ansible tasks

Possible tags:

  • gpu - task is suitable for GPU servers;
  • bm - task is suitable for bare-metal server;
  • vm - task is suitable for VM (VPS);
  • vgpu - task is suitable for vGPU server;
  • default - default value.

POST-request, cURL

curl -s "https://invapi.hostkey.com/jenkins.php" -X POST \
--data "action=get_tasks" \
Positive response
{
    "result": "OK",
    "tasks": [{
        "id": -1,
        "task": "",
        "desc": "Do nothing",
        "tag": "",
        "tags": [{
            "tag": "gpu"
        }, {
            "tag": "vgpu"
        }, {
            "tag": "vm"
        }, {
            "tag": "bm"
        }]
    }, {
        "id": 1,
        "task": "invapi_gpu_conf_iommu_patch_gpu_linux_auto.dsl", // task name
        "desc": "Install GPU drivers" // human readable description
        "tag": "gpu_driver", // task variant
        "tags": [{ // Tags for filtering output in the user interface
            "tag": "gpu"
        }, {
            "tag": "vgpu"
        }, {
            "tag": "default"
        }]
    }, {
        "id": 2,
        "task": "invapi_gpu_conf_iommu_patch_gpu_linux_auto.dsl",
        "desc": "Install GPU drivers + NVIDIA docker",
        "tag": "gpu_driver_docker",
        "tags": [{
            "tag": "gpu"
        }, {
            "tag": "vgpu"
        }]
    }, {
        "id": 3,
        "task": "invapi_gpu_conf_iommu_patch_gpu_linux_auto.dsl",
        "desc": "Install GPU drivers + NVIDIA docker + IOMMU patch",
        "tag": "gpu_driver_docker_iommu",
        "tags": [{
            "tag": "gpu"
        }, {
            "tag": "vgpu"
        }]
    }]
}    

Post-install script - the piece of bash/PS code to be executed on the first run in fresh OS. Useful for automation to include a new server to the managed infrastructure.

Post-install callback URL - URL which will be called from the fresh server after installation. Useful for billing purposes.

As we have all data ready, we could try to create a PXE config for OS install

eq/create_pxe

Create PXE config for OS install.

HTTP method - POST

Parameter Required Type Value/default Description
action * string create_pxe main action - creating a PXE configuration for OS installation
token * string session token
id * int server ID
pin * int PIN code
os_id * int OS ID from os/list
root_pass * string password for the administrative user. length and content should meet security policy - min 8 symbols, with some numbers and letters in caps
hostname * string desired hostname for the server
ssh_key string Public ssh key(optional)
post_install_callback string URL to call after install is completed
post_install_script string Post-install script to run
reinstall_key string $REINSTALL_KEY from eq/reinstall to track reinstallation steps

POST-request, cURL

curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=create_pxe" \
--data "token=$HOSTKEY_TOKEN" \
--data "email=" \
--data "pin={PIN code}" \
--data "id={Server ID}" \
--data "os_id={OS ID}" \
--data "root_pass={root password}" \
--d--data "hostname={Server name}" \
--data "ssh_key={public SSH key}" \
--data "post_install_callback=" \
--data "post_install_script=" \
--data "reinstall_key=$REINSTALL_KEY" \
Positive response
{
result":"OK",
"action":"create_pxe",
"callback":"e22cc91dbf065348a4789e6122f6995d
}    
This action has an asynchronous response
{
"result":"OK",
"scope":"Configuration_successfully_created",
"context":{"action":"create_pxe","id":"9536","location":"NL"},
"debug":null,
"key":"e22cc91dbf065348a4789e6122f6995d
}

If there was no errors, we need to set server's boot order to network boot via PXE call eq/boot_dev.

eq/boot_dev

HTTP method - POST

Parameter Required Type Value/default Description
action * string boot_dev main action - set boot order for VM or bare-metal server
token * string session token
pin * int PIN code
id * int server ID
media int pxe for PXE boot, disk local storage device boot, cd for mounted CD boot (usually via virtual media via IPMI)

POST-request, cURL

curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=boot_dev" \
--data "token=$HOSTKEY_TOKEN" \
--data "id={Server ID}" \
--data "pin={PIN code}" \
--data "media=pxe"
Positive response
{
"result":"OK",
"action":"boot_dev",
"callback":"9d274e99e293b909fb562129a70988c4"
}    
This action has an asynchronous response
{
"result":"OK",
"scope":"Set Boot Device to pxe",
"context":{"action":"bootdev_pxe","id":"9536","location":"NL"},
"debug":null,
"key":"9d274e99e293b909fb562129a70988c4"
}

After successful change of boot order we should reboot server via call eq/reboot.

The system will reboot and start loading from PXE. After the OS installer is loaded, you will see stage notifications - it could be retrieved with the main reinstall key from eq/reinstall and call eq_callback/check.

If eq_callback/check have got result OK, this means server is online and reinstall is completed. After we will retrieve this value, reinstall key will be removed from database.

Now you need to perform post-installation tasks:

  • Reboot from disk calling eq/boot_dev with parameter media=disk
This action has an asynchronous response
{
"result":"OK",
"scope":"VM is boot for disk",
"context":{"action":"bootdev_disk","id":"42253","location":"NL"},
"debug":null,
"key":"724311d38e9df10e25f987f718820c46"
}

Attention

Be sure to clear the PXE configuration. This will prevent sudden reinstallations.

eq/clear_pxe

Clear PXE config.

HTTP method - POST

Parameter Required Type Value/default Description
action * string clear_pxe main action - clear PXE config to avoid sudden reinstalls
token * string session token
id * int server ID
hostname * string server name

POST-request, cURL

curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=clear_pxe" \
--data "token=$HOSTKEY_TOKEN" \
--data "id={Server ID}" \
--d--data "hostname={Server name}" \
Positive response
{
"result":"OK",
"action":"clear_pxe",
"callback":"ee8a179e8b3a4e28f3a84f44264a10ec"
}    
This action has an asynchronous response
{
"result":"OK",
"scope":"Configuration_successfully_cleared",
"context":{"action":"clear_pxe","id":"42253","location":"NL"},
"debug":null,
"key":"ee8a179e8b3a4e28f3a84f44264a10ec"
}

Network operations

Resource Action Description
net.php get_status Retrieve interface status
net.php port_off Disable interface
net.php port_on Enable interface
net.php show_cacti View port speed graphs
ip.php show_cacti Get IP information
ip.php get_ptr Get PTR record for IP
ip.php update_ptr Update PTR record for IP
ip.php set_main Set IP option for a server
net.php block_ip Block specific IP
net.php unblock_ip Unblock specific IP

net/get_status

Displays the status of the network interface.

HTTP method - POST

Parameter Required Type Value/default Description
action * string get_status main action — retrieve interface status
token * string session token
id * int server ID
pin * int PIN code
port string physical port's switch
switch string switch ID and address
vlan int VLAN number (if any)
speed string physical interface speed
status string interface status, connected or not
mac string MAC information (if any)
port_security string maximum allowed MACs on port (if any)
shape string port speed limits (if any)

POST-request, cURL

curl -s "https://invapi.hostkey.com/net.php" -X POST \
--data "action=get_status" \
--data "token=$HOSTKEY_TOKEN" \
--data "id={Server ID}" \
--data "pin={PIN code}" \
Positive response
{
    "result": "OK",
    "action": "get_status",
    "callback": "a1bc5aebbfb62a8350020d9da42e1c1e"
}
This action has an asynchronous response
{
    "result": "OK",
    "scope": "{\"switch\":\"virtual\",\"port\":\"virtual\",\"vlan\":\"v415\",\"speed\":\"1000\",\"status\":\"connected\",\"mac\":[\"56:6f:ff:5b:08:7b\"],\"port_security\":\"\",\"shape\":\"\",\"interface\":\"eth0\"}", // interface description
    "context": {
        "action": "get_status",
        "id": "34533",
        "location": "NL",
        "ip_ipmi": "0.0.0.0",
        "interface_id": "eth0",
        "port": "eth0" // physical port Switch
    },
    "debug": "get status port via Ovirt API",
    "key": "a1bc5aebbfb62a8350020d9da42e1c1e"
}

net/port_off

Allows you to disable the network port.

HTTP method - POST

Parameter Required Type Value/default Description
action * string port_off main action — disable interface
token * string session token
id * int server ID
pin * int PIN code
port * string physical port's switch

POST-request, cURL

curl -s "https://invapi.hostkey.com/net.php" -X POST \
--data "action=port_off" \
--data "token=$HOSTKEY_TOKEN" \
--data "id={Server ID}" \
--data "port={port}" \
--data "pin={PIN code}" \
Positive response
{
    "result": "OK",
    "action": "port_off",
    "callback": "97b516c96623a69f707ba423c4e51a30"
}
This action has an asynchronous response
{
    "result": "OK",
    "scope": "Port is off",
    "context": {
        "action": "port_off",
        "id": "34533",
        "location": "NL",
        "ip_ipmi": "0.0.0.0",
        "interface_id": "eth0",
        "port": "eth0"
    },
    "debug": "Unplugged",
    "key": "97b516c96623a69f707ba423c4e51a30"
}

net/port_on

Enables the network port.

HTTP method - POST

Parameter Required Type Value/default Description
action * string port_on main action — enable interface
token * string session token
id * int server ID
pin * int PIN code
port * string physical port's switch

POST-request, cURL

curl -s "https://invapi.hostkey.com/net.php" -X POST \
--data "action=port_on" \
--data "token=$HOSTKEY_TOKEN" \
--data "id={Server ID}" \
--data "port=" \
--data "pin={PIN code}" \
Positive response
{
    "result": "OK",
    "action": "port_on",
    "callback": "4bf035a1b4259cd0df21a4ee1faea867"
}
This action has an asynchronous response
{
    "result": "OK",
    "scope": "Port is on",
    "context": {
        "action": "port_on",
        "id": "34533",
        "location": "NL",
        "ip_ipmi": "0.0.0.0",
        "interface_id": "eth0",
        "port": "eth0"
    },
    "debug": "Plugged",
    "key": "4bf035a1b4259cd0df21a4ee1faea867"
}

net/show_cacti

Lets you view a graph of port speeds over a period of time.

HTTP method - POST

Parameter Required Type Value/default Description
action * string show_cacti main action — show port speed graphs
token * string session token
id * int server ID
pin * int PIN code
port * string physical port's switch
graph * string graph values - 1 for daily, 2 for monthly, 3 for annual graphs

POST-request, cURL

curl -s "https://invapi.hostkey.com/net.php" -X POST \
--data "action=show_cacti" \
--data "token=$HOSTKEY_TOKEN" \
--data "id={Server ID}" \
--data "port={port}" \
--data "graph={1, 2 or 3}"
Positive response

traffic graph image

Failure response :
{
"result": -1,
"action": "show_cacti",
"error": "net/show_cacti: failed to load img for server 34533 port eth0: failed to find cacti id for this server interface",
"context": {
    "id": 34533,
    "port": "eth0"
}

ip/get_ip

Lets you get information about a network interface by IP address.

HTTP method - POST

Parameter Required Type Value/default Description
action * string get_ip main action — get IP information
token * string session token
ip * int IP address

POST-request, cURL

curl -s "https://invapi.hostkey.com/ip.php" -X POST \
--data "action=get_ip" \
--data "token=$HOSTKEY_TOKEN" \
--data "ip={IP address}" \
Positive response
{
    "network": "176.222.34.0",