InvAPI Control Panel API Documentation¶

This documentation describes the overall design and principles of the API, along with specific endpoints and usage examples.

Overview

The invapi.hostkey.com control panel is built on top of this API.

Making API Requests¶

All API requests must be made over HTTPS to ensure encryption of data in transit.

Use the POST method for all requests unless otherwise specified.

API Example Format¶

Examples in this documentation use curl, a command-line HTTP client. curl is pre-installed on most Linux and macOS systems and is available for download on all major platforms, including Windows.

Each example is split across multiple lines using the \ line continuation character, which is compatible with bash. A typical request looks like this:

Example POST Request:

curl -s "https://invapi.hostkey.com/tags.php" -X POST \
  --data "action=list" \
  --data "token=$HOSTKEY_TOKEN" \
  --data "id=SERVER_ID"

The -X flag specifies the HTTP method. For consistency, the method is included in all examples, even when not explicitly required for GET requests.

Examples that require a JSON payload in the request body pass the data via the --data parameter.

All API responses are returned in JSON format and formatted in this documentation for readability.

Tip: Environment Variables

To avoid repeating your API token in every example, you can export it once as an environment variable in your terminal. On Linux or macOS:

export HOSTKEY_TOKEN="your_api_token_here"

The token will then be automatically substituted in your requests.

Disclaimer

All values shown in this documentation are for illustrative purposes only. Do not rely on operating system IDs, plan identifiers, or other example values. Always use your actual server, network, or domain identifiers when querying or creating resources. In some cases, only the account API key will work, not the specific server key (and vice versa), so if you encounter method authorization errors, try switching the API key type.

api_keys.php¶

API key management module: creation, editing, deletion, viewing history, and retrieving lists of keys for customers and servers.

Method	Description
`add`	Creates a new API key for a customer or a specific server. The customer must have active servers.
`delete`	Deletes the specified API key from the system.
`edit`	Modifies parameters of an existing API key (name, IP, status, expiration).
`history`	Returns the history of actions performed on API keys (creation, modification, deletion).
`list`	Returns a list of all API keys for the current customer.
`list_for_server`	Returns a list of API keys bound to a specific server.
`view`	Returns detailed information about a single API key.

auth.php¶

Authentication and authorization module: session management, login via WHMCS, LDAP, API keys, and SSO (Google, GitHub, VK), 2FA verification, SMS and email, as well as client tag management.

Method	Description
`2fa_check`	Confirms the two-factor authentication code previously sent to the user. Requires a valid session token.
`2fa_resend`	Resends the two-factor authentication code to the linked method (email, sms, app). 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 provided, the list is filtered by the user's or administrator's location.
`email_check`	Validates the client's email, sends a confirmation code, or checks the entered code. Used for email address verification.
`flip_tag`	Toggles the state of the specified tag for the current user. If the tag exists, it is removed. If it does not exist, it is created. Available only for allowed tags (e.g., 'auto_credit' for clients).
`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 parameters for initializing OAuth authorization via GitHub (client_id and redirect_uri).
`github_signin`	Processes the callback from GitHub OAuth. Exchanges the code for a token, retrieves user data, checks the SSO hash binding to the account, or redirects to the login page with SSO parameters.
`google_signin`	Performs login or links a Google account. If a valid session token is provided, it links the Google ID to the current user. If no token is provided, it returns data for subsequent SSO login.
`info`	Returns detailed information about the current token: role, access rights, linked servers, verification status, and billing settings.
`login`	Returns an access token for the API based on the provided client API key. Checks access rights, IP binding, and the presence of active servers.
`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. For clients, only the 'auto_credit' tag is allowed.
`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 OAuth2 authorization via VK ID (PKCE flow). Creates a unique session ID, code_verifier, and code_challenge, saves them in tags, and returns data for redirection.
`vk_signin`	Processes the callback from VK OAuth2. Exchanges the code for a token, checks state and code_verifier, links the VK account to the user, or redirects to the login page with an SSO hash.
`whmcslogin`	Logs into the system using WHMCS credentials (email/password) or SSO (Google). Returns a session token, client information, access rights, and 2FA status.

eq.php¶

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

Method	Description
`abort_reinstall`	Interrupts the server reinstallation process, removes associated tags (reinstall_start, autodeploy_start, autodeploy_timeout), and restores VLAN settings.
`add_ipmi_admin`	Adds a user with administrator privileges to the server's IPMI. 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, permission management parameters are passed via admin_user.
`announceip`	Requests announcement of a specified subnet or a specific IP address for the server.
`backup_get_schedule`	Returns the current backup schedule for the specified server.
`backup_list`	Returns a list of available backups for the specified server.
`backup_save_schedule`	Saves the configured backup schedule for the specified server.
`boot_dev`	Requests a server reboot to boot from specified media (PXE or disk) depending on the mode.
`check_backup_lock`	Checks for an active lock to perform operations with the server backup.
`check_pin`	Checks the PIN code for operations.
`clear_pxe`	Clears the current PXE configuration for the specified server.
`create_backup`	Initiates the backup creation process for the specified server. The operation is performed asynchronously.
`create_pxe`	Creates a configuration for booting the server via network (PXE), specifying OS parameters, disks, and network settings.
`delete_backup`	Deletes the specified server backup. Requires passing the backup name.
`deploy`	Starts the deployment process of a specific server by its ID or via a preset in the specified location. Supports various modes: from standard to dry-run.
`get_ipmi`	Returns a list of available IPMI interfaces for the server, including IP address and device model.
`get_traffic`	Returns IPv4 traffic data for the specified server.
`get_upgrade_key`	Returns an upgrade key linked to a specific invoice (invoice_id) via hardware tags.
`getserversforannounce`	Returns a list of active or powered off (power_off) user servers that have passed the IPv4 subnet mask limit check (/23 and /24).
`groups`	Returns a list of groups for the specified server.
`hard_off`	Performs a forced (hard) shutdown of the hardware by the specified ID. Requires permission check and resource locking if the request comes from a client.
`history`	Returns the server event history.
`list`	Returns a list of hardware based on various search criteria.
`off`	Turns off the server.
`on`	Turns on the server.
`order_instance`	Starts the process of ordering a new server from a preset or initiates a reinstallation (reinstall) of an existing server with selection of OS, software, and network parameters.
`ovirt_novnc`	Requests access to the oVirt noVNC console for the specified server.
`reboot`	Sends a request to reboot the hardware by the specified ID. If the server is in standby mode, permission verification may be required.
`reinstall`	Initiates the process of creating a key for server reinstallation and queues the task (stage: create_pxe).
`remove_ipmi_user`	Deletes an additional IPMI user for the specified server.
`request_backup_link`	Requests a temporary link to download a server backup. Returns a callback key to track task execution.
`restore_backup`	Starts the process of restoring a server from an existing backup. The operation is asynchronous.
`search`	Returns a list of available hardware (servers, VPS) based on specified filters: group, location, status, type, etc.
`sensors`	Returns server sensor data.
`set_pin`	Sets a PIN code for operations.
`show`	Returns detailed data about the server, including hardware configuration, IP addresses, interfaces, IPMI, and tags.
`status`	Returns the current hardware status, including hardware data, IP addresses, and interfaces.
`status_check`	Returns the current hardware health check status.
`suspend`	Requests suspension (suspend) or unsuspension (unsuspend) of a VPS/server.
`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 the server management module (IPMI). If the request requires confirmation, a callback is returned.
`unsuspend`	Request to remove the suspension (unsuspend) from a server. If the request is successful, the server will be unsuspended.
`update_servers`	Updates the list of available servers linked to the client account in WHMCS, including active, suspended, and services awaiting payment.

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

Method	Description
`cancel_payment_account_deletion`	Cancels a previously requested deletion of 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, registers the user, creates a bucket, and processes payment.
`delete_account`	Completely deletes the user's S3 account, including action audit and history logging. Requires specifying the client ID (for admins) or uses the current user, 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 S3 account 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 account buckets, information on storage usage, quota, traffic metrics, and access keys. Uses a message queue (RMQ) to retrieve 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 actions for the specified S3 plan or entity by ID.
`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¶

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