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 for handling creation, modification, deletion, and listing of API keys with IP access control and server association.

Method	Description
`add`	Creates a new API key for the authenticated customer. If the customer has active services or balance, they can create keys.
`add_history`	Manually adds a history log entry for an API key.
`count_owned`	Returns the total number of API keys owned by the authenticated customer.
`delete`	Deletes an API key.
`edit`	Updates an existing API key's name, IP restrictions, or server association.
`history`	Retrieves the audit log/history for API keys.
`list`	Returns a list of all API keys owned by the authenticated customer.
`list_for_customer`	Lists API keys filtered by a specific customer ID.
`list_for_server`	Lists API keys associated with a specific server.
`view`	Returns detailed information for a specific 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 provided two-factor authentication (2FA) code to complete the login process.
`2fa_resend`	Triggers a new 2FA (Two-Factor Authentication) verification code to be sent to the user's registered contact method.
`billing_list`	Returns a list of billing records or active services associated with the client, potentially filtered by location.
`email_check`	Checks if a specific email address is already registered in the system to prevent duplicates.
`flip_tag`	Toggles the state of a specific tag for a given component.
`get_log`	Returns the authorization event log for a specified period or by token.
`get_log_details`	Retrieves detailed information about a specific authentication log entry using the provided token.
`github_init`	Initializes the GitHub authentication process.
`github_signin`	Authenticates a user using GitHub OAuth credentials to establish a session.
`google_signin`	Authenticates a user via Google OAuth2 and establishes a session.
`info`	Retrieves information about the current authenticated session or client status.
`ipalogin`	Authenticates a user via FreeIPA and returns the associated roles and account information.
`list_hashes`	Returns a list of all existing authentication hashes.
`login`	Authenticates a user via email and password, initiating a session and logging the attempt.
`logout`	Terminates the current user session by invalidating the provided token.
`register`	Registers a new client or account within the system.
`session_reset`	Resets the current user session, effectively logging out or invalidating existing session tokens.
`set_tag`	Mass inserts or updates tags for various components. Supports web icon assignment for presets.
`sms_check`	Verifies the provided SMS authentication code for a specific user or session.
`sms_send`	Sends an SMS message to a specified phone number.
`sms_validate`	Validates the provided SMS code for a specific user or session to complete authentication.
`tg_verify`	Verifies a user via Telegram authentication process.
`track_sale`	Records a sale event in the system, typically used for synchronizing billing or tracking transaction history.
`unregister`	Unregisters a specific tag from a component, effectively removing the association between an entity and a tag.
`validate`	Validates the provided authentication credentials and returns a session or error status.
`validate_login`	Validates user credentials and returns authentication status or error details.
`vk_init`	Initializes a VK session or performs authentication-related setup.
`vk_signin`	Authenticates a user via VKontakte social media integration.
`whmcslogin`	Authenticates a user using email/password or an SSO provider (Google, GitHub, VK). If multiple billing locations are found with valid credentials, it returns an async response to select the correct one. On success, returns a session token and user permissions.

eq.php¶

Equipment management module for server lifecycle operations including deployment, reconfiguration, backup management, and IPMI/NoVNC console access.

Method	Description
`abort_reinstall`	Aborts an ongoing server reinstallation process, removes related tags and cleans up deployment state.
`add_ipmi_user`	Adds a new IPMI user to the server. If admin access is requested, specific permissions are required.
`announceip`	Announces an IP subnet via BGP.
`backup_get_schedule`	Retrieves the backup schedule.
`backup_list`	Returns a list of available backups for the specified server.
`backup_save_schedule`	⚠️ Documentation temporarily unavailable.
`boot_dev`	Request server to boot from specified media - PXE or disk.
`check_backup_lock`	Checks if a backup lock is active.
`check_pin`	Validate pin for workers.
`clear_pxe`	Clear PXE config for specific host.
`console`	Request server start/console.
`create_backup`	Initiates a new backup job for the specified server.
`create_pxe`	Request server reinstall via PXE.
`delete_backup`	Deletes a specific backup by name.
`deploy`	Deploys a server by ID or preset name.
`get_ipmi`	Returns the server's IPMI address and model.
`get_traffic`	Returns IPv4 traffic statistics for the server.
`get_upgrade_key`	Retrieves the upgrade key associated with a specific invoice.
`getserversforannounce`	Get servers for announcement.
`groups`	Returns the list of preset groups for a specific server.
`hard_off`	Requests a hard power-off for the server.
`list`	Returns a list of available equipment based on search criteria.
`novnc`	Requests a NoVNC console session for the server.
`off`	Requests a graceful shutdown for the server.
`on`	Requests a server power-on.
`order_instance`	Orders a new server instance from a preset or stock.
`ovirt_novnc`	Request oVirt noVNC console.
`reboot`	Request server reboot.
`recreate_novnc`	Restarts the NoVNC console session.
`reinstall`	Starts the reinstallation stage for a server.
`remove_ipmi_user`	Delete extra IPMI users.
`request_backup_link`	Request a backup link.
`restore_backup`	Restores a server from a specified backup.
`search`	Return available equipment by different search requests.
`sensors`	Retrieves hardware sensor data for the server.
`set_pin`	Sets a PIN for worker authentication.
`show`	Returns detailed hardware and software data for a specific server.
`status`	Requests the current status of a server.
`status_check`	Checks the overall system status.
`stop_novnc`	Terminate noVNC console.
`suspend`	Suspends a VPS server.
`traffic_add`	Adds extra outbound traffic limit to a server and creates an invoice.
`unit_reset`	Requests an IPMI unit reset for the server.
`unsuspend`	Unsuspends a VPS server.
`update_servers`	Updates the cached server list for a specific user/token.

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 current status of an asynchronous job using a 32-character hex key. Returns job scope, context, and debug information.
`reinstall`	Processes the completion of a server reinstallation job, updates billing status via WHMCS, notifies customers, and cleans up deployment tags.

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`	Retrieves the client's IP address from the request context.
`get_ip`	Returns full network information regarding a specific IP address including netmask and other network details.
`get_ptr`	Retrieves the PTR record for a specific IP address belonging to a given server ID.
`get_traffic`	Returns network traffic statistics (in/out) for a specific IP address within a given time period.
`list_free_ip`	Returns a list of unused IPv4 addresses for a specific location or subnet. For customers, it validates ownership via tags before returning results.
`set_main`	Sets a specific IP as the primary (main) address for a given server interface and updates billing data if necessary.
`update_ptr`	Updates the PTR (Reverse DNS) record for a specific IP address assigned 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 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 one or multiple IPv4 addresses to a specific server interface. If no IP is provided, the system searches for available free IPs based on location and VLAN.
`block_ip`	Blocks a specific IP address using BIRD or blackhole mode. If an expiration time is set, it adds a block_expire tag to the server.
`get_status`	Manages network port states (on/off), bandwidth shaping, and interface configurations for a specific server.
`port_off`	Disables a specific network port on the target device.
`port_on`	Enables a specific network port on the target device.
`remove_ipv4`	Removes a specific IPv4 address or all IPv4 addresses from the specified server.
`show_cacti`	Retrieves a specific Cacti graph for the given resource ID.
`show_ipv4_free`	Returns a list of available IPv4 addresses for a specific server, interface (port), and VLAN, considering ownership and subnet constraints.
`unblock_ip`	Removes an IP block from a specific server using BIRD or blackhole management.

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 filtered list of operating systems based on server hardware, instance presets, or customer location.

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 the list of available preset groups.
`info`	Returns detailed information about a specific preset including pricing, availability, and tags.
`list`	Returns a list of all available presets. If a valid token is provided, the 'total' field is removed from each preset object for public access.
`search`	Search appropriate servers for a specific preset by name, filtering by scope (free or all) and location.
`show`	Returns the configuration and pricing details of a specific preset by its ID.

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`	Sends a new message to an existing Remote Hands Request, updates the conversation history, and optionally creates support tickets or media attachments.
`discard`	Discards a specific Remote Hands Request by ID. If a response is provided, it is logged in the request history.
`list`	Returns a list of Remote Hands Requests (RHR) based on filters like location, status, and date range. If the user is a customer, it also includes historical logs related to these requests.

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 storage account associated with a specific client.
`create_account`	Creates a new S3 storage account based on a selected plan, validates bucket name, and processes billing.
`create_bucket`	Creates a new S3 bucket with specified configuration.
`create_order`	Creates a new S3 storage order, provisions an S3 user account, and creates a bucket.
`delete_account`	Deletes an S3 account associated with a specific bucket name and region.
`delete_bucket`	Deletes a specified S3 bucket from the storage system.
`delete_file`	Deletes a specific file from S3 storage. Requires valid authentication token and appropriate permissions.
`delete_payment_account`	Deletes a specific S3 payment account associated with a bucket.
`get_buckets`	Retrieves a list of S3 buckets for the authenticated user, including usage statistics and snapshot information.
`get_buckets_rmq`	Retrieves detailed information about S3 buckets, including usage statistics, metering history, billing info, and access credentials for a specific S3 user.
`get_files`	Retrieves a list of files from S3 storage based on provided parameters.
`get_users`	Retrieves a list of users associated with S3 storage configurations.
`history`	Retrieves the history of S3 operations or access logs based on provided filters.
`list_plans`	Returns a list of available S3 storage plans, including pricing and location information.
`show_key`	Retrieves S3 access credentials or configuration for a specific bucket/account.
`tariff_upgrade`	Upgrades the S3 storage tariff for a specific service or account.
`update_traffic_info`	Updates traffic usage information or configuration for a specific S3 bucket/account.

saas.php¶

SaaS panels endpoint router for managing SaaS-related operations and service installations.

Method	Description
`install`	Initiates a new SaaS installation process. Requires valid authentication token.

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 available software components including their IDs, internal status, and associated tags.

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 the list of available tags for a specific server or component, with optional filtering by internal status.
`remove`	Removes a specific tag from a component by name or removes multiple tags using an ID list.
`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 traffic plans with optional filtering by location, scope, or active status.

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`	Creates a new snapshot of the specified virtual machine.
`get_snapshot`	Retrieves information about a specific VM snapshot by its ID.
`load_stats`	Loads statistical information for a specific virtual machine or server group.
`remove_snapshot`	Removes a specific snapshot from the virtual machine.
`restore_snapshot`	Restores a virtual machine to a previously saved snapshot state.
`update_restore_settings`	Updates the restoration configuration settings for a specific 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.
`apply_credit`	Applies available account credit to a specific unpaid invoice. If the invoice is fully paid, it may trigger traffic overusage clearing for associated tags.
`create_addfunds`	Creates an 'Add Funds' invoice in the connected WHMCS account for a specific 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 customer. Requires ownership or appropriate permissions.
`download_invoice`	Downloads a specific invoice as a PDF file in binary format. The response is sent directly to the output stream.
`generate_due_invoice`	Generates the next due invoice for a specific server, provided that no upgrade tags are present and there are no unpaid invoices.
`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, including prebill data and billing status.
`get_client`	Fetches detailed information about the authorized client from WHMCS, including billing location, group data, and custom fields.
`get_clientgroups`	Returns the list of preset client groups from WHMCS for a specific location.
`get_contacts`	Retrieves a list of contacts associated with a WHMCS customer. If a subaccount email is provided, it filters the results to only include that specific contact 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 returns all available data from WHMCS.
`get_related_invoices`	Retrieves a list of invoices associated with a specific server or account.
`getcredits`	Retrieves the credit balance and account history for a specific user in WHMCS.
`getpaymentgw`	Returns the list of available payment gateways for a specific invoice, including processed call URLs.
`mass_pay`	Processes the payment for a collection of specified invoice IDs simultaneously.
`request_cancellation`	Requests a cancellation for a specific server, performing billing validation, refund calculations (including EU B2C rules), and traffic overusage checks.
`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 multi-step password reset process. First call sends a reset link via email; subsequent calls with a token and 2FA code (if enabled) update the client's password.
`transactions`	Retrieves a list of transactions for the authenticated user or specified transaction ID.
`update_client`	Updates customer profile data including personal/company details, contact information, and IP access lists.
`update_contact`	Updates the profile data of an existing contact, including personal details, email, phone number, and password.