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 entered two-factor authentication code for the current user session.
`2fa_resend`	Sends a new two-factor authentication code to the linked channel (email or SMS)
`billing_list`	Returns a list of available payment systems (billings) linked to the current session or available to the administrator.
`email_check`	Validates the email, registers the customer in the system (if not found), and sends a verification code to the email address.
`flip_tag`	Creates or removes the specified tag for the customer. If the tag already exists, it will be removed; if it does not exist, it will be added.
`get_log`	Returns the authorization event log for a specified period or by token.
`get_log_details`	Returns detailed information about authentication events linked to a 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 token for subsequent code-to-session exchange.
`google_signin`	Performs login using a Google ID Token. If the token is valid, it links the account to the user or updates the existing session.
`info`	Returns detailed information about the current user session, including role, permissions, customer data, and active servers.
`login`	Authorizes a user via the provided API key, checking IP restrictions and linked servers. Returns a session token and a list of available servers.
`logout`	Clears the current active access token of the user.
`session_reset`	Terminates all active user sessions based on their email and reset token. Performs tag (session) cleanup in the database.
`set_tag`	Creates or removes a tag for the customer. Allows setting values for various metadata (e.g., auto_credit).
`tg_verify`	Links the user's Telegram username to their account (removing the old ID) and returns a link to the bot.
`vk_init`	Initiates the authorization process via VK, generating parameters for the client side (code_challenge, state, and device_id).
`vk_signin`	Initiates the authorization process through the VK social network, generating temporary data for OAuth2 (state, code_verifier) and saving it in the system.
`whmcslogin`	Performs login to the system. Supports standard authorization (email/password) and SSO methods (Google, GitHub, VK). Upon successful login, returns a session token, user data, and permissions.

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`	Aborts an ongoing server reinstallation process, removes related deployment tags, resets network interfaces if necessary, and updates deployment logs.
`add_ipmi_admin`	Adds a user with administrator privileges to the IPMI interface for a specific server. 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, the provided credentials are used.
`announceip`	Performs announcement of the specified subnet for a server with a specific ASN.
`backup_get_schedule`	Returns the current automatic backup schedule for the specified server.
`backup_list`	Returns a list of available backups for the specified equipment (server).
`backup_save_schedule`	Saves the configured backup schedule for the specified server.
`boot_dev`	Requests to boot the server from a specified media type (PXE or disk) in UEFI or Legacy 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 current PXE configuration for the specified host.
`console`	Requests access to the server management console via IPMI/NoVNC.
`create_backup`	Initiates the backup creation process for the specified server. The operation is executed asynchronously via a queue.
`create_pxe`	Creates a Preboot Execution Environment (PXE) configuration to install a selected OS on the server. Supports configuring hostname, SSH keys, and post-install scripts.
`delete_backup`	Deletes the specified server backup. The backup name is required.
`deploy`	Deploys a specific server by ID or creates one from a preset. Supports OS selection, custom hostnames, and prebill service linking.
`get_ipmi`	Returns the IP address and IPMI interface model for the specified server. May contain multiple interfaces.
`get_traffic`	Returns IPv4 traffic data for the specified server.
`get_upgrade_key`	Returns the upgrade key linked to a specific invoice (invoice_id).
`getserversforannounce`	Returns a list of available servers (rent or power_off) that match IP subnet and mask constraints to perform the announcement procedure.
`groups`	Returns a list of groups for the specified server.
`hard_off`	Performs a forced shutdown of the server (Hard Off). If the server is in OpenStack, a forced reboot is performed.
`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`	Deploys a new server from a preset or reinstalls an existing one with specified OS, software, and hardware configurations.
`ovirt_novnc`	Requests access to the oVirt console via noVNC protocol for the specified server.
`reboot`	Sends a request to reboot the hardware. If the server is in standby mode, execution via IPMI may be required.
`reinstall`	Creates a key to start the server reinstallation process and adds the task to the queue.
`remove_ipmi_user`	Deletes additional IPMI user accounts for the specified server.
`request_backup_link`	Requests a temporary link to download a server backup.
`restore_backup`	Initiates the process of restoring a server from a specified backup. The method is asynchronous and returns a callback to track task execution.
`search`	Returns a list of available or active equipment based on various filters (group, location, status, IP, MAC, etc.).
`sensors`	Returns sensor status data 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, state data, and available management parameters.
`status_check`	Performs a status check on the specified equipment or component.
`suspend`	Requests suspension (suspend) or unsuspension (unsuspend) of a VPS/server. Operation requires access rights and, in some cases, an administrator lock check.
`traffic_add`	Increases the outbound traffic limit for the server and creates a corresponding invoice in WHMCS.
`unified_server_search`	Unified server search by query.
`unit_reset`	Request to reset (reset) the device via the IPMI interface for the specified server.
`unsuspend`	Unsuspends a server if it was temporarily suspended.

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 IP addresses for a specific location or subnet, optionally filtering by special exclusion rules.
`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 the selected port and VLAN. If no IP is specified, the system selects available free addresses from those available in the current location.
`block_ip`	Blocks the specified IP address for the server via BIRD or blackhole. If the description parameter is not provided, the system's owner prefix is used.
`get_status`	Returns the current state and parameters of the server's network interface (speed, VLAN, status, security settings).
`port_off`	Disables the server's network port by adding an administrative block with a reason specified in the interface tags.
`port_on`	Enables the server's network port by removing associated blocking tags (e.g., 'block'). If an administrative ban is set on the port, the action will be rejected.
`remove_ipv4`	Removes one or more IPv4 addresses from the server. If the remove_all parameter is specified, all IP addresses are removed (depending on backend implementation logic). Upon successful execution, the PTR record in DNS is cleared.
`show_cacti`	Returns data for displaying Cacti charts for a specific port and graph ID.
`show_ipv4_free`	Returns a list of available IPv4 addresses for assignment to a specific server, port, and VLAN, taking into account location and tags.
`unblock_ip`	Removes the block from the specified IP address via BIRD. If the action is performed by a client, it checks for the presence of a corresponding entry in the interface description.

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 configuration information 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
`list`	Returns a list of available presets, considering location and user permissions
`search`	Returns a list of suitable servers based on the preset name, scope (free/all), and location
`show`	Returns detailed information about a specific preset by its ID or name, taking into account restrictions for certain regions and payment parameters.

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). Supports KVM, Unblock, or Service types. If the client is a customer, emoji are not allowed in the request text.
`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 scheduled deletion of an S3 payment account.
`create_account`	Creates a new S3 storage account based on a specific plan and location. This action handles user creation in the S3 system, bucket initialization, and billing service setup.
`create_bucket`	Creates a new S3 bucket with specified configurations.
`create_order`	Creates a new S3 account and bucket based on the selected plan, location, and bucket name. Handles billing, quota allocation, and service activation.
`delete_account`	Deletes an S3 account associated with a specific bucket name and region.
`delete_bucket`	Deletes a specified S3 bucket from the system.
`delete_file`	Deletes a specific file from S3 storage
`delete_payment_account`	Deletes a specific S3 payment account associated with a bucket.
`get_buckets`	Retrieves a list of S3 buckets, usage statistics, and account credentials for the specified user.
`get_buckets_rmq`	Retrieves detailed S3 account information including bucket list, storage usage, metering, billing info, and credentials.
`get_files`	Retrieves a list of files from S3 buckets based on provided filters.
`get_users`	Retrieves a list of S3 users/accounts based on provided filters.
`history`	Retrieves the history of S3 operations or logs based on provided filters.
`list_plans`	Returns a list of available S3 storage plans including pricing and location information.
`show_key`	Retrieves S3 UID information based on bucket name, region, and storage type.

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 to the WHMCS system with specified details.
`apply_credit`	Applies available account credit to a specific unpaid WHMCS invoice. If the invoice is paid via this method, it may trigger traffic usage clearing for certain tags.
`create_addfunds`	Creates an 'Add Funds' invoice in the specified WHMCS account for a customer.
`delete_cancellation_request`	Removes a cancellation request for a specific server, potentially restoring the cancelled invoice or generating a new one.
`delete_contact`	Deletes a specific contact associated with a WHMCS client. Requires ownership or appropriate permissions.
`download_invoice`	Downloads a specific WHMCS invoice as a PDF file in binary format. The response is sent directly to the output stream with appropriate headers.
`generate_due_invoice`	Generates the next due invoice for a specific server, subject to upgrade tags and billing cycle constraints.
`get_billing_data`	Retrieves detailed billing information for a specific server, including EU withdrawal license costs and customer details.
`get_cancellation_requests`	Returns a list of active cancellation requests for a specific server or user, merging data from WHMCS and prebill services.
`get_client`	Returns detailed information about the authenticated client, including WHMCS data and internal system tags.
`get_clientgroups`	Returns the list of preset client groups from WHMCS for a specific location.
`get_contacts`	Retrieves a list of sub-contacts associated with a customer in WHMCS. If a specific email is provided, it filters the results and checks permissions.
`get_invoice`	Fetches detailed information about a specific WHMCS invoice, including client data if authorized.
`get_invoices`	Fetches the list of invoices for a specific customer. If called by a customer, it returns their own invoices; otherwise, it retrieves all invoices for the authorized client.
`get_related_invoices`	Retrieves a list of invoices associated with a specific server or account.
`getcredits`	Retrieves the credit history for a specific WHMCS user in a given location.
`getpaymentgw`	Returns the list of available payment gateways for a specific invoice, including processed HTML call actions.
`mass_pay`	Processes multiple WHMCS invoices for mass payment for a specific client and location.
`request_cancellation`	Requests a cancellation for a specific server, handling refunds, EU B2C withdrawal rules, and traffic overusage surcharges.
`request_subscription_cancellation`	Requests the cancellation of a subscription for a specific server. It checks billing status, validates existing JIRA tickets to prevent duplicates, and creates a new JIRA ticket for manual processing.
`reset_password`	Handles the password reset process. If no token is provided, it sends a reset link to the client's email. If a token is provided, it validates the token and 2FA (if enabled) before updating the password.
`transactions`	Retrieves a list of transactions for the authenticated user or specific transaction ID.
`update_client`	Updates customer profile data including personal/company information, contact details, and custom fields. Supports IP ACL updates and 2FA settings.
`update_contact`	Updates contact information (first name, last name, email, phone number) and permissions for an existing WHMCS contact.