ip.php¶

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

API Methods¶

Method	Action	Description
`get_client_ip`	get client IP	Returns the IP address of the current client making the request.
`get_ip`	get IP information	Returns full information about a specific IP address, including network data, mask, and ownership.
`get_ptr`	get PTR record	Returns the PTR record (reverse DNS name) for the specified IP address bound to a server.
`get_traffic`	get traffic statistics	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`	get list of free IPs	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`	set main IP	Sets the specified IP address as the primary IP for the server interface. Updates billing data in WHMCS if applicable.
`update_ptr`	update PTR record	Sets the reverse DNS record (PTR) for the specified IP address bound to a server.

ip/get_client_ip¶

Returns the IP address of the current client making the request.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `get_client_ip`
token	✅	string	Authorization token

Example Request

curl -s "https://invapi.hostkey.com/ip.php" -X POST \
--data "action=get_client_ip" \
--data "token=HOSTKEY_TOKEN"

Example of a successful response

{
"result": "OK",
"data": {
"ip": "192.168.1.100"
}
}

Failure response

{
"code": -1,
"message": "authentication required"
}

ip/get_ip¶

Returns full information about a specific IP address, including network data, mask, and ownership.

HTTP Method: POST|GET

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `get_ip`
token	✅	string	Authorization token
ip	✅	string	IP address to retrieve information for
full	❌	boolean	Flag to retrieve full data (wrapped in data)

Example Request

curl -s "https://invapi.hostkey.com/ip.php" -X POST \
--data "action=get_ip" \
--data "token=HOSTKEY_TOKEN" \
--data "ip=VALUE"

Example of a successful response

{
"result": "OK",
"module": "ip",
"action": "get_ip",
"ip": "192.168.1.1",
"network": "192.168.1.0",
"netmask": "255.255.255.0",
"location": "NL",
"vlan_id": 100,
"server_id": 12345,
"status": "active"
}

Failure response

``` { "code": -1, "message": "ip/get_ip: malformed IP=192.168.1.1 for token abc123" }

```

ip/get_ptr¶

Returns the PTR record (reverse DNS name) for the specified IP address bound to a server.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `get_ptr`
token	✅	string	Authorization token
id	✅	integer	Server ID to which the IP belongs
ip	✅	string	IP address for which to retrieve the PTR record
location	❌	string	Location (optional, used internally by pdns_get_ptr)

Example Request

curl -s "https://invapi.hostkey.com/ip.php" -X POST \
--data "action=get_ptr" \
--data "token=HOSTKEY_TOKEN" \
--data "id=VALUE" \
--data "ip=VALUE"

Example of a successful response

{
"result": "OK",
"message": "server.example.com"
}

Failure response

{
"code": -1,
"message": "ip/get_ptr: invalid request"
}

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

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `get_traffic`
token	✅	string	Authorization token
ip	❌	string	IP address to retrieve traffic statistics for
period_start	❌	integer	Start of the period in Unix timestamp (default: 24 hours ago)
period_stop	❌	integer	End of the period in Unix timestamp (default: current time)
summary	❌	integer	Summary mode: 1 - only total values, 0 - detailed breakdown by timestamps
unbilled	❌	integer	Payment filter: 1 - only unpaid records, 0 - all records

Example Request

curl -s "https://invapi.hostkey.com/ip.php" -X POST \
--data "action=get_traffic" \
--data "token=HOSTKEY_TOKEN" \
--data "ip=192.168.1.10"

Example of a successful response

{
"result": "OK",
"traffic": [
{
"ip": "192.168.1.10",
"timestamp": 1715625600,
"in": 1024.5,
"out": 2048.2
}
]
}

Failure response

``` { "code": -1, "message": "ip/get_traffic: no significant traffic detected for 192.168.1.10 in the period 01-05-2024 - 02-05-2024" }

```

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

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `list_free_ip`
token	✅	string	Authorization token
exclude_special	❌	int	Exclude special IPs (0/1)
id	❌	int	Subnet ID (for clients)
location	❌	string	Location code (for administrators)

Example Request

curl -s "https://invapi.hostkey.com/ip.php" -X POST \
--data "action=list_free_ip" \
--data "token=HOSTKEY_TOKEN"

Example of a successful response

{
"result": "OK",
"action": "list_free_ip",
"ip": [
"192.168.1.10",
"192.168.1.11"
]
}

Failure response

``` { "code": -1, "message": "illegal IP subnet" }

```

ip/set_main¶

Sets the specified IP address as the primary IP for the server interface. Updates billing data in WHMCS if applicable.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `set_main`
token	✅	string	User authorization token
id	✅	integer	Server ID
ip	✅	string	IP address to set as primary
main	❌	integer	Primary IP flag (0 or 1)
description	❌	string	IP address description

Example Request

curl -s "https://invapi.hostkey.com/ip.php" -X POST \
--data "action=set_main" \
--data "token=HOSTKEY_TOKEN" \
--data "id=VALUE" \
--data "ip=VALUE"

Example of a successful response

{
"result": "OK",
"message": "IP set as main"
}

Failure response

``` { "code": -1, "message": "ip/set_main: invalid request" }

```

ip/update_ptr¶

Sets the reverse DNS record (PTR) for the specified IP address bound to a server.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `update_ptr`
token	✅	string	Authorization token
id	✅	integer	Server ID to which the IP is bound
ip	✅	string	IP address for which to set the PTR
ptr	❌	string	PTR record value (hostname)
location	❌	string	Server location

Example Request

curl -s "https://invapi.hostkey.com/ip.php" -X POST \
--data "action=update_ptr" \
--data "token=HOSTKEY_TOKEN" \
--data "id=VALUE" \
--data "ip=VALUE"

Example of a successful response

{
"result": "OK",
"message": ""
}

Failure response

``` { "code": -1, "message": "IP 192.168.1.1 is not assigned for server 123" }