API-Documentation¶
In this article
- invapi.hostkey.com control panels API documentation
- API examples format
- Authorization using an API key
- Working with API keys using apikeys calls
- Authorization
- PIN codes
- Billing interaction
- Instant servers
- Stock servers
- Remote access
- Virtual servers
- Server control
- Server power control
- Reinstall the operating system on the server (second option)
- Network operations
- DNS zone management
- Remote hands
- Server tags
- Asynchronous actions
invapi.hostkey.com control panels API documentation¶
We have developed an API to manage all our services. It offers full functionality to daily operations and integrations.
Information
Control panel invapi.hostkey.com is built on top of this API.
Key Features:
- Search: Search for the server by IP, hostname, location, and tag
- Order: order standard servers and receive access details in 10-30 minutes
- Power management: reboot, power on/off, read sensors and power status
- Networking: view network settings, enable/disable NICs, block/unblock specific IPs. Set DNS RRs.
- Reinstalls: perform fully automated reinstalls for standard OS: Centos, Ubuntu, Debian, and Windows Server. SSH keys, post-install scripts, and HTTP callbacks are supported.
- IPMI access: get raw access to the server IPMI, create network pass-through with admin user and manage server directly via a standard DRAC or IPMI interface with HTML5 or Java console
- Console access: one-click access to HTML5 or Java server console without installing anything locally
- ISO library access: server may be booted directly from one of our ISO images for installation or troubleshooting
- Remote hands requests: one-click experience to create remote hands requests to check your server or other common tasks
- Billing operations: top-up account directly, pay bills directly from the panel. Request cancellations.
- Statistics: View traffic usage graphs per interface or specific IP. View server performance metrics with the monitoring agent installed.
- Tags: setup own tags/values for a server, perform search operations, access these tags via API to keep server states and other server-related data like your billing ID
- Coming soon: hourly billing, create your own users with various permissions, allocate budget limits to users, post-payment for verified customers, server monitoring with notifications. Private IP blocks management.
API Requests¶
All requests must be made over the HTTPS protocol to ensure transaction encryption.
Unless otherwise specified, all requests should use the POST method.
API examples format¶
Examples in this documentation are described using a command line HTTP client curl. On computers with Linux and MacOS curl are usually installed by default, and it is available for loading on all popular platforms, including Windows.
Each example is divided into several lines with a symbol of \, which is compatible with bash. A typical example looks like this:
POST request example:
The parameter -X sets the request method. For consistency, the method will be indicated in all examples, even if it is clearly not required for GET methods.
Examples for which the JSON object is required in the body of the request, transmit the required data through the --data parameter.
The response to requests takes place in JSON format and is formatted in the documentation for habitability.
Attention
To use the API at the beginning, you need to get an session token. This can be done using API calls auth/login or auth/whmcslogin
Note
To use the above examples, without substituting your token each time, you can add a token once to the environment variables in your console. For example, on Linux this can be done using a command:
After that, the token will be automatically substituted in your requests.
Note
Please note that all values in this documentation are examples. Do not rely on identifiers of operating systems, tariffs, etc., used in examples. Use your values of servers/networks/domains to obtain values or before creating resources.
Authorization using an API key¶
To utilize the API, you must first acquire a session token. This can be achieved by making an API call to auth/login, after obtaining an API key in Invapi, or through the call api_keys/add.
A session token can also be obtained through the auth/whmcslogin call using the account login and password.
To access both the entire account and a specific server, you can obtain authorization through an API key by making a call to auth/login. If the key is found in the database and authorization is successful, the system will return the session token $HOSTKEY_TOKEN.
The token's authority will apply to the entire account if using a shared key or only to a specific server if using a per-server key. This method enables automatic server management and ordering services through our API without requiring login credentials or interactive 2FA verification.
Working with API keys using api_keys calls¶
To work with API calls and obtain an API key, you will need a session token. The session token can be obtained through the auth/whmcslogin call and is valid for one hour by default. After obtaining the session token, we recommend generating an API key for your account and using it to work with the API. To receive the session token, use the auth/login call.
| Resource | Action | Description |
|---|---|---|
| api_keys.php | list | obtain data on all generated API keys associated with the account |
| api_keys.php | list_for_server | obtain data on API keys generated for a specific server |
| api_keys.php | view | view information regarding a particular API key |
| api_keys.php | add | obtain an API key for an account or server |
| api_keys.php | edit | modify the API key parameters |
| api_keys.php | delete | delete an API key |
| api_keys.php | history | display of API key usage information for a specified time period |
api_keys/list¶
Displays all API keys generated by the account associated with the session token.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | list | main action - obtain data on all generated API keys associated with the account |
| token | * | string | session token |
POST-request
Positive response
{
"result": "OK",
"module": "api_keys",
"action": "list",
"data": [
{
"id": 484, //Account API key ID
"name": "new_api",
"active": 1,
"ip": "",
"server_id": 0,
"token_view": "0cab",
"login_notify_method": "none",
"login_notify_address": null
},
{
"id": 237, //Server API key ID
"name": "test_control_panel",
"active": 1,
"ip": "",
"server_id": 39601, //Server ID for the assigned key's server
"token_view": "b66d",
"login_notify_method": "none",
"login_notify_address": null
}
]
}
api_keys/list_for_server¶
Displays the API keys generated for a particular server.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | list_for_server | main action - obtain data on API keys generated for a specific server |
| server_id | * | int | Server ID | |
| token | * | string | session token |
POST-request
Positive response
api_keys/view¶
Displays information about a specific API key.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | view | main action - view information regarding a particular API key |
| id | * | int | API key ID (can be obtained by calling api_keys/list) | |
| token | * | string | session token |
POST-request
Positive response
api_keys/add¶
Allows you to obtain an API key for an account or server.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | add | main action - obtain an API key for an account or server |
| name | * | string | key name | |
| server_id | int | server ID, if the key is not issued for the entire account | ||
| ip | string | provide a list of authorized IP addresses for key usage (for example 10.0.0.2, 10.4.6.3/24) | ||
| login_notify_method | * | string | select the notification method for login using the provided API key (none, email, webhook) | |
| login_notify_address | string | email or notification webhook address will depend on the value set in the login_notify_method | ||
| active | * | int | 1 - enable the key, 0 - disable the key | |
| token | * | string | session token |
Note
When specifying an API key for the server, make sure to set the login notify method to none.
POST-request
curl -s "https://invapi.hostkey.com/api_keys.php" -X POST \
--data "action=add" \
--data "params[name]={API key name}" \
--data "params[server_id]={Server ID}" \
--data "params[ip]={IP address "white list"} \
--data "params[login_notify_method]={`none`, `email` or `webhook`}" \
--data "params[login_notify_address]=" \
--data "params[active]={1 or 0}" \
--data "token=$HOSTKEY_TOKEN"
Positive response
{
"result": "OK",
"module": "api_keys",
"action": "add",
"data": {
"id": 501, //API key ID
"name": "test key",
"active": 1,
"ip": "10.0.0.1 10.3.4.5",
"server_id": 0,
"token_view": "d981",
"login_notify_method": "email",
"login_notify_address": "[email protected]",
"api_key": "d9815703f6f41d3f-5d52f141ff7ac755" // Generated API key
}
}
api_keys/edit¶
Allows you to modify the API key parameters.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | edit | main action - modify the API key parameters |
| id | * | int | API key ID (can be obtained by calling api_keys/list) | |
| name | * | string | key name | |
| ip | string | provide a list of authorized IP addresses for key usage (for example 10.0.0.2, 10.4.6.3/24) | ||
| login_notify_method | * | string | select the notification method for login using the provided API key (none, email, webhook) | |
| login_notify_address | string | email or notification webhook address will depend on the value set in the login_notify_method | ||
| active | * | int | 1 - enable the key, 0 - disable the key | |
| token | * | string | session token |
POST-request
curl -s "https://invapi.hostkey.com/api_keys.php" -X POST \
--data "action=edit" \
--data "params[id]={API key ID}" \
--data "params[name]={API key name}" \
--data "params[server_id]={Server ID}" \
--data "params[ip]={IP address ACL} \
--data "params[login_notify_method]={`none`, `email` or `webhook`}" \
--data "params[login_notify_address]=" \
--data "params[active]={1 or 0}" \
--data "token=$HOSTKEY_TOKEN"
api_keys/delete¶
Allows you to delete an API key.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | delete | main action - delete an API key |
| id | * | int | API key ID (can be obtained by calling api_keys/list) | |
| token | * | string | session token |
POST-request
Positive response
api_keys/history¶
Allows you to display of API key usage information for a specified time period.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | history | main action - display of API key usage information for a specified time period |
| id | * | int | API key ID (can be obtained by calling api_keys/list) | |
| period_from | string | Date from which to output history in Y-M-D format | ||
| period_to | string | Date to which you want to output the history in the format Y-M-D | ||
| token | * | string | session token |
POST-request
Positive response
{
"result": "OK",
"module": "api_keys",
"action": "history",
"data": [
{
"id": 20818097,
"date": "2024-02-14 11:14:05",
"message": "Deleted api_key 506. json:{\"id\":\"506\"}",
"type": "action",
**Login**: "[email protected]"
},
{
"id": 20817742,
"date": "2024-02-14 11:10:45",
"message": "Changed api_key 506. name from 'test key 2' to 'new_new test', active from '1' to '0', ip from '10.0.0.1 10.3.4.5' to '78.8.8.6', login_notify_method from 'none' to 'email', login_notify_address from '' to '[email protected]'",
"type": "action",
**Login**: "[email protected]"
},
{
"id": 20817738,
"date": "2024-02-14 11:10:45",
"message": "Updated api_key 506. json:{\"id\":\"506\",\"name\":\"new_new test\",\"ip\":\"78.8.8.6\",\"login_notify_method\":\"email\",\"login_notify_address\":\"[email protected]\",\"active\":\"0\"}",
"type": "action",
**Login**: "[email protected]"
},
{
"id": 20816506,
"date": "2024-02-14 11:03:51",
"message": "Created new api_key 506. json:{\"name\":\"test key 2\",\"ip\":\" 10.0.0.1, 10.3.4.5\",\"login_notify_method\":\"none\",\"active\":\"1\",\"server_id\":\"34533\"}",
"type": "action",
**Login**: "[email protected]"
}
]
}
Authorization¶
| Resource | Action | Description |
|---|---|---|
| auth.php | login | obtain a session token via API KEY |
| auth.php | whmcslogin | obtain a session token from a login/password pair |
| auth.php | logout | session token removal |
| auth.php | info | obtain complete equipment data |
| eq.php | set_pin | set/change PIN Code |
| eq.php | check_pin | validate entered PIN |
auth/login¶
Allows you to obtain a session token using an account or server API key.
Note
The most important data is the token (hereafter $HOSTKEY_TOKEN in the examples). All information about the token data and permissions is stored on the API server, the rest of the data helps to build the right web interface for a particular role.
The token is normally valid for 2 hours, if a different token lifetime is required, it can be specified in seconds using the ttl parameter. If the token is requested again within this time, a valid token will be returned. The token is usually bound to the user's IP if not required - the binding can be removed with the fix_ix=0 parameter. If the token is bound to the IP and the IP changes, the system will generate an error and it will be necessary to get the token again.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | login | Main action - obtains an access token |
| key | * | string | API access key | |
| ttl | int | 7200 | session duration in seconds, default is 7200 (2 hours) |
POST-request
Positive response
{
"result": {
"token": c92e48c4506320873286b84440e74sfd", // SESSION TOKEN
"role": "Customer billing",
"role_type": "Customer",
"whmcs_id": 3172,
"whmcs_location": "whmcs_com",
"servers": [
34533
32645
17405
],
"customer_id": 38157,
"permissions": [ // LIST OF AVAILABLE API CALLS FOR A SPECIFIC ROLE
"api_keys/edit",
"api_keys/view",
"auth/2fa_check",
"auth/billing_list",
"auth/flip_tag",
"auth/sms_send",
"customers/update_acl",
"datacenter/list",
"datacenter/show",
"eq/add_ipmi_admin",
"eq/add_ipmi_user",
"eq/appraise",
"eq/boot_dev",
"eq/console",
"eq/create_pxe",
"eq/get_ipmi",
"eq/get_traffic",
"eq/list",
"eq/novnc",
"eq/off",
"eq/on",
"eq/order_instance",
"eq/reboot",
"eq/reinstall",
"eq/remove_ipmi_user",
"eq/sensors",
"eq/set_pin",
"eq/show",
"eq/status",
"eq/suspend",
"eq/unit_reset",
"eq/unsuspend",
"foreman/get_hostgroup",
"foreman/get_media",
"foreman/get_network",
"foreman/get_os",
"foreman/get_ptable",
"ip/get_ip",
"ip/get_ptr",
"ip/get_traffic",
"ip/list_free_ip",
"ip/set_main",
"ip/update_ptr",
"iso/list_iso",
"iso/mount_iso",
"iso/unmount_iso",
"jenkins/call",
"jenkins/get_tasks",
"license/list",
"location/list",
"location/show",
"locations/view",
"nat/add_static_nat",
"nat/remove_static_nat",
"net/block_ip",
"net/get_acl",
"net/get_bps_in",
"net/get_bps_out",
"net/get_port",
"net/get_pspeed",
"net/get_snmp",
"net/get_status",
"net/ip_chart",
"net/ip_settings",
"net/nmap",
"net/port_off",
"net/port_on",
"net/remove_ipv4",
"net/show_cacti",
"net/show_ip_graph",
"net/unblock_ip",
"os/list",
"os/search",
"paypal/check_order",
"paypal/check_subscription",
"paypal/create_order",
"paypal/create_subscription",
"pdns/add_dns",
"pdns/add_domain",
"pdns/add_subdomain",
"pdns/create_dns",
"pdns/create_zone",
"pdns/delete_domain",
"pdns/delete_zone",
"pdns/edit",
"pdns/get_domains",
"pdns/get_subdomains",
"pdns/get_zone",
"pdns/list_domains",
"pdns/list_servers",
"pdns/list_subdomains",
"pdns/view",
"pdns/view_zone",
"pdu/get",
"presets/list",
"presets/search",
"soft/list",
"ssh_keys/add",
"ssh_keys/delete",
"ssh_keys/list",
"stocks/list",
"stocks/show",
"sumsub/get_token",
"tag/add",
"tag/clear",
"tag/list",
"tag/remove",
"traffic_plans/list",
"vat/check_vat",
"vm/create_snapshot",
"vm/get_engine",
"vm/get_snapshot",
"vm/load_stats",
"vm/remove_snapshot",
"vm/restore_snapshot",
"whmcs/add_contact",
"whmcs/add_os_addon",
"whmcs/apply_credit",
"whmcs/cancel_order",
"whmcs/create_addfunds",
"whmcs/delete_cancellation_request",
"whmcs/delete_contact",
"whmcs/download_invoice",
"whmcs/generate_due_invoice",
"whmcs/getcredits",
"whmcs/getpaymentgw",
"whmcs/get_billing_data",
"whmcs/get_cancellation_requests",
"whmcs/get_client",
"whmcs/get_contacts",
"whmcs/get_invoice",
"whmcs/get_invoices",
"whmcs/get_related_invoices",
"whmcs/mass_pay",
"whmcs/request_cancellation",
"whmcs/transactions",
"whmcs/update_client",
"whmcs/update_contact",
"whmcs/update_product",
"whmcs/verify_address",
"whmcs/verify_email",
"yookassa/check_payment",
"yookassa/init"
],
"token_expire": 1702895140,
"new": 1
}
}
auth/whmcslogin¶
Allows you to obtain a session token by pairing your account login and password.
HTTP method - POST
Note
Authorization by login/password pair is performed for the entire account and all its servers. If authorization is successful, the system returns a session token $HOSTKEY_TOKEN. You can bind the session token to a specific IP address, then you must retrieve it when logging in from a different IP.
Attention
If you have 2FA enabled, this call will send a request to your 2FA device and you will need to enter an access code.
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | whmcslogin | main action - to obtain a session token |
| user | * | string | billing login | |
| password | * | string | billing password | |
| fix_ip | int | fix_ip=0 - do not bind token to address, fix_ip=1 - bind | ||
| ttl | int | 10800 | session duration in seconds, default is 3600 (1 hour) |
POST-request, cURL
Positive response
{
"result": {
"token": c92e48c4506320873286b84440e74sfd", // SESSION TOKEN
{ "role": "Customer Billing", // ROLE
"role_type": "Customer", // ROLE TYPE
"whmcs_id": 3172, // BILLING ACCOUNT_ID
"whmcs_location": "whmcs_com", // WHICH BILLING IS USED HERE
"whmcs_token": null,
"permissions": [ // LIST OF API CALLS AVAILABLE FOR A GIVEN ROLE
"api_keys/edit",
"api_keys/view",
"auth/2fa_check",
"auth/billing_list",
"auth/flip_tag",
"auth/sms_send",
"customers/update_acl",
"datacenter/list",
"datacenter/show",
"eq/add_ipmi_admin",
"eq/add_ipmi_user",
"eq/appraise",
"eq/boot_dev",
"eq/console",
"eq/create_pxe",
"eq/get_ipmi",
"eq/get_traffic",
"eq/list",
"eq/novnc",
"eq/off",
"eq/on",
"eq/order_instance",
"eq/reboot",
"eq/reinstall",
"eq/remove_ipmi_user",
"eq/sensors",
"eq/set_pin",
"eq/show",
"eq/status",
"eq/suspend",
"eq/unit_reset",
"eq/unsuspend",
"foreman/get_hostgroup",
"foreman/get_media",
"foreman/get_network",
"foreman/get_os",
"foreman/get_ptable",
"ip/get_ip",
"ip/get_ptr",
"ip/get_traffic",
"ip/list_free_ip",
"ip/set_main",
"ip/update_ptr",
"iso/list_iso",
"iso/mount_iso",
"iso/unmount_iso",
"jenkins/call",
"jenkins/get_tasks",
"license/list",
"location/list",
"location/show",
"locations/view",
"nat/add_static_nat",
"nat/remove_static_nat",
"net/block_ip",
"net/get_acl",
"net/get_bps_in",
"net/get_bps_out",
"net/get_port",
"net/get_pspeed",
"net/get_snmp",
"net/get_status",
"net/ip_chart",
"net/ip_settings",
"net/nmap",
"net/port_off",
"net/port_on",
"net/remove_ipv4",
"net/show_cacti",
"net/show_ip_graph",
"net/unblock_ip",
"os/list",
"os/search",
"paypal/check_order",
"paypal/check_subscription",
"paypal/create_order",
"paypal/create_subscription",
"pdns/add_dns",
"pdns/add_domain",
"pdns/add_subdomain",
"pdns/create_dns",
"pdns/create_zone",
"pdns/delete_domain",
"pdns/delete_zone",
"pdns/edit",
"pdns/get_domains",
"pdns/get_subdomains",
"pdns/get_zone",
"pdns/list_domains",
"pdns/list_servers",
"pdns/list_subdomains",
"pdns/view",
"pdns/view_zone",
"pdu/get",
"presets/list",
"presets/search",
"soft/list",
"ssh_keys/add",
"ssh_keys/delete",
"ssh_keys/list",
"stocks/list",
"stocks/show",
"sumsub/get_token",
"tag/add",
"tag/clear",
"tag/list",
"tag/remove",
"traffic_plans/list",
"vat/check_vat",
"vm/create_snapshot",
"vm/get_engine",
"vm/get_snapshot",
"vm/load_stats",
"vm/remove_snapshot",
"vm/restore_snapshot",
"whmcs/add_contact",
"whmcs/add_os_addon",
"whmcs/apply_credit",
"whmcs/cancel_order",
"whmcs/create_addfunds",
"whmcs/delete_cancellation_request",
"whmcs/delete_contact",
"whmcs/download_invoice",
"whmcs/generate_due_invoice",
"whmcs/getcredits",
"whmcs/getpaymentgw",
"whmcs/get_billing_data",
"whmcs/get_cancellation_requests",
"whmcs/get_client",
"whmcs/get_contacts",
"whmcs/get_invoice",
"whmcs/get_invoices",
"whmcs/get_related_invoices",
"whmcs/mass_pay",
"whmcs/request_cancellation",
"whmcs/transactions",
"whmcs/update_client",
"whmcs/update_contact",
"whmcs/update_product",
"whmcs/verify_address",
"whmcs/verify_email",
"yookassa/check_payment",
"yookassa/init"
],
"corporate": 0,
"verified": null,
"token_expire": 1703059226,
"new": 0,
"billing_options": {
"location": "NL",
"company": "HOSTKEY B.V.",
"active": 1,
"allowed_payments": [
"yookassa"
],
"native_endpoint": "invapi.hostkey.com"
}
},
"timings": [ // ???
{
"init": 2
},
{
"auth_log_start": 2
},
{
"auth_log_done": 3
},
{
"check_brute_done": 131
},
{
"auth_find_customer_done": 3
},
{
"check_whmcs_user at whmcs_com": 469
},
{
"log_brute_done": 5
},
{
"usleep_done": 84
},
{
"auth_get_hash_done": 2
},
{
"hash_init_done": 5
},
{
"auth_set_token_done": 423
},
{
"auth_get_role_done": 1
},
{
"auth_list_permissions_done": 2
},
{
"auth_check_customer_init": 0
},
{
"auth_check_customer_done": 5
},
{
"auth_add_tags_done": 0
},
{
"auth_log_time": [
{
"add_log": 3
},
{
"amqp_sendmessage": 28
}
]
},
{
"whmcslogin total": 1166
}
]
}
Failure response
auth/logout¶
Allows you to end a client session.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | logout | main action - delete the session token from the database. When the session is finished, you should log out of the system. This avoids potential security issues. |
| token | * | string | removal token |
POST-request, cURL
auth/info¶
Allows you to get user information (available API requests, account type and role, and id servers associated with the account).
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | info | main action - info will return full data about your token including your server's identification numbers when you are logged in. |
| token | * | string | session token |
POST-request, cURL
Positive response
{
"result": {
"servers": { // ID SERVERS ASSOCIATED WITH THE ACCOUNT
"34533": "34533"
"32645": "32645"
"17405": "17405"
},
"show_products": 1,
"manage_products": 1,
"show_invoices": 1,
"manage_orders": 1,
"email": "[email protected]",
"token_expire": 1703059020,
"whmcs_id": "3172",
"whmcs_location": "whmcs_com",
"billing_servers": [],
"deploy_keys": [],
"permissions": [ // LIST OF AVAILABLE API CALLS FOR A SPECIFIC ROLE
"api_keys/edit",
"api_keys/view",
"auth/2fa_check",
"auth/billing_list",
"auth/flip_tag",
"auth/sms_send",
"customers/update_acl",
"datacenter/list",
"datacenter/show",
"eq/add_ipmi_admin",
"eq/add_ipmi_user",
"eq/appraise",
"eq/boot_dev",
"eq/console",
"eq/create_pxe",
"eq/get_ipmi",
"eq/get_traffic",
"eq/list",
"eq/novnc",
"eq/off",
"eq/on",
"eq/order_instance",
"eq/reboot",
"eq/reinstall",
"eq/remove_ipmi_user",
"eq/sensors",
"eq/set_pin",
"eq/show",
"eq/status",
"eq/suspend",
"eq/unit_reset",
"eq/unsuspend",
"foreman/get_hostgroup",
"foreman/get_media",
"foreman/get_network",
"foreman/get_os",
"foreman/get_ptable",
"ip/get_ip",
"ip/get_ptr",
"ip/get_traffic",
"ip/list_free_ip",
"ip/set_main",
"ip/update_ptr",
"iso/list_iso",
"iso/mount_iso",
"iso/unmount_iso",
"jenkins/call",
"jenkins/get_tasks",
"license/list",
"location/list",
"location/show",
"locations/view",
"nat/add_static_nat",
"nat/remove_static_nat",
"net/block_ip",
"net/get_acl",
"net/get_bps_in",
"net/get_bps_out",
"net/get_port",
"net/get_pspeed",
"net/get_snmp",
"net/get_status",
"net/ip_chart",
"net/ip_settings",
"net/nmap",
"net/port_off",
"net/port_on",
"net/remove_ipv4",
"net/show_cacti",
"net/show_ip_graph",
"net/unblock_ip",
"os/list",
"os/search",
"paypal/check_order",
"paypal/check_subscription",
"paypal/create_order",
"paypal/create_subscription",
"pdns/add_dns",
"pdns/add_domain",
"pdns/add_subdomain",
"pdns/create_dns",
"pdns/create_zone",
"pdns/delete_domain",
"pdns/delete_zone",
"pdns/edit",
"pdns/get_domains",
"pdns/get_subdomains",
"pdns/get_zone",
"pdns/list_domains",
"pdns/list_servers",
"pdns/list_subdomains",
"pdns/view",
"pdns/view_zone",
"pdu/get",
"presets/list",
"presets/search",
"soft/list",
"ssh_keys/add",
"ssh_keys/delete",
"ssh_keys/list",
"stocks/list",
"stocks/show",
"sumsub/get_token",
"tag/add",
"tag/clear",
"tag/list",
"tag/remove",
"traffic_plans/list",
"vat/check_vat",
"vm/create_snapshot",
"vm/get_engine",
"vm/get_snapshot",
"vm/load_stats",
"vm/remove_snapshot",
"vm/restore_snapshot",
"whmcs/add_contact",
"whmcs/add_os_addon",
"whmcs/apply_credit",
"whmcs/cancel_order",
"whmcs/create_addfunds",
"whmcs/delete_cancellation_request",
"whmcs/delete_contact",
"whmcs/download_invoice",
"whmcs/generate_due_invoice",
"whmcs/getcredits",
"whmcs/getpaymentgw",
"whmcs/get_billing_data",
"whmcs/get_cancellation_requests",
"whmcs/get_client",
"whmcs/get_contacts",
"whmcs/get_invoice",
"whmcs/get_invoices",
"whmcs/get_related_invoices",
"whmcs/mass_pay",
"whmcs/request_cancellation",
"whmcs/transactions",
"whmcs/update_client",
"whmcs/update_contact",
"whmcs/update_product",
"whmcs/verify_address",
"whmcs/verify_email",
"yookassa/check_payment",
"yookassa/init"
],
"role_type": "Customer",
"role_name": "Customer billing",
"verified": null,
"sumsub_id": null,
"sumsub_comment": null,
"corporate": 0,
"tags": [
{
"id": 582523,
"component": "customers",
"component_id": 38157,
"tag": "email_verification",
"value": "verified",
"extra": "1699523441",
"internal": 0
}
],
"billing_options": {
"url": "https://billing-itb.hostkey.com/",
"location": "NL",
"company": "HOSTKEY B.V.",
"active": 1,
"allowed_payments": [
"paypal"
],
"native_endpoint": "invapi.hostkey.com"
},
"client_ip": "185.130.215.70",
"timing": [
{
"auth_validate_token": 0
},
{
"auth_tags": 0
},
{
"auth_get_role": 0
},
{
"whmcs_get_server_raw": 0
},
{
"eq_search": 0
},
{
"add new tags": 0
},
{
"list_permissions": 0
},
{
"private_block": 0
},
{
"auth_log": 0
}
]
}
}
PIN codes¶
We are trying to keep our customer's servers safe, even in case of data leaks on the user's devices. The system will ask for a PIN for every critical server's operation.
The PIN is a short password to keep equipment safe and should not be stored anywhere. We could only reset it via manual support request after extra security verification.
Note
- PIN's hashes are stored very separately from our billing and inventory databases.
- Most of the management functions will not work without or with an empty PIN. It should be set once.
eq/set_pin¶
Allows you to set/change the client PIN.
HTTP method - POST/GET
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | set_pin | main action - set/change PIN for the user |
| token | * | string | session token | |
| old_pin | if modified | int | old PIN code | |
| new_pin | * | int | new PIN code |
POST-request, cURL
Positive response
Failure response
Note
This action has an asynchronous response.
eq/check_pin¶
Allows you to confirm the correctness of the entered client PIN.
HTTP method - POST/GET
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | check_pin | main action - validate entered PIN |
| token | * | string | session token | |
| old_pin | if modified | int | PIN code |
POST-request, cURL
Positive response
Failure response
```json
{ "result": "OK", "scope": "Invalid pin code", "context": { "action": "check_pin", "id": "0" }, "debug": "Blocked For Security Purposes", "key": "d862ecc7ea64c5af55f39b132f3b7502" } ```
Note
This action has an asynchronous response.
Attention
After several failures API will return only failed responses with long delays to avoid bruteforce.
Billing interaction¶
HOSTKEY uses WHMCS as its billing software.
| Resource | Action | Description |
|---|---|---|
| whmcs.php | get_client | customer information acquisition |
| whmcs.php | update_client | change customer account details |
| whmcs.php | reset_password | reset customer account password |
| whmcs.php | get_contacts | retrieve a list of additional contacts |
| whmcs.php | add_contact | add another contact to the account |
| whmcs.php | update_contact | change details for an additional contact |
| whmcs.php | delete_contact | delete additional contact for account |
| whmcs.php | create_addfunds | create add funds invoice |
| whmcs.php | getpaymentgw | get information how to pay this invoice |
| whmcs.php | get_billing_data | retrieve billing information for the server |
| whmcs.php | getcredits | get information about the movement of funds on the personal account, all accruals and write-offs of credits |
| whmcs.php | generate_due_invoice | create the following invoice for the server |
| whmcs.php | transactions | retrieve a list of transactions by client account |
| whmcs.php | mass_pay | create a group invoice for payment from multiple invoices |
| whmcs.php | download_invoice | download an invoice in PDF format |
| whmcs.php | get_related_invoices | get a list of invoices for a specific server |
| whmcs.php | apply_credit | pay the invoice with credit balance |
| whmcs.php | create_addfunds | create an invoice in order to top up credit balance |
| whmcs.php | get_invoice | retrieve invoice data for payment |
| whmcs.php | get_invoices | retrieve a complete list of invoices for payment |
| whmcs.php | request_cancellation | request a cancellation of the service |
| whmcs.php | delete_cancellation_request | delete a request to service cancellation |
| whmcs.php | get_cancellation_requests | get an active list of service cancellation requests |
whmcs/get_client¶
Allows you to retrieve the required customer data from the billing system.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | get_client | main action - customer information acquisition |
| token | * | string | session token |
POST-request, cURL
Positive response
{
"result": "success",
"client": {
"userid": 3172,
"id": 3172,
"uuid": "b6d0bd75-1bd1-4ffc-9ec5-3870668b1ea9",
"firstname": "John", // NAME
"lastname": "Hostkey", // SURNAME
"fullname": "Hostkey", // FULL NAME
"companyname": "",
"email": "[email protected]", // CLIENT E-MAIL
"address1": "Veldweg 111", // CLIENT ADDRESS
"address2": "",
"city": "Amsterdam", // CITY
"fullstate": "",
"state": "", // STATE/PROVINCE/AREA
"postcode": "7845 TC", // ZIP CODE
"countrycode": "NL", // COUNTRY CODE
"country": "NL", // COUNTRY CODE
"phonenumber": "79658742356", // PHONE NUMBER
"tax_id": "",
"Password": "",
"email_preferences": {
"general": 1,
"invoice": 1,
"support": 1,
"product": 1,
"domain": 1,
"affiliate": 1
},
"statecode": "",
"countryname": "Netherlands", // COUNTRY NAME
"phonecc": 7, // COUNTRY CALLING CODE
"phonenumberformatted": "+31.06-95005645",
"telephoneNumber": "06-95005645", // PHONE NUMBER
"billingcid": 0,
"twofaenabled": false,
"currency": 2,
"defaultgateway": "",
"groupid": 2,
"status": "Active",
"credit": "998.39",
"taxexempt": false,
"latefeeoveride": false,
"overideduenotices": false,
"separateinvoices": false,
"disableautocc": false,
"emailoptout": false,
"marketing_emails_opt_in": true,
"overrideautoclose": false,
"allowSingleSignOn": 1,
"email_verified": false,
"language": "",
"isOptedInToMarketingEmails": true,
"lastlogin": "Date: 2023/09/11 12:27<br>IP Address: 176.222.34.23<br>Host: 176.222.56.20", // DATE, IP ADDRESS AND HOST IP
"currency_code": "EUR", // VALUE CODE
"co_autopayment": {
"name": "Autopayment enabled",
"type": "checkbox",
"required": false,
"value": ""
},
"co_payfirstday": {
"name": "Services for first day",
"type": "checkbox",
"required": false,
"value": ""
},
"co_marktemails": {
"name": "Marketing e-mails",
"type": "checkbox",
"required": false,
"value": "on"
},
"co_subscription": {
"name": "Autopayments via PayPal",
"type": "text",
"size": 40,
"required": false,
"value": ""
},
"co_marktsms": {
"name": "Marketing SMS",
"type": "checkbox",
"required": false,
"value": "on"
},
"co_smsnum": {
"name": "SMS number for 2FA and notices",
"type": "text",
"size": 26,
"required": false,
"placeholder": "+310695005645",
"value": "310695005645"
},
"co_customertype": {
"name": "Client type",
"type": "select",
"options": [
"Individual",
"Legal entity"
],
"required": true,
"value": "Individual"
},
"co_regaddress": {
"name": "Legal address",
"type": "text",
"size": 100,
"required": false,
"value": ""
},
"co_bankdata": {
"name": "Bank information",
"type": "text",
"size": 100,
"required": false,
"value": ""
},
"co_secret": {
"name": "Secret word",
"type": "text",
"size": 26,
"required": true,
"value": "server"
},
"co_skype": {
"name": "Skype/Telegram",
"type": "text",
"size": 26,
"required": false,
"value": ""
},
},
"billing_location": "whmcs_com",
"groupdata": {
"id": 2,
"groupname": "Customers",
"groupcolour": "#ffffff",
"discountpercent": "0.00",
"susptermexempt": "",
"separateinvoices": ""
},
"internal": {
"id": 38157,
"billing": "whmcs_com",
"account_id": 3172,
"email": "[email protected]",
"active_since": "2023-11-09",
"monthly": null,
"verified": null,
"corporate": 0,
"tags": [
{
"id": 582523,
"component": "customers",
"component_id": 38157,
"tag": "email_verification",
"value": "verified",
"extra": "1699523441",
"internal": 0
}
]
}
}
whmcs/update_client¶
Allows you to modify customer account details.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | update_client | main action - change customer account details |
| token | * | string | session token | |
| billing_status | string | billing status | ||
| billing_firstname | string | Customer's first name | ||
| billing_lastname | string | Customer's last name | ||
| billing_companyname | string | Company name | ||
| billing_email | string | Customer's email | ||
| billing_address1 | string | Customer address string 1 | ||
| billing_address2 | string | Customer address string 2 | ||
| billing_city | string | Customer's city | ||
| billing_state | string | Customer's state or region | ||
| billing_postcode | string | Customer's postcode | ||
| billing_country | string | Customer's country | ||
| billing_phonenumber | string | Customer's phonenumber | ||
| billing_twofaenabled | string | Enabling two-factor authorisation (true/false) | ||
| billing_currency | int | Payment currency 1 - , 2 - , 3 - | ||
| billing_groupid | int | (1/0) | ||
| billing_taxexempt | string | (true/false) | ||
| billing_latefeeoveride | string | (true/false) | ||
| billing_overideduenotices | string | (true/false) | ||
| billing_separateinvoices | string | (true/false) | ||
| billing_disableautocc | string | (true/false) | ||
| billing_emailoptout | string | (true/false) | ||
| billing_marketingoptin | string | Subscription to marketing mailings (true/false) | ||
| billing_overrideautoclose | string | (true/false) | ||
| billing_allowSingleSignOn | int | (1/0) | ||
| co_autopayment | checkbox | Activate automatic payments (on/off) | ||
| co_payfirstday | checkbox | Pay on the first of the month (on/off) | ||
| co_marktemails | checkbox | Marketing emails (on/off) | ||
| co_subscription | string | Automatic payments through the service (PayPal, etc) | ||
| co_marktsms | checkbox | Marketing mailing approval (on/off) | ||
| co_smsnum | string | SMS notification or 2FA authentication code number send | ||
| co_customertype | string | Type of customer: Natural person/Legal entity | ||
| co_regaddress | string | Customer's legal address | ||
| co_bankdata | string | Customer's bank details | ||
| co_secret | string | Secret word | ||
| co_skype | string | Skype/Telegram adress |
POST-request, cURL
whmcs/reset_password¶
Allows you to reset the access password for the client account.
Attention
The `email' parameter must match the client's email address in the account where the password is being reset.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | reset_password | main action - reset customer account password |
| token | * | string | session token | |
| * | string | a password reset link will be sent to the email address provided. |
POST-request, cURL
Positive response
Failure response
whmcs/get_contacts¶
Lets you retrieve a list of additional contacts for a customer account.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | get_contacts | main action - retrieve a list of additional contacts |
| token | * | string | session token |
POST-request, cURL
Positive response
{
"result": "success",
"contacts": [
{
"id": 121, // ADDITIONAL CONTACT ID
"userid": 3172,
"firstname": "Dimitry",
"lastname": "Servers",
"companyname": "",
"email": "[email protected]",
"address1": "",
"address2": "",
"city": "",
"state": "",
"postcode": "",
"country": "NL",
"phonenumber": "",
"tax_id": "",
"subaccount": 1,
**Password**: "$2y$10$pSlFQ1Vvq0UcKD5eE9dZ2.J5s779skGChaD0fPJB7ooURi1/KnDJm",
"permissions": "",
"domainemails": 0,
"generalemails": 0,
"invoiceemails": 0,
"productemails": 0,
"supportemails": 0,
"affiliateemails": 0,
"pwresetkey": "",
"created_at": "0000-00-00 00:00:00",
"updated_at": "2023-12-22 11:31:45",
"pwresetexpiry": "0000-00-00 00:00:00"
}
]
}
whmcs/add_contact¶
Allows you to add an additional contact to an account.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | add_contact | main action - add an additional contact to an account |
| token | * | string | session token |
POST-request, cURL
Attention
A new additional contact will be created with a random 'email'. This must always be changed via the INVAPI.
whmcs/update_contact¶
Allows you to change the details of an additional contact.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | update_contact | main action - change details for an additional contact |
| contact_id | * | int | additional Contact ID | |
| * | string | additional contact's email for the account | ||
| password2 | string | new password for additional contact | ||
| phonenumber | int | phone number of the additional contact. Adding a number includes 2FA via SMS. | ||
| token | * | string | session token |
POST-request, cURL
curl -s "https://invapi.hostkey.com/whmcs.php" -X POST \
--data "action=update_contact" \
--data "contact_id=121" \
--data "token=29cfb2b6fb8f1bc838455fe36e032aaa" \
--data "[email protected]" \
--data "phonenumber=+79656754663" \
--data "password2=4321" \
whmcs/delete_contact¶
Lets you delete an additional contact for an account.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | delete_contact | main action - delete additional contact for account |
| contact_id | * | int | additional Contact ID | |
| token | * | string | session token |
POST-request, cURL
Failure response
whmcs/getpaymentgw¶
Provides information on how to pay your invoice.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | getpaymentgw | main action - get information how to pay this invoice |
| invoice_id | * | int | invoice ID | |
| token | * | string | session token |
POST-request, cURL
Positive response
{
"result": "OK",
"methods": {
"paypal": {
"name": "PayPal",
"call": "<table><tr><td><form target=_blank action=\"https:\/\/www.paypal.com\/cgi-bin\/webscr\" method=\"post\">\n<input type=\"hidden\" name=\"cmd\" value=\"_xclick\">\n<input type=\"hidden\" name=\"business\" value=\"[email protected]\"><input type=\"hidden\" name=\"item_name\" value=\"HOSTKEY - Invoice #"invoice_id"\">\n<input type=\"hidden\" name=\"amount\" value=\"10.00\">\n<input type=\"hidden\" name=\"tax\" value=\"0.00\">\n<input type=\"hidden\" name=\"no_note\" value=\"1\">\n<input type=\"hidden\" name=\"no_shipping\" value=\"1\">\n<input type=\"hidden\" name=\"address_override\" value=\"0\">\n<input type=\"hidden\" name=\"first_name\" value=\""your firstname\">\n<input type=\"hidden\" name=\"last_name\" value=\""your lastname\">\n<input type=\"hidden\" name=\"email\" value=\""your email"\">\n<input type=\"hidden\" name=\"address1\" value=\"your address"\">\n<input type=\"hidden\" name=\"city\" value=\"your city"\">\n<input type=\"hidden\" name=\"state\" value=\"\">\n<input type=\"hidden\" name=\"zip\" value=\"11-111\">\n<input type=\"hidden\" name=\"country\" value=\"PL\">\n<input type=\"hidden\" name=\"night_phone_a\" value=\"48\">\n<input type=\"hidden\" name=\"night_phone_b\" value=\"48512515151\"><input type=\"hidden\" name=\"charset\" value=\"utf-8\">\n<input type=\"hidden\" name=\"currency_code\" value=\"EUR\">\n<input type=\"hidden\" name=\"custom\" value=\"196727\">\n<input type=\"hidden\" name=\"return\" value=\"https:\/\/invapi.hostkey.com?invoice_id=196727&paymentsuccess=true\">\n<input type=\"hidden\" name=\"cancel_return\" value=\"https:\/\/invapi.hostkey.com?invoice_id=196727&paymentfailed=true\">\n<input type=\"hidden\" name=\"notify_url\" value=\"https:\/\/bill.hostkey.com\/modules\/gateways\/callback\/paypal.php\">\n<input type=\"hidden\" name=\"bn\" value=\"WHMCS_ST\">\n<input type=\"hidden\" name=\"rm\" value=\"2\">\n<input type=\"image\" src=\"https:\/\/www.paypal.com\/en_US\/i\/btn\/x-click-but03.gif\" border=\"0\" name=\"submit\" alt=\"Make a one time payment with PayPal\">\n<\/form><\/td><\/tr><\/table>"
},
"banktransfer": {
"name": "Bank Transfer",
"call": "<span style='text-align:left'>Please wire funds in favor of: <p>HOSTKEY B.V.<br \/>\r\nWillem Frederik Hermansstraat 91, 1011DG<br \/>\r\nAmsterdam, the Netherlands<br \/>\r\nVAT: … KvK: … <br \/>\r\nIBAN: … SWIFT: …<br \/>\r\nBank: Co\u00f6peratieve Rabobank U.A.<br \/>Reference Number: 196727<\/p>"
},
"roudiappstripealipay": {
"name": "Alipay (\u652f\u4ed8\u5b9d)",
"call": "<!-- MoStripe New buy process -->\n\t<br \/><br \/>\n\t\n\t<script src=\"https:\/\/code.jquery.com\/jquery-1.10.2.min.js\"><\/script>\n\t<script src=\"https:\/\/js.stripe.com\/v3\/\"><\/script>\n\t<p><button id=\"mostripeOBT\" class=\"btn btn-primary\" title=\"moStripe Pay Now\">Pay Now<\/button><\/p>\n\t<p><\/p>\n\t<p id=\"resulterror\"><\/p>\n\t<form target=_blank action=\"#\" method=\"post\" id=\"roudifrm\">\n\t\t<input type=\"hidden\" name=\"invoiceid\" value=\"196727\" \/>\n\t\t<input type=\"hidden\" name=\"alipay_amount\" value=\"1000\" \/>\n\t\t<input type=\"hidden\" name=\"mostripeshakey\" value=\"5f18bcb3057b3a00f233f2cc3ca62a1bf9336b6e\" \/>\n\t\t<input type=\"hidden\" name=\"currency\" value=\"eur\" \/>\n\t\t<input type=\"hidden\" name=\"userid\" value=\"22160\" \/>\n\t\t\n\t<script type=\"text\/javascript\">\n\t\tvar stripe = Stripe( 'pk_live_LBhYzleiKSQfyNixR2vL2zjp');\n\t\t\n\t\tjQuery(function($) {\n\t\t $('#mostripeOBT').click(function(){\n\t\t\t stripe.createSource({\n\t\t\t\t type: 'alipay',\n\t\t\t\t amount: 1000,\n\t\t\t\t currency: 'eur',\n\t\t\t\t metadata: {\n\t\t\t\t \tuserid: '22160',\n\t\t\t\t \tinvoiceid: '196727'\n\t\t\t\t },\n\t\t\t\t redirect: {\n\t\t\t\t return_url: 'https:\/\/bill.hostkey.com\/modules\/gateways\/callback\/roudiappstripealipay.php?id=196727&alipay_amount=1000¤cy=eur&userid=22160',\n\t\t\t\t },\n\t\t\t\t}).then(function(result) {\n\t\t\t\t \/\/ handle result.error or result.source\n\t\t\t\t if(result.error === 'payment_method_not_available'){\n\t\t\t\t\t $('#resulterror').html('The payment method is currently not available');\n\t\t\t\t } else if(result.error === 'processing_error'){\n\t\t\t\t\t $('#resulterror').html('An unexpected error occurred preventing us from creating your payment.');\n\t\t\t\t }\n\t\t\t\t \/\/if successfull\n\t\t\t\t if(result.source){\n\t\t\t\t\t $(location).attr('href', result.source.redirect.url);\n\t\t\t\t }\n\t\t\t\t});\n\t\t\t\t\n\t\t\t\treturn false;\n\t\t });\n\t\t});\n\t<\/script>\n\t<\/form>\n\t<!-- MoStripe New buy process ends -->"
},
"paymaster": {
"name": "Webmoney (WME)",
"call": "<form target=_blank method=\"post\" action=\"https:\/\/psp.paymaster24.com\/Payment\/Init\">\n <input type=\"hidden\" name=\"LMI_MERCHANT_ID\" value=\"f8ebdab8-979c-41e6-90e6-69bdba4b5411\" \/>\n\t\t <input type=\"hidden\" name=\"LMI_PAYMENT_DESC_BASE64\" value=\"SE9TVEtFWSAtIEludm9pY2UgIzE5NjcyNw==\" \/>\n\t\t <input type=\"hidden\" name=\"LMI_PAYMENT_NO\" value=\"196727\" \/>\n\t\t <input type=\"hidden\" name=\"LMI_PAYMENT_AMOUNT\" value=\"10.00\" \/>\n\t\t <input type=\"hidden\" name=\"LMI_CURRENCY\" value=\"EUR\" \/>\n\t\t <input type=\"hidden\" name=\"LMI_FAILURE_URL\" value=\"https:\/\/invapi.hostkey.com?invoice_id=196727&paymentfailed=true\" \/>\n\t\t <input type=\"hidden\" name=\"LMI_SUCCESS_URL\" value=\"https:\/\/invapi.hostkey.com?invoice_id=196727&paymentsuccess=true\" \/>\n\t\t <input type=\"hidden\" name=\"LMI_INVOICE_CONFIRMATION_URL\" value=\"https:\/\/bill.hostkey.com\/\/modules\/gateways\/callback\/paymaster.php\" \/>\n\t\t <input type=\"hidden\" name=\"LMI_PAYMENT_CONFIRMATION_URL\" value=\"https:\/\/bill.hostkey.com\/\/modules\/gateways\/callback\/paymaster.php\" \/>\n\t\t <input type=\"hidden\" name=\"LMI_PAYMENT_NOTIFICATION_URL\" value=\"https:\/\/bill.hostkey.com\/\/modules\/gateways\/callback\/paymaster.php\" \/>\n\t\t <input type=\"hidden\" name=\"sign\" value=\"f5c5b30b12f544ce1686a1d69b50df36800acb08\" \/>\n\t\t <input type=\"submit\" value=\"Pay Now\" \/>\n\t\t <\/form>"
},
"bitpaycheckout": {
"name": "Cryptocurrency (BTC, ETH and other)",
"call": "<form target=_blank action=\"https:\/\/bill.hostkey.com\/modules\/gateways\/bit-pay\/createinvoice.php\" method=\"POST\"><input type=\"hidden\" name=\"invoiceId\" value = \"196727\" \/><input type=\"hidden\" name=\"systemURL\" value = \"https:\/\/bill.hostkey.com\" \/><input type=\"hidden\" name=\"buyerName\" value = \"\" \/><input type=\"hidden\" name=\"buyerAddress1\" value = \"\" \/><input type=\"hidden\" name=\"buyerAddress2\" value = \"\" \/><input type=\"hidden\" name=\"buyerCity\" value = \"warsava\" \/><input type=\"hidden\" name=\"buyerState\" value = \"\" \/><input type=\"hidden\" name=\"buyerZip\" value = \"11-111\" \/><input type=\"hidden\" name=\"buyerEmail\" value = \"[email protected]\" \/><input type=\"hidden\" name=\"buyerPhone\" value = \"48512515151\" \/><input type=\"submit\" value=\"Pay Now\" \/><\/form>"
}
}
}
whmcs/get_billing_data¶
Allows you to retrieve payment information for server rentals or other products.
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | get_billing_data | main action - retrieve billing information for the server |
| id | * | int | server ID | |
| token | * | string | session token |
POST-request, cURL
Positive response
{
"IP": "nl-vmmini", // Hostname/IP from billing
"client_id": 3172, // Client ID in WHMCS
"order_id": 5448, // Order ID in WHMCS
"suspend_reason": "", // Specify the reason why the server was stopped (if such a situation occurred)
"billing_setupfee": "5.00", // Initial payment amount
"product_id": 5724, // Product ID in WHMCS
"whmcs_location": "whmcs_com", // Payment identification
"billing_status": "Active", // Server billing status
"reg_date": "2023-12-14", // Service Start Date
"billing_cycle": "Monthly", // Payment cycle
"next_due_date": "2024-01-14", // Next payment due date
"billing_reccuring": "5.00", // Amount of periodic payment
"billing_name": "Services related to the provision of computing facilities (Instant server NL)",
"billing_dedicatedip": "176.222.34.23",
"billing_domain": "nl-vmmini",
"promoid": 0,
"terminationdate": null,
"subscriptionid": "",
"overideautosuspend": 0,
"overidesuspenduntil": "0000-00-00",
"currencyprefix": "", // Currency symbol
"currencysuffix": "EUR", // Cuttency name
"is_company": 0,
"tax_id": "",
"groupdata": {
"id": 2,
"groupname": "Customers",
"groupcolour": "#ffffff",
"discountpercent": "0.00",
"susptermexempt": "",
"separateinvoices": ""
},
"days_left": 23,
"customer_name": "John Hostkey", // Client name
"customer_email": "[email protected]", // Client e-mail
"result": "OK"
}
whmcs/getcredits¶
Allows you to get information about the movement of funds on the personal account, all accruals and write-offs of credits.
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | getcredit | main action - get information about the movement of funds on the personal account, all accruals and write-offs of credits |
| id | * | int | server ID | |
| token | * | string | session token |
POST-request, cURL
Positive response
{
"result": "OK",
"message": {
"result": "success",
"totalresults": 5,
"clientid": 3172,
"credits": {
"credit": [
{
"id": 2526,
"date": "2023-11-09",
"description": "Credit Applied to Invoice #10116",
"amount": "-5.00",
"relid": 0
},
{
"id": 4657,
"date": "2023-12-14",
"description": "Credit Applied to Invoice #18580",
"amount": "-5",
"relid": 0
}
]
}
}
}
whmcs/generate_due_invoice¶
Lets you create the following invoice for the server
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | generate_due_invoice | main action - create the following invoice for the server |
| id | * | int | server ID | |
| token | * | string | session token |
POST-request, cURL
Failure response
whmcs/transactions¶
Allows you to retrieve a list of transactions by client account.
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | transactions | main action - retrieve a list of transactions by client account |
| invoice_id | int | invoice number for which transactions are required | ||
| transaction_id | int | Information transaction | ||
| token | * | string | session token |
POST-request, cURL
whmcs/mass_pay¶
Lets you create a group invoice for payment from multiple invoices.
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | mass_pay | main action - create a group invoice for payment from multiple invoices |
| invoices[] | * | array | array of account numbers | |
| token | * | string | session token |
POST-request, cURL
whmcs/download_invoice¶
Allows you to download an invoice in PDF format.
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | download_invoice | main action - download an invoice in PDF format |
| invoice_id | * | int | Invoice number for download | |
| token | * | string | session token |
POST-request, cURL
Positive response
Invoice ID in PDF
whmcs/get_related_invoices¶
Lets you get a list of invoices for a specific server.
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | get_related_invoices | main action - get a list of invoices for a specific server |
| id | * | int | server ID | |
| token | * | string | session token |
POST-request, cURL
Positive response
{
"result": "success",
"invoices": [
{
"id": 23451,
"userid": 3172,
"invoicenum": "",
"date": "2023-12-25",
"duedate": "2024-01-14",
"datepaid": "0000-00-00 00:00:00",
"last_capture_attempt": "0000-00-00 00:00:00",
"date_refunded": "0000-00-00 00:00:00",
"date_cancelled": "0000-00-00 00:00:00",
"subtotal": "5.00",
"credit": "0.00",
"tax": "0.00",
"tax2": "0.00",
"total": "5.00",
"taxrate": "0.00",
"taxrate2": "0.00",
"status": "Unpaid",
"paymentmethod": "paipal",
"paymethodid": null,
"notes": "",
"created_at": "2023-12-25 11:20:31",
"updated_at": "2023-12-25 11:20:31"
},
{
"id": 18580,
"userid": 3172,
"invoicenum": "",
"date": "2023-12-14",
"duedate": "2023-12-29",
"datepaid": "2023-12-14 05:54:52",
"last_capture_attempt": "0000-00-00 00:00:00",
"date_refunded": "0000-00-00 00:00:00",
"date_cancelled": "0000-00-00 00:00:00",
"subtotal": "5.00",
"credit": "5.00",
"tax": "0.00",
"tax2": "0.00",
"total": "0.00",
"taxrate": "0.00",
"taxrate2": "0.00",
"status": "Paid",
"paymentmethod": "paipal",
"paymethodid": null,
"notes": "",
"created_at": "2023-12-14 05:54:31",
"updated_at": "2023-12-14 05:54:52"
}
]
}
Failure response
whmcs/apply_credit¶
Allows you to pay a invoice in full or in part from a credit balance.
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | apply_credit | main action - pay the invoice with credit balance |
| invoice_id | * | int | invoice number | |
| amount | * | int | replenishment amount | |
| token | * | string | session token |
POST-request, cURL
whmcs/create_addfunds¶
Allows you to create an invoice in order to top up credit balance.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | create_addfundst | main action - create an invoice in order to top up credit balance |
| amount | * | int | replenishment amount | |
| token | * | string | session token |
POST-request, cURL
whmcs/get_invoice¶
Allows you to retrieve invoice data for payment.
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | get_invoice | main action - retrieve invoice data for payment |
| invoice_id | * | int | invoice number | |
| token | * | string | session token |
POST-request, cURL
Positive response
{
"result": "success",
"invoiceid": 23455,
"invoicenum": "",
"userid": 3172,
"date": "2023-12-25",
"duedate": "2023-12-25",
"datepaid": "0000-00-00 00:00:00",
"lastcaptureattempt": "0000-00-00 00:00:00",
"subtotal": "800.00",
"credit": "0.00",
"tax": "0.00",
"tax2": "0.00",
"total": "800.00",
"balance": "8.00",
"taxrate": "0.00",
"taxrate2": "0.00",
"status": "Unpaid",
"paymentmethod": "paypal",
"notes": "",
"ccgateway": false,
"items": {
"item": [
{
"id": 25727,
"type": "Invoice",
"relid": 23449,
"description": "Invoice #23449",
"amount": "3.00",
"taxed": 0,
"inv_id": -1
},
{
"id": 25731,
"type": "Invoice",
"relid": 23451,
"description": "Invoice #23451",
"amount": "5.00",
"taxed": 0,
"inv_id": -1
}
]
},
"transactions": ""
}
Failure response
whmcs/get_invoices¶
Allows you to retrieve a complete list of invoices for payment.
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | get_invoices | main action - retrieve a complete list of invoices for payment |
| token | * | string | session token |
POST-request, cURL
Positive response
{
"result": "success",
"totalresults": 6,
"numreturned": 5,
"invoices": {
"invoice": [
{
"id": 23455,
"userid": 3172,
"firstname": "John",
"lastname": "Hostkey",
"companyname": "",
"invoicenum": "",
"date": "2023-12-25",
"duedate": "2023-12-25",
"datepaid": "0000-00-00 00:00:00",
"last_capture_attempt": "0000-00-00 00:00:00",
"date_refunded": "0000-00-00 00:00:00",
"date_cancelled": "0000-00-00 00:00:00",
"subtotal": "8.00",
"credit": "0.00",
"tax": "0.00",
"tax2": "0.00",
"total": "8.00",
"taxrate": "0.00",
"taxrate2": "0.00",
"status": "Unpaid",
"paymentmethod": "paypal",
"paymethodid": null,
"notes": "",
"created_at": "2023-12-25 12:01:27",
"updated_at": "2023-12-25 12:01:27",
"currencycode": "EUR",
"currencyprefix": "",
"currencysuffix": "EUR"
},
{
"id": 23451,
"userid": 3172,
"firstname": "John",
"lastname": "Hostkey",
"companyname": "",
"invoicenum": "",
"date": "2023-12-25",
"duedate": "2024-01-14",
"datepaid": "0000-00-00 00:00:00",
"last_capture_attempt": "0000-00-00 00:00:00",
"date_refunded": "0000-00-00 00:00:00",
"date_cancelled": "0000-00-00 00:00:00",
"subtotal": "5.00",
"credit": "0.00",
"tax": "0.00",
"tax2": "0.00",
"total": "5.00",
"taxrate": "0.00",
"taxrate2": "0.00",
"status": "Unpaid",
"paymentmethod": "paypal",
"paymethodid": null,
"notes": "",
"created_at": "2023-12-25 11:20:31",
"updated_at": "2023-12-25 11:20:31",
"currencycode": "EUR",
"currencyprefix": "",
"currencysuffix": "EUR"
},
{
"id": 23449,
"userid": 3172,
"firstname": "John",
"lastname": "Hostkey",
"companyname": "",
"invoicenum": "",
"date": "2023-12-25",
"duedate": "2024-01-09",
"datepaid": "2023-12-25 13:08:58",
"last_capture_attempt": "0000-00-00 00:00:00",
"date_refunded": "0000-00-00 00:00:00",
"date_cancelled": "0000-00-00 00:00:00",
"subtotal": "3.00",
"credit": "3.00",
"tax": "0.00",
"tax2": "0.00",
"total": "0.00",
"taxrate": "0.00",
"taxrate2": "0.00",
"status": "Paid",
"paymentmethod": "paypal",
"paymethodid": null,
"notes": "",
"created_at": "2023-12-25 11:15:14",
"updated_at": "2023-12-25 13:08:58",
"currencycode": "EUR",
"currencyprefix": "",
"currencysuffix": "EUR"
},
{
"id": 18580,
"userid": 3172,
"firstname": "John",
"lastname": "Hostkey",
"companyname": "",
"invoicenum": "",
"date": "2023-12-14",
"duedate": "2023-12-29",
"datepaid": "2023-12-14 05:54:52",
"last_capture_attempt": "0000-00-00 00:00:00",
"date_refunded": "0000-00-00 00:00:00",
"date_cancelled": "0000-00-00 00:00:00",
"subtotal": "5.00",
"credit": "5.00",
"tax": "0.00",
"tax2": "0.00",
"total": "0.00",
"taxrate": "0.00",
"taxrate2": "0.00",
"status": "Paid",
"paymentmethod": "paypal",
"paymethodid": null,
"notes": "",
"created_at": "2023-12-14 05:54:31",
"updated_at": "2023-12-14 05:54:52",
"currencycode": "EUR",
"currencyprefix": "",
"currencysuffix": "EUR"
},
{
"id": 10116,
"userid": 3172,
"firstname": "John",
"lastname": "Hostkey",
"companyname": "",
"invoicenum": "",
"date": "2023-11-09",
"duedate": "2023-11-24",
"datepaid": "2023-11-09 13:13:37",
"last_capture_attempt": "0000-00-00 00:00:00",
"date_refunded": "0000-00-00 00:00:00",
"date_cancelled": "0000-00-00 00:00:00",
"subtotal": "2.5.00",
"credit": "2.5.00",
"tax": "0.00",
"tax2": "0.00",
"total": "0.00",
"taxrate": "0.00",
"taxrate2": "0.00",
"status": "Paid",
"paymentmethod": "paypal",
"paymethodid": null,
"notes": "",
"created_at": "2023-11-09 12:48:29",
"updated_at": "2023-11-09 13:13:37",
"currencycode": "EUR",
"currencyprefix": "",
"currencysuffix": "EUR"
}
]
}
}
whmcs/request_cancellation¶
Allows you to request a cancellation of the service.
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | request_cancellation | main action - request a cancellation of the service |
| id | * | int | server ID | |
| cancellation_type | * | int | 1 - immediate cancellation with partial refund (if possible), 0 - cancellation at the end of the current billing period. | |
| terminate_reason_custom | string | reason for cancellation | ||
| token | * | string | session token |
POST-request, cURL
Positive response
Failure response
whmcs/delete_cancellation_request¶
Allows you to cancel a request to service cancellation.
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | delete_cancellation_request | main action - delete a request to service cancellation |
| id | * | int | server ID | |
| token | * | string | session token |
POST-request, cURL
Failure response
whmcs/get_cancellation_requests¶
Allows you to get an active list of service cancellation requests.
HTTP Method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | get_cancellation_requests | main action - get an active list of service cancellation requests |
| id | int | server ID | ||
| token | * | string | session token |
POST-request, cURL
Positive response
Failure response
Instant servers¶
Standard configurations for instant servers include compute (VMs), physical servers, physical servers with GPUs, and vGPU servers (VMs with PCIe-passthrough GPUs). These configurations are pre-built and deployed automatically within 10-20 minutes.
You may order instant servers via this API. All payments for instant servers go from the billing's credit account. You should have the necessary funds on account to place an order.
| Resource | Action | Description |
|---|---|---|
| presets.php | list | get a list of available instances for a region |
| os.php | list | get OS list for a specific instance |
| traffic_plans.php | list | get appropriate traffic plans for specific instance |
| eq.php | order_instance | order a specific instance. The order will be fulfilled upon payment of the invoice or from the credit balance. |
The following abbreviations can be used in the response in the name of the instances:
- BM - bare-metal server;
- VM - virtual instance (VM);
- Compute - instance belongs to compute group. Compute group is general use KVM-based virtual servers (VPS);
- Gpu - GPU server;
- Vgpu - vGPU server.
presets/list¶
Allows you to get an up-to-date list of available instances with rental fees. Session token not required.
Information
Currently available instances in Netherlands (ND), USA (US), Finland (FI), Germany (DE), Iceland (IS) and Turkey (TR).
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | list | main action — get a list of available instances for a region |
| location | * | string | instances location - NL/US/FI/DE/IS/TR (Netherlands, USA, Finland, Germany, Iceland, Turkey) |
POST-request, cURL
Positive response
{
"result": "OK",
"action": "list",
"presets": [
{
"id": 108, // instance ID
"name": "vm.pico", // instance name
"active": 1, // active instance
"monthly_com": 3, // price in EUR without local VAT. For EU customers without VAT ID appropriate local VAT needs to be added.
"description": "VM instance 1/1/15 SSD", // Description
"cpu": 1, // CPU cores
"ram": 1, // RAM amount in Gb
"hdd": "15", // storage size in Gb
"gpu": "", // GPU installed, if any
"locations": "NL,US,FI,DE,IS,TR", // available in locations.
"virtual": 1, // an indication that the instance is a virtualized instance (VM)
"price": { // price depends on location
"NL": {
"USD": -1,
"EUR": 3,
},
"US": {
"USD": -1,
"EUR": 3,
},
"FI": {
"USD": -1,
"EUR": 3,
},
"DE": {
"USD": -1,
"EUR": 3,
},
"IS": {
"USD": -1,
"EUR": 3,
},
"TR": {
"USD": -1,
"EUR": 3,
}
},
"available": 184, // amount available immediately to order
"server_type": "Virtual Private Server",
"tags": [ // set of tags to specify proper UI
{
"id": 312305, // Server ID
"component": "presets",
"component_id": 108,
"tag": "stock",
"value": "10",
"extra": "",
"internal": 0
},
{
"id": 312306,
"component": "presets",
"component_id": 108,
"tag": "web_group",
"value": "General",
"extra": "vm",
"internal": 0
},
{
"id": 312307,
"component": "presets",
"component_id": 108,
"tag": "pid_fi",
"value": "3216",
"extra": "",
"internal": 0
},
{
"id": 346027,
"component": "presets",
"component_id": 108,
"tag": "web_hdd",
"value": "SSD",
"extra": "",
"internal": 0
},
{
"id": 346292,
"component": "presets",
"component_id": 108,
"tag": "web_storage",
"value": "true",
"extra": "15GB SSD",
"internal": 0
},
{
"id": 438294,
"component": "presets",
"component_id": 108,
"tag": "pid_de",
"value": "3219",
"extra": "",
"internal": 0
},
{
"id": 481712,
"component": "presets",
"component_id": 108,
"tag": "web_geekbench_score_max",
"value": "11121",
"extra": "",
"internal": 0
},
{
"id": 559071,
"component": "presets",
"component_id": 108,
"tag": "pre_order",
"value": "true",
"extra": "TR",
"internal": 0
},
{
"id": 736612,
"component": "presets",
"component_id": 108,
"tag": "no_increase",
"value": "",
"extra": "",
"internal": 0
},
{
"id": 312308,
"component": "presets",
"component_id": 108,
"tag": "vm",
"value": "true",
"extra": "",
"internal": 1
},
{
"id": 312309,
"component": "presets",
"component_id": 108,
"tag": "compute",
"value": "1",
"extra": "",
"internal": 1
},
{
"id": 312311,
"component": "presets",
"component_id": 108,
"tag": "web_ghz",
"value": "2.6",
"extra": "",
"internal": 1
},
{
"id": 312312,
"component": "presets",
"component_id": 108,
"tag": "web_addinfo",
"value": "true",
"extra": "param1=Delivery ETA: from 2-5 minutes param2=Upgrade: No",
"internal": 1
},
{
"id": 312315,
"component": "presets",
"component_id": 108,
"tag": "pid_nl",
"value": "3201",
"extra": "",
"internal": 1
},
{
"id": 312316,
"component": "presets",
"component_id": 108,
"tag": "pid_us",
"value": "3203",
"extra": "",
"internal": 1
},
{
"id": 458740,
"component": "presets",
"component_id": 108,
"tag": "web_geekbench_score",
"value": "492",
"extra": "Performance",
"internal": 1
},
{
"id": 567279,
"component": "presets",
"component_id": 108,
"tag": "web_label",
"value": "true",
"extra": "[{ "name": "SSD + Xeon E5-26xx","color": "#E23329","number": 2}]",
"internal": 1
},
{
"id": 580969,
"component": "presets",
"component_id": 108,
"tag": "pid_is",
"value": "3221",
"extra": "",
"internal": 1
},
{
"id": 581092,
"component": "presets",
"component_id": 108,
"tag": "pid_tr",
"value": "3223",
"extra": "",
"internal": 1
}
]
} ... , {
"id": 15,
"name": "bm.v1-mini",
"active": 1,
"monthly_com": 35,
"description": "BM i3\/8\/240", // bare-metal server with dual-core i3 processor
"cpu": 2,
"ram": 8,
"hdd": 240,
"gpu": "",
"locations": "NL",
"virtual": 0,
"tags": [
{
"id": 7130,
"tag": "bm", // bare-metal server
"value": "true",
"extra": "",
"internal": 1
}],
"available": 3
}, ... , {
"id": 8,
"name": "vgpu.v1-mini",
"active": 1,
"monthly_com": 157,
"description": "vGPU 4\/16\/240 + 1080",
"cpu": 4,
"ram": 16,
"hdd": 240,
"gpu": "1xGTX1080", // this server is equipped with a GTX 1080 GPU.
"locations": "NL",
"virtual": 1,
"tags": [
{
"id": 7118,
"tag": "gpu", // it's a GPU server
"value": "1",
"extra": "",
"internal": 1
},
{
"id": 11428,
"tag": "vgpu", // it's a vGPU server
"value": "true",
"extra": "",
"internal": 1
}
],
"available": 1
} ... ]
}
Note
Operating system information and a list of post-installation tasks are required for ordering.
os/list¶
Returns a list of suitable operating systems for a given instance. All Windows license prices are already calculated. Without specifying an instance id, the call returns available operating systems for all available instances. Session token is not required.
Note
Please note that all prices are only for the purpose of creating a proper user interface. They will be recalculated in the backend at the time of ordering.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | list | main action — get OS list for a specific instance |
| instance_id | int | instance ID (which can be obtained using the presets/list call) |
POST-request, cURL
Positive response
{
"result": "OK",
"action": "list",
"os_list": [
{
"id": 183, // Operation system ID
"name": "RockyLinux 8",
"api_enabled": 0,
"type_login": 1,
"pxe_os_id": null,
"active": 1,
"description": "",
"tags": [
{
"id": 78797,
"tag": "bm",
"value": "true",
"extra": "",
"component_id": 183,
"component": "OS",
"internal": 0
},
{
"id": 78798,
"tag": "gpu",
"value": "true",
"extra": "",
"component_id": 183,
"component": "OS",
"internal": 0
},
{
"id": 78799,
"tag": "vgpu",
"value": "true",
"extra": "",
"component_id": 183,
"component": "OS",
"internal": 0
},
{
"id": 78800,
"tag": "vm",
"value": "true",
"extra": "",
"component_id": 183,
"component": "OS",
"internal": 0
},
{
"id": 264231,
"tag": "family",
"value": "RockyLinux",
"extra": "50",
"component_id": 183,
"component": "OS",
"internal": 0
},
{
"id": 627236,
"tag": "vds",
"value": "",
"extra": "",
"component_id": 183,
"component": "OS",
"internal": 0
}
]
}, {
"id": 202,
"name": "Windows Server 2022 VM",
"api_enabled": 0,
"type_login": 1,
"pxe_os_id": null,
"active": 0,
"description": "WS22 DC for VMs",
"tags": [
{
"id": 241628,
"tag": "vm",
"value": "true",
"extra": "",
"component_id": 202,
"component": "OS",
"internal": 0
},
{
"id": 241630,
"tag": "min_ram", // minimum RAM requirements
"value": "4", // 4 Gb
"extra": "",
"component_id": 202,
"component": "OS",
"internal": 0
},
{
"id": 241631,
"tag": "min_hdd", // minimum disk space requirements
"value": "32", // 32 Gb
"extra": "",
"component_id": 202,
"component": "OS",
"internal": 0
},
{
"id": 241632,
"tag": "price_per_core_EUR", // MS license fee for the SPLA product in Euro per core
"value": "2",
"extra": "",
"component_id": 202,
"component": "OS",
"internal": 0
},
{
"id": 241634,
"tag": "user_name",
"value": "Administrator",
"extra": "",
"component_id": 202,
"component": "OS",
"internal": 0
},
{
"id": 264276,
"tag": "family",
"value": "Windows Server",
"extra": "70",
"component_id": 202,
"component": "OS",
"internal": 0
},
{
"id": 264320,
"tag": "short_name",
"value": "WS 2022 for VPS",
"extra": "",
"component_id": 202,
"component": "OS",
"internal": 0
}
],
"price_EUR": 2,
"billing_plan": {
"EUR": {
"1": 2, // the estimated cost of this license in Euro (excluding VAT) depending on the number of cores.
"3": 6,
"6": 12,
"12": 24
},
},
"price_EUR": 2
}
]
}
software/list¶
Returns a list of available software to install on the server.
Without specifying an instance ID the call will return the available software to install for all available instances. No session token is required.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | list | main action - get a list of software available for installation on a given instance. |
| location | string | instances location - NL/US/FI/DE/IS/TR (Netherlands, USA, Finland, Germany, Iceland, Turkey) | ||
| instance_id | int | instance ID (which can be obtained using the presets/list call) |
POST-request, cURL
Positive response
{
"result": "OK",
"action": "list",
"software": [
{
"id": 26, // software id
"name": "3X-UI + Shadowsocks/Xray/V2ray VPN server",
"description": "3X-UI provides a graphical user interface for managing a private VPN server with Shadowsocks, V2ray, Xray, Trojan and other popular protocols.",
"price": 0,
"active": 1,
"icon": "",
"task": "invapi_external_3x_vpn_ui_install.dsl",
"tags": [
{
"id": 325472,
"tag": "vm",
"value": "1",
"extra": "",
"component_id": 26,
"component": "software",
"internal": 1
},
{
"id": 325473,
"tag": "bm",
"value": "1",
"extra": "",
"component_id": 26,
"component": "software",
"internal": 1
},
{
"id": 325474,
"tag": "group",
"value": "VPN servers",
"extra": "",
"component_id": 26,
"component": "software",
"internal": 0
},
{
"id": 325475,
"tag": "task",
"value": "invapi_external_3x_vpn_ui_install.dsl",
"extra": "",
"component_id": 26,
"component": "software",
"internal": 1
},
{
"id": 325476,
"tag": "family",
"value": "VPN servers",
"extra": "120",
"component_id": 26,
"component": "software",
"internal": 0
},
{
"id": 345944,
"tag": "description_en",
"value": "",
"extra": "Various web-panels and software for a private VPN servers",
"component_id": 26,
"component": "software",
"internal": 0
},
{
"id": 351007,
"tag": "vgpu",
"value": "1",
"extra": "",
"component_id": 26,
"component": "software",
"internal": 1
},
{
"id": 353230,
"tag": "gpu",
"value": "1",
"extra": "",
"component_id": 26,
"component": "software",
"internal": 1
},
{
"id": 356028,
"tag": "os",
"value": [
"160",
"183",
"184",
"157",
"180",
"144",
"187",
"193"
],
"extra": "U20.4, U22.4, RL8, AL8, D10, D11",
"component_id": 26,
"component": "software",
"internal": 0
},
{
"id": 538578,
"tag": "min_cpu",
"value": "1",
"extra": "",
"component_id": 26,
"component": "software",
"internal": 0
},
{
"id": 538579,
"tag": "min_ram",
"value": "1",
"extra": "",
"component_id": 26,
"component": "software",
"internal": 0
},
{
"id": 611129,
"tag": "family_desc_en",
"value": "",
"extra": "A VPN server is a type of server that enables the hosting and delivery of VPN services. It is a combination of hardware and software technologies that provide a secure connection. Get your ready-to-go VPN server in 15 minutes.",
"component_id": 26,
"component": "software",
"internal": 0
},
{
"id": 1142361,
"tag": "timeout",
"value": "600",
"extra": "",
"component_id": 26,
"component": "software",
"internal": 1
}
]
},
...
{
"id": 65,
"name": "Minecraft: Java Edition Server",
"description": "Minecraft: Java Edition Server is a player-owned or business-owned multiplayer game server software.",
"price": 0,
"active": 1,
"icon": "",
"task": "invapi_external_minecraft_server_install.dsl",
"tags": [
{
"id": 856009,
"tag": "vm",
"value": "1",
"extra": "",
"component_id": 65,
"component": "software",
"internal": 1
},
{
"id": 856011,
"tag": "bm",
"value": "1",
"extra": "",
"component_id": 65,
"component": "software",
"internal": 1
},
{
"id": 856013,
"tag": "vgpu",
"value": "1",
"extra": "",
"component_id": 65,
"component": "software",
"internal": 1
},
{
"id": 856016,
"tag": "min_cpu",
"value": "1",
"extra": "",
"component_id": 65,
"component": "software",
"internal": 0
},
{
"id": 856020,
"tag": "min_ram",
"value": "1",
"extra": "",
"component_id": 65,
"component": "software",
"internal": 0
},
{
"id": 856023,
"tag": "os",
"value": [
"180",
"219",
"219",
"160",
"187",
"217"
],
"extra": "D11,12 U20,22,23",
"component_id": 65,
"component": "software",
"internal": 1
},
{
"id": 856063,
"tag": "tasks",
"value": "invapi_external_minecraft_server_install.dsl",
"extra": "",
"component_id": 65,
"component": "software",
"internal": 0
},
{
"id": 856073,
"tag": "docs_en",
"value": "",
"extra": "https://url.hostkey.com/Minecraft",
"component_id": 65,
"component": "software",
"internal": 0
},
{
"id": 856076,
"tag": "group",
"value": "Games",
"extra": "",
"component_id": 65,
"component": "software",
"internal": 0
},
{
"id": 856081,
"tag": "family",
"value": "Games",
"extra": "31",
"component_id": 65,
"component": "software",
"internal": 0
},
{
"id": 856089,
"tag": "family_desc_en",
"value": "",
"extra": "Game servers are your gateway to hosting and managing online gaming experiences. From multiplayer setups to collaborative gameplay, this category offers server solutions optimized for seamless, high-performance gaming environments. With HOSTKEY you can build your own gaming infrastructure in a few clicks ordering servers with pre-installed games.",
"component_id": 65,
"component": "software",
"internal": 0
}
]
}
]
}
traffic_plans/list¶
Allows you to get a network traffic map for a specific instance in a specific location. Does not require a session token.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | list | main action — get appropriate traffic plans for specific instance |
| location | * | string | instances location - NL/US/FI/DE/IS/TR (Netherlands, USA, Finland, Germany, Iceland, Turkey) | |
| instance_id | int | instance ID (which can be obtained using the presets/list call) |
POST-request, cURL
Positive response
{
"result": "OK",
"action": "list",
"traffic_plans": [
{
"id": 25, // traffic plan ID
"name": "3Tb traffic (1Gbps) VM", // traffic plan name
"limit_in": 999, // Incoming limit, Tb
"limit_out": 3, // Outgoing limit, Tb
"rate_in": 0, // cost of excessive incoming traffic in Euros/Tb
"rate_out": 2, // cost of excessive outbound traffic in Euros/Tb
"bandwidth": 1000, // bandwidth limitation (Mbps)
"locations": "NL,US,FI,DE,IS,TR,", // server region
"currency_id": 0, // this plan for Euro, currency id = 0
"active": 1,
"web_plan": 0,
"price": 0, // flat rate, free of charge
"main_plan": 37,
"tags": [
{
"id": 11449,
"component": "traffic_plans",
"component_id": 25,
"tag": "vm",
"value": "true",
"extra": "",
"internal": 1
}
]
},
{
"id": 37,
"name": "3Tb traffic (1Gbps) VM",
"limit_in": 999,
"limit_out": 3,
"rate_in": 0,
"rate_out": 180,
"bandwidth": 1000,
"locations": "NL,US,FI,DE,IS,TR,",
"currency_id": 0
"active": 1,
"web_plan": 0,
"price": 0,
"main_plan": 25,
"tags": [
{
"id": 11471,
"component": "traffic_plans",
"component_id": 37,
"tag": "vm",
"value": "true",
"extra": "",
"internal": 1
}
]
}
]
}
Failure response
eq/order_instance¶
Allows you to order instant or stock servers (instances) with specified parameters, operating system and software defaults.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | list | main action — order an instance with specified parameters |
| token | * | string | session token | |
| deploy_period | * | string | month, quarter, 6 months, year (monthly, quarterly, semi-annually, annually) | |
| deploy_notify | * | string | email notification upon successful completion of deployment true/false | |
| pin | * | int | PIN code | |
| preset | * | string | deployment instance name - name from presets/list | |
| location_name | * | string | server location name - NL/US/FI/DE/IS/TR (Netherlands, USA, Finland, Germany, Iceland, Turkey) | |
| os_id | * | int | OS ID from the list of operating systems from the output os/list | |
| soft_id | int | Software ID from the output software/list | ||
| traffic_plan | * | string | ID of the selected traffic plan traffic_plans/list | |
| root_pass | * | string | default root password. The password must be a minimum of 8 characters long and include both uppercase and lowercase Latin letters, as well as at least one special character | |
| hostname | string | host name of the deployed instance. Defaults to the instance ID | ||
| ssh_key | string | ssh public key for root user | ||
| post_install_callback | string | URL to be invoked after successful deployment | ||
| post_install_script | string | code to run after successful deployment | ||
| os_name | string | OS name | ||
| own_os | int | if set to 1, the instance will be shipped without without OS installation. This call is useful if you plan to install the operating system later | ||
| root_size | int | is the size of the root partition (/) on the disk in percent. If not specified, it is assumed to be 100 | ||
| jenkins_task | string | Jenkins task ID to run after deployment. Valid values: 1 - install GPU driver, 2 - GPU driver plus NVIDIA docker, 3 - driver, docker plus IOMMU patch, -1 - do nothing. |
POST-request, cURL
curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=order_instance" \
--data "token=$HOSTKEY_TOKEN" \
--data "deploy_period={monthly,quarterly,semi-annually,annually}" \
--data "deploy_notify=true" \
--data "pin={PIN}" \
--data "preset={instance preset name}" \
--data "location_name={Two-letter area code}"
--data "traffic_plan={Traffic plan ID}" \
--data "os_id={operating system ID}" \
--data "soft_id={software ID}" \
--data "root_pass={root password}" \
--data "hostname={host name}" \
--data "ssh_key={public SSH key}" \
--data "post_install_callback=" \
--data "post_install_script=" \
--data "os_name=" \
--data "own_os=" \
--data "root_size=100" \
--data "jenkins_task={Jenkins Task ID, -1, 1, 2, 3}" \
Positive response
Instant Server Ordering Algorithm with eq/order_instance¶
-
Generate a client API key;
-
Choose the location for server ordering from the following options: NL/US/FI/DE/IS/TR (Netherlands, USA, Finland, Germany, Iceland, and Turkey);
-
To determine the ID of the preset to deploy, use the presets/list prompt.
This ID will be used further as
instance_idorpreset. For example, if"id": 108, the values areinstance_id=108andpreset=108; -
Using the os/list query, determine the
os_idof the operating system to be installed, using the instance ID from step 3. For example, for Ubuntu 22.04, this value will be returned in the query response as"id": 187;Note
To deploy the server without installing an operating system, simply specify the
own_os=1parameter at a later time. -
Use the software/list query to determine the deployable software for a given instance and get its ID (hereafter parameter
soft_id). For example, for CMS Wodrpress the query output will be"id": 20;Note
If desired, the software can be installed during deployment or at a later time.
-
Use the [traffic_plans/list] query to get the network traffic plan ID for your server. For example, for a
3Tb traffic (1Gbps) VM plan, the call will return the value"id": 25; -
Obtain the session token
$HOSTKEY_TOKENby making a request to auth/login. -
To order the server, insert the data obtained in steps 2-7 into the eq/order_instance request. Make sure to specify your PIN code (if you haven't set it yet, do so via the eq/set_pin request), root password, and deploy period (monthly, quarterly, 6 months, or yearly). You can choose to receive deployment notifications by mail by setting
deploy_notifytotrue(recommended).
In the eq/order_instance call, you have the option to specify additional parameters.
Here is an example of how to order a server with Wordpress (id=20) on Debian 11 (id=180):
Example POST request for ordering an instant server, cURL
curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=order_instance" \
--data "token=eeee51003b1d81d2eca65660735c0531" \
--data "deploy_period=monthly" \
--data "deploy_notify=true" \
--data "pin=1907" \
--data "preset=108" \
--data "location_name=NL" \
--data "os_id=180" \
--data "soft_id=20" \
--data "traffic_plan=25" \
--data "root_pass=mdLus8Ng" \
Positive response
Upon receiving the request, INVAPI will select/create the appropriate server at a specific location and proceed with its deployment. Prior to any installation, a credit check will be performed (if autopayments from credit is set) or a payment invoice will be issued. If the installation is successful, the new server will be associated with the customer's account. The customer will be notified by email if requested. All paid licenses will be added to the order as add-ons.
Note
Incompatible operating systems and software will result in an error message similar to this:
{
"result": -1,
"error": "reinstall: extra software Odoo (#49) is not compatible with Ubuntu 22.04"
}
To select a different operating system, set a different os_id parameter.
Attention
You may begin using the server once you receive notification of its deployment completion via email or when the server's status changes to Active in the My Servers section of the Invapi control panel . If there is a failure during the server deployment process, you will be notified via email. Please note that deployment may take 20 minutes or longer.
To track the deployment and its status, use asynchronous actions. You can obtain the deploy key by executing the eq/update_servers call.
The installation will be considered successful once you receive an asynchronous action message like this:
Reinstall server using eq/order_instance.¶
To reinstall the server, follow the same steps as for ordering, but include the additional parameter id - the ID of the server to be reinstalled from Invapi - and omit some of the other parameters in eq/order_instance call. You have the option to select a different operating system and pre-installed software, or perform a "clean slate" reinstallation by setting the own_os=1 parameter.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | list | main action — order an instance with specified parameters |
| token | * | string | session token | |
| pin | * | int | PIN code | |
| hostname | string | host name of the deployed instance. Defaults to the instance ID | ||
| os_id | * | int | OS ID from the list of operating systems from the output os/list | |
| soft_id | int | Software ID from the output software/list | ||
| root_pass | * | string | default root password. The password must be a minimum of 8 characters long and include both uppercase and lowercase Latin letters, as well as at least one special character | |
| ssh_key | string | ssh public key for root user | ||
| post_install_script | string | code to run after successful deployment | ||
| own_os | int | if set to 1, the instance will be shipped without without OS installation. This call is useful if you plan to install the operating system later | ||
| root_size | int | is the size of the root partition (/) on the disk in percent. If not specified, it is assumed to be 100 | ||
| id | * | int | reinstall server ID |
Reinstallation POST request, cURL
curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=order_instance" \
--data "token=$HOSTKEY_TOKEN" \
--data "pin={PIN}" \
--data "hostname={host name}" \
--data "os_id={operating system ID}" \
--data "soft_id={software ID}" \
--data "root_pass={root password}" \
--data "ssh_key={public SSH key}" \
--data "post_install_script=" \
--data "os_name=" \
--data "own_os=" \
--data "root_size=100" \
--data "id={Server ID from Invapi}" // Having an ID will initiate the server reinstallation process.
Attention
If you receive a message stating that no server with that ID was found when requesting reinstallation, update the list of servers associated with the session token by executing the eq/update_servers query.
Note
Incompatible operating systems and software will result in an error message similar to this:
{
"result": -1,
"error": "reinstall: extra software Odoo (#49) is not compatible with Ubuntu 22.04"
}
To select a different operating system, set a different os_id parameter.
Attention
Do not begin a new reinstallation until the previous one is complete, or you will receive a warning:
To move our server from its current operating system to Rocky Linux 9 (id=205) and Grafana (id=18), please follow these steps:
Example POST request for reinstallation, cURL
Positive response
Attention
No notification of successful reinstallation will be sent to your email when using this method. Please remember and save the new root password or use the old server password. Information about accessing the ordered software can be found in the Marketplace documentation or directly in the server card of the Invapi control panel.
By utilizing the asynchronous key (callback field), we can monitor the reinstallation process through asynchronous actions.
Example of a successful reinstallation response
Stock servers¶
Stock servers are physical servers with standard configurations that are deployed within one business day, unless otherwise specified.
Stock servers can be ordered through the API.
All payments for stock servers are made from the billing account. To place an order, the required amount must be in the account.
| Resource | Action | Description |
|---|---|---|
| stocks.php | list | get a list of available servers |
| stocks.php | show | get detailed information for a single server |
| eq.php | order_instance | create an order for stock server deployment in the billing, that will be fulfilled once the invoice is paid |
stocks/list¶
This action will let you retrieve a fresh list of available stock servers with configuration and basic pricing. No access token is required
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | list | main action - get a list of available servers |
| location | * | string | 'NL','US','FI','DE','IS','TR' | server location |
| group | * | string | 'ALL', '1CPU', '2CPU', 'GPU', 'AMD', 'AMD-MODERN', 'INTEL' | server group |
- Currently available instances in Netherlands (ND), USA (US), Finland (FI), Germany (DE), Iceland (IS) and Turkey (TR).
- Servers are categorized into the following groups: ALL - all servers, 1CPU - single-processor servers, 2CPU - dual-processor servers, GPU - GPU-based servers, AMD - servers with AMD processors, AMD-MODERN - servers with modern AMD Ryzen processors, INTEL - servers with AMD processors. GPU servers are excluded from other groups.
- Server performance score is shown for its CPU, not GPU.
POST-request, cURL
Positive response
{
"result": "OK",
"action": "list",
"servers": [
{
"id": 40514,
"name": "40514",
"hardware": {
"config": "AMD Ryzen 9 5950X 3.4GHz (16 cores)/128Gb/1Tb NVMe SSD/PSU",
"motherboard_name": "ASRock X570D4U",
"cpu_name": "AMD Ryzen 9 5950X 3.4GHz (16 cores)",
"cpu_type": "AMD-MODERN",
"cpu_count": 1,
"cpu_cores": 16,
"cpu_frq": "3.4",
"ram": 128,
"ram_type": "ddr4ecc",
"hdd_count": 1,
"hdd_groups": [
{
"name": "1Tb NVMe SSD",
"type": "HDD",
"count": 1,
"size": "1024"
}
],
"hdd_pairs": 0,
"gpu_name": null,
"gpu_count": 0,
"raid_levels": [
"LVM_HBA"
]
},
"location": "FI",
"cpu_count": "1",
"cpu_perf": 46719,
"cpu_perflink": "http://www.cpubenchmark.net/cpu_lookup.php?cpu=AMD+Ryzen+9+5950X&id=3862",
"tags": {
"ipmi": {
"tag": "ipmi",
"value": "ami_bmc",
"extra": ""
}
},
"deployment_estimate": "auto",
"billing_plan": {
"EUR": {
"1": 115,
"3": 334.65,
"6": 648.6,
"12": 1214.4
},
},
"server_group": "Dedicated Server"
},
{
"id": 44717,
"name": "44717 2U",
"hardware": {
"config": "2xXeon E5-2680v2 2.8GHz (10 cores)/128Gb/960Gb SSD/2xPSU",
"motherboard_name": "DELL PE R720 MB (native)",
"cpu_name": "Xeon E5-2680v2 2.8GHz (10 cores)",
"cpu_type": "INTEL",
"cpu_count": 2,
"cpu_cores": 20,
"cpu_frq": "2.8",
"ram": 128,
"ram_type": "ddr3reg",
"hdd_count": 1,
"hdd_groups": [
{
"name": "960Gb SSD",
"type": "HDD",
"count": 1,
"size": "960"
}
],
"hdd_pairs": 0,
"gpu_name": null,
"gpu_count": 0,
"raid_levels": [
"LVM_HBA"
]
},
"location": "FI",
"cpu_count": "2",
"cpu_perf": 12615,
"cpu_perflink": "http://www.cpubenchmark.net/cpu_lookup.php?cpu=Intel+Xeon+E5-2680+v2+%40+2.80GHz&id=2061",
"tags": {
"ipmi": {
"tag": "ipmi",
"value": "dell_idrac9",
"extra": ""
},
"hwraid": {
"tag": "hwraid",
"value": "1",
"extra": ""
}
},
"deployment_estimate": "auto",
"billing_plan": {
"EUR": {
"1": 107,
"3": 311.37,
"6": 603.48,
"12": 1129.92
},
},
"server_group": "Dedicated Server"
}
]
}
stocks/show¶
Allows you to get advanced information about a specific server from the general list of available servers.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | show | main action - get detailed information for a single server |
| id | * | int | server ID | |
| eq.php | order_instance | create an order for a stock server deployment. The order will be executed after the invoice is paid |
POST-request, cURL
Positive response
{
"result": "OK",
"action": "show",
"server_data": {
"id": 44717,
"name": "44717 2U",
"hardware": {
"config": "2xXeon E5-2680v2 2.8GHz (10 cores)/128Gb/960Gb SSD/2xPSU",
"motherboard_name": "DELL PE R720 MB (native)",
"cpu_name": "Xeon E5-2680v2 2.8GHz (10 cores)",
"cpu_type": "INTEL",
"cpu_count": 2,
"cpu_cores": 20,
"cpu_frq": "2.8",
"ram": 128,
"ram_type": "ddr3reg",
"hdd_count": 1,
"hdd_groups": [
{
"name": "960Gb SSD",
"type": "HDD",
"count": 1,
"size": "960"
}
],
"hdd_pairs": 0,
"gpu_name": null,
"gpu_count": 0,
"raid_levels": [
"LVM_HBA"
]
},
"location": {
"dc_location": "FI",
"location_id": 4,
"country": "FI"
},
"cpu_count": "2",
"cpu_perf": 12615,
"cpu_perflink": "http://www.cpubenchmark.net/cpu_lookup.php?cpu=Intel+Xeon+E5-2680+v2+%40+2.80GHz&id=2061",
"tags": {
"ipmi": {
"tag": "ipmi",
"value": "dell_idrac9",
"extra": ""
},
"hwraid": {
"tag": "hwraid",
"value": "1",
"extra": ""
}
},
"deployment_estimate": "auto",
"billing_plan": {
"EUR": {
"1": 107,
"3": 311.37,
"6": 603.48,
"12": 1129.92
},
}
}
}
Notable equipment tags¶
- ipmi - The server has an IPMI/DRAC/ILO/etc. managing interface. This does not necessarily mean it can be automatically deployed, but some management tasks will be easier to perform;
- hwraid - The server has a hardware RAID controller installed or identical feature integrated into motherboard. If you want to use this feature, automatic deployment will not be possible, as RAID controller configuration is done by our operations team, usually within the next business day;
- no_autodeploy - This server can not be deployed using our automation tools. Like with hardware raid setup, it will require involvement of our operations team and will be done during the next business day.
Creating a stock server deployment order¶
To order a stock server, use the eq/order_instance call with the ID of the stock server.
Related endpoints¶
- os/list - list appropriate OS's for a given server;
- traffic_plans/list - list appropriate traffic plans for a given server;
- jenkins/get_tasks - list available post-install tasks;
- eq/order_instance - order specific instance/stock server (asynchronous action);
Remote access¶
Bare-metal servers¶
If the server is equipped with IPMI, we could provide direct access there. All our servers have IPMI in the gray IP range. We provide NAT on-demand to external IPs for 2 hours to perform necessary operations.
Asynckeys for all NAT operations should be checked with nat_callback.php:
https://invapi.hostkey.com/nat_callback.php?action=check&key=XXXX
| Resource | Action | Description |
|---|---|---|
| nat.php | add_static_nat | create static DNAT pass-through rule to server's IPMI (public IP to access IPMI of the server) |
| nat.php | remove_static_nat | remove static DNAT pass-through to server's IPMI |
| eq.php | add_ipmi_user | create temp IPMI user for IPMI web access |
| eq.php | remove_ipmi_user | remove temp IPMI user for IPMI web access |
| eq.php | unit_reset | reset IPMI module |
nat/add_static_nat¶
Creates a static DNAT pass-through access rule for the IPMI server.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | add_static_nat | main action - create static DNAT pass-through rule to server's IPMI (public IP to access IPMI of the server) |
| token | * | string | session token | |
| id | * | int | server ID | |
| pin | * | int | PIN code |
POST-request, cURL
Positive response
This action has an asynchronous response
nat/remove_static_nat¶
HTTP method - POST
Removes a static DNAT pass-through to the IPMI server
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | remove_static_nat | main action- remove a static DNAT pass-through to the IPMI server |
| token | * | string | session token | |
| id | * | int | server ID |
POST-request, cURL
Positive response
This action has an asynchronous response
eq/add_ipmi_user¶
Creates a temporary user for web access to IPMI.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | add_ipmi_user | main action - create temp IPMI user for IPMI web access |
| token | * | string | session token | |
| id | * | int | server ID |
POST-request, cURL
Positive response
This action has an asynchronous response
{
"result": "OK",
"scope": "{\"result\":\"OK\",\"message\":\"User added\",\"debug\":\"\"}\n2021/05/17 22:46:55 Set User Password command successful (user 4)\n\n2021/05/17 22:46:55 \n2021/05/17 22:46:56 Set User Access (channel 1 id 4) successful.\n\n2021/05/17 22:46:56 exit status 1\n",
"context": {
"action": "add_ipmi_user",
"id": "server ID",
"location": "NL",
"User": "uHFxxxxx",
"Password": "4Djxxxxx"
},
"debug": null,
"key": "f685eaa0f06e47faa2e6bb5002828b00"
}
eq/remove_ipmi_user¶
Deletes a temporary IPMI user
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | remove_ipmi_user | main action - remove temp IPMI user for IPMI web access |
| token | * | string | session token | |
| id | * | int | server ID |
curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=remove_ipmi_user" \
--data "token=$HOSTKEY_TOKEN" \
--data "id={Server ID}"
POST-request, cURL
This action has an asynchronous response
eq/unit_reset¶
Reloads the IPMI module for a specific server.
Attention
In some cases, it may be necessary to reset the IPMI module if it stops responding or fails to perform some operations. Resetting the IPMI controller can help in these situations.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | unit_reset | main action - reset IPMI module. |
| token | * | string | session token | |
| id | * | int | server ID | |
| pin | * | int | PIN code |
POST-request, cURL
Positive response
This action has an asynchronous response
Virtual servers¶
Remote access actions for Virtual Machines:¶
| Resource | Action | Description |
|---|---|---|
| eq | console | get access to VM console |
eq/console¶
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | console | main action - get access to VM console |
| token | * | string | session token | |
| id | * | int | server ID | |
| pin | * | int | PIN code |
POST-request, cURL
Positive response
This action has an asynchronous response
{
"result": "OK",
"scope": "[virt-viewer]\ntype=spice\nhost=146.0.78.94\nport=6194\npassword=HY14U9qL\n# Password is valid for 120 seconds.\ndelete-this-file=1\nfullscreen=0\ntitle=34533:%d\ntoggle-fullscreen=shift+f11\nrelease-cursor=shift+f12\nsecure-attention=ctrl+alt+end\ntls-port=6195\nenable-smartcard=0\nenable-usb-autoshare=0\nusb-filter=null\ntls-ciphers=DEFAULT\nhost-subject=O=infra.hostkey.com,CN=172.18.2.34\nca=-----BEGIN CERTIFICATE-----\\nMIID+jCCAuKgAwIBAgICEAAwDQYJKoZIhvcNAQELBQAwWjELMAkGA1UEBhMCVVMxGTAXBgNVBAoM\\nEGluZnJhLmhvc3RrZXkucnUxMDAuBgNVBAMMJ292ci1ubC1lbmdpbmUwMmEuaW5mcmEuaG9zdGtl\\neS5ydS40NDU2MTAeFw0yMjA2MDUwNjQyNTZaFw00MjA2MDEwNjQyNTZaMFoxCzAJBgNVBAYTAlVT\\nMRkwFwYDVQQKDBBpbmZyYS5ob3N0a2V5LnJ1MTAwLgYDVQQDDCdvdnItbmwtZW5naW5lMDJhLmlu\\nZnJhLmhvc3RrZXkucnUuNDQ1NjEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCmOyY2\\n9SE0+o37Uft2HQjNcUsa/+KFQ+3/Dk9QTb2/wxIRmQLDWA/TleV2tI2rdRE+UfCnbWarP4++luvy\\nrxqKFKYU5qcf1jC1QXyS9ILkD9Akmj76GGxggmfV2YsvYCxEifSRctL6foUfYiztOqHOtj5MxC2Q\\njC/7yns+Mj8U5aM8J6wYZJI7Cv50qFgKOEMLWqguSalPRInPaFiLxb0PR9MM4vI82UBWY13sCaY2\\nUtAItk3LkKEwuJAW9XaBKPR4eP2v8c9FmvfyUK7uyV+FdEitQWsQlA07fz/Dz2AdodObgmlv9NoO\\ncg0O8sTQsVt8GcXsTXOScrylqUuljGthAgMBAAGjgckwgcYwHQYDVR0OBBYEFGZ9uIc9qrUCU7DZ\\niR4k5/OCDdE4MIGDBgNVHSMEfDB6gBRmfbiHPaq1AlOw2YkeJOfzgg3ROKFepFwwWjELMAkGA1UE\\nBhMCVVMxGTAXBgNVBAoMEGluZnJhLmhvc3RrZXkucnUxMDAuBgNVBAMMJ292ci1ubC1lbmdpbmUw\\nMmEuaW5mcmEuaG9zdGtleS5ydS40NDU2MYICEAAwDwYDVR0TAQH/BAUwAwEB/zAOBgNVHQ8BAf8E\\nBAMCAQYwDQYJKoZIhvcNAQELBQADggEBAHcQuHN3LEEdS3bCh41xOfPD3zbR4pcmHp6N5ng0FDCs\\nOZD5sO+PSrIsYP3gegVFxUomjR3AJ9TZojpodZYnzbgzaCCvC1JOb6VT35ekmNinvMfpkMB2WptM\\nPkME6sFJS4oxo6pmoPZvlKINBr3dYLcpLmFv9nYLALvL+LYxGjgnxa8bLokPYI3Pz5LL4JE8TQp0\\nFL9U6cs4DDueN0vwmNeRYb//PdSS8snlcYRhSKRsRdxx0moYSM0+CMOutjuVlXGjDxq3f6clnz1I\\nVY1/VLw1OyJTHOCHez+phC702Oh4Z5/1lMzWbRrKdZMEWweMif3VmIMMXe5JnaluF6lopW4=\\n-----END CERTIFICATE-----\\n\nsecure-channels=main;inputs;cursor;playback;record;display;smartcard;usbredir\nversions=rhev-win64:2.0-160;rhev-win32:2.0-160;rhel8:7.0-3;rhel7:2.0-6;rhel6:99.0-1\nnewer-version-url=http://www.ovirt.org/documentation/admin-guide/virt/console-client-resources\n\n[ovirt]\nhost=ovr-nl-engine02a.infra.hostkey.com:443\nvm-guid=12b720b2-d878-4f6c-a2cc-61a61f200a48\nsso-token=mcHYs92LDliDuVJ2lHKY8nNugkPS49IuTnS3_hpKOtylYX8DbCxAOAAm8J5ib_5-XNoRzoltHvjruHsWAY7fAw\nadmin=1\nca=-----BEGIN CERTIFICATE-----\\nMIID+jCCAuKgAwIBAgICEAAwDQYJKoZIhvcNAQELBQAwWjELMAkGA1UEBhMCVVMxGTAXBgNVBAoM\\nEGluZnJhLmhvc3RrZXkucnUxMDAuBgNVBAMMJ292ci1ubC1lbmdpbmUwMmEuaW5mcmEuaG9zdGtl\\neS5ydS40NDU2MTAeFw0yMjA2MDUwNjQyNTZaFw00MjA2MDEwNjQyNTZaMFoxCzAJBgNVBAYTAlVT\\nMRkwFwYDVQQKDBBpbmZyYS5ob3N0a2V5LnJ1MTAwLgYDVQQDDCdvdnItbmwtZW5naW5lMDJhLmlu\\nZnJhLmhvc3RrZXkucnUuNDQ1NjEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCmOyY2\\n9SE0+o37Uft2HQjNcUsa/+KFQ+3/Dk9QTb2/wxIRmQLDWA/TleV2tI2rdRE+UfCnbWarP4++luvy\\nrxqKFKYU5qcf1jC1QXyS9ILkD9Akmj76GGxggmfV2YsvYCxEifSRctL6foUfYiztOqHOtj5MxC2Q\\njC/7yns+Mj8U5aM8J6wYZJI7Cv50qFgKOEMLWqguSalPRInPaFiLxb0PR9MM4vI82UBWY13sCaY2\\nUtAItk3LkKEwuJAW9XaBKPR4eP2v8c9FmvfyUK7uyV+FdEitQWsQlA07fz/Dz2AdodObgmlv9NoO\\ncg0O8sTQsVt8GcXsTXOScrylqUuljGthAgMBAAGjgckwgcYwHQYDVR0OBBYEFGZ9uIc9qrUCU7DZ\\niR4k5/OCDdE4MIGDBgNVHSMEfDB6gBRmfbiHPaq1AlOw2YkeJOfzgg3ROKFepFwwWjELMAkGA1UE\\nBhMCVVMxGTAXBgNVBAoMEGluZnJhLmhvc3RrZXkucnUxMDAuBgNVBAMMJ292ci1ubC1lbmdpbmUw\\nMmEuaW5mcmEuaG9zdGtleS5ydS40NDU2MYICEAAwDwYDVR0TAQH/BAUwAwEB/zAOBgNVHQ8BAf8E\\nBAMCAQYwDQYJKoZIhvcNAQELBQADggEBAHcQuHN3LEEdS3bCh41xOfPD3zbR4pcmHp6N5ng0FDCs\\nOZD5sO+PSrIsYP3gegVFxUomjR3AJ9TZojpodZYnzbgzaCCvC1JOb6VT35ekmNinvMfpkMB2WptM\\nPkME6sFJS4oxo6pmoPZvlKINBr3dYLcpLmFv9nYLALvL+LYxGjgnxa8bLokPYI3Pz5LL4JE8TQp0\\nFL9U6cs4DDueN0vwmNeRYb//PdSS8snlcYRhSKRsRdxx0moYSM0+CMOutjuVlXGjDxq3f6clnz1I\\nVY1/VLw1OyJTHOCHez+phC702Oh4Z5/1lMzWbRrKdZMEWweMif3VmIMMXe5JnaluF6lopW4=\\n-----END CERTIFICATE-----\\n\n\n",
"context": {
"action": "console",
"id": "34533",
"location": "NL",
"ip_ipmi": ""
},
"debug": "",
"key": "f28dfd83fbc1dbb914710774d8e9e30a"
}
Data from scope should be stored in console.vv file for virtual machine viewer or accessed other way via VNC.
Following JS code do this action:
var blob = new Blob([result.scope], {
type: 'text/octet-stream'
});
var filename = "console.vv";
if (window.navigator.msSaveOrOpenBlob) {
window.navigator.msSaveBlob(blob, "console.vv");
} else {
var elem = document.createElement('a');
elem.href = window.URL.createObjectURL(blob);
elem.download = filename;
document.body.appendChild(elem);
elem.click();
document.body.removeChild(elem);
}
Server control¶
Information
Most of the server control actions are part of the eq (equipment) resource.
| Resource | Action | Description |
|---|---|---|
| eq.php | list | get servers list, search for servers |
| eq.php | show | get full information about the server |
| eq.php | update_servers | refresh the active server's list |
eq/list¶
Searches servers by location, status, hardware, IP, and properties.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | list | main action - Get servers list, search for servers. The list function returns the server's id which matched search criteria. |
| default (no extra parameters) | (without additional parameters) - return all assigned server's ID | |||
| location | string | Show servers from a specific region. Possible values: NL,US,FI,DE,IS and TR. Example: location=IS,NL (all servers from IS and NL regions) | ||
| status | string | show servers with a specific status. Possible customer's statuses: rent (active server), power_off (suspended for a reason). Example: status=power_off will show all suspended servers. | ||
| component | string | servers with a specific component like CPU or GPU. Usage component=12345,5456,.. where numbers are components ID | ||
| ip | string | server with specific IP address. Example: ip=199.100.7.5 | ||
| mac | string | server with specific MAC address. Example: mac=00.00.00.00.00.00 | ||
| Mini | string | compact servers with single CPU and IPMI | ||
| Storage | string | servers intended to be used as a storage | ||
| Nodes | string | servers intend to be used as virtualization nodes | ||
| Micro | string | servers with single CPU and without IPMI | ||
| VPS | string | virtual servers | ||
| 1CPU | string | servers with single CPU | ||
| 2CPU | string | servers with dual CPU's | ||
| Dell | string | Dell branded servers | ||
| Gpu | string | GPU servers | ||
| Instances | string | servers with standard configuration and full remote control | ||
| AMD | string | EPYC and Ryzen based servers |
You may request several groups like all servers with groups 1CPU AND AMD:
Note
For search inside server's tags API call resource tags, action user_search.
POST-request, cURL
eq/show¶
Provides information about a specific server.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | show | main action - provides information about a specific server. |
| token | * | string | session token | |
| id | * | int | server ID |
POST-request, cURL
Positive response
{
"result": "OK",
"server_data": {
"id": 34533,
"ref_tableName": "VPS",
"Condition_Component": "rent",
"account_id": 5724,
"type_billing": "whmcs_com",
"is_owner": "Rent",
"cost_trafficIN": 0,
"limit_trafficIN": 999,
"cost_traffic": 180,
"limit_traffic": 3,
"new_limit_traffic": 0,
"limit_bands": 1000,
"trafficPeriodOut": 0,
"trafficPeriodIn": 0,
"trafficPeriodOutBilling": 0,
"trafficPeriodInBilling": 0,
"datePeriod": "2024-01-14 00:00:00",
"IsShape": 1,
"hwconfig": "4 vCore/4Gb/60Gb SSD",
"status": "rent",
"type": "VPS",
"days_left": 18,
"due_date": "2024-01-14"
},
"hardware": {
"config": "4 vCore/4Gb/60Gb SSD",
"components": [
{
"Type": "Platform",
"Name": "Ovirt VM",
"Count": 1,
"hdd_type": "SSD"
},
{
"Type": "CPU",
"Name": "VPS Core",
"Count": 4,
"hdd_type": "SSD",
"Cores": 4,
"cpu_type": "INTEL"
},
{
"Type": "RAM",
"Name": "VPS RAM 1Gb",
"Count": 4,
"hdd_type": "SSD",
"Size": 1
},
{
"Type": "HDD",
"Name": "VPS HDD 10 Gb",
"Count": 6,
"hdd_type": "SSD",
"Size": 10
}
],
"tags": {
"platform_ipmi": [
"ovirt"
],
"platform_location": [
"NL,US,FI,IS,DE"
],
"platform_tdp": [
"1"
],
"platform_blades": [
"100"
],
"platform_nojava_console": [
""
],
"platform_vm": [
"true"
],
"platform_virt": [
"1"
],
"cpu_location": [
"NL,US,FI,IS,TR",
"NL,US,FI,IS,TR",
"NL,US,FI,IS,TR",
"NL,US,FI,IS,TR"
],
"cpu_deprecation": [
"8",
"8",
"8",
"8"
],
"cpu_production_start": [
"",
"",
"",
""
],
"cpu_tdp": [
"1",
"1",
"1",
"1"
],
"cpu_virt": [
"1",
"1",
"1",
"1"
],
"cpu_frq": [
"2.4",
"2.4",
"2.4",
"2.4"
],
"cpu_cores": [
"1",
"1",
"1",
"1"
],
"ram_vm": [
"1",
"1",
"1",
"1"
],
"ram_location": [
"NL,US,FI,IS,TR",
"NL,US,FI,IS,TR",
"NL,US,FI,IS,TR",
"NL,US,FI,IS,TR"
],
"ram_ram_type": [
"VRAM",
"VRAM",
"VRAM",
"VRAM"
],
"ram_size": [
"1",
"1",
"1",
"1"
],
"ram_ramtype": [
"VRAM",
"VRAM",
"VRAM",
"VRAM"
],
"ram_virt": [
"1",
"1",
"1",
"1"
],
"hdd_location": [
"NL,US,FI,IS,TR",
"NL,US,FI,IS,TR",
"NL,US,FI,IS,TR",
"NL,US,FI,IS,TR",
"NL,US,FI,IS,TR",
"NL,US,FI,IS,TR"
],
"hdd_tdp": [
"0.01",
"0.01",
"0.01",
"0.01",
"0.01",
"0.01"
],
"hdd_size": [
"10",
"10",
"10",
"10",
"10",
"10"
],
"hdd_type": [
"HDD",
"HDD",
"HDD",
"HDD",
"HDD",
"HDD"
],
"hdd_virt": [
"1",
"1",
"1",
"1",
"1",
"1"
],
"hdd_interface": [
"SATA",
"SATA",
"SATA",
"SATA",
"SATA",
"SATA"
],
"hdd_interface_sata": [
"SATA",
"SATA",
"SATA",
"SATA",
"SATA",
"SATA"
],
"eta": 0.07
},
"vm": 1,
"gpu": 0,
"vds": 0,
"uefi": 0,
"hwraid": 0,
"motherboard_name": "",
"cpu_name": "vCPU",
"cpu_type": "vCPU",
"cpu_count": 4,
"cpu_cores": 4,
"cpu_frq": "2.4",
"ram": 4,
"ram_type": "vram",
"hdd": 60,
"hdd_count": 1,
"hdd_groups": [
{
"name": "60Gb SSD",
"type": "HDD",
"count": 1,
"size": "60"
}
],
"hdd_pairs": 0,
"gpu_name": null,
"gpu_count": 0,
"raid_levels": [
"LVM_HBA"
]
},
"groups": [
{
"ID": "26",
"Code": "Micro",
"Name": "Micro",
"active": 0
},
{
"ID": "32",
"Code": "1CPU",
"Name": "1CPU",
"active": 0
},
{
"ID": "33",
"Code": "2CPU",
"Name": "2CPU",
"active": 0
},
{
"ID": "39",
"Code": "OUT",
"Name": "OUT",
"active": 0
},
{
"ID": "41",
"Code": "Gpu",
"Name": "Gpu",
"active": 0
},
{
"ID": "52",
"Code": "1CPU_OUT_NEW",
"Name": "1CPU_OUT_NEW",
"active": 0
},
{
"ID": "53",
"Code": "Ryzen",
"Name": "Ryzen",
"active": 0
},
{
"ID": "54",
"Code": "5Ghz",
"Name": "5Ghz",
"active": 0
},
{
"ID": "55",
"Code": "2CPU_OUT_NEW",
"Name": "2CPU_OUT_NEW",
"active": 0
},
{
"ID": "59",
"Code": "Promo",
"Name": "Promo",
"active": 0
}
],
"licenses": [
{
"id": 124,
"name": "ISPmanager 6 Lite on IP 31.207.44.105",
"amount": 1,
"date_buy": ""
}
],
"location": {
"dc_location": "NL",
"location_id": 1
},
"OS": null,
"IP": [
{
"port": "eth0",
"MAC": "56:6f:ff:5b:08:7b",
"IP": "31.207.44.105",
"status": "enable",
"main_ip": 1,
"locked": 0,
"date_block": null,
"license_id": 124,
"main_int": 1,
"vlan": 415,
"updated": 13,
"license_name": "ISPmanager",
"white_ddos": 0,
"description": ""
}
],
"interfaces": [
{
"id": 122936,
"type": "eth0",
"mac": "56:6f:ff:5b:08:7b",
"upstream_id": null,
"IsMain": 1,
"IsVirt": 0,
"Status": "enable",
"switch_owner": "",
"switch_model": "virtual"
}
],
"IPMI": {
"model": "ovirt",
"interfaces": []
},
"tags": [
{
"id": 799108,
"component": "Component1",
"component_id": 34533,
"tag": "order_origin",
"value": "invapi",
"extra": "1",
"internal": 0
},
{
"id": 799112,
"component": "Component1",
"component_id": 34533,
"tag": "hostname",
"value": "nl-vmmini",
"extra": "",
"internal": 0
},
{
"id": 799116,
"component": "Component1",
"component_id": 34533,
"tag": **Password**,
"value": "wK5Vjwx_BC",
"extra": "",
"internal": 0
},
{
"id": 799128,
"component": "Component1",
"component_id": 34533,
"tag": "OS",
"value": "Ubuntu 22.04",
"extra": "",
"internal": 0
},
{
"id": 799132,
"component": "Component1",
"component_id": 34533,
"tag": "user_name",
"value": "root",
"extra": "",
"internal": 0
},
{
"id": 799137,
"component": "Component1",
"component_id": 34533,
"tag": "webpanel",
"value": "ispmanager6",
"extra": "https://isp34533.hostkey.in:1500/ispmgr",
"internal": 0
}
],
"preset": "vm.mini",
"preset_description": "VM instance 4/4/60 SSD"
}
eq/update_servers¶
Refresh the active server's list. If the customer has ordered or released a server, it's necessary to refresh the server's list. This action will check again inventory and refresh token with the current server's list.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | update_servers | main action - refresh the active server's list |
| token | * | string | session token |
POST-request, cURL
Server power control¶
We manage our bare-metal servers via an out-of-band IPMI module. oVirt VMs are managed via standard API.
| Resource | Action | Description |
|---|---|---|
| eq.php | status | get power status |
| eq.php | sensors | get sensors data (bare-metal only) |
| eq.php | on | turn power on |
| eq.php | off | turn power off |
| eq.php | reboot | reboot server |
eq/status¶
Allows you to view the power status of the server.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | status | main action - get power status |
| token | * | string | session token | |
| id | * | int | server ID |
POST-request, cURL
Positive response
This action has an asynchronous response
eq/sensors (bare-metal only)¶
Allows you to retrieve data from the bare-metal server's sensors.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | sensors | main action- get sensors data |
| token | * | string | session token | |
| id | * | int | server ID |
POST-request, cURL
Positive response
This action has an asynchronous response
{
"result": "OK",
"scope": "CPU Temp | 36 degrees C | ok\nPCH Temp | 37 degrees C | ok\nSystem Temp | 25 degrees C | ok\nPeripheral Temp | 33 degrees C | ok\nVcpuVRM Temp | 34 degrees C | ok\nVmemABVRM Temp | 31 degrees C | ok\nVmemCDVRM Temp | 30 degrees C | ok\nP1-DIMMA1 Temp | 26 degrees C | ok\nP1-DIMMB1 Temp | 26 degrees C | ok\nP1-DIMMC1 Temp | no reading | ns\nP1-DIMMD1 Temp | no reading | ns\nFAN | 3100 RPM | ok\n12V | 12.06 Volts | ok\n5VCC | 5.08 Volts | ok\n3.3VCC | 3.33 Volts | ok\nVBAT | 3.00 Volts | ok\nVcpu | 1.84 Volts | ok\nVDIMMAB | 1.22 Volts | ok\nVDIMMCD | 1.22 Volts | ok\n5VSB | 5.10 Volts | ok\n3.3VSB | 3.27 Volts | ok\n1.5V PCH | 1.53 Volts | ok\n1.2V BMC | 1.23 Volts | ok\n1.05V PCH | 1.06 Volts | ok\nPS Status | 0x01 | ok\n",
"context": {
"action": "get_sensors",
"id": "Server ID",
"location":"NL"
},
"debug":"CPU Temp | 36 degrees C | okPCH Temp | 37 degrees C | okSystem Temp | 25 degrees C | okPeripheral Temp | 33 degrees C | okVcpuVRM Temp | 34 degrees C | okVmemABVRM Temp | 31 degrees C | okVmemCDVRM Temp | 30 degrees C | okP1-DIMMA1 Temp | 26 degrees C | okP1-DIMMB1 Temp | 26 degrees C | okP1-DIMMC1 Temp | no reading | nsP1-DIMMD1 Temp | no reading | nsFAN | 3100 RPM | ok12V | 12.06 Volts | ok5VCC | 5.08 Volts | ok3.3VCC | 3.33 Volts | okVBAT | 3.00 Volts | okVcpu | 1.84 Volts | okVDIMMAB | 1.22 Volts | okVDIMMCD | 1.22 Volts | ok5VSB | 5.10 Volts | ok3.3VSB | 3.27 Volts | ok1.5V PCH | 1.53 Volts | ok1.2V BMC | 1.23 Volts | ok1.05V PCH | 1.06 Volts | okPS Status | 0x01 | ok",
"key":"f685eaa0f06e47faa2e6bb5002828b00"
}
eq/on¶
Allows you to power on the server.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | on | main action - turn power on |
| token | * | string | session token | |
| id | * | int | server ID | |
| pin | * | int | PIN code |
POST-request, cURL
Positive response
This action has an asynchronous response
eq/off¶
Allows you to turn off power to the server.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | off | main action - turn power off |
| token | * | string | session token | |
| id | * | int | server ID | |
| pin | * | int | PIN code |
POST-request, cURL
Positive response
This action has an asynchronous response
eq/reboot¶
Allows you to perform a server reboot.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | reboot | main action - reboot server |
| token | * | string | session token | |
| id | * | int | server ID | |
| pin | * | int | PIN code |
POST-request, cURL
Positive response
This action has an asynchronous response
Reinstall the operating system on the server (second option)¶
This reinstall option is used for servers that failed to reinstall using the first method.
We are using Foreman to deploy servers via PXE network boot. The installation process goes in several stages:
- Create reinstall stage key (optional) via eq/reinstall;
- Create PXE config with parameters via eq/create_pxe;
- Change server boot order via eq/bootdev. It should run from PXE;
- Reboot the server via eq/reboot;
- The server will
catchthe 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;
- After installing the operating system, you should change the boot order via eq/bootdev. The server must boot from the HDD;
- Run extra Jenkins task on a server (i.e. install GPU drivers);
- Remove PXE config via eq/clear_pxe. This action will prevent a sudden reinstallation.
| Resource | Action | Description |
|---|---|---|
| eq.php | reinstall | create master key for reinstall OS |
| os.php | list | get a list of OS for a server |
| jenkins.php | list | retrieve available Ansible tasks |
| eq.php | create_pxe | create PXE config for OS install |
| eq.php | boot_dev | set boot order for VM or bare-metal server |
| eq.php | reboot | reboot server |
eq/reinstall¶
Allows you to create a $REINSTALL_KEY master key for reinstalling the operating system.
Note
If we need to automate the whole reinstall process, we will need a master key to keep track of different actions. All stage alerts from the OS installer go to this key. As the OS install goes on, it will report stages via async responses via this key. This key will be required for eq/create_pxe.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | string | reinstall | main action - create master key for reinstall | |
| token | * | string | session token | |
| id | * | int | server ID |
POST-request, cURL
Positive response
Note
For information on all steps of the reinstallation process, call eq_callback/check.
eq_callback/check¶
Get information about all stages of reinstalling the operating system.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | string | check | main action - get information about the stage of the OS reinstallation | |
| reinstall_key | string | $REINSTALL_KEY from eq/reinstall to track reinstallation steps |
POST-request, cURL
Positive response
{
"result":"Stage", // Informative message about the progress of the installation process
"scope":" (1\/5) OS installation started", // Stage information
"context":{"action":"reinstall","id":"42253","location":"NL"}, // Installation information (main action, server ID, and location)
"key":"aa719bfc59c3626c059950c1dcb4dbfa" // $REINSTALL_KEY
}
Actions to take before starting the OS installation¶
Before we start with reinstall, some mandatory information should be collected:
-
Get the list of operating systems that can be installed by calling os_list
Attention
You will also need to select a host name and password before starting the reinstallation.
-
Select disk partitioning scheme:
- LVM_RAID0 - create stripe across all disks via LVM;
- LVM_HBA - install OS on the smallest device, let the rest untouched, applicable if there are more than 1 storage device;
- LVM_RAID1 - create disk mirror via LVM, applicable if there are two similar storage devices;
- LVM_RAID10 - create LVM RAID10 across all storage device pairs, minimum 2 pairs of devices required;
- LVM_RAID10S - create LVM RAID1 on smallest storage devices pairs for OS, create LVM RAID10 on rest of storage devices pars.
-
Prepare a Public ssh key if you want to set your SSH key for admin login.
-
Think about Post-install tasks - standardized Ansible tasks that can be run on the server after installation via Jenkins. You can get a list of them by calling jenkins/get_tasks.
jenkins/get_tasks¶
This will retrieve all possible Ansible tasks with its tags. You could load this data in JS variables and show it for appropriate servers - checking by tags.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | get_tasks | main action - retrieve available Ansible tasks |
Possible tags:
- gpu - task is suitable for GPU servers;
- bm - task is suitable for bare-metal server;
- vm - task is suitable for VM (VPS);
- vgpu - task is suitable for vGPU server;
- default - default value.
POST-request, cURL
Positive response
{
"result": "OK",
"tasks": [{
"id": -1,
"task": "",
"desc": "Do nothing",
"tag": "",
"tags": [{
"tag": "gpu"
}, {
"tag": "vgpu"
}, {
"tag": "vm"
}, {
"tag": "bm"
}]
}, {
"id": 1,
"task": "invapi_gpu_conf_iommu_patch_gpu_linux_auto.dsl", // task name
"desc": "Install GPU drivers" // human readable description
"tag": "gpu_driver", // task variant
"tags": [{ // Tags for filtering output in the user interface
"tag": "gpu"
}, {
"tag": "vgpu"
}, {
"tag": "default"
}]
}, {
"id": 2,
"task": "invapi_gpu_conf_iommu_patch_gpu_linux_auto.dsl",
"desc": "Install GPU drivers + NVIDIA docker",
"tag": "gpu_driver_docker",
"tags": [{
"tag": "gpu"
}, {
"tag": "vgpu"
}]
}, {
"id": 3,
"task": "invapi_gpu_conf_iommu_patch_gpu_linux_auto.dsl",
"desc": "Install GPU drivers + NVIDIA docker + IOMMU patch",
"tag": "gpu_driver_docker_iommu",
"tags": [{
"tag": "gpu"
}, {
"tag": "vgpu"
}]
}]
}
Post-install script - the piece of bash/PS code to be executed on the first run in fresh OS. Useful for automation to include a new server to the managed infrastructure.
Post-install callback URL - URL which will be called from the fresh server after installation. Useful for billing purposes.
As we have all data ready, we could try to create a PXE config for OS install
eq/create_pxe¶
Create PXE config for OS install.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | create_pxe | main action - creating a PXE configuration for OS installation |
| token | * | string | session token | |
| id | * | int | server ID | |
| pin | * | int | PIN code | |
| os_id | * | int | OS ID from os/list | |
| root_pass | * | string | password for the administrative user. length and content should meet security policy - min 8 symbols, with some numbers and letters in caps | |
| hostname | * | string | desired hostname for the server | |
| ssh_key | string | Public ssh key(optional) | ||
| post_install_callback | string | URL to call after install is completed | ||
| post_install_script | string | Post-install script to run | ||
| reinstall_key | string | $REINSTALL_KEY from eq/reinstall to track reinstallation steps |
POST-request, cURL
curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=create_pxe" \
--data "token=$HOSTKEY_TOKEN" \
--data "email=" \
--data "pin={PIN code}" \
--data "id={Server ID}" \
--data "os_id={OS ID}" \
--data "root_pass={root password}" \
--d--data "hostname={Server name}" \
--data "ssh_key={public SSH key}" \
--data "post_install_callback=" \
--data "post_install_script=" \
--data "reinstall_key=$REINSTALL_KEY" \
Positive response
This action has an asynchronous response
If there was no errors, we need to set server's boot order to network boot via PXE call eq/boot_dev.
eq/boot_dev¶
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | boot_dev | main action - set boot order for VM or bare-metal server |
| token | * | string | session token | |
| pin | * | int | PIN code | |
| id | * | int | server ID | |
| media | int | pxe for PXE boot, disk local storage device boot, cd for mounted CD boot (usually via virtual media via IPMI) |
POST-request, cURL
Positive response
This action has an asynchronous response
After successful change of boot order we should reboot server via call eq/reboot.
The system will reboot and start loading from PXE. After the OS installer is loaded, you will see stage notifications - it could be retrieved with the main reinstall key from eq/reinstall and call eq_callback/check.
If eq_callback/check have got result OK, this means server is online and reinstall is completed. After we will retrieve this value, reinstall key will be removed from database.
Now you need to perform post-installation tasks:
- Reboot from disk calling eq/boot_dev with parameter
media=disk
This action has an asynchronous response
- Clear PXE configuration calling eq/clear_pxe.
Attention
Be sure to clear the PXE configuration. This will prevent sudden reinstallations.
eq/clear_pxe¶
Clear PXE config.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | clear_pxe | main action - clear PXE config to avoid sudden reinstalls |
| token | * | string | session token | |
| id | * | int | server ID | |
| hostname | * | string | server name |
POST-request, cURL
Positive response
This action has an asynchronous response
Network operations¶
| Resource | Action | Description |
|---|---|---|
| net.php | get_status | Retrieve interface status |
| net.php | port_off | Disable interface |
| net.php | port_on | Enable interface |
| net.php | show_cacti | View port speed graphs |
| ip.php | show_cacti | Get IP information |
| ip.php | get_ptr | Get PTR record for IP |
| ip.php | update_ptr | Update PTR record for IP |
| ip.php | set_main | Set IP option for a server |
| net.php | block_ip | Block specific IP |
| net.php | unblock_ip | Unblock specific IP |
net/get_status¶
Displays the status of the network interface.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | get_status | main action — retrieve interface status |
| token | * | string | session token | |
| id | * | int | server ID | |
| pin | * | int | PIN code | |
| port | string | physical port's switch | ||
| switch | string | switch ID and address | ||
| vlan | int | VLAN number (if any) | ||
| speed | string | physical interface speed | ||
| status | string | interface status, connected or not | ||
| mac | string | MAC information (if any) | ||
| port_security | string | maximum allowed MACs on port (if any) | ||
| shape | string | port speed limits (if any) |
POST-request, cURL
Positive response
This action has an asynchronous response
{
"result": "OK",
"scope": "{\"switch\":\"virtual\",\"port\":\"virtual\",\"vlan\":\"v415\",\"speed\":\"1000\",\"status\":\"connected\",\"mac\":[\"56:6f:ff:5b:08:7b\"],\"port_security\":\"\",\"shape\":\"\",\"interface\":\"eth0\"}", // interface description
"context": {
"action": "get_status",
"id": "34533",
"location": "NL",
"ip_ipmi": "0.0.0.0",
"interface_id": "eth0",
"port": "eth0" // physical port Switch
},
"debug": "get status port via Ovirt API",
"key": "a1bc5aebbfb62a8350020d9da42e1c1e"
}
net/port_off¶
Allows you to disable the network port.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | port_off | main action — disable interface |
| token | * | string | session token | |
| id | * | int | server ID | |
| pin | * | int | PIN code | |
| port | * | string | physical port's switch |
POST-request, cURL
Positive response
This action has an asynchronous response
net/port_on¶
Enables the network port.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | port_on | main action — enable interface |
| token | * | string | session token | |
| id | * | int | server ID | |
| pin | * | int | PIN code | |
| port | * | string | physical port's switch |
POST-request, cURL
Positive response
This action has an asynchronous response
net/show_cacti¶
Lets you view a graph of port speeds over a period of time.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | show_cacti | main action — show port speed graphs |
| token | * | string | session token | |
| id | * | int | server ID | |
| pin | * | int | PIN code | |
| port | * | string | physical port's switch | |
| graph | * | string | graph values - 1 for daily, 2 for monthly, 3 for annual graphs |
POST-request, cURL
Positive response
traffic graph image
Failure response :
ip/get_ip¶
Lets you get information about a network interface by IP address.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | get_ip | main action — get IP information |
| token | * | string | session token | |
| ip | * | int | IP address |
POST-request, cURL