API-Documentation
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:
Example 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:
--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:
--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"
}
| scope | message to the user |
| context | JSON with initial request and some extra data. Usefull to proceed during AJAX calls |
| debug | hardware output from device |
| key | our 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:
| Resource | Action | Description |
|---|---|---|
| tags.php | add | Action add a tag to the server or change existing tag |
| tags.php | remove | Action removes a tag for a server |
| tags.php | list | Action gets all tags for the server |
| tags.php | user_search | Action find the servers with tags |
Tags/Add
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | add | 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:
--data "action=add" \
--data "token=" \
--data "id=" \
--data "tag=" \
--data "value=" \
--data "extra="
Example change existing tag cURL:
--data "action=add" \
--data "token=" \
--data "id=" \
--data "tag=" \
--data "value=" \
--data "extra="
Tags/Remove
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | remove | Main action - removes a tag from a server |
| token | * | string | Your session token | |
| id | * | int | Your server ID | |
| tag | * | string | Tag name |
--data "action=remove" \
--data "token=" \
--data "id=" \
--data "tag="
Tags/List
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | list | Main action - retrive all tags from the server server_id |
| token | * | string | Your session token | |
| id | * | int | Your server ID |
--data "action=list" \
--data "token=" \
--data "id="
Tags/User_search
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| 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 |
--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
Auth actions:
| Resource | Action | Description |
|---|---|---|
| auth.php | whmcslogin | Obtains a session token |
| auth.php | logout | Removes a session token |
| auth.php | info | Gets session token environment |
| eq.php | set_pin | set/change PIN for the user |
| eq.php | check_pin | validate entered PIN (optional) |
Auth/Whmcslogin
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | whmcslogin | Main action - Obtains an access token |
| user | * | string | Your billing login | |
| password | * | string | Your billing password | |
| fix_ip | int | fix_ip=0 - do not bind token to address, fix_ip=1 - bind | ||
| ttl | int | 10800 | Session lifetime in seconds, default 10800 (3 hours) |
--data "action=whmcslogin" \
--data "user=" \
--data "password="
Auth/Logout
HTTP Method - POST/GET
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | logout | 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 |
--data "action=logout" \
--data "token="
Auth/Info
HTTP Method - POST/GET
| 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 | Your API token |
--data "action=info" \
--data "token="
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.
Eq/Set_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 | Your API token | |
| old_pin | for change | int | Old PIN code | |
| new_pin | * | int | New PIN code |
--data "action=set_pin" \
--data "token=" \
--data "old_pin=" \
--data "new_pin="
Eq/Check_pin
HTTP Method - POST/GET
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | check_pin | Main action - Validate entered PIN |
| token | * | string | Your API token | |
| pin | * | int | Your PIN code |
--data "action=check_pin" \
--data "token=" \
--data "pin="
Server control and operations
Server control actions:
| 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
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) | 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.
--data "action=list" \
--data "token=" \
Eq/Show
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | show | Main action - The show action provides full data about the specific server. |
| token | * | string | Your session token | |
| id | * | int | Your server ID |
--data "action=show" \
--data "token=" \
--data "id="
Eq/Update_servers
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | update_servers | Main 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 |
| Resource | Action | HTTP Method | Description |
|---|
--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:
| 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
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | status | Main action - Get power status |
| token | * | string | Your session token | |
| id | * | int | Your server ID |
--data "action=status" \
--data "token=" \
--data "id="
Eq/Sensors (bare-metal only)
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | sensors | Main action - Get sensors data |
| token | * | string | Your session token | |
| id | * | int | Your server ID |
--data "action=sensors" \
--data "token=" \
--data "id="
Eq/On
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | on | Main action - Turn power on |
| token | * | string | Your session token | |
| id | * | int | Your server ID | |
| pin | * | int | Your PIN code |
--data "action=on" \
--data "token=" \
--data "id=" \
--data "pin="
Eq/Off
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | off | Main action - Turn power off |
| token | * | string | Your session token | |
| id | * | int | Your server ID | |
| pin | * | int | Your PIN code |
--data "action=off" \
--data "token=" \
--data "id=" \
--data "pin="
Eq/Reboot
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | reboot | Main action - Reboot server |
| token | * | string | Your session token | |
| id | * | int | Your server ID | |
| pin | * | int | Your PIN code |
| Resource | Action | HTTP Method | Description |
|---|---|---|---|
| eq | on | POST | Reboot server |
--data "action=reboot" \
--data "token=" \
--data "id=" \
--data "pin="
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.
Remote access actions for bare-metal:
| 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
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 | Your session token | |
| id | * | int | Your server ID | |
| pin | * | int | Your PIN code |
--data "action=add_static_nat" \
--data "token=" \
--data "id=" \
--data "pin="
Nat/Remove_static_nat
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | remove_static_nat | Main action - remove static DNAT pass-through to server's IPMI |
| token | * | string | Your session token | |
| id | * | int | Your server ID |
--data "action=remove_static_nat" \
--data "token=" \
--data "id="
Eq/Add_ipmi_user
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 | Your session token | |
| id | * | int | Your server ID |
--data "action=add_ipmi_user" \
--data "token=" \
--data "id="
Eq/Remove_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 | Your session token | |
| id | * | int | Your server ID |
--data "action=remove_ipmi_user" \
--data "token=" \
--data "id= "
Eq/Unit_reset
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | unit_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 |
--data "action=unit_reset" \
--data "token=" \
--data "id=" \
--data "pin="
Virtual servers
Remote access actions for Virtual Machines:
| Resource | Action | Description |
|---|---|---|
| eq.php | 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 | Your session token | |
| id | * | int | Your server ID | |
| pin | * | int | Your PIN code |
--data "action=console" \
--data "token=" \
--data "id=" \
--data "pin="
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:
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:
| Resource | Action | Description |
|---|---|---|
| jira.php | request_pon | Open RHR to power on the server |
| jira.php | request_poff | Open RHR to power down the server |
| jira.php | request_reboot | Open RHR to reboot the server |
| jira.php | request_PXEboot | Open RHR to boot the server from PXE |
| jira.php | request_kvm | Open RHR to connect IP KVM to the server |
| jira.php | request_check | Open 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
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | request_pon | Main action - Open RHR to power on the server |
| token | * | string | Your session token | |
| id | * | int | Your server ID |
--data "action=request_pon" \
--data "token=" \
--data "id="
Jira/Request_poff
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | request_poff | Main action - Open RHR to power down the server |
| token | * | string | Your session token | |
| id | * | int | Your server ID |
--data "action=request_poff" \
--data "token=" \
--data "id="
Jira/Request_reboot
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | request_reboot | Main action - Open RHR to reboot the server |
| token | * | string | Your session token | |
| id | * | int | Your server ID |
--data "action=request_reboot" \
--data "token=" \
--data "id="
Jira/Request_PXEboot
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | request_PXEboot | Main 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 |
--data "action=request_PXEboot" \
--data "token=" \
--data "id="
Jira/Request_kvm
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | request_kvm | Main 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 |
--data "action=request_kvm" \
--data "token=" \
--data "id="
Jira/Request_check
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | request_check | Main 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 |
--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:
- Create reinstall stage key (optional);
- Create PXE config with parameters;
- Change boot order for the server to start with PXE;
- Reboot the server;
- The server will catch the PXE bootloader and OS installation will go on;
- OS will report installation stages during install progress:
- 1st stage: OS installation was started;
- 2nd stage: base OS was installed, proceed with post-install tasks;
- 3rd stage: Post-install tasks are completed, running final tasks;
- 4th stage: Install is completed, restarting the server;
- 5th stage: The server is online;
- Change boot order back to HDD;
- Run extra Jenkins task on a server (i.e. install GPU drivers);
- Remove PXE config to avoid a sudden reinstall.
Reinstall procedures data:
| Resource | Action | Description |
|---|---|---|
| eq.php | reinstall | Create master key for reinstall |
| os.php | list | Get a list of OS for a server |
| jenkins.php | get_tasks | 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 |
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
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | reinstall | Main action - Create master key for reinstall |
| token | * | string | Your session token | |
| id | * | int | Your server ID |
--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
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | list | Main 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;
--data "action=list" \
--data "token=" \
--data "id=" \
Disk partitioning scheme:
According to the number of storage devices in the server, the user should decide which partitioning will be used:
- 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.
- 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
| 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.
--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
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | create_pxe | Main 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 |
--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=" \
If there was no errors, we need to set server's boot order to network boot via PXE.
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 | 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) |
--data "action=boot_dev" \
--data "token=" \
--data "id=" \
--data "pin=" \
After successful change of boot order we should reboot server.
Eq/Reboot
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | reboot | Main action - Reboot server |
| token | * | string | Your session token | |
| pin | * | int | Your PIN code | |
| id | * | int | Your server ID |
--data "action=reboot" \
--data "id=" \
--data "token=" \
--data "pin=" \
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
--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.
Post-install tasks and cleanup:
Eq/boot_dev
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | boot_dev | Main 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 |
--data "action=boot_dev" \
--data "token=" \
--data "id=" \
--data "media=" \
--data "pin=" \
Eq/clear_pxe
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | clear_pxe | Main action - Clear PXE config to avoid sudden reinstalls |
| token | * | string | Your session token | |
| id | * | int | Your server ID | |
| hostname | * | string | Your server name |
--data "action=clear_pxe" \
--data "token=" \
--data "id=" \
--data "hostname=" \
Network operations
Network operations data:
| 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 | Enable interface |
| 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
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | get_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 |
--data "action=get_status" \
--data "token=" \
--data "id=" \
--data "port= \
--data "pin=" \
Net/Port_off
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | port_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 |
--data "action=port_off" \
--data "token=" \
--data "id=" \
--data "port=physical port's switch" \
--data "pin=" \
Net/Port_on
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | port_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 |
--data "action=port_on" \
--data "token=" \
--data "id=" \
--data "port=" \
--data "pin=" \
Net/Show_cacti
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | show_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 |
--data "action=show_cacti" \
--data "token=" \
--data "id=" \
--data "port=" \
--data "graph=" \
Response: traffic graph image
Ip/Get_ip
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | get_ip | Main action - Get IP information |
| token | * | string | Your session token | |
| ip | * | int | Your IP address |
--data "action=get_ip" \
--data "token=" \
--data "ip=" \
Get_ptr
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | get_ptr | Main action - Get PTR record for IP |
| token | * | string | Your session token | |
| id | * | int | Your server ID | |
| ip | * | int | Your IP address |
--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
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | update_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 |
--data "action=update_ptr" \
--data "token=" \
--data "id=" \
--data "ip=" \
--data "ptr=" \
Ip/Set_main
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | set_main | Main 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.
--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
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | block_ip | Main 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. |
--data "action=block_ip" \
--data "token=" \
--data "id=" \
--data "ip=" \
--data "pin=" \
--data "description=this+is+block+test" \
--data "four_hours=1" \
Net/Unblock_ip
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | unblock_ip | Main action - Unblock specific IP |
| token | * | string | Your session token | |
| id | * | int | Your server ID | |
| ip | * | int | Your IP address | |
| pin | * | int | Your PIN code |
--data "action=unblock_ip" \
--data "token=" \
--data "id=" \
--data "ip=" \
--data "pin=" \
Billing interaction
Billing actions:
| Resource | Action | Description |
|---|---|---|
| whmcs.php | get_client | Get customer information |
| whmcs.php | create_addfunds | Create add funds invoice |
| whmcs.php | getpaymentgw | Get information how to pay this invoice |
| whmcs.php | get_billing_data | This 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
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | get_client | Main action - Get customer information |
| token | * | string | Your session token |
--data "action=get_client" \
--data "token=" \
Whmcs/Create_addfunds
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | create_addfundst | Main action - Create add funds invoice |
| amount | * | int | Replenishment amount | |
| token | * | string | Your session token |
--data "action=create_addfunds" \
--data "amount=" \
--data "token=" \
Whmcs/Getpaymentgw
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 number | |
| token | * | string | Your session token |
--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
| Parameter | Required | Type | Value/default | Description | |
|---|---|---|---|---|---|
| action | * | string | get_billing_data | Main action - this call retrieve billing information for the server. | |
| id | * | int | Server token | ||
| token | * | string | Your access token |
--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:
| 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 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
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | list | Main action - Get a list of available instances for a region |
| location | * | string | Instances location |
--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.
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | list | Main action - Get OS list for a specific instance |
| location | * | string | Instances location | |
| instance_id | * | int | id specific instance |
--data "action=list" \
--data "instance_id=" \
Traffic_plans/List
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 | |
| instance_id | * | int | Id specific instance |
--data "action=list" \
--data "location=" \
--data "instance=" \
Eq/Order_instance
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | order_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 |
--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.