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, history viewing, and retrieving key lists for customers and servers.

Method	Description
`add`	Creates a new API key for a customer or a specific server. Requires the customer to have active servers.
`delete`	Removes 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 passed in the user_token parameter. Requires a valid session token.
`2fa_resend`	Resends the two-factor authentication code to the linked method (email or SMS). Requires a valid session token.
`billing_list`	Returns a list of available billing systems (WHMCS) for the current deployment domain. If a valid token is passed, the list is filtered by the user's or administrator's location.
`email_check`	Client email validation, sending a confirmation code, or checking the entered code.
`flip_tag`	Enables or disables the specified tag for the current user. If the tag exists, it is removed. If it does not exist, it is created.
`get_log`	Returns the authorization event log for the specified period or by token.
`get_log_details`	Returns detailed information about an authorization log entry by the specified user token. Requires a valid session token and auth/get_log access rights.
`github_init`	Returns data for initializing OAuth authorization via GitHub (client_id and redirect_uri).
`github_signin`	Handles the callback from GitHub OAuth. Exchanges the code for an access token, retrieves user data, and links the GitHub account to the current session or creates a new SSO link.
`google_signin`	Handles login via Google. Checks the JWT token, links the Google account to an existing user (if token is passed), or returns data for subsequent login.
`info`	Returns detailed information about the current token: role, access rights, server list, verification status, billing settings, and private IP ranges.
`login`	Returns an access token for the API based on the provided client API key. Checks key validity, access rights, and IP address binding.
`logout`	Clears the access token and terminates the current user session.
`session_reset`	Forcefully terminates all active user sessions by email and reset token, clears associated tags, and redirects to the login page.
`set_tag`	Sets or removes the specified tag for the current authenticated user. Available only for administrators or for clients to set the 'auto_credit' tag.
`tg_verify`	Links the specified Telegram username to the current user's account and returns a link to the notification bot.
`vk_init`	Generates parameters to start the OAuth authorization process via VKontakte (client_id, redirect_uri, code_challenge, device_id, state) and saves the verification code to the database.
`vk_signin`	Handles the callback from VK ID after authorization. Exchanges the code for a token, checks state and code_verifier, links the VK account to the platform user, or redirects to the login page with an SSO hash.
`whmcslogin`	Logs into the system using WHMCS credentials (email/password) or SSO. Returns an access token, role information, access rights, and client details. Supports login via SSO (Google, VK) and standard authentication.

eq.php¶

Equipment management module (eq.php): API for server deployment, power management, IPMI, backups, search, and retrieving detailed equipment configuration information.

Method	Description
`abort_reinstall`	Cancels the server reinstall process, removes corresponding tags, and restores the VLAN.
`add_ipmi_admin`	Adds an IPMI user with administrator privileges.
`add_ipmi_user`	Adds an IPMI user.
`announceip`	Announces an IP address or subnet.
`backup_get_schedule`	Returns the backup schedule for the server.
`backup_list`	Returns a list of available server backups.
`backup_save_schedule`	Saves the backup schedule for the server.
`boot_dev`	Requests the server to boot from a specified medium (PXE or disk).
`check_backup_lock`	Checks for a lock on creating a backup.
`check_pin`	Checks the PIN code for operations.
`clear_pxe`	Clears the PXE configuration for the server.
`create_backup`	Initiates the creation of a server backup.
`create_pxe`	Creates a PXE configuration for server reinstall.
`delete_backup`	Deletes a server backup.
`deploy`	Deploys a server by ID or preset name.
`get_ipmi`	Returns the server's IPMI address and model.
`get_traffic`	Returns IPv4 traffic data for the server.
`getserversforannounce`	Returns a list of servers available for announcement.
`groups`	Returns groups for a specific server.
`hard_off`	Hard powers off the server.
`history`	Returns the server's event history.
`list`	Returns a list of equipment based on various search criteria.
`off`	Powers off the server.
`on`	Powers on the server.
`order_instance`	Initiates the order of a new server from a preset or the reinstall of an existing server. Performs balance, license, and OS compatibility checks, and creates a task in the deployment queue.
`reboot`	Reboots the server.
`reinstall`	Starts the server reinstall process.
`remove_ipmi_user`	Removes an IPMI user.
`request_backup_link`	Requests a link to download a backup.
`restore_backup`	Restores the server from a backup.
`search`	Searches for equipment based on various criteria.
`sensors`	Returns server sensor data.
`set_pin`	Sets the PIN code for operations.
`show`	Returns data about the server and equipment.
`status`	Returns the server status.
`suspend`	Suspends the server.
`unified_server_search`	Unified server search by query.
`unit_reset`	Requests a reset of the server's IPMI.
`unsuspend`	Removes suspension from the server.
`update_servers`	Updates the server list for a specific token.

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¶

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¶

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¶

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, retrieving usage statistics, managing billing plans and billing.

Method	Description
`cancel_payment_account_deletion`	Cancels a previously initiated procedure for deleting a paid S3 account. Requires token validation and access rights check.
`create_account`	Creates a new S3 account for the client, links a billing plan, creates a bucket, and places an order in billing.
`create_bucket`	Creates a new bucket in S3 storage for the specified user. Requires a valid s3uid of the current client.
`create_order`	Creates a new S3 storage order for the client. Validates the billing plan, checks free account limits or credits, creates an S3 user, bucket, and billing service.
`delete_account`	Completely deletes the user's S3 account. Requires specifying the client ID (for an administrator) or uses the current user's ID, as well as the s3uid of the target account.
`delete_bucket`	Deletes the specified S3 bucket. Checks access rights and bucket ownership by the user.
`delete_file`	Deletes the specified file from the S3 bucket. Requires token validation and client access rights check.
`delete_payment_account`	Initiates cancellation of a paid S3 account. Sets the cancellation date for the service associated with the specified s3uid.
`get_buckets`	Returns a list of buckets for the specified S3 account, including information on storage usage, quota, metrics, and access keys. Uses an asynchronous request via a task queue.
`get_buckets_rmq`	Returns a list of S3 user buckets, information on storage usage, quota, traffic metrics, and access keys. Uses a message queue (RMQ) to retrieve current data.
`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 usage, and service status. Supports filtering by client ID, plan ID, email, billing, s3uid, bucket_name, storage_type. Sorting and pagination are available for administrators.
`history`	Returns the history of changes or events related to the specified S3 billing plan.
`list_plans`	Returns a list of available S3 billing plans. Hides inactive plans for clients (if no s3_test tag). For administrators, specifying id returns details of a specific plan.
`show_key`	Returns the decrypted access key (access_key or secret_key) for the specified S3 account.

software.php¶

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¶

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¶

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¶

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¶

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 clients, invoices, credits, order cancellations, and server billing data.

Method	Description
`add_contact`	Adds a new contact to an existing client in the billing system.
`apply_credit`	Applies credit from the client's balance to pay a specified invoice.
`create_addfunds`	Creates an invoice for adding funds (Add Funds).
`delete_cancellation_request`	Removes an active server cancellation request and restores the invoice.
`delete_contact`	Removes a contact from the client account.
`download_invoice`	Generates and returns the invoice PDF file.
`generate_due_invoice`	Generates the next invoice for server payment.
`get_billing_data`	Retrieves synchronized billing data for a server.
`get_cancellation_requests`	Returns a list of active server cancellation requests.
`get_client`	Returns information about the authorized client or by ID.
`get_clientgroups`	Returns a list of client groups in the billing system.
`get_contacts`	Returns a list of additional client contacts.
`get_invoice`	Returns data for a specific invoice.
`get_invoices`	Returns a list of client invoices.
`get_related_invoices`	Returns invoices associated with a server or account.
`getcredits`	Returns the client's credit history.
`getpaymentgw`	Returns available payment methods for an invoice.
`mass_pay`	Creates a single invoice to pay multiple specified invoices (mass payment).
`request_cancellation`	Initiates the server cancellation process with refund calculation.
`request_subscription_cancellation`	Initiates the bank subscription cancellation process for a specified server by creating a JIRA ticket. Checks for an active subscription and the status of previous requests.
`reset_password`	Initiates a password reset or sets a new one with 2FA.
`transactions`	Returns the client's transaction history.
`update_client`	Updates the client profile data in the billing system.
`update_contact`	Updates the client contact data.