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`	Exchanges the authorization code for a GitHub access token and links the account to the user (SSO). If the token is already linked, it redirects to an 'already used' page; otherwise, it performs the linking.
`google_signin`	Logs in using a Google ID Token. If the token is already linked to the user, the method links the current session with this 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 the user's Telegram username to their account and returns a link to the bot for notifications.
`vk_init`	Initiates the authorization process via VK by generating temporary parameters (code_challenge, state) and saving them for subsequent verification during login.
`vk_signin`	Performs user authorization via the VK OAuth2 protocol. Exchanges the code for a token and links the account to the user.
`whmcslogin`	Logs in 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`	Stops the server reinstallation process, removes associated tags (reinstall_start, autodeploy_start, autodeploy_timeout), and restores 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`	Adds a new user to the IPMI management system for a specific server. If the user is an administrator, parameters may be overridden.
`announceip`	Performs announcement of a specified subnet or IP address via BGP. Supports permission checks and sub-account handling.
`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 a server reboot to boot from the specified media (PXE or disk) depending on the boot mode.
`check_backup_lock`	Checks if there is an active lock on backup operations for the specified server.
`check_pin`	Checks the PIN code for operations.
`clear_pxe`	Clears the current PXE configuration for the specified host.
`create_backup`	Initiates the backup creation process for the specified server. The operation is performed asynchronously.
`create_pxe`	Requests the creation of a PXE configuration for subsequent OS reinstallation on the server. Returns a callback to track the process.
`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 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 (rent/power_off) user servers that match IPv4 mask restrictions (/23 and /24), which can be used for IP address announcement.
`groups`	Returns the list of groups for a specific server.
`hard_off`	Performs a forced (hard) power-off of the equipment by the specified ID.
`history`	Returns the server event history.
`list`	Returns a list of available equipment with filtering options by various parameters (location, status, type, etc.).
`off`	Powers off the server.
`on`	Powers on the server.
`order_instance`	Starts the deployment process for a new server from a preset or reinstallation of an existing server with OS and additional software selection.
`ovirt_novnc`	Requests the launch of a NoVNC console for the server via the oVirt interface. Requires access permissions to the server.
`reboot`	Sends a request to reboot the specified server. If the server belongs to a client, a lock (lock) is checked.
`reinstall`	Creates a key to start the server reinstallation process and sets the initial stage (create_pxe).
`remove_ipmi_user`	Removes an additional IPMI user for the specified server.
`request_backup_link`	Requests the generation of a temporary link to download a server backup.
`restore_backup`	Starts the process of restoring the server from the specified backup. The operation is asynchronous.
`search`	Returns a list of available servers and instances based on various filtering criteria (location, status, type, IP, MAC, etc.).
`sensors`	Returns current sensor readings for the specified server.
`set_pin`	Sets the PIN code for operations.
`show`	Returns full data about the server, including hardware configuration (hwconfig), operating system, IP addresses, interfaces, and IPMI.
`status`	Returns the current equipment status (power_off, rent, TT, etc.) and related data.
`status_check`	Performs a check of the current equipment state (eq_status_check).
`suspend`	Requests suspension (suspend) or unsuspension (unsuspend) of a VPS/server. If the action is suspend, the server will be locked.
`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 an IPMI module reset for the specified server.
`unsuspend`	Request to remove a lock (unsuspend) from a server. If the request is successful, the server will be unlocked.
`update_servers`	Updates the list of available servers linked to the client account in WHMCS, including checking active services and prebill servers.

eq_callback.php¶

Module for processing asynchronous responses from workers for equipment (EQ) and virtual machine management. Handles task statuses (deploy, reinstall, backup, network), updates billing, and sends noti

Method	Description
`check`	Checks the current status of a task by key and returns the execution context if the task is completed or at an intermediate stage.
`reinstall`	Callback handler from the worker after the reinstallation operation is completed. Updates the server status, clears temporary tags, sends an email to the client with access credentials, and updates billing.

ip.php¶

Module for managing IP addresses and network infrastructure: retrieving IP information, managing PTR records, monitoring traffic, and working with subnets and VLANs.

Method	Description
`get_client_ip`	Returns the IP address of the current client making the request.
`get_ip`	Returns full information about a specific IP address, including network data, mask, and ownership.
`get_ptr`	Returns the PTR record (reverse DNS name) for the specified IP address bound to a server.
`get_traffic`	Returns incoming and outgoing traffic statistics for the specified IP address over a given period. Supports summary mode or detailed breakdown by timestamps.
`list_free_ip`	Returns a list of unused IP addresses for the specified location or subnet. For clients, the subnet ID is used; for administrators, the location code is used.
`set_main`	Sets the specified IP address as the primary IP for the server interface. Updates billing data in WHMCS if applicable.
`update_ptr`	Sets the reverse DNS record (PTR) for the specified IP address bound to a server.

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 related to server management (power, reboot, KVM) and sales assistance requests.

Method	Description
`request_PXEboot`	Creates a Jira ticket for manual server PXE boot if remote management is unavailable.
`request_assistance`	Creates a Jira ticket for the sales department with details regarding service cancellation or modification.
`request_check`	Creates a Jira ticket to check and boot the server into the OS if remote management is unavailable.
`request_kvm`	Creates a Jira ticket to connect an IP KVM to the server.
`request_poff`	Creates a Jira ticket for manual server power off.
`request_pon`	Creates a Jira ticket for manual server power on.
`request_reboot`	Creates a Jira ticket for manual server reboot.

nat.php¶

Module for managing static NAT: adding and removing IP address forwarding rules via MikroTik.

Method	Description
`add_static_nat`	Adds a static NAT passthrough for the specified server. Accepts the server ID and ACL for IPMI.
`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 presets management module: retrieving lists, grouping, searching for suitable servers, and detailing configurations with prices in various currencies.

Method	Description
`groups`	Returns a list of available preset groups
`info`	Returns a list of presets with prices in specified currencies, defaulting to EUR and USD
`list`	Returns a list of available server presets with filtering by location and access rights
`search`	Searches for suitable servers for a specific preset by name, scope, and location.
`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 service cancellation process for an S3 account, restoring its status.
`create_account`	Creates a new user's S3 account linked to a pricing plan, with automatic creation of a billing order in WHMCS.
`create_bucket`	Creates a new S3 bucket for the user, linked to their existing account.
`create_order`	Creates a new S3 account linked to a pricing plan, including bucket creation and payment order processing in WHMCS.
`delete_account`	Deletes the user's S3 account, performs an action audit, and logs the operation in history.
`delete_bucket`	Deletes the specified bucket from storage if it belongs to the user.
`delete_file`	Deletes the specified file from the S3 bucket. Requires authorization and verification of the user's access rights to the account.
`delete_payment_account`	Requests cancellation of the S3 service and subsequent deletion of the payment account. The method checks for an active service linked to the user and initiates the annulment process.
`get_buckets`	Method intended to retrieve a list of S3 buckets, usage information, and snapshots. In the current code version, this method is commented out.
`get_buckets_rmq`	Returns a list of user buckets, their usage, quota, metric data, and S3 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 information on traffic, storage, and service data. Supports filtering by plan, email, billing, s3uid, and location.
`history`	Returns the event history for the specified S3 plan.
`list_plans`	Returns a list of available S3 plans considering user permissions and location. For administrators, it returns the full list; for users, only active plans with prices in their currency.
`show_key`	Returns the decrypted secret key or public access key (access_key) for the specified S3 account.

software.php¶

Software Management Module: provides methods for retrieving a list of available software with filtering by server characteristics or presets, as well as selecting compatible presets and operating syst

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 promotional offers.

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 adding to a list of IDs via id_list.
`list`	Returns a list of all tags for the specified server or component.
`remove`	Removes a tag by name from the specified server or component. Supports removal by ID list.

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 an additional contact person 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 for a selected invoice. If the credit amount exceeds the invoice total, the maximum possible amount is applied.
`create_addfunds`	Creates an invoice in WHMCS to top up the customer's balance. If the subscribe option is enabled, it activates automatic payments.
`delete_cancellation_request`	Deletes an active subscription cancellation request for a specific server, allowing the order status to be restored.
`delete_contact`	Deletes an additional contact associated with a customer in WHMCS.
`download_invoice`	Returns a PDF invoice file in base64 format for downloading or viewing.
`generate_due_invoice`	Generates the next invoice for a server in WHMCS if the current billing cycle is not completed and there are no unpaid invoices.
`get_billing_data`	Returns detailed information about the billing account and the current service status for the specified Server ID.
`get_cancellation_requests`	Returns a list of active cancellation requests for a specific server or user, with filtering by type, payment status, and date.
`get_client`	Returns detailed information about the authenticated client, including data from WHMCS and internal system tags.
`get_clientgroups`	Returns a list of available customer groups from WHMCS for the specified location.
`get_contacts`	Returns a list of contacts associated with a customer in WHMCS. If an email subaccount is specified, only contacts with appropriate access rights are returned.
`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 the client in the selected WHMCS location.
`get_related_invoices`	Returns a list of invoices associated with a specific server (via account_id).
`getcredits`	Returns information about available credits (balance) on the user's account in WHMCS.
`getpaymentgw`	Returns a list of available payment methods (payment gateways) for a specific invoice.
`mass_pay`	Allows making a bulk payment for several invoices with a single transaction, creating a corresponding transaction record in WHMCS.
`request_cancellation`	Initiates the order or subscription cancellation process. It checks for active licenses, server status, and automatic refund eligibility depending on the billing type.
`request_subscription_cancellation`	Initiates the bank subscription cancellation process for a server. It checks for active subscriptions, payment status, and creates a JIRA ticket to process the request.
`reset_password`	Initiates the password reset process. If reset_token is not provided, it sends a link via email and enables 2FA. If a token is provided, it allows setting a new password after verifying the 2FA code.
`transactions`	Returns a list of user transactions filtered by (Client ID, Server ID, Invoice ID, or specific transaction ID).
`update_client`	Updates customer information in WHMCS, including contact details (name, email, phone), address, marketing settings, and custom profile fields.
`update_contact`	Updates additional contact information for a client (first name, last name, email, phone) in the WHMCS system. Changing the primary email or phone may require re-verification.