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 client tag management.

Method	Description
`2fa_check`	Validates the two-factor authentication code for the current user session.
`2fa_resend`	Resends the two-factor authentication code to the linked channel (email or SMS) for the current session.
`billing_list`	Returns a list of available payment systems (billings) configured for the current user or administrator.
`email_check`	Checks if a client exists by email in the specified billing location. If the client is not found, a new one is created. Also sends a verification code to the email.
`flip_tag`	Allows toggling the state (create or delete) of a specified tag for the client. If the tag already exists, it will be deleted; if it does not exist, it will be created.
`get_log`	Returns the authorization event log for a specified period or by token.
`get_log_details`	Returns detailed information about authentication events by user token.
`github_init`	Initiates the authorization process via GitHub, generates a unique state, and returns the necessary data to redirect the user to the GitHub OAuth page.
`github_signin`	Initiates the OAuth authorization process via GitHub. Generates a temporary state and returns client data for user redirection.
`google_signin`	Performs user authentication using a Google ID Token. If the token is valid, it links the Google account to the current session or connects it to an existing client.
`info`	Returns detailed information about the current user session, including role, permissions, client data, and active servers.
`login`	User authorization using an API key. Returns an access token, role information, and a list of available servers.
`logout`	Clears the current user access token, ending the session.
`session_reset`	Terminates all active user sessions based on their email and reset token. Performs tag purging for all found hashes.
`set_tag`	Creates or deletes a tag for the client. If the set parameter is 1, the tag is created; if 0, it is deleted.
`tg_verify`	Binds the specified Telegram username to the user account and returns a link to the bot. Deletes the old tg_user_id tag.
`vk_init`	Initiates the OAuth authorization process via VK, generates a code_challenge, and returns the necessary data for user redirect.
`vk_signin`	Initiates the authorization process through the VKontakte social network. Generates temporary data (state, code_verifier) and saves it in temporary storage for subsequent verification when the user returns.
`whmcslogin`	Performs system login. Supports standard email/password authorization, as well as login via third-party services (Google, GitHub, VK) and automatic billing selection.

eq.php¶

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

Method	Description
`abort_reinstall`	Cancels the server reinstallation process, removes associated tags (reinstall_start, autodeploy_start, autodeploy_timeout), and resets VLAN settings.
`add_ipmi_admin`	Creates a new user with administrator privileges for IPMI management. If the user already exists, returns their data.
`add_ipmi_user`	Creates a new IPMI user for the server. If the user is an administrator, appropriate permissions are required.
`announceip`	Performs IP address or subnet announcement for the specified server. Supports permission checks and sub-account operations.
`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 hardware (server).
`backup_save_schedule`	Saves the configured automatic backup schedule for the specified server.
`boot_dev`	Request to boot the server from the specified media (PXE or disk) depending on the selected boot mode.
`check_backup_lock`	Checks for an active lock before 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; if 0, only the platform remains.
`console`	Requests the launch of the server management console via IPMI/NoVNC.
`create_backup`	Initiates the backup creation process for the specified server. The operation is performed asynchronously.
`create_pxe`	Prepares configuration for booting the server via network (PXE), specifying OS, disk, and network settings.
`delete_backup`	Deletes the specified server backup. The operation is asynchronous and returns a task tracking key.
`deploy`	Starts the deployment process of a specific server by its ID or via a preset in the specified location. Supports OS selection, hostname configuration, SSH keys, and post-install scripts.
`get_ipmi`	Returns the IP address and IPMI interface model for the specified server. May return multiple interfaces.
`get_traffic`	Returns IPv4 traffic usage data for the specified server.
`get_upgrade_key`	Returns a key to perform an upgrade operation, linked to a specific invoice (invoice_id).
`getserversforannounce`	Returns a list of available servers (type Server) in rent or power_off status that have passed IP announcement limit checks for the current user/sub-account.
`groups`	Returns the list of groups for a specific server.
`hard_off`	Sends a request for a forced server shutdown (Hard Off).
`history`	Returns the server event history.
`list`	Returns a list of available servers and hardware with support for advanced search by various parameters (location, status, type, IP, MAC, etc.).
`off`	Shuts down the server.
`on`	Powers on the server.
`order_instance`	Starts a new server deployment from a preset or reinstallation of an existing server with OS, software, and network parameter selection.
`ovirt_novnc`	Requests the launch of an oVirt noVNC console for the specified server. Returns a callback key to track task execution.
`reboot`	Sends a request to reboot the hardware. If the server is in rental mode, a notification will be sent to the client.
`reinstall`	Starts the server reinstallation preparation process, creates an operation key, and notifies the client.
`remove_ipmi_user`	Deletes an additional IPMI user for the specified server.
`request_backup_link`	Requests a temporary link to download a server backup.
`restore_backup`	Starts the server restoration process from the specified backup. The method is asynchronous and returns a callback to track status.
`search`	Returns a list of available hardware based on various filters (group, location, status, type, IP, MAC, etc.).
`sensors`	Returns current sensor readings (temperature, fan speed, etc.) for the specified server.
`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 server status (power_off, rent, repair, etc.).
`status_check`	Returns the current hardware status via eq_status_check call.
`suspend`	Requests suspension (suspend) or unsuspension (unsuspend) of a VPS server. Requires appropriate permissions and no administrator locks.
`traffic_add`	Increases the outbound traffic limit for the server and creates a corresponding invoice in WHMCS.
`unified_server_search`	Unified search for servers by query.
`unit_reset`	Requests an IPMI module reset for the specified server.
`unsuspend`	Request to remove suspension (unsuspend) from a server.

eq_callback.php¶

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

Method	Description
`check`	Checks the execution status of an asynchronous job by key. Returns current state, context, and debug information.
`reinstall`	Starts the operating system reinstallation process on the server. If the deploy_options=reinstall parameter is specified in the request, a full cleanup of tags and configuration is performed upon completion.

ip.php¶

IP address and network infrastructure management module: retrieving IP information, managing PTR records, traffic monitoring, working 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 over a selected period. Can return both summary information and detailed timestamps.
`list_free_ip`	Returns a list of unused IPv4 addresses for the specified 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 one for the server's network interface.
`update_ptr`	Updates the reverse DNS record (PTR) for a specified IP address within a specific location. Requires server access permission verification.

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, checking for duplicates, and collecting server and billing data.
`request_check`	Creates a Jira ticket to check the server and boot it into the 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 states, retrieving statistics, and displaying Cacti charts.

Method	Description
`add_ipv4`	Adds the specified number of IPv4 addresses to a server in a given port and VLAN. If no IP is specified, the system selects available free addresses from those available in this location.
`block_ip`	Blocks the specified IP address via BIRD or blackhole for a specific server. It can set an expiration period for the block if required.
`get_status`	Returns information about the state of the server's network interface (port), including configuration parameters and current settings.
`port_off`	Disables the server's network port. If a reason (block_reason) is provided, an administrative block tag is created.
`port_on`	Enables the server's network port, removing associated blocking tags (e.g., 'block'). If the user has the customer role and there is an administrative ban on the port, the operation will be rejected.
`remove_ipv4`	Removes one or more IPv4 addresses from the server. If the remove_all parameter is specified, all IPs are removed (depending on backend implementation). Upon successful execution, it returns a list of removed IPs and keys.
`show_cacti`	Returns data for constructing Cacti graphs for a specific server port.
`show_ipv4_free`	Returns a list of available IPv4 addresses for assignment in the specified VLAN and subnet for a specific server.
`unblock_ip`	Removes the block from the specified IP address on the server. If the action is performed by a client, the presence of a corresponding entry in the port description is checked.

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 detailed configurations with prices in different currencies.

Method	Description
`groups`	Returns a list of available preset groups
`info`	Returns a list of available currencies for displaying preset prices. By default, it returns EUR and RUB.
`list`	Returns a list of available server presets with filtering by location and access rights
`search`	Returns a list of servers matching the specified preset parameters (name, location, search area)
`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 via a deletion request. Restores the service status.
`create_account`	Creates a new S3 account based on the selected pricing plan, checks free account limits and user credits, and creates an order in the billing system.
`create_bucket`	Creates a new S3 bucket for an existing user account. Requires an active s3uid belonging to the client.
`create_order`	Creates a new S3 account (bucket) for the user, links it to a pricing plan, and places an order in the billing system.
`delete_account`	Deletes the user's S3 account, cancels associated services, and performs action auditing.
`delete_bucket`	Deletes the specified S3 bucket after verifying its ownership by the user and its presence in the list of available buckets.
`delete_file`	Deletes the specified file from the S3 bucket. Requires a valid s3uid of the account owner.
`delete_payment_account`	Requests subscription cancellation and S3 account deletion. If successful, the service is moved to cancellation status.
`get_buckets`	Returns a list of S3 buckets, traffic information, and snapshots for the specified account.
`get_buckets_rmq`	Returns the user's bucket list, storage usage information, billing data, and S3 access credentials.
`get_files`	Returns a list of files and folders in the specified S3 bucket with pagination support via continuation token.
`get_users`	Returns a list of S3 accounts with detailed information on plans, traffic, and storage usage. Supports filtering by plan_id, email, s3uid, billing, and location.
`history`	Returns the action history associated with a specific ID (likely an account or user).
`list_plans`	Returns a list of available S3 plans including VAT rate and user currency. For administrators, it can return a specific plan by ID.
`show_key`	Returns the decrypted secret key or public access key for the specified 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 additional contact for a 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 selected invoice. If the credit amount is greater than the invoice amount, only the required portion is applied.
`create_addfunds`	Creates an invoice in WHMCS for topping up the customer's balance (Add Funds). If the subscribe option is enabled, automatic renewal is activated.
`delete_cancellation_request`	Deletes an active service cancellation request for a specific server. If the server was linked to WHMCS, the operation may initiate the unmounting process.
`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 viewing or downloading.
`generate_due_invoice`	Generates the next due invoice for the server. It is blocked if the customer has unpaid invoices or if the current billing cycle is not completed.
`get_billing_data`	Returns detailed information about a specific server's billing data, including EU B2C status and refund data (if applicable).
`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 customer information from WHMCS, including profile data, contact details, and assigned groups.
`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 customer or checks access rights to them.
`get_invoice`	Returns detailed information about an invoice from WHMCS, including customer data and payment status.
`get_invoices`	Returns a list of all invoices associated with a customer in WHMCS for the specified location.
`get_related_invoices`	Returns a list of invoices associated with a specific server or account in WHMCS.
`getcredits`	Returns information about the user's available balance (credits) in WHMCS for the specified location.
`getpaymentgw`	Returns a list of payment gateways available for a specific invoice, considering the customer's currency and regional restrictions.
`mass_pay`	Creates one combined invoice to pay several selected customer invoices.
`request_cancellation`	Initiates the order or service cancellation process. It checks for active licenses, invoice payment status, and automatic refund eligibility (including EU B2C rules). If there are traffic debts, they are taken into account when calculating the refund amount.
`request_subscription_cancellation`	Sends a request to cancel a bank subscription by creating a ticket in JIRA. It checks for active subscriptions and payment status.
`reset_password`	Initiates the password reset process. If no token is provided, a link is sent via email. If the token is valid, it verifies 2FA and updates the password.
`transactions`	Returns a list of user financial transactions from WHMCS based on filters.
`update_client`	Updates the customer profile in WHMCS, including personal data (name, email), contact information, and custom fields. Supports email uniqueness check and verification via SMS/2FA.
`update_contact`	Updates additional contact data (first name, last name, email, phone) for an existing customer in WHMCS. Supports email uniqueness check and phone number validation.