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.

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 verification, as well as client tag manageme

Method	Description
`2fa_check`	Verifies the two-factor authentication code passed in the user_token parameter.
`2fa_resend`	Requests a resend of the 2FA code to the bound method.
`billing_list`	Returns a list of available billing systems (WHMCS) for the current domain or user.
`email_check`	Initializes or verifies the user's email address verification.
`flip_tag`	Sets or removes a tag for a client (e.g., auto_credit).
`get_log`	Returns the authorization event log for a specified period or by token.
`get_log_details`	Returns detailed information about a specific log event by token.
`github_init`	Returns data to initialize the OAuth flow with GitHub.
`github_signin`	Processes the OAuth code from GitHub for login or account linking.
`google_signin`	Processes the JWT token from Google for login or account linking.
`info`	Returns information about the current session, access rights, servers, and billing.
`login`	Authorizes a client or server by API key.
`logout`	Clears the current session token.
`session_reset`	Resets all active user sessions by email and reset token.
`set_tag`	Sets or removes a tag for a client with the ability to specify a value.
`tg_verify`	Binds a Telegram username to the user account.
`vk_init`	Returns data to initialize the OAuth flow with VK ID.
`vk_signin`	Processes the OAuth code from VK for login or account linking.
`whmcslogin`	Main login method via WHMCS credentials (email/password) or SSO.

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 reinstallation 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`	Boots the server from the specified media (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 reinstallation.
`delete_backup`	Deletes a server backup.
`deploy`	Deploys a server by ID or preset name.
`get_ipmi`	Returns the IPMI address and model of the server.
`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 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`	Creates an order for a new server or reinstalls an existing one. Supports selection of preset, OS, traffic, software, and promo codes. Returns a task key for status tracking.
`reboot`	Reboots the server.
`reinstall`	Starts the server reinstallation 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 an IPMI server reset.
`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, tracking traffic, and working with subnets and VLANs.

Method	Description
`get_client_ip`	Returns the current client's IP address
`get_ip`	Returns full information about a specific IP address (network, mask, etc.)
`get_ptr`	Checks and returns the PTR record for the specified IP
`get_traffic`	Returns incoming and outgoing traffic statistics for an IP over a specified period
`list_free_ip`	Returns a list of available IP addresses for a specified location or subnet
`set_main`	Sets the specified IP as the primary IP for the server interface
`update_ptr`	Updates the PTR record (reverse DNS) for the specified IP

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 states, retrieving statistics, and displaying Cacti graphs.

Method	Description
`add_ipv4`	Adds a specified number of IPv4 addresses to a server on a specific port and VLAN. Supports selecting specific addresses or automatic selection of free ones.
`block_ip`	Blocks a specified IP address on the server via BIRD or blackhole. Accepts a block reason and a blackhole flag.
`get_status`	Returns the current status of the network interface (port) for the specified server. Automatically determines the port if not explicitly specified.
`port_off`	Disables the specified network port of the server. If the reason parameter is passed, a block tag with the specified reason is added.
`port_on`	Enables the specified network port of the server, removing the block (tag 'block') if it was applied by the user.
`remove_ipv4`	Removes one or all IPv4 addresses from the specified server. Clears PTR records in DNS.
`show_cacti`	Returns Cacti monitoring graph data for the specified server and port.
`show_ipv4_free`	Returns a list of available free IPv4 addresses for the specified server, port, and VLAN. Supports filtering by tags and freshness period.
`unblock_ip`	Unblocks a specified IP address on the server, removing block rules in BIRD and clearing block tags.

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 the scheduled deletion of a paid S3 account, restoring its status and expiration date.
`create_account`	Creates a new S3 account for a client, links a billing plan, creates a bucket, and places an order in billing.
`create_bucket`	Creates a new bucket with the specified name for an existing client S3 account.
`create_order`	Creates a new order for an S3 account based on the specified billing plan, validates the bucket name, checks limits and credits, and creates a user and service in billing.
`delete_account`	Completely deletes a user's S3 account, including all associated buckets and data.
`delete_bucket`	Deletes the specified bucket from the client's S3 account after checking access rights and ownership.
`delete_file`	Deletes the specified file from the user's S3 bucket.
`delete_payment_account`	Initiates the process of canceling a paid S3 account, setting the cancellation date in the billing system.
`get_buckets`	Returns a list of S3 buckets for the specified user, including information on storage usage, bandwidth, snapshots, and access keys.
`get_buckets_rmq`	Returns a list of S3 buckets for the specified user, including information on storage usage, bandwidth, snapshots, and access 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 accounts with information about the service, traffic, and storage usage. Supports filtering and pagination for administrators.
`history`	Returns the change history for the specified S3 plan or account by ID.
`list_plans`	Returns a list of available S3 billing plans. Hides inactive plans for clients (if no s3_test tag), for administrators it can return a specific plan by ID.
`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.