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 operations with the servers could take along and exceed the usual script execution time. To manage it we created asynchronous operations - you send a request to action and may check its status via API call. As it will be done, it will return the call result.

If results couldn't be returned right now - API call will return the async key.


Example:

Step 1 Request to reboot server with id 10000:

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 asyncronous request was successfully sent, key to keep track of it is f685eaa0f06e47faa2e6bb5002828b00


Step 2 You could track request state:

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

Response:

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

the operation is not completed yet, try again later.


Step 3 When calling second time in a second, we receive the final response:

{
 "result": "OK",
 "scope": "Host is on",
 "context": {
   "action": "on",
   "id": "SERVER_ID",
   "location": "NL"
  },
 "debug": "Chassis Power Control: Up/On",
 "key": "f685eaa0f06e47faa2e6bb5002828b00"
}
scopemessage to the user
contextJSON with the initial request and some extra data. Useful to proceed during AJAX calls
debughardware output from the device, if any
keyour async key. It is deleted after a 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 data:

Data IDData TypeDescription
idintegerunique tag identifier
tagstringtag itself, tag name
valuestringtag value
extrastringextra value if necessary to keep several values for the key

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.

Tag actions:

ActionDescription
addAction add a tag to the server or change existing tag
removeAction removes a tag for a server
listAction gets all tags for the server
user_searchAction find the servers with tags

Add

ResourceActionHTTP MethodDescription
tagsaddPOSTAction add a tag to the server or change existing tag


Remove

ResourceActionHTTP MethodDescription
tagsremovePOSTAction removes a tag for a server

List

ResourceActionHTTP MethodDescription
tagslistPOSTAction retirive all tags from the server server_id


ResourceActionHTTP MethodDescription
tagsuser_searchPOSTThis request searches for servers IDs with tag name or value mathing search_pattern as a substing. 


Authorization

To start with API, you need to get an authorization token first from the authorization script: invapi.hostkey.com/auth.php

Input data:

Data IDData TypeDescription
userstringyour WHMCS (billing) user email user@domain.tld
passwordstringyour WHMCS password
tokenstringyour session token

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.
If you have an active session, you will get an existing token. The token is valid for 2 hours.  The token is assigned to your IP. If IP will change, you will need to get the token again.

Authorization script actions:

ActionDescription
whmcsloginThe action to obtain an access token with your billing credentials
logoutThe action removes the security token
infoThe action gets security token environment

whmcslogin - get access token for billing credentials

ResourceActionHTTP MethodDescription
authwhmcsloginPOSTObtain an access token

Example to obtain a new access token to API via cURL:

curl -s "https://invapi.hostkey.com/auth.php" -X POST \
--data "action=whmcslogin" \
--data "user=YOUR_USERNAME" \
--data "password=SECURE_PASSWORD"



logout - remove access token

ResourceActionHTTP MethodDescription
authwhmcsloginPOSTAction logout will remove auth token from the database. Please do not forget to log out to avoid possible security issues.

Example remove access token via API access cURL:

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

info - get the token scope and access data

ResourceActionHTTP MethodDescription
authinfoPOSTAction will return full data about your token including the assigned server's identification numbers. 

Example obtain token info cURL:

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



PIN-codes

We are trying to keep our customer's servers safe, even in case of data leaks or account compromises. The user sets his own PIN on the initial login and the system will ask for this PIN for every critical server's operation.

PINs hashes are stored very separately from our billing and inventory databases.

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.

There are some API functions to manage PIN with resource eq

set_pin - change or set user's PIN

ResourceActionHTTP MethodDescription
eqset_pinPOSTset/change user's PIN

Example set/change PIN cURL:

curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=set_pin" \
--data "token=YOUR_API_TOKEN" \
--data "old_pin=YOUR_PREVIOUS_PIN_CODE (optional)" \
--data "new_pin=NEW_PIN_VALUE"


This action has asynchronous response via https://invapi.hostkey.com/eq_callback.php?action=check&key=XXXX:



check_pin - validate user's PIN

ResourceActionHTTP MethodDescription
eqcheck_pinPOSTvalidate entered PIN (optional)

Example validate pin cURL:

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


This action has asynchronous response via https://invapi.hostkey.com/eq_callback.php?action=check&key=XXXX:



After several failures API will return only failed responses with long delays to avoid brute-force attempts.

Server control and operations

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

Server control actions:

ActionDescription
listGet servers list, search for servers
showGet full information about the server
update_serversRefresh the active server's list

List

ResourceActionHTTP MethodDescription
eqlistPOSTGet servers list, search for servers. The "list" function returns the server's id which matched search criteria. 

Possible search keys:

  • default (no extra parameters) - return all assigned server's ids
  • location - show servers from a specific region. Possible values: RU, NL and US. Example: location=RU,NL (all servers from RU and NL regions)
  • status - 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 - servers with a specific component like CPU or GPU. Usage component=12345,5456,.. where numbers are components ids.
  • ip - server with specific IP address. Example: ip=199.100.7.5
  • mac - server with specific MAC address.  Example: mac=00.00.00.00.00.00
  • group:
    • Mini - compact servers with single CPU and IPMI
    • Storage - servers intended to be used as a storage
    • Nodes - servers intend to be used as virtualization nodes
    • Micro - servers with single CPU and without IPMI
    • VPS - virtual servers
    • 1CPU - servers with single CPU
    • 2CPU - servers with dual CPU's
    • Dell - Dell branded servers
    • Gpu - GPU servers
    • Instances - Servers with standard configuration and full remote control
    • AMD - 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.


Show

ResourceActionHTTP MethodDescription
eqshowPOSTThe show action provides full data about the specific server.

Data: id - server's id



Update_servers

ResourceActionHTTP MethodDescription
equpdate_serversPOSTRefresh 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


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:

ActionDescription
StatusGet power status
SensorsGet sensors data
OnTurn power on
OffTurn power off
RebootReboot server

Status

ResourceActionHTTP MethodDescription
eqstatusPOSTGet power status


This action has asynchronous response via https://invapi.hostkey.com/eq_callback.php?action=check&key=XXXX:



Sensors (bare-metal only)

ResourceActionHTTP MethodDescription
eqsensorsPOSTGet sensors data


This action has asynchronous response via https://invapi.hostkey.com/eq_callback.php?action=check&key=XXXX:


On

ResourceActionHTTP MethodDescription
eqonPOSTTurn power on


This action has asynchronous response via https://invapi.hostkey.com/eq_callback.php?action=check&key=XXXX:


Off

ResourceActionHTTP MethodDescription
eqoffPOSTTurn power off


This action has asynchronous response via https://invapi.hostkey.com/eq_callback.php?action=check&key=XXXX:


Reboot

ResourceActionHTTP MethodDescription
eqonPOSTReboot server


This action has asynchronous response via https://invapi.hostkey.com/eq_callback.php?action=check&key=XXXX:


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
natadd_static_natCreate static DNAT pass-through rule to server's IPMI (public IP to access IPMI of the server)
natremove_static_natRemove static DNAT pass-through to server's IPMI
eqadd_ipmi_userCreate temp IPMI user for IPMI web access
eqremove_ipmi_userRemove temp IPMI user for IPMI web access
eqUnit_resetReset IPMI module

Add_static_nat

ResourceActionHTTP MethodDescription
natadd_static_natPOSTcreate static DNAT pass-through rule to server's IPMI (public IP to access IPMI of the server)


This action has asynchronous response via https://invapi.hostkey.com/nat_callback.php?action=check&key=XXXX:


Remove_static_nat

ResourceActionHTTP MethodDescription
natremove_static_natPOSTremove static DNAT pass-through to server's IPMI


This action has asynchronous response via https://invapi.hostkey.com/nat_callback.php?action=check&key=XXXX:


Add_ipmi_user

ResourceActionHTTP MethodDescription
eqadd_ipmi_userPOSTCreate temp IPMI user for IPMI web access


This action has asynchronous response via https://invapi.hostkey.com/eq_callback.php?action=check&key=XXXX:


Remove_ipmi_user

ResourceActionHTTP MethodDescription
eqremove_ipmi_userPOSTRemove temp IPMI user for IPMI web access


This action has asynchronous response via https://invapi.hostkey.com/eq_callback.php?action=check&key=XXXX:


Unit_reset

ResourceActionHTTP MethodDescription
equnit_resetPOSTReset 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


This action has asynchronous response via https://invapi.hostkey.com/eq_callback.php?action=check&key=XXXX:


Virtual servers

Remote access actions for Virtual Machines:

ResourceActionDescription
eqconsoleGet access to VM console

Console

ResourceActionHTTP MethodDescription
eqconsolePOSTGet access to VM console


This action has asynchronous response via https://invapi.hostkey.com/eq_callback.php?action=check&key=XXXX:


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
jirarequest_ponOpen RHR to power on the server
jirarequest_poffOpen RHR to power down the server
jirarequest_rebootOpen RHR to reboot the server
jirarequest_PXEbootOpen RHR to boot the server from PXE
jirarequest_kvmOpen RHR to connect IP KVM to the server
jirarequest_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.

Request_pon

ResourceActionHTTP MethodDescription
jirarequest_ponPOSTOpen RHR to power on the server


Request_poff

ResourceActionHTTP MethodDescription
jirarequest_poffPOSTOpen RHR to power down the server


Request_reboot

ResourceActionHTTP MethodDescription
jirarequest_rebootPOSTOpen RHR to reboot the server


Request_PXEboot

ResourceActionHTTP MethodDescription
jirarequest_PXEbootPOSTOpen 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.


Request_kvm

ResourceActionHTTP MethodDescription
jirarequest_kvmPOSTOpen RHR to connect IP KVM to the server. The duty shift will connect the IP KVM device to the server


Request_check

ResourceActionHTTP MethodDescription
jirarequest_checkPOSTOpen RHR to check and load the server into OS. The duty shift will check the server and try to bring it back online.


Reinstall procedures and options

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

  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 tsks
    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

Step 0: Create 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

You may create one with action reinstall for eq resource:

Reinstall

ResourceActionHTTP MethodDescription
eqreinstallPOSTCreate an optional reinstall key


Step 1: Create PXE config

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

Os/List

ResourceActionHTTP MethodDescription
eqreinstallPOSTGet a list of OS for a server with all necessary information

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.
  • price_per_core_RUR - price per core for MS SPLA licenses in RUR including Russian VAT. Minimal 8 licenses are required with increment van 2.


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

ResourceActionHTTP MethodDescription
jenkinsget_tasksPOSTThis action 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.

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

ResourceActionHTTP MethodDescription
eqcreate_pxePOSTCreate PXE config for OS install

Data:

  • token - the access token
  • email - billing email (optional)
  • pin - PIN code
  • id - server id
  • os_id - selected OS id from os/list
  • root_pass - password for the administrative user. length and content should meet security policy  - min 8 symbols, with some numbers and letters in caps.
  • hostname - desired hostname for the server
  • ssh_key - public ssh key (optional)
  • post_install_callback - URL to call after install is completed (optional)
  • post_install_script - post-install script to run (optional)
  • reinstall_key - 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




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

Step 2: Set boot order for VM or bare-metal server

Eq/Boot_dev

ResourceActionHTTP MethodDescription
eqboot_devPOSTSet boot device for VM or bare-metal server

Data:

  • media - pxe for PXE boot, disk for local storage device boot, cd for mounted CD boot (usually via virtual media via IPMI) 




After successful change of boot order we should reboot server:

Step 3: Server reboot

Eq/Reboot

ResourceActionHTTP MethodDescription
eqrebootPOSTReboot virtual or bare-metal server



The system will reboot and start loading from PXE.

Step 4: Installation stages control

After the OS installer is loaded, you will see stage notifications - it could be retrieved with the main reinstall key from eq/reinstall

Eq_callback/Check

ResourceActionHTTP MethodDescription
eq_callbackcheckPOSTThe check action provides data about server installation stage.


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.



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.

Step 5: Post-install tasks and cleanup

  • Switch boot order back to disk:
curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=boot_dev" \
--data "token=YOUR_USER_TOKEN" \
--data "id=SERVER_ID" \
--data "pin=YOUR_PIN_CODE" \
--data "media=disk"


  • Clear PXE config to avoid sudden reinstalls:
curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=clear_pxe" \
--data "token=YOUR_USER_TOKEN" \
--data "id=SERVER_ID" \
--data "hostname=HOSTNAME"



Network operations

Net - Network control resource

net/get_status - get network interface status

ResourceActionHTTP MethodDescription
netget_statusPOSTAction to retrieve interface status

Data:

  •  port  - port name (ipmi, eth0 etc)




Key's description for a response:

  • switch - switch id and address
  • port - physical port's switch
  • vlan - VLAN number if any
  • speed - physical interface speed 
  • status - interface status, connected or not
  • mac - mac information if any
  • port_security - the maximum allowed MACs on the port if any
  • shape - port speed limits if any

net/port_off - disable network interface

ResourceActionHTTP MethodDescription
netport_offPOSTNetwork interface disable

Input data:

  •  port  - port name (ipmi, eth0 etc)



net/port_on - enable network interface

ResourceActionHTTP MethodDescription
netport_onPOSTNetwork interface enable

Input data:

  •  port  - port name (ipmi, eth0 etc)



net/show_cacti - show traffic speed graph for a network interface

ResourceActionHTTP MethodDescription
netshow_cactiPOSTShow port speed graphs

Input data:

  •  port  - port name (ipmi, eth0 etc)
  •  graph  - 1 for daily, 2 for monthly, 3 for annual graphs


net/block_ip - block specific IP

ResourceActionHTTP MethodDescription
netblock_ipPOSTBlock specific 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.

Data:

  •  description  - the reason for the block
  •  four_hours  - if set, the block will be automatically lifted after 4 hours.



net/unblock_ip - unblock specific IP

ResourceActionHTTP MethodDescription
netunblock_ipPOSTUnblock specific IP



IP  - a resource to control address IP operations

ip/get_ip - retrieve IP information (netmask, gateway, etc)

ResourceActionHTTP MethodDescription
ipget_ipPOSTGet IP information

ip/get_ptr - get PTR records for specific IP

ResourceActionHTTP MethodDescription
ipget_ptrPOSTGet PTR record for IP

ip/update_ptr - update PTR record for specific IP

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

ip/set_main - set specific IP as main for a server

ResourceActionHTTP MethodDescription
ipset_mainPOSTSet IP option for a server. 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.

Billing interaction

HOSTKEY is using the WHMCS billing system to keep track of customer's services. Control panel API provides an easy way to retrieve necessary data and perform billing operations.

get_client - get customer's billing data

ResourceActionHTTP MethodDescription
whmcsget_clientPOSTGet customer billing data from billing system

create_addfunds - create add funds invoice to top-up funds for a customer account

ResourceActionHTTP MethodDescription
whmcscreate_addfundsPOSTCreate add funds invoice

getpaymentgw - return payment gateways information to proceed with invoice payment

in response, API will return HTML code for redirection to payment systems like PayPal to pay the specific invoice. You may 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_clinet  call 

ResourceActionHTTP MethodDescription
whmcsgetpaymentgwPOSTGet information on how to pay this invoice


get_billing_data - return billing information for a specific server

ResourceActionHTTP MethodDescription
whmcsget_billing_dataPOSTGet product billing information.

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 (VPS), 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.

presets/list - get standard server configurations list 

Call will return full information for standard servers, available in specific region - including pricing and availability.  

ResourceActionHTTP MethodDescription
presetslistPOSTGet a list of available instances for a region. 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.


os/list - get OS list for the specific server

ResourceActionHTTP MethodDescription
oslistPOSTGet OS list for a specific instance. 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.

traffic_plans/list - get traffic plans for the specific server

ResourceActionHTTP MethodDescription
traffic_planslistPOSTGet appropriate traffic plans for specific instance

eq/order_instance - place order for the specific standard server

ResourceActionHTTP MethodDescription
eqorder_instancePOSTOrder a specific instance

Data:

  • action - order_instance
  • token - your session token
  • deploy_period - monthly, quarterly, semi-annualy, annually. Discounts is 3, 6 and 12% resectivly, not including traffic plans and licenses.
  • deploy_notify - notify customer by email about successful deployment
  • pin - your security PIN
  • id - -1, server id is not known yet
  • os_id - OS id from the os/list
  • root_pass - default root password
  • hostname - default hostname
  • ssh_key - public ssh key to root user
  • post_install_callback - URL to call after successful deployement
  • post_install_script - code to run after successful deployment
  • os_name - OS name in readable format from os/list
  • own_os - if set into 1, instance will be delivered without reinstall. Usefull if you would like interactively reinstall it later
  • jenkins_task - jenkins task id to run after deployment, -1 if you don't need it
  • traffic_plan - selected traffic plan ID from traffic_plans/list
  • preset - instance code to be deployed
  • location_name - NL/RU/US 

After receiving the request, INVAPI will select an appropriate server in a specific location and proceed with its deployment. Before any install, it will check funds availability on a billing account. When server is ready, a new service 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.


Response keys description: 

  • callback - async key to track installation process
  • deploy_status - install means what install was started
  • id - new server id


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: