InvAPI Control Panel API Documentation¶

This documentation describes the overall design and principles of the API, along with specific endpoints and usage examples.

Overview

The invapi.hostkey.com control panel is built on top of this API.

Making API Requests¶

All API requests must be made over HTTPS to ensure encryption of data in transit.

Use the POST method for all requests unless otherwise specified.

API Example Format¶

Examples in this documentation use curl, a command-line HTTP client. curl is pre-installed on most Linux and macOS systems and is available for download on all major platforms, including Windows.

Each example is split across multiple lines using the \ line continuation character, which is compatible with bash. A typical request looks like this:

Example POST Request:

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

The -X flag specifies the HTTP method. For consistency, the method is included in all examples, even when not explicitly required for GET requests.

Examples that require a JSON payload in the request body pass the data via the --data parameter.

All API responses are returned in JSON format and formatted in this documentation for readability.

Tip: Environment Variables

To avoid repeating your API token in every example, you can export it once as an environment variable in your terminal. On Linux or macOS:

export HOSTKEY_TOKEN="your_api_token_here"

The token will then be automatically substituted in your requests.

Disclaimer

All values shown in this documentation are for illustrative purposes only. Do not rely on operating system IDs, plan identifiers, or other example values. Always use your actual server, network, or domain identifiers when querying or creating resources. In some cases, only the account API key will work, not the specific server key (and vice versa), so if you encounter method authorization errors, try switching the API key type.

api_keys.php¶

API key management module: creation, editing, deletion, viewing history, and retrieving lists of keys for customers and servers.

Method	Description
`add`	Creates a new API key for a customer or a specific server. The customer must have active servers.
`delete`	Deletes the specified API key from the system.
`edit`	Modifies parameters of an existing API key (name, IP, status, expiration).
`history`	Returns the history of actions performed on API keys (creation, modification, deletion).
`list`	Returns a list of all API keys for the current customer.
`list_for_server`	Returns a list of API keys bound to a specific server.
`view`	Returns detailed information about a single API key.

auth.php¶

Authentication and authorization module: session management, login via WHMCS, LDAP, API keys, and SSO (Google, GitHub, VK), 2FA verification, SMS and email, as well as customer tag management.

Method	Description
`2fa_check`	Verifies the correctness of the two-factor authentication code for the current user session.
`2fa_resend`	Requests a resend of the two-factor authentication code for the user. If the user is in debug mode, the code is returned in the response.
`billing_list`	Returns a list of available payment systems (billings) available to the current user or administrator.
`email_check`	Verifies email validity, sends a verification code, or checks an existing code/token to confirm the address.
`flip_tag`	Creates or removes the specified tag for the user. If the tag already exists, it will be removed; if it does not exist, it will be created.
`get_log`	Returns an authorization event log for a specified period or by token.
`get_log_details`	Returns detailed information about authentication events for the current user (via user_token).
`github_init`	Returns the data required to initialize authorization via GitHub (client_id and redirect_uri).
`github_signin`	Initiates the authorization process via GitHub. Generates a temporary state and token for subsequent code-to-session exchange.
`google_signin`	Performs login using a Google ID Token. If the token is already linked to a user, the method links the current session with that account.
`info`	Returns detailed information about the current user session, including role, permissions, customer data, and a list of active servers.
`login`	Authorization via client API key. Returns an access token, user role, and a list of available servers.
`logout`	Clears the current access token.
`session_reset`	Terminates all active user sessions corresponding to the provided reset token and clears associated tags.
`set_tag`	Creates or removes a tag for the customer. Allows setting values for specific parameters (e.g., auto_credit) or simply toggling the presence of a tag.
`tg_verify`	Links a user's Telegram username to their account and returns a link to the bot for notifications.
`vk_init`	Initiates the authorization process via the VKontakte social network, generating temporary OAuth2 parameters (code_challenge, state, etc.).
`vk_signin`	Performs user authorization via the VK OAuth2 protocol. Exchanges the code for a token and links the account to the user.
`whmcslogin`	Performs login using WHMCS credentials (email/password) or SSO (Google). Returns a session token, customer information, permissions, and 2FA status.

eq.php¶

Equipment Management Module (eq.php): API for server deployment, power management, IPMI, backups, searching, and retrieving detailed hardware configuration information.

Method	Description
`abort_reinstall`	Interrupts the server reinstallation process, removes associated tags (reinstall_start, autodeploy_start, autodeploy_timeout), and restores VLAN settings.
`add_ipmi_admin`	Creates a new IPMI administrative user for the specified equipment. If the user already exists, returns their credentials.
`add_ipmi_user`	Creates a new IPMI user for the server. If the user is an administrator, appropriate permissions are required.
`announceip`	Performs the announcement procedure of the specified subnet range for the server.
`backup_get_schedule`	Returns a list of scheduled backup tasks for the specified server.
`backup_list`	Returns a list of available backups for the specified equipment (server).
`backup_save_schedule`	Saves the configured automatic backup schedule for the specified server.
`boot_dev`	Requests a server reboot to boot from the specified media (PXE or disk) depending on the selected mode.
`check_backup_lock`	Checks for an active lock for performing operations with server backups.
`check_pin`	Checks the PIN code for operations.
`clear_pxe`	Clears the PXE configuration for the specified host. If the full parameter is 1, all content is deleted.
`console`	Requests the launch of the server management console via IPMI/NoVNC.
`create_backup`	Initiates the backup creation process for the specified equipment. The operation is performed asynchronously.
`create_pxe`	Creates a PXE boot configuration for subsequent OS reinstallation on the server. Supports OS selection, hostname configuration, SSH keys, and post-install scripts.
`delete_backup`	Deletes the specified server backup. Requires execution of an asynchronous task.
`deploy`	Starts the deployment process for the selected server or preset. Supports OS selection, hostname configuration, SSH keys, and disk parameters.
`get_ipmi`	Returns a list of available IPMI interfaces of the server, including IP address and vendor model.
`get_traffic`	Returns IPv4 traffic data for the specified server.
`get_upgrade_key`	Returns the upgrade key linked to a specific invoice (invoice_id), if a corresponding upgrade_key tag is found for it.
`getserversforannounce`	Returns a list of available servers (type Server) in rent or power_off status that have passed subnet mask restriction checks and are available for IP address announcement.
`groups`	Returns the list of groups for the specified server.
`hard_off`	Sends a request for immediate (hard) power-off of the equipment via IPMI/controller.
`history`	Returns the server event history.
`list`	Returns a list of available servers and equipment with support for advanced search by various parameters (location, status, type, IP, MAC, etc.).
`off`	Turns off the server.
`on`	Turns on the server.
`order_instance`	Starts the deployment process of a new server from a preset or reinstallation of an existing server with selection of OS, software, and network parameters.
`ovirt_novnc`	Requests the launch of a NoVNC console for a server in an oVirt environment. Requires authorization and equipment management permissions.
`reboot`	Sends a request to reboot the equipment by the specified ID. If the server is in standby mode, execution via IPMI may be required.
`reinstall`	Starts the server reinstallation preparation process, creating a task key and notifying the client.
`remove_ipmi_user`	Deletes additional IPMI user accounts for the specified server.
`request_backup_link`	Requests a temporary link to download a server backup. The method is asynchronous and returns a callback key.
`restore_backup`	Starts the server restoration process from an existing backup by backup name.
`search`	Returns a list of available servers and equipment matching the specified filters (group, location, status, type, IP, MAC, etc.).
`sensors`	Returns current sensor readings for the specified server (e.g., temperature or disk status).
`set_pin`	Sets a PIN code for operations.
`show`	Returns detailed information about the server, including hardware (hwconfig), operating system, IP addresses, interfaces, and IPMI.
`status`	Returns the current equipment status and related data (IP, interfaces, IPMI, tags).
`status_check`	Returns the current equipment status (available for checking without authorization).
`suspend`	Requests suspension or unsuspension of a VPS/server. If the action is unsuspend, the server will be unblocked.
`traffic_add`	Increases the outbound traffic limit for the server and generates an invoice in WHMCS.
`unified_server_search`	Unified search for servers by query.
`unit_reset`	Requests a reset operation for the IPMI interface of the specified server.
`unsuspend`	Request to unblock (unsuspend) a server. If the server was blocked by an administrator, the action is performed immediately.

eq_callback.php¶

Module for processing asynchronous responses from workers to manage equipment (EQ) and virtual machines. It handles task statuses (deploy, reinstall, backup, network), updates billing, and sends notif

Method	Description
`check`	Returns the current execution status of an asynchronous task (done, stage, failure) and the execution context.
`reinstall`	Processes the completion of a server reinstall process, updates statuses in billing, and notifies the customer.

ip.php¶

IP address and network infrastructure management module: get IP information, manage PTR records, track traffic, work with subnets and VLANs.

Method	Description
`get_client_ip`	Returns the current IP address of the client making the request to the API
`get_ip`	Returns full network configuration information for a specific IP address (mask, network, etc.)
`get_ptr`	Checks if the IP address belongs to the server and returns the current PTR record for this IP in the specified location.
`get_traffic`	Returns inbound and outbound traffic data for a specified IP address for a selected period. Can return both summary information and detailed timestamps.
`list_free_ip`	Returns a list of unused IP addresses for a specific location based on Route Reflector tags. For clients, it is only available within their own subnets.
`set_main`	Sets the specified IP address as the primary (main) for the server's network interface.
`update_ptr`	Updates the reverse DNS record (PTR) for a specified IP address, provided that this IP is assigned to a server with the given ID.

iso.php¶

ISO Image Management Module: uploading, deleting, mounting, and unmounting images on servers, as well as retrieving lists of available and uploaded images.

Method	Description
`add`	Adds a new ISO image or updates an existing one by name.
`delete`	Deletes an ISO image by ID.
`list_iso`	Returns a list of available ISO images.
`mount_iso`	Mounts an ISO image on the specified server.
`unmount_iso`	Unmounts an ISO image from the specified server.
`upload`	Uploads an ISO image via URL.
`uploaded`	Returns a list of uploaded ISO images for a client or staff member.

jenkins.php¶

Jenkins integration module for task management: retrieving the list of available tasks and executing them for servers.

Method	Description
`get_tasks`	Returns the list of available Jenkins tasks accessible to the current user or client.

jira.php¶

Jira integration module for creating support tickets for server management (power, reboot, KVM) and sales assistance requests.

Method	Description
`request_PXEboot`	Creates a Jira ticket for manual PXE booting of the server if remote control is unavailable.
`request_assistance`	Sends a request for technical or commercial assistance by creating a Jira ticket for a specific server. Includes a check for duplicate open requests.
`request_check`	Creates a Jira ticket to check and boot the server into an OS if remote control is unavailable.
`request_kvm`	Creates a Jira ticket to connect IP KVM to the server.
`request_poff`	Creates a Jira ticket for manual power off of the server.
`request_pon`	Creates a Jira ticket for manual power on of the server.
`request_reboot`	Creates a Jira ticket for manual reboot of the server.

nat.php¶

Static NAT management module: adding and removing IP address forwarding rules via MikroTik.

Method	Description
`add_static_nat`	Creates a static NAT passthrough via Microtic for the specified server with ACL and TTL support.
`remove_static_nat`	Removes the static NAT passthrough for the specified server or white IP.

net.php¶

Network infrastructure management module: adding and removing IP addresses, blocking traffic, managing network port status, retrieving statistics, and displaying Cacti graphs.

Method	Description
`add_ipv4`	Adds the specified number of IPv4 addresses to a server or assigns specific IP addresses. Supports automatic search for free IPs in a VLAN or manual specification of a list.
`block_ip`	Blocks the specified IP address on the server via BIRD or blackhole. Requires authentication.
`get_status`	Returns the current status and configuration of the server's network port. Requires authentication.
`port_off`	Disables the specified server network port and adds a block tag with the specified reason.
`port_on`	Enables the specified server network port, removing the block (tag 'block') if it was not set by an administrator.
`remove_ipv4`	Removes the specified IPv4 address from the server. If the remove_all flag is passed, all addresses are removed.
`show_cacti`	Returns traffic monitoring graph data for the specified server and port from the Cacti system.
`show_ipv4_free`	Returns a list of available IPv4 addresses for the specified server and interface in a given VLAN. Requires authentication.
`unblock_ip`	Removes the block from the specified IP address on the server. Requires access rights verification.

os.php¶

Operating system management module: provides methods for adding, removing, updating, and retrieving a list of OS with filtering by hardware compatibility and licenses.

Method	Description
`list`	Returns a list of operating systems. If id or instance_id is specified, filters OS by compatibility with hardware or preset. Also returns a list of excluded OS.

pdns.php¶

DNS record and zone management module: adding, deleting, and viewing domains, subdomains, and zones, as well as retrieving callback-URL information.

Method	Description
`add_dns`	Adds a new DNS record to the specified zone.
`add_domain`	Adds a new domain to the DNS system for the specified client.
`delete_dns`	Deletes the specified DNS record.
`delete_domain`	Deletes the domain and all associated records.
`get_cb_url`	Returns the URL for callback notifications.
`list_domains`	Returns the list of client domains.
`list_zones`	Returns the list of DNS zones.
`view_zone`	Returns details of the specified DNS zone.

presets.php¶

Server preset management module: retrieving lists, grouping, searching for suitable servers, and detailing configurations with prices in different currencies.

Method	Description
`groups`	Returns a list of available preset groups
`info`	Returns a list of available presets considering the selected currencies (default EUR, RUB)
`list`	Returns a list of available server presets with filtering by location and access rights
`search`	Returns a list of servers matching the parameters of the specified preset. If the user is not authorized, the search is limited to free offers only.
`show`	Returns information about a preset by ID or name. Supports filtering and limits.

rhr.php¶

Remote Hands Requests Management Module: creation, filtering, status updates, and communication regarding requests.

Method	Description
`add`	Creates a new Remote Hands Request (RHR) specifying the type and equipment.
`chat`	Adds a client-visible message to the request history.
`discard`	Recursively changes the request status to canceled or closed.
`list`	Returns a list of available RHR tasks with filtering by location, status, and date.

s3.php¶

S3 storage management module: creating and deleting accounts, managing buckets and files, obtaining usage statistics, managing pricing plans and billing.

Method	Description
`cancel_payment_account_deletion`	Cancels the S3 account deletion process initiated due to payment issues. Resets the suspension reason and updates commit dates.
`create_account`	Creates a new S3 account (bucket) for the client, links it to a pricing plan, and creates a corresponding order in billing.
`create_bucket`	Creates a new bucket for an existing user's S3 account.
`create_order`	Creates a new S3 account (bucket) for the client, links it to a pricing plan, and creates a corresponding order in the billing system.
`delete_account`	Deletes a user's S3 account, performs action audit, and logs the operation in history.
`delete_bucket`	Deletes the specified bucket from S3 storage if it belongs to the user.
`delete_file`	Deletes the specified file from an S3 bucket. Requires authorization and access rights to the account.
`delete_payment_account`	Requests S3 service cancellation, initiating the deletion/unsubscription process. Upon successful execution, returns information about the cancellation date.
`get_buckets`	Returns a list of the user's S3 buckets, traffic usage information, and snapshots.
`get_buckets_rmq`	Returns a list of the user's buckets, their usage information, billing data, metrics, and S3 access credentials.
`get_files`	Returns a list of files and folders in the specified S3 bucket with pagination and search support.
`get_users`	Returns a list of S3 users with detailed information about plans, traffic consumption, and service data.
`history`	Returns event logs for the specified S3 account or user.
`list_plans`	Returns a list of available S3 plans considering user permissions, location, and client currency. Administrators can view a specific plan by ID.
`show_key`	Returns the decrypted secret key or access key for the specified S3 account.

software.php¶

Software management module: provides methods to get a list of available software filtered by server characteristics or preset, as well as selecting compatible presets and operating systems for specifi

Method	Description
`list`	Returns a list of software suitable for a specific server (id) or preset (instance_id), taking into account licenses, hardware specifications, and promotions.

stocks.php¶

Server inventory management module: provides lists of available servers with filtering by locations and groups, as well as detailed information about a specific server.

Method	Description
`list`	Returns a list of available servers in inventory with the ability to filter by location and group.
`show`	Returns detailed information about a specific server by its identifier.

tags.php¶

Tag management module for infrastructure components: adding, removing, clearing, searching, and displaying tag lists for servers and variables.

Method	Description
`add`	Adds a custom tag to a server or component. Supports bulk addition via an ID list.
`clear`	Clears all or non-essential tags from a component. For clients, only public tags are available.
`get`	Retrieves tags for a component. (Implementation is empty in code, method is in whitelist)
`list`	Returns a list of tags for a specific server or component. For clients, there is a restriction by component type (eq, vars).
`remove`	Removes a tag by its name for a specific component or removes all specified tags from an ID list. If id_list is passed, the operation is performed in bulk.
`search`	Searches for components matching a specific tag and value.
`search_user`	Searches for user equipment by tag value. Used in global search form.
`show`	Shows possible tags for a component. (Implementation is empty in code, method is in whitelist)

traffic_plans.php¶

Traffic tariff plan management module: creation, deletion, updating, and retrieval of available plans with filtering by server or location and price conversion.

Method	Description
`list`	Returns a list of suitable traffic tariff plans for the specified server (id) or location. Supports filtering by hardware type and price conversion to EUR/USD.

vm.php¶

Virtual Machine (VM) management module providing an API for creating, retrieving, deleting, and restoring snapshots, as well as loading statistics.

Method	Description
`create_snapshot`	Initiates the creation of a snapshot for the specified virtual machine. Returns a task key for status tracking.
`get_snapshot`	Returns a list of snapshots and settings for the specified virtual machine.
`load_stats`	Initiates the loading of resource usage statistics for the virtual machine.
`remove_snapshot`	Initiates the deletion of a snapshot with the specified name.
`restore_snapshot`	Initiates the restoration of the virtual machine state from a snapshot.
`update_restore_settings`	Updates automatic restore and snapshot rotation settings for the specified virtual machine.

whmcs.php¶

WHMCS integration module for managing customers, invoices, credit, order cancellations, and server billing data.

Method	Description
`add_contact`	Adds a new contact user to an existing customer in WHMCS. If the request type is not specified, a random contact is created.
`apply_credit`	Applies the customer's available balance (credit) to pay a specific unpaid invoice. If payment is successful, the invoice status changes to Paid.
`create_addfunds`	Creates an invoice in WHMCS for topping up the customer's balance (Add Funds). If the subscribe option is enabled, automatic billing is activated.
`delete_cancellation_request`	Deletes an existing service cancellation request, restoring the invoice status or allowing the order to be recreated.
`delete_contact`	Deletes an additional contact associated with a customer in WHMCS.
`download_invoice`	Returns a PDF file of the invoice in base64 format for downloading or viewing.
`generate_due_invoice`	Generates the next invoice for a server in WHMCS, considering the current billing cycle and active add-ons. It is blocked if the customer has unpaid invoices or if the server is undergoing an upgrade.
`get_billing_data`	Returns detailed information about the billing data of a specific server, including EU withdrawal status and synchronized data from WHMCS.
`get_cancellation_requests`	Returns a list of active service cancellation requests for a specific server or user with filtering by date, type, and payment status.
`get_client`	Returns detailed information about the authenticated client, including data from WHMCS and internal system data (tags, verification status). Supports extended output mode via the full parameter.
`get_clientgroups`	Returns a list of available customer groups from WHMCS for the specified location.
`get_contacts`	Returns a list of additional contacts for the specified client or checks access rights to user contacts.
`get_invoice`	Returns detailed information about an invoice from WHMCS, including client data and payment status.
`get_invoices`	Returns a list of all invoices associated with the client in WHMCS for the specified location.
`get_related_invoices`	Returns a list of invoices associated with a specific server (order/service)
`getcredits`	Returns the user's current credit balance in WHMCS for the specified location.
`getpaymentgw`	Returns a list of available payment methods (gateways) attached to a specific invoice in WHMCS.
`mass_pay`	Allows bulk payment of several client invoices in a single request. A minimum of 2 invoices is required.
`request_cancellation`	Sends a request to cancel the bank subscription for a server. It checks for active licenses, invoice payment status, and eligibility for automatic refunds (EU withdrawal).
`request_subscription_cancellation`	Initiates the process of canceling the bank subscription for a server. Creates a JIRA ticket and attaches a request tag to the server.
`reset_password`	Initiates the password reset process. If no token is provided, a link is sent via email. If the token is valid, it allows setting a new password (with 2FA support).
`transactions`	Returns a list of financial transactions for the user associated with an invoice or a specific transaction.
`update_client`	Updates the customer profile in WHMCS, including personal data (name, email), contact information, 2FA settings, and custom fields. Supports updating legal data for companies.
`update_contact`	Updates additional contact information (first name, last name, email, phone) in the WHMCS system. Changing the primary email or phone may require re-verification.