API-Documentation¶
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.
Main information¶
API is built on traditional principles with action selector and auth token authorization.
ou can use POST or GET messages for all API calls, except authorization actions.
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:
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
We will use POST examples only in this documentation because this method is preferred.
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
``` bash
{ "result": "Fail", "scope": "Invalid PIN/email combination, please check", "context": { "action": "set_pin", "id": "0" }, "status": "failure", "created": "2021-05-17 21:07:55", "debug": null, "key": "4746d646be54d7805f10e1b6c4f003bb" } ```
Note
This action has an asynchronous response.
eq/check_pin¶
Allows you to confirm the correctness of the entered client PIN.
HTTP method - POST/GET
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | check_pin | main action - validate entered PIN |
| token | * | string | session token | |
| old_pin | if modified | int | PIN code |
POST-request, cURL
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. |
| 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
curl -s "https://invapi.hostkey.com/ip.php" -X POST \
--data "action=get_ip" \
--data "token=$HOSTKEY_TOKEN" \
--data "ip={IP address}" \
Positive response
ip/get_ptr¶
Allows you to retrieve a PTR record for a specified IP address.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | get_ptr | main action — get PTR record for IP |
| token | * | string | session token | |
| id | * | int | server ID | |
| ip | * | int | IP address |
POST-request, cURL
ip/update_ptr¶
Allows you to update PTR record for a specified IP address.
Note
There are allowed to have more than one reverse record for IP. Supplying several RRs could be done with a %0A separator.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | update_ptr | main action — update PTR record for IP |
| token | * | string | session token | |
| id | * | int | server ID | |
| ip | * | int | IP address | |
| ptr | * | string | PTR data |
POST-request, cURL
curl -s "https://invapi.hostkey.com/ip.php" -X POST \
--data "action=update_ptr" \
--data "token=$HOSTKEY_TOKEN" \
--data "id={Server ID}" \
--data "ip={IP address}" \
--data "ptr={PTR data}" \
ip/set_main¶
Allows you to designate a specific IP address as "main" when multiple IP addresses are assigned to the server.
Attention
A config is created for the main IP address only.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | set_main | main action — set IP option for a server |
| token | * | string | session token | |
| id | * | int | server ID | |
| ip | * | int | IP address | |
| main | * | int | IP address to be set as main |
POST-request, cURL
curl -s "https://invapi.hostkey.com/ip.php" -X POST \
--data "action=set_main" \
--data "token=$HOSTKEY_TOKEN" \
--data "id={Server ID}" \
--data "ip={IP address}" \
--data "main={main IP address}"
net/block_ip¶
With this call you could block the specific IP on a server, this is useful to manage abuse requests. This is done on HOSTKEY's network layer.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | block_ip | main action — block specific IP |
| token | * | string | session token | |
| id | * | int | server ID | |
| ip | * | int | IP address | |
| pin | * | int | PIN code | |
| description | * | string | the reason for the block | |
| four_hours | int | If set 1, the block will be automatically lifted after 4 hours. |
POST-request, cURL
Positive response
This action has an asynchronous response
net/unblock_ip¶
HTTP method - POST
Allows you to unblock a previously blocked IP address on a server.
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | unblock_ip | main action — unblock a previously blocked IP address |
| token | * | string | session token | |
| id | * | int | server ID | |
| ip | * | int | IP address | |
| pin | * | int | PIN code |
POST-request, cURL
Positive response
This action has an asynchronous response
DNS zone management¶
The PDNS APIs are divided into 2 groups based on the required permissions. These are pdns/view and pdns/edit privileges.
- The
list_domains,list_subdomains,list_zonesandview_zonecalls require pdns/view permissions. - The
add_domain,delete_domain,add_subdomain,edit_subdomain,delete_subdomain,add_zone,delete_zone,add_dnsanddelete_dnscalls require pdns/edit permissions.
| Resource | Action | Description |
|---|---|---|
| pdns.php | list_domains | get all domains of the user from the domains table |
| pdns.php | add_domain | add a new domain for the user to the domains table |
| pdns.php | delete_domain | delete a domain from the domains table |
| pdns.php | list_subdomains | get all subdomains from the subdomains table |
| pdns.php | add_subdomain | add a new subdomain to the subdomains table for the user |
| pdns.php | edit_subdomain | update the specified subdomain |
| pdns.php | delete_subdomain | delete a subdomain from the subdomain table |
| pdns.php | list_zones | get a list of all zones on the PowerDNS server |
| pdns.php | view_zone | retrieve zone data from an authoritative PowerDNS server |
| pdns.php | add_zone | add a zone |
| pdns.php | delete_zone | delete zone, all associated metadata and resource records from PowerDNS authoritative server |
| pdns.php | add_dns | add a new DNS record to the specified DNS zone |
| pdns.php | delete_dns | delete a DNS record from a PowerDNS authoritative server |
pdns/list_domains¶
Lets you get a list of the user's domains.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | get_client | main action - get all domains of the user from the domains table |
| token | * | string | session token |
POST-request, cURL
Positive response
pdns/add_domain¶
Lets you create a new DNS zone and add the new domain to the domains table.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | add_domain | main action - add a new domain for the user to the domains table |
| token | * | string | session token | |
| name | * | string | domain name |
POST-request, cURL
Positive response
pdns/delete_domain¶
Allows you to delete the corresponding DNS zone, the domain itself from the domains table, and all subdomains of this domain from the subdomains table by domain ID.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | get_client | main action - delete a domain from the domains table |
| token | * | string | session token | |
| server_id | * | int | server ID | |
| domain_id | * | int | Domain ID (you can view the call pdns/list_domains |
POST-request, cURL
Positive response
pdns/list_subdomains¶
Lets you get a list of subdomains of a domain by their ID.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | list_subdomains | main action - get all subdomains from the subdomains table |
| token | * | string | session token | |
| server_id | * | int | server ID |
POST-request, cURL
Positive response
pdns/add_subdomain¶
Lets you add a new subdomain to the subdomains table.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | add_subdomain | main action - add a new subdomain to the subdomains table for the user |
| token | * | string | session token | |
| server_id | * | int | server ID | |
| domain_id | * | int | domain ID | |
| name | * | string | subdomain name |
POST-request, cURL
Positive response
pdns/edit_subdomain¶
Lets you update the specified subdomain.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | edit_subdomain | main action - update the specified subdomain |
| token | * | string | session token | |
| id | * | int | subdomain ID |
POST-request, cURL
Positive response
pdns/delete_subdomain¶
Lets you remove a subdomain from the subdomains table.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | delete_subdomain | main action - delete a subdomain from the subdomain table |
| token | * | string | session token | |
| server_id | * | int | server ID | |
| id | * | int | subdomain ID |
POST-request, cURL
Positive response
pdns/list_zones¶
Lets you get a list of all the zones on the PowerDNS server.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | list_zones | main action - get a list of all zones on the PowerDNS server |
| token | * | string | session token |
POST-request, cURL
Positive response
{
"result": "OK",
"module": "pdns",
"action": "list_zones",
"data": [
{
"account": "",
"dnssec": false,
"edited_serial": 2018041900,
"id": "hostbuy.com.",
"kind": "Master",
"last_check": 1612322161,
"masters": [
"141.105.71.185"
],
"name": "hostbuy.com.",
"notified_serial": 2018041900,
"serial": 2018041900,
"url": "/api/v1/servers/localhost/zones/hostbuy.com."
},
…
],
}
pdns/view_zone¶
Allows you to retrieve data for a zone from an authoritative PowerDNS server.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | view_zone | main action - retrieve zone data from an authoritative PowerDNS server |
| token | * | string | session token | |
| zone | * | string | zone name |
POST-request, cURL
Positive response
{
"result": "OK",
"module": "pdns",
"action": "view_zone",
"data": [
{
"account": "",
"api_rectify": false,
"dnssec": false,
"edited_serial": 2023101604,
"id": "aaa.com.",
"kind": "Master",
"last_check": 0,
"master_tsig_key_ids": [],
"masters": [],
"name": "aaa.com.",
"notified_serial": 2023101604,
"nsec3narrow": false,
"nsec3param": "",
"rrsets": [
{
"comments": [],
"name": "tesrt._domainkey.aaa.com.",
"records": [
{
"content": "\"v=DKIM1; p=dsdsdsd\"",
"disabled": false
}
],
"ttl": 3600,
"type": "TXT"
},
…
],
"serial": 2023101604,
"slave_tsig_key_ids": [],
"soa_edit": "",
"soa_edit_api": "DEFAULT",
"url": "/api/v1/servers/localhost/zones/aaa.com."
},
…
],
}
pdns/add_zone¶
Allows you to add a new DSN zone
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | add_zone | main action - add a zone |
| name | * | string | example.com | domain name |
| rrsets | * | bool | true | use RRset instead of records |
| dnssec | * | bool | false | use DNSSEC |
| kind | * | string | Master | domain type: Master/Slave |
| masters | * | array | [] | master server list |
| dns | * | object | DNS parameters | |
| - ttl | * | int | 3600 | TTL by default |
| - mname | * | string | ns1.example.com | primary NS domain name |
| - rname | * | string | admin.example.com | administrator e-mail |
| - serial | * | int | 2023122800 | zone serial number. We recommend that you use the format YYYYMMDD00 |
| - refresh | * | int | 14400 | zone update time |
| - retry | * | int | 3600 | query repeat interval |
| - expire | * | int | 604800 | zone expiration time |
| - minimum | * | int | 3600 | min. TTL value |
| nameservers | * | array | [ns1.hostkey.com, ns2.hostkey.com] | NS servers list |
POST-request, cURL
curl -s "https://invapi.hostkey.com/pdns.php" -X POST \
--data "action=add_zone" \
--data "token=$HOSTKEY_TOKEN" \
--data "server_id={Server ID}" \
--data "zonename=example.com" \
--data "rrsets=true" \
--data "dnssec=false" \
--data "kind=master" \
--data "masters[]=[]" \
--data "dns[ttl]=3600" \
--data "dns[mname]=ns1.hostkey.com" \
--data "dns[rname]=admin.example.com" \
--data "dns[serial]=2023101800" \
--data "dns[refresh]=14400" \
--data "dns[retry]=3600" \
--data "dns[expire]=604800" \
--data "dns[minimum]=3600" \
--data "nameservers[]=ns1.hostkey.com" \
--data "nameservers[]=ns1.hostkey.com"
Positive response
{
"result": "OK",
"module": "pdns",
"action": "view_zone",
"data": [
{
"account": "",
"api_rectify": false,
"dnssec": false,
"edited_serial": 2023101604,
"id": "aaa.com.",
"kind": "Master",
"last_check": 0,
"master_tsig_key_ids": [],
"masters": [],
"name": "aaa.com.",
"notified_serial": 2023101604,
"nsec3narrow": false,
"nsec3param": "",
"rrsets": [
{
"comments": [],
"name": "tesrt._domainkey.aaa.com.",
"records": [
{
"content": "\"v=DKIM1; p=dsdsdsd\"",
"disabled": false
}
],
"ttl": 3600,
"type": "TXT"
},
…
],
"serial": 2023101604,
"slave_tsig_key_ids": [],
"soa_edit": "",
"soa_edit_api": "DEFAULT",
"url": "/api/v1/servers/localhost/zones/aaa.com."
},
…
],
}
pdns/delete_zone¶
Allows you to delete a DNS zone by name.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | delete_zone | main action - delete zone, all associated metadata and resource records from PowerDNS authoritative server |
| token | * | string | session token | |
| zone | * | string | zone name |
POST-request, cURL
pdns/add_dns¶
Allows you to add a new DNS record to the specified DNS zone.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | delete_zone | main action - add a new DNS record to the specified DNS zone |
| token | * | string | session token | |
| zone | * | string | example.com | name of the DNS zone to add |
| name | string | www | name of the DNS record to add | |
| old_name | string | old DNS record name on change, used to modify an existing record | ||
| type | * | string | A | Type of DNS record to add |
| content | * | string | 10.56.121.5 10.56.121.6 | value/data for the DNS record |
| ttl | int | 3600 | cache time in seconds | |
| increase_soa_serial | bool | 1 | automatic serial increment flag in SOA zone records | |
| mname | * | string | ns1.example.com | primary DNS server name in SOA record |
| rname | * | string | admin.example.com | administrator e-mail in SOA record |
| serial | int | 2023101800 | serial number in the SOA record | |
| refresh | int | 14400 | update time in seconds in SOA record | |
| retry | int | 3600 | repeat interval in seconds in SOA Record | |
| expire | int | 604800 | expiration time in seconds in the SOA record | |
| minimum | int | 3600 | minimum cache time in seconds in SOA record | |
| proto | string | tcp | protocol for SRV record | |
| priority | int | 10 | priority for SRV record | |
| weight | int | 5 | size for balancing in SRV record | |
| port | int | 450 | target service port in SRV record | |
| target | string | example.com. | the domain of the target service in the SRV record | |
| masters | array | [] | list of external zone master servers | |
| dns[ttl] | int | 3600 | ttl check in SOA record | |
| dns[mname] | string | ns1.example.com | primary NS check in SOA record | |
| dns[rname] | string | admin.example.com | email check in SOA record | |
| dns[serial] | int | 2023101800 | serial check in SOA record | |
| dns[refresh] | int | 14400 | refresh check in SOA record | |
| dns[retry] | int | 3600 | retry check in SOA record | |
| dns[expire] | int | 604800 | expire check in SOA record | |
| dns[minimum] | int | 3600 | minimum check in SOA record | |
| nameservers[] | array | ns1.example.com | List of NS servers in the zone |
POST-request, cURL
curl -s "https://invapi.hostkey.com/pdns.php" -X POST \
--data "action=add_zone" \
--data "token=$HOSTKEY_TOKEN" \
--data "zone=example.com"
--data "name=www"
--data "old_name="
--data "type=A"
--data "content=10.56.121.5 10.56.121.6"
--data "ttl=3600"
--data "increase_soa_serial=1"
--data "mname=ns1.example.com"
--data "rname=admin.example.com"
--data "serial=2023101800"
--data "refresh=14400"
--data "retry=3600"
--data "expire=604800"
--data "minimum=3600"
--data "proto=tcp"
--data "priority=10"
--data "weight=5"
--data "port=450"
--data "target=example.com."
--data "masters=[]"
--data "dns[ttl]=3600"
--data "dns[mname]=ns1.example.com"
--data "dns[rname]=admin.example.com"
--data "dns[serial]=2023101800"
--data "dns[refresh]=14400"
--data "dns[retry]=3600"
--data "dns[expire]=604800"
--data "dns[minimum]=3600"
--data "nameservers[]=ns1.example.com"
--data "nameservers[]=ns1.example.com"
pdns/delete_dns¶
Allows you to remove a specific DNS record from the DNS zone.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | delete_dns | main action - delete a DNS record from a PowerDNS authoritative server |
| token | * | string | session token | |
| zone | * | string | zone name | |
| name | * | string | record name | |
| type | * | string | record type |
POST-request, cURL
Remote hands¶
Some servers do not have a remote control. Our duty shift could perform necessary power actions and connect external IP KVM to the server. This could be done via API, which will create tickets in our Service desk software (Remote Hand Request - RHR).
| Resource | Action | Description |
|---|---|---|
| jira.php | request_pon | open RHR to power on the server |
| jira.php | request_poff | open RHR to power down the server |
| jira.php | request_reboot | open RHR to reboot the server |
| jira.php | request_PXEboot | open RHR to boot the server from PXE |
| jira.php | request_kvm | open RHR to connect IP KVM to the server |
| jira.php | request_check | open RHR to check and load the server into OS |
Each action will create JIRA (TICKET_ID) accessible via https://my.hostkey.com/servicedesk/customer/portal/1/TICKET_ID with subject and message on behalf of the user.
The user will receive an email message with confirmation. After the requested action was performed, the duty shift will communicate with the customer via this ticket.
jira/request_pon¶
Creates a request to manually start the server.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | request_pon | main action - open RHR to power on the server |
| token | * | string | session token | |
| id | * | int | server ID |
POST-request, cURL
Positive response
{
"result": "OK",
"action": {
"permission": "eq/on",
"subject": "CP request: Manual power ON the server SERVER_ID please",
"message": "Dear HOSTKEY support, please power on the server SERVER_ID since it doesn't have remote control. \n This is automated message from INVAPI, no extra verification required.",
"msg": {
"action": "request_pon",
"id": Server ID,
"callback_url": "https://invapi.hostkey.com/eq_callback.php",
"callback_key": ""
}
},
"jira_url": "https://my.hostkey.com/servicedesk/customer/portal/1/TICKET_ID",
"jira_issue": "TICKET_ID"
}
jira/request_poff¶
Creates a request to manually shut down the server.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | request_poff | main action - open RHR to power down the server |
| token | * | string | session token | |
| id | * | int | server ID |
POST-request, cURL
Positive response
{
"result": "OK",
"action": {
"permission": "eq/off",
"subject": "CP request: Manual power OFF the server SERVER_ID please",
"message": "Dear HOSTKEY support, please power off the server SERVER_ID since it doesn't have remote control. \n This is automated message from INVAPI, no extra verification required.",
"msg": {
"action": "request_poff",
"id": Server ID,
"callback_url": "https://invapi.hostkey.com/eq_callback.php",
"callback_key": ""
}
},
"jira_url": "https://my.hostkey.com/servicedesk/customer/portal/1/TICKET_ID",
"jira_issue": "TICKET_ID"
}
jira/request_reboot¶
Creates a request to manually restart the server.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | request_reboot | main action - open RHR to reboot the server |
| token | * | string | session token | |
| id | * | int | server ID |
POST-request, cURL
Positive response
{
"result": "OK",
"action": {
"permission": "eq/reboot",
"subject": "CP request: Manual REBOOT the server SERVER_ID please",
"message": "Dear HOSTKEY support, please reboot the server SERVER_ID since it doesn't have remote control. \n This is automated message from INVAPI, no extra verification required.",
"msg": {
"action": "request_reboot",
"id": Server ID,
"callback_url": "https://invapi.hostkey.com/eq_callback.php",
"callback_key": ""
}
},
"jira_url": "https://my.hostkey.com/servicedesk/customer/portal/1/TICKET_ID",
"jira_issue": "TICKET_ID"
}
jira/request_PXEboot¶
Creates a request to boot the server from PXE.
Note
This request is required during the reinstall process when the server without remote control unit should be booted from PXE to start the reinstall process.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | request_PXEboot | main action - open RHR to boot the server from PXE |
| token | * | string | session token | |
| id | * | int | server ID |
POST-request, cURL
Positive response
{
"result": "OK",
"action": {
"permission": "eq/PXEboot",
"subject": "CP request: Manual boot from PXE the server SERVER_ID please",
"message": "Dear HOSTKEY support, please set PXE boot the server SERVER_ID since it doesn't have remote control. \n This is automated message from INVAPI, no extra verification required.",
"msg": {
"action": "request_PXEboot",
"id": Server ID,
"callback_url": "https://invapi.hostkey.com/eq_callback.php",
"callback_key": ""
}
},
"jira_url": "https://my.hostkey.com/servicedesk/customer/portal/1/TICKET_ID",
"jira_issue": "TICKET_ID"
}
jira/request_kvm¶
Creates a request to manually connect the IP KVM to the server. The duty shift will connect the IP KVM device to the server
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | request_kvm | main action - open RHR to connect IP KVM to the server |
| token | * | string | session token | |
| id | * | int | server ID |
POST-request, cURL
Positive response
{
"result": "OK",
"action": {
"permission": "eq/kvm",
"subject": "CP request: KVM to the server SERVER_ID please",
"message": "Dear HOSTKEY support, please connect KVM module to the server SERVER_ID since it doesn't have remote control. \n This is automated message from INVAPI, no extra verification required.”,
"msg": {
"action": "request_kvm",
"id": Server ID,
"callback_url": "https://invapi.hostkey.com/eq_callback.php",
"callback_key": ""
}
},
"jira_url": "https://my.hostkey.com/servicedesk/customer/portal/1/TICKET_ID",
"jira_issue": "TICKET_ID"
}
jira/request_check¶
Creates a request to manually check server health and operating system load. The duty shift will check the server and try to bring it back online.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | request_check | main action - open RHR to check and load the server into OS |
| token | * | string | session token | |
| id | * | int | server ID |
POST-request, cURL
Positive response
{
"result": "OK",
"action": {
"permission": "eq/check",
"subject": "CP request: Manual check the server SERVER_ID please",
"message": "Dear HOSTKEY support, please check the server SERVER_ID and boot in into OS since it doesn't have remote control. \n This is automated message from INVAPI, no extra verification required.",
"msg": {
"action": "request_check",
"id": Server ID,
"callback_url": "https://invapi.hostkey.com/eq_callback.php",
"callback_key": ""
}
},
"jira_url": "https://my.hostkey.com/servicedesk/customer/portal/1/TICKET_ID",
"jira_issue": "TICKET_ID"
}
Server tags¶
We keep auxiliary and temporary information about servers and their components in tags. Tags may be assigned to any server's element. Some tags are visible to the end-user, some are not.
| Resource | Action | Description |
|---|---|---|
| tags.php | list | gets all tags for the server |
| tags.php | add | add a tag to the server or change existing tag |
| tags.php | remove | removes a tag for a server |
| tags.php | user_search | find the servers with tags |
Note
The tag could be mounted to the server itself, or its CPU, or NIC or IP address - any DB component. The customer could assign their own tags to servers via API (and web interface). It's possible to search for tags, change or remove them.
It may be useful to keep some automation data, user settings, or application states in tags.
tags/list¶
Allows you to get a list of all tags for a specific server.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | list | Main action - retrive all tags from the server with Server ID |
| token | * | string | session token | |
| id | * | int | server ID |
POST-request, cURL
Positive response
{
"result": "OK",
"action": "list",
"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
}
]
}
tags/add¶
Allows you to add a new tag or modify an existing one for a server.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | add | main action - add a tag to the server or change existing tag |
| token | * | string | session token | |
| id | * | int | server ID | |
| tag | * | string | tag name | |
| value | * | string | tag value | |
| extra | string | extra value if necessary to keep several values for the tag |
Example of adding a tag to the server, POST-request, cURL
Positive response
Example of modifying an existing tag, POST-request, cURL
Positive response
tags/remove¶
Lets you delete an existing tag for a server.
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | remove | main action - removes a tag from a server |
| token | * | string | session token | |
| id | * | int | server ID | |
| tag | * | string | tag name |
POST-request, cURL
Positive response
tags/user_search¶
HTTP method - POST
| Parameter | Required | Type | Value/default | Description |
|---|---|---|---|---|
| action | * | string | user_search | main action - Search for Server ID by tag name or tag value |
| token | * | string | session token | |
| value | * | string | search pattern |
POST-request, cURL
Asynchronous actions¶
Some operation with the servers could take a long. Many API calls will return async key when called.
Step 1 Example request to power on the server cURL¶
POST-request, cURL
curl -s "https://invapi.hostkey.com/eq.php" -X POST \
--data "action=on" \
--data "token=$HOSTKEY_TOKEN" \
--data "id={Server ID} \
--data "pin={PIN code}"
Positive response
It means what async request was successfully sent, async key to keep track of it is f685eaa0f06e47faa2e6bb5002828b00.
Step 2 You could track state of the request:¶
POST-request, cURL
curl -s "https://invapi.hostkey.com/eq_callback.php" -X POST \
--data "action=check" \
--data "key=f685eaa0f06e47faa2e6bb5002828b00" //asynchronous key from the request to which the response is given
Uncompleted task response (Result: Not ready)
Completed task response (Result: OK)
{
"result": "OK",
"scope": "Post is on",
"context": {
"action": "on",
"id": "Serve ID",
"location": "NL"
},
"debug": "Chassis Power Control: Up/On",
"key": "f685eaa0f06e47faa2e6bb5002828b00"
}
Key description:
- scope - message to the user;
- context - JSON with initial request and some extra data. Usefull to proceed during AJAX calls;
- debug - hardware output from device;
- key - our async key. Its become deleted after successful response -
OK.