Control panel API documentation  invapi.hostkey.com

We have developed an API to manage all our services. It offers full functionality to daily operations and integrations.  
Control panel invapi.hostkey.com is built on top of this API. 

Main 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.

  Table of Content

Common information

API is built on traditional principles with action selector and auth token authorization.

You can use POST or GET messages for all API calls, except authorization actions.

Example GET:

curl -s "https://invapi.hostkey.com/tags.php?action=list&token=XXX&id=SERVER_ID" -X GET

Example POST:

curl -s "https://invapi.hostkey.com/tags.php" -X POST \
--data "action=list" \
--data "token=XXXX" \
--data "id=SERVER_ID"

We will use POST examples only in this documentation because this method is preferred.

Asynchronous actions

Some operation with the servers could take a long. Many API calls will return async key when called.

Example:


Step 1 Example request to reboot server cURL:

curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=on" \
--data "token=YOUR_ACCESS_TOKEN" \
--data "id=SERVER_ID" \
--data "pin=PIN_CODE"

Response:

{
 "result":"OK",
 "action":"on",
 "callback":"f685eaa0f06e47faa2e6bb5002828b00"
}

it means what async request was successfully sent, async key to keep track of it is f685eaa0f06e47faa2e6bb5002828b00


Step 2 You could track state of the request:

curl -s "https://invapi.hostkey.com/eq_callback.php" -X POST \
--data "action=check" \
--data "key=f685eaa0f06e47faa2e6bb5002828b00"

Uncompleted task response (Result: Not ready):

{
 "result":"Not ready",
 "key":"f685eaa0f06e47faa2e6bb5002828b00"
}

Completed task response (Result: OK):

{
 "result": "OK",
 "scope": "Post is on",
 "context": {
   "action": "on",
   "id": "SERVER_ID",
   "location": "NL"
  },
 "debug": "Chassis Power Control: Up/On",
 "key": "f685eaa0f06e47faa2e6bb5002828b00"
}
scopemessage to the user
contextJSON with initial request and some extra data. Usefull to proceed during AJAX calls
debughardware output from device
keyour async key. Its become deleted after successful response OK

Tags

We keep auxiliary and temporary information about servers and their components in tags. Tags may be assigned to any server's element. Some tags are visible to the end-user, some are not. 

Tag actions:

ResourceActionDescription
tags.phpaddAction add a tag to the server or change existing tag
tags.phpremoveAction removes a tag for a server
tags.phplistAction gets all tags for the server
tags.phpuser_searchAction find the servers with tags

The tag could be mounted to the server itself, or its CPU, or NIC or IP address - any DB component. The customer could assign their own tags to servers via API (and web interface). It's possible to search for tags, change or remove them.
It may be useful to keep some automation data, user settings, or application states in tags.

Tags/Add


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringadd Main action - Action add a tag to the server or change existing tag
token     *        string              Your session token
id     *        int              Your server ID
tag     *      string              Tag name
value    *    string              Tag value
extra       string              extra value if necessary to keep several values for the key

Example create new tag cURL:

curl -s "https://invapi.hostkey.com/tags.php" -X POST \
--data "action=add" \
--data "token=" \
--data "id=" \
--data "tag=" \
--data "value=" \
--data "extra="

Example change existing tag cURL:

curl -s "https://invapi.hostkey.com/tags.php" -X POST \
--data "action=add" \
--data "token=" \
--data "id=" \
--data "tag=" \
--data "value=" \
--data "extra="

Tags/Remove


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringremove Main action - removes a tag from a server
token     *        string              Your session token
id     *        int              Your server ID
tag     *      string         Tag name
curl -s "https://invapi.hostkey.com/tags.php" -X POST \
--data "action=remove" \
--data "token=" \
--data "id=" \
--data "tag="

Tags/List


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringlist Main action - retrive all tags from the server server_id
token     *        string              Your session token
id     *        int              Your server ID
curl -s "https://invapi.hostkey.com/tags.php" -X POST \
--data "action=list" \
--data "token=" \
--data "id="



HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        string user_search Main action - this request searches for servers IDs with tag name or value matching search_pattern as a substing
token     *        string              Your session token
value   *        string              search pattern
curl -s "https://invapi.hostkey.com/tags.php" -X POST \
--data "action=user_search" \
--data "token=" \
--data "value="


Authorization

In order to use API, you need to get an authorization token first.  

This could be done via an API call to Auth URL: invapi.hostkey.com/auth.php

The most important data is a token.  All information regarding your token data and permissions are stored on the API server, the rest of the data helps only to build a proper web interface for the specific role.
The token is valid for 2 hours by default. 

Auth actions:

ResourceActionDescription
auth.phpwhmcsloginObtains a session token
auth.phplogoutRemoves a session token
auth.phpinfoGets session token environment
eq.phpset_pinset/change PIN for the user
eq.phpcheck_pinvalidate entered PIN (optional)

Auth/Whmcslogin


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringwhmcslogin    Main action - Obtains an access token
user      *        string              Your billing login
password  *        string              Your billing password
ttl                int   10800         Session lifetime in seconds, default 10800 (3 hours)
curl -s "https://invapi.hostkey.com/auth.php" -X POST \
--data "action=whmcslogin" \
--data "user=" \
--data "password="



Auth/Logout


HTTP Method - POST/GET


ParameterRequiredType Value/defaultDescription
action    *        stringlogout        Main action - logout will remove auth token from the database. Please do not forget to log out to avoid possible security issues
token     *        string              Token for expiration
curl -s "https://invapi.hostkey.com/auth.php" -X POST \
--data "action=logout" \
--data "token="

Auth/Info


HTTP Method - POST/GET


ParameterRequiredType Value/defaultDescription
action    *        stringinfo          Main action - info will return full data about your token including your server's identification numbers when you are logged in.
token     *        string              Your API token
curl -s "https://invapi.hostkey.com/auth.php" -X POST \
--data "action=info" \
--data "token="

Data in servers is a list of server's id which are linked to your billing account, you may use it later to manage it



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.

  • PINs 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


HTTP Method - POST/GET


ParameterRequired Type Value/defaultDescription
action    *         stringset_pin       Main action - Set/Change PIN for the user
token     *         string              Your API token
old_pin   for changeint                 Old PIN code
new_pin   *         int                 New PIN code
curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=set_pin" \
--data "token=" \
--data "old_pin=" \
--data "new_pin="

This action has an asynchronous response



Eq/Check_pin


HTTP Method - POST/GET


ParameterRequiredType Value/defaultDescription
action    *        stringcheck_pin     Main action - Validate entered PIN
token     *        string              Your API token
pin       *        int                 Your PIN code
curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=check_pin" \
--data "token=" \
--data "pin="

This action has asynchronous response

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


Server control and operations

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

Server control actions:

ResourceActionDescription
eq.phplistGet servers list, search for servers
eq.phpshowGet full information about the server
eq.phpupdate_serversRefresh the active server's list

Eq/List


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringlist Main action - Get servers list, search for servers. The "list" function returns the server's id which matched search criteria. 
default (no extra parameters)                         Return all assigned server's ids
location              string               Show servers from a specific region. Possible values: RU, NL and US. Example: location=RU,NL (all servers from RU 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 ids
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 group=1CPU,AMD (mean all servers with groups 1CPU AND AMD)
For search inside server's tags  API call resource tags, action user_search. More information in the Tags documentation.

curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=list" \
--data "token=" \

Eq/Show


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringshow Main action - The show action provides full data about the specific server. 
token      *        string              Your session token
id     *        int              Your server ID
curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=show" \
--data "token=" \
--data "id="


Eq/Update_servers


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringupdate_serversMain action - 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. 
token      *        string              Your session token
ResourceActionHTTP MethodDescription
curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=update_servers" \
--data "token=YOUR_USER_TOKEN"


Server's power operations

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

Server power actions:

ResourceActionDescription
eq.phpstatusget power status
eq.phpsensorsGet sensors data (bare-metal only)
eq.phponTurn power on
eq.phpoffTurn power off
eq.phprebootReboot server

Eq/Status


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringstatus Main action - Get power status
token     *        string              Your session token
id     *        int              Your server ID
curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=status" \
--data "token=" \
--data "id="


This action has asynchronous response



Eq/Sensors (bare-metal only)


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringsensors Main action - Get sensors data
token     *        string              Your session token
id     *        int              Your server ID
curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=sensors" \
--data "token=" \
--data "id="


This action has asynchronous response


Eq/On


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringon Main action - Turn power on
token     *        string              Your session token
id     *        int              Your server ID
pin     *        int              Your PIN code
curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=on" \
--data "token=" \
--data "id=" \
--data "pin="


This action has asynchronous response 


Eq/Off


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringoff Main action - Turn power off
token     *        string              Your session token
id     *        int              Your server ID
pin     *        int              Your PIN code
curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=off" \
--data "token=" \
--data "id=" \
--data "pin="


This action has asynchronous response


Eq/Reboot


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringreboot Main action - Reboot server
token     *        string              Your session token
id     *        int              Your server ID
pin     *        int              Your PIN code
ResourceActionHTTP MethodDescription
eqonPOSTReboot server
curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=reboot" \
--data "token=" \
--data "id=" \
--data "pin="


This action has asynchronous response


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.

Async keys for all NAT operations should be checked with nat_callback.php, i.e.

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

Remote access actions for bare-metal:

ResourceActionDescription
nat.phpadd_static_natCreate static DNAT pass-through rule to server's IPMI (public IP to access IPMI of the server)
nat.phpremove_static_natRemove static DNAT pass-through to server's IPMI
eq.phpadd_ipmi_userCreate temp IPMI user for IPMI web access
eq.phpremove_ipmi_userRemove temp IPMI user for IPMI web access
eq.phpunit_resetReset IPMI module

Nat/Add_static_nat


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringadd_static_nat Main action - create static DNAT pass-through rule to server's IPMI (public IP to access IPMI of the server)
token     *        string               Your session token
id     *        int                Your server ID
pin     *        int                Your PIN code
curl -s "https://invapi.hostkey.com/nat.php" -X POST \
--data "action=add_static_nat" \
--data "token=" \
--data "id=" \
--data "pin="


This action has asynchronous response.


Nat/Remove_static_nat


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringremove_static_nat Main action - remove static DNAT pass-through to server's IPMI
token     *        string               Your session token
id     *        int                Your server ID
curl -s "https://invapi.hostkey.com/nat.php" -X POST \
--data "action=remove_static_nat" \
--data "token=" \
--data "id="


This action has asynchronous response.


Eq/Add_ipmi_user


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringadd_ipmi_user Main action - create temp IPMI user for IPMI web access
token     *        string               Your session token
id     *        int                Your server ID
curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=add_ipmi_user" \
--data "token=" \
--data "id="

This action has asynchronous response.


Eq/Remove_ipmi_user


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringremove_ipmi_user Main action - remove temp IPMI user for IPMI web access
token     *        string               Your session token
id     *        int                Your server ID
curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=remove_ipmi_user" \
--data "token=" \
--data "id= "


This action has asynchronous response.


Eq/Unit_reset


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringunit_reset Main action - reset IPMI module. In some cases it's necessary to reset the IPMI module, it may fall unresponsive or failed to perform some operations. Cold reset may help
token     *        string               Your session token
id     *        int                Your server ID
pin     *        int                Your PIN code
curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=unit_reset" \
--data "token=" \
--data "id=" \
--data "pin="


This action has asynchronous response.


Virtual servers

Remote access actions for Virtual Machines:

ResourceActionDescription
eq.phpconsoleGet access to VM console

Eq/Console


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringconsole Main action - get access to VM console
token     *        string               Your session token
id     *        int                Your server ID
pin     *        int                Your PIN code
curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=console" \
--data "token=" \
--data "id=" \
--data "pin="


This action has asynchronous response.


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);
}

Remote hands requests (RHR)

Some servers do not have a remote control. Our duty shift could perform necessary power actions and connect external IP KVM to the server. This could be done via API, which will create tickets in our Service desk software (Remote Hand Request - RHR).

Remote hands actions:

ResourceActionDescription
jira.phprequest_ponOpen RHR to power on the server
jira.phprequest_poffOpen RHR to power down the server
jira.phprequest_rebootOpen RHR to reboot the server
jira.phprequest_PXEbootOpen RHR to boot the server from PXE
jira.phprequest_kvmOpen RHR to connect IP KVM to the server
jira.phprequest_checkOpen RHR to check and load the server into OS

Each action will create JIRA ticket TICKET_ID accessible via https://my.hostkey.com/servicedesk/customer/portal/1/TICKET_ID with subject and message on behalf of the user. The user will receive an email message with confirmation. After the requested action was performed, the duty shift will communicate with the customer via this ticket.

Jira/Request_pon


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringrequest_ponMain action - Open RHR to power on the server
token     *        string              Your session token
id     *        int              Your server ID
curl -s "https://invapi.hostkey.com/jira.php" -X POST \
--data "action=request_pon" \
--data "token=" \
--data "id="


Jira/Request_poff


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringrequest_poffMain action - Open RHR to power down the server
token     *        string              Your session token
id     *        int              Your server ID
curl -s "https://invapi.hostkey.com/jira.php" -X POST \
--data "action=request_poff" \
--data "token=" \
--data "id="


Jira/Request_reboot


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringrequest_rebootMain action - Open RHR to reboot the server
token     *        string              Your session token
id     *        int              Your server ID
curl -s "https://invapi.hostkey.com/jira.php" -X POST \
--data "action=request_reboot" \
--data "token=" \
--data "id="


Jira/Request_PXEboot


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringrequest_PXEbootMain action - Open RHR to boot the server from PXE. This request is required during the reinstall process when the server without remote control unit should be booted from PXE to start the reinstall process.
token     *        string              Your session token
id     *        int              Your server ID

curl -s "https://invapi.hostkey.com/jira.php" -X POST \
--data "action=request_PXEboot" \
--data "token=" \
--data "id="


Jira/Request_kvm


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringrequest_kvmMain action - Open RHR to connect IP KVM to the server. The duty shift will connect the IP KVM device to the server
token     *        string              Your session token
id     *        int              Your server ID
curl -s "https://invapi.hostkey.com/jira.php" -X POST \
--data "action=request_kvm" \
--data "token=" \
--data "id="


Jira/Request_check


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringrequest_checkMain action - Open RHR to check and load the server into OS. The duty shift will check the server and try to bring it back online.
token     *        string              Your session token
id     *        int              Your server ID
curl -s "https://invapi.hostkey.com/jira.php" -X POST \
--data "action=request_check" \
--data "token=" \
--data "id="


Reinstall procedures and options

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

  1. Create reinstall stage key (optional);
  2. Create PXE config with parameters;
  3. Change boot order for the server to start with PXE;
  4. Reboot the server;
  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. Change boot order back to HDD;
  8. Run extra Jenkins task on a server (i.e. install GPU drivers);
  9. Remove PXE config to avoid a sudden reinstall.

Reinstall procedures data:

ResourceActionDescription
eq.phpreinstallCreate master key for reinstall
os.phplistGet a list of OS for a server
jenkins.phpget_tasksRetrieve available Ansible tasks
eq.phpcreate_pxeCreate PXE config for OS install
eq.phpboot_devSet boot order for VM or bare-metal server
eq.phprebootReboot server

Stage 0: Create an optional reinstall key

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 call.

Eq/Reinstall


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringreinstall Main action - Create master key for reinstall
token     *        string               Your session token
id     *        int                Your server ID

curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=reinstall" \
--data "token=" \
--data "id=" \


Stage 1: Create PXE config

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

Os/list


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringlistMain action - Get a list of OS for a server
token     *        string               Your session token
id     *        int                Your server ID

Retrieve JSON with a suitable OS list for a specific server with server_id (25250 for example). The only applicable OSes will be listed.

Notable tags will be provided for each OS to generate proper UI:

  • bm - this OS could run on a bare-metal server;
  • gpu - OS could run on GPU server;
  • vgpu - OS could run on vGPU server (VM with GPU in PCIe pass-through mode);
  • vm - OS could run on a virtual machine (VPS);
  • min_ram - minimal requirements for RAM in Gb;
  • min_hdd - minimal requirements for HDD in Gb;
  • price_per_core_EUR - price per core for MS SPLA licenses in EUR without applicable VAT. Minimal 8 licenses are required with increment van 2;

curl -s "https://invapi.hostkey.com/os.php" -X POST \
--data "action=list" \
--data "token=" \
--data "id=" \


The user should select hostname and password.

Disk partitioning scheme:

According to the number of storage devices in the server, the user should decide which partitioning will be used:

  1. LVM_RAID0 - create stripe across all disks via LVM;
  2. LVM_HBA - install OS on the smallest device, let the rest untouched, applicable if there are more than 1 storage device;
  3. LVM_RAID1 - create disk mirror via LVM, applicable if there are two similar storage devices;
  4. LVM_RAID10 - create LVM RAID10 across all storage device pairs, minimum 2 pairs of devices required;
  5. LVM_RAID10S - create LVM RAID1 on smallest storage devices pairs for OS, create LVM RAID10 on rest of storage devices pars. 
  • Public ssh key - if the customer wants to install one for the administrative user, he could provide it for configuration request.
  • Post-install task - standardized Ansible tasks which could be run on the server after installation via Jenkins.

You could retrieve applicable tasks via jenkins/list call:

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


ParameterRequiredType Value/defaultDescription
action    *        stringget_tasksMain 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.

curl -s "https://invapi.hostkey.com/jenkins.php" -X POST \
--data "action=get_tasks" \


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


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringcreate_pxeMain action - Create PXE config for OS install
token     *        string               Your session token
id     *        int                Your server ID
pin     *        int                Your PIN code
os_id     *        int                Selected 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
post_install_callback            string                URL to call after install is completed
post_install_script           string                Post-install script to run
reinstall_key          string                optional key from eq/reinstall to keep track of reinstall stages. All reinstall stages will be reported from this key via eq_callback.php?action=check&key=reinstall_key_value

curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=create_pxe" \
--data "token=" \
--data "email=" \
--data "pin=" \
--data "id=" \
--data "os_id=" \
--data "root_pass=" \
--data "hostname=" \
--data "ssh_key=" \
--data "post_install_callback=" \
--data "post_install_script=" \
--data "reinstall_key=" \


This action has asynchronous response


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

Eq/Boot_dev


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringboot_devMain action - Set boot order for VM or bare-metal server
token     *        string               Your session token
pin     *        int                Your PIN code
id     *        int                Your server ID
media - pxe             int                 for PXE boot, disk for local storage device boot, cd for mounted CD boot (usually via virtual media via IPMI) 

curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=boot_dev" \
--data "token=" \
--data "id=" \
--data "pin=" \


This action has asynchronous response


After successful change of boot order we should reboot server.

Eq/Reboot


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringrebootMain action - Reboot server
token     *        string               Your session token
pin     *        int                Your PIN code
id     *        int                Your server ID

curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=reboot" \
--data "id=" \
--data "token=" \
--data "pin=" \


This action has asynchronous response


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


curl -s "https://invapi.hostkey.com/eq_callback.php" -X POST \
--data "action=check" \
--data "key=" \


When "result" key is "Stage" - this means its informative message about status progress. "scope" key contains user-readable information. "context" key helps us to keep track of installation data, it contains main action, server id and it's location. "key" is master reinstall key.

There will be 5 such a notifications, last one will be.



If we 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.

Post-install tasks and cleanup:

Eq/boot_dev


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringboot_devMain action - Switch boot order back to disk
token     *        string               Your session token
id     *        int                Your server ID
media    *        int                Switch boot order back to disk
pin     *        int                Your PIN code

curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=boot_dev" \
--data "token=" \
--data "id=" \
--data "media=" \
--data "pin=" \

This action has asynchronous response


Eq/clear_pxe

Сlear PXE config to avoid sudden reinstalls.


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringclear_pxeMain action - Clear PXE config to avoid sudden reinstalls
token     *        string               Your session token
id     *        int                Your server ID
hostname    *        string    Your server name

curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=clear_pxe" \
--data "token=" \
--data "id=" \
--data "hostname=" \


This action has asynchronous response


Network operations

Network operations data:

ResourceActionDescription
net.phpget_statusRetrieve interface status
net.phpport_offDisable interface
net.phpport_onEnable interface
net.phpshow_cactiEnable interface
ip.phpshow_cactiGet IP information
ip.phpget_ptrGet PTR record for IP
ip.phpupdate_ptrUpdate PTR record for IP
ip.phpset_mainSet IP option for a server
net.phpblock_ipBlock specific IP
net.phpunblock_ipUnblock specific IP

Net/ Get_status


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringget_status Main action - Retrieve interface status
token     *        string               Your session token
id     *        int                Your server ID
pin     *        int                Your 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

curl -s "https://invapi.hostkey.com/net.php" -X POST \
--data "action=get_status" \
--data "token=" \
--data "id=" \
--data "port= \
--data "
pin=" \


This action has asynchronous response.


Net/Port_off


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringport_off Main action - Disable interface
token     *        string               Your session token
id     *        int                Your server ID
pin     *        int                Your PIN code
port    *       string                Physical port's switch

curl -s "https://invapi.hostkey.com/net.php" -X POST \
--data "action=port_off" \
--data "token=" \
--data "id=" \
--data "port=physical port's switch" \
--data "pin=" \


This action has asynchronous response.


Net/Port_on


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringport_on Main action - Enable interface
token     *        string               Your session token
id     *        int                Your server ID
pin     *        int                Your PIN code
port    *       string                Physical port's switch

curl -s "https://invapi.hostkey.com/net.php" -X POST \
--data "action=port_on" \
--data "token=" \
--data "id=" \
--data "port=" \
--data "pin=" \


This action has asynchronous response.


Net/Show_cacti


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringshow_cacti Main action - Show port speed graphs
token     *        string               Your session token
id     *        int                Your server ID
pin     *        int                Your PIN code
port    *       string                Physical port's switch
graph   *       string                Graph values - 1 for daily, 2 for monthly, 3 for annual graphs

curl -s "https://invapi.hostkey.com/net.php" -X POST \
--data "action=show_cacti" \
--data "token=" \
--data "id=" \
--data "port=" \
--data "graph=" \

Response:  traffic graph image

Ip/Get_ip


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringget_ip Main action - Get IP information
token     *        string               Your session token
ip     *        int                Your IP address

curl -s "https://invapi.hostkey.com/ip.php" -X POST \
--data "action=get_ip" \
--data "token=" \
--data "ip=" \


Get_ptr


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringget_ptr Main action - Get PTR record for IP
token     *        string               Your session token
id     *        int                Your server ID
ip     *        int                Your IP address

curl -s "https://invapi.hostkey.com/ip.php" -X POST \
--data "action=get_ptr" \
--data "token=" \
--data "id=" \
--data "ip=" \


Ip/Update_ptr

There are allowed to have more than one reverse record for IP. Supplying several RRs could be done with a %0A separator. 


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringupdate_ptr Main action - Update PTR record for IP
token     *        string               Your session token
id     *        int                Your server ID
ip     *        int                Your IP address
ptr    *        string                Your ptr data

curl -s "https://invapi.hostkey.com/ip.php" -X POST \
--data "action=update_ptr" \
--data "token=" \
--data "id=" \
--data "ip=" \
--data "ptr=" \


Ip/Set_main


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringset_mainMain action - Set IP option for a server
token     *        string               Your session token
id     *        int                Your server ID
ip     *        int                Your IP address
main    *        int               Ip address to be set as main 

If a server has several IPs assigned, one should be marked as "main" for installation purposes, the config will be created only for the main IP, and the rest of the server will be configured with it.


curl -s "https://invapi.hostkey.com/ip.php" -X POST \
--data "action=set_main" \
--data "token=" \
--data "id=" \
--data "ip=" \
--data "main=" \


Net/Block_ip

With this call you could block the specific IP on a server, this is useful to manage abuse requests. This is done on HOSTKEY's network layer.


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringblock_ipMain action - Block specific IP
token     *        string               Your session token
id     *        int                Your server ID
ip     *        int                Your IP address
pin     *        int                Your PIN code
description            string               The reason for the block
four_hours           int               If set, the block will be automatically lifted after 4 hours.

curl -s "https://invapi.hostkey.com/net.php" -X POST \
--data "action=block_ip" \
--data "token=" \
--data "id=" \
--data "ip=" \
--data "pin=" \
--data "description=this+is+block+test" \
--data "four_hours=1" \


This action has asynchronous response


Net/Unblock_ip


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringunblock_ipMain action - Unblock specific IP
token     *        string               Your session token
id     *        int                Your server ID
ip     *        int                Your IP address
pin     *        int                Your PIN code

curl -s "https://invapi.hostkey.com/net.php" -X POST \
--data "action=unblock_ip" \
--data "token=" \
--data "id=" \
--data "ip=" \
--data "pin=" \


This action has asynchronous response


Billing interaction

Billing actions:

ResourceActionDescription
whmcs.phpget_clientGet customer information
whmcs.phpcreate_addfundsCreate add funds invoice
whmcs.phpgetpaymentgwGet information how to pay this invoice
whmcs.phpget_billing_dataThis call retrieve billing information for the server.

Whmcs/Get_client

HOSTKEY is using WHMCS as billing software.  With get_client you will have necessary customer data from billing. Important keys are in bold.


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringget_client Main action - Get customer information
token      *        string              Your session token

curl -s "https://invapi.hostkey.com/whmcs.php" -X POST \
--data "action=get_client" \
--data "token=" \


Whmcs/Create_addfunds


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action   *        stringcreate_addfundst Main action - Create add funds invoice
amount *        int               Replenishment amount
token    *        string              Your session token

curl -s "https://invapi.hostkey.com/whmcs.php" -X POST \
--data "action=create_addfunds" \
--data "amount=" \
--data "token=" \


Whmcs/Getpaymentgw


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action   *        stringgetpaymentgw Main action - Get information how to pay this invoice
invoice_id *        int               Invoice id number
token    *        string              Your session token

curl -s "https://invapi.hostkey.com/whmcs.php" -X POST \
--data "action=getpaymentgw" \
--data "invoice_id=" \
--data "token=" \


In order to proceed with this invoice, you should show HTML from the "call" key to the customer. It contains all the necessary form data to proceed with payment. When customer's pay, it will increase account credit. You could check the actual credit amount with whmcs/get_client  call 

Whmcs/Get_billing_data


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action   *        string get_billing_data Main action - this call retrieve billing information for the server.
id *        int               Server token
token    *        string              Your access token

curl -s "https://invapi.hostkey.com/whmcs.php" -X POST \
--data "action=get_billing_data" \
--data "token=" \
--data "id=" \


Instant servers (standard automated servers)

HOSTKEY provides several basic services:

  • custom build servers - single and dual CPU servers built according to customer's specifications from the last generation hardware
  • standard configurations (instances): compute (VM), bare-metal, gpu bare-metals, and vGPU servers (VM with PCIe-passthrough GPU). Those configurations are stocked up and deployed automatically in 10-20 minutes. 
  • stock servers - bare metals from old generations, non-standard configurations, servers without remote control modules.
  • Ryzen/i9/i10 servers - high-speed single-CPU servers built around the latest Ryzen9 or i9/i10 CPUs, usually without a remote control.

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.

Order instant servers actions:

ResourceActionDescription
presets.phplist Get a list of available instances for a region
os.phplist Get OS list for a specific instance
traffic_plans.phplist Get appropriate traffic plans for specific instance
eq.phporder_instance Order a specific instance

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

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

Presets/List

locations are currently RU, NL, and the US. Using this call you could check availability and retrieve a fresh list of available instances with all basic pricing. No access token is required.


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringlist Main action - Get a list of available instances for a region
location     *        string               Instances location

curl -s "https://invapi.hostkey.com/presets.php" -X POST \
--data "action=list" \
--data "location=" \


In order to place an order, we should retrieve the appropriate OS and post-install tasks list.

OS/List

Basically, you could safely ignore all the tags with this request. The call will return only suitable OS for the specific instance. All Windows license prices are already calculated.

Please note, all prices are provided only to create proper UI - it will be calculated again in the backend during order.


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringlist Main action - Get OS list for a specific instance
location     *        string               Instances location
instance_id     *        int          id specific instance

curl -s "https://invapi.hostkey.com/os.php" -X POST \
--data "action=list" \
--data "instance_id=" \


Traffic_plans/List


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringlist Main action - Get appropriate traffic plans for specific instance
location     *        string               Instances location
instance_id     *        int          Id specific instance

curl -s "https://invapi.hostkey.com/traffic_plans.php" -X POST \
--data "action=list" \
--data "location=" \
--data "instance=" \


Eq/Order_instance


HTTP Method - POST


ParameterRequiredType Value/defaultDescription
action    *        stringorder_instance Main action - Order a specific instance
token         *    string                         Your session token
deploy_period      *    string                         Monthly, quarterly, semi-annualy, annually. Discounts for server is 3, 6 and 12%, not including traffic plans and licenses
deploy_notify *  string                         Notify customer by email about successful deployment
pin     *    int                          Your security PIN
id *  int                          Server id is not known yet
os_id     *    int                          OS id from the os/list
root_pass  string                         Default root password
hostname           string                         Default hostname
ssh_key      string                         Public ssh key to root user
post_install_callback  string                         URL to call after successful deployment
post_install_script    string                         Сode to run after successful deployment
os_name   string                         OS name in readable format
own_os         string                         If set into 1, instance will be delivered without reinstall. Usefull if you would like interactively reinstall it later
jenkins_task  string                         Jenkins task id to run after deployment, -1 if you don't need it
traffic_plan  *   string                         Selected traffic plan ID
preset *    string                         Instance code to be deployed
location_name *  string                         NL/RU/US 

curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=order_instance" \
--data "token=" \
--data "deploy_period=" \
--data "deploy_notify=" \
--data "email=" \
--data "pin=" \
--data "id=-" \
--data "os_id=" \
--data "root_pass=" \
--data "hostname=" \
--data "ssh_key=" \
--data "post_install_callback=" \
--data "post_install_script=" \
--data "reinstall_key=" \
--data "os_name=" \
--data "imitate_deploy=" \
--data "imitate_error=" \
--data "own_os=0" \
--data "jenkins_task=" \
--data "traffic_plan=" \
--data "invoice_relid=" \
--data "preset=" \
--data "location_name=" \

After receiving the request, INVAPI will select/create an appropriate server in a specific location and proceed with its deployment. Before any install, it will check funds availability on a credit account. If install will be successful, a new server will be linked to the customer's account. Customer will be notified by email if requested. All paid licenses will be added as order addons.

This action has an asynchronous response


This action has asynchronous response


After "result" OK you could start using this server. If there will be any failure, you will be notified. Please note what deployment could take up to 20 minutes, usually 5-10 minutes.

Tags: