ip.php¶

IP address and network infrastructure management module: retrieving IP information, managing PTR records, traffic monitoring, working with subnets and VLANs.

API Methods¶

Method	Action	Description
`get_client_ip`	get client ip	Retrieves the client's IP address from the request context.
`get_ip`	get ip info	Returns full network information regarding a specific IP address including netmask and other network details.
`get_ptr`	get ptr	Retrieves the PTR record for a specific IP address belonging to a given server ID.
`get_traffic`	get traffic	Returns network traffic statistics (in/out) for a specific IP address within a given time period.
`list_free_ip`	get list of free IPs	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`	set main ip address	Sets a specific IP as the primary (main) address for a given server interface and updates billing data if necessary.
`update_ptr`	update ptr record	Updates the PTR (Reverse DNS) record for a specific IP address assigned to a server.

ip/get_client_ip¶

Retrieves the client's IP address from the request context.

HTTP Method: POST

Parameters:

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

Example Request

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

Example of a successful response

{
"result": "OK",
"action": "get_client_ip",
"data": {
"ip": "192.168.1.1"
}
}

Failure response

{
"code": -1,
"message": "Error retrieving client IP"
}

ip/get_ip¶

Returns full network information regarding a specific IP address including netmask and other network details.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `get_ip`
ip	✅	string	The IP address to retrieve information for.
full	❌	boolean	Whether to return full network details wrapped in a data object.

Example Request

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

Example of a successful response

{
"result": "OK",
"action": "get_ip",
"data": {
"network": "192.168.1.0",
"netmask": "255.255.255.0",
"gateway": "192.168.1.1",
"broadcast": "192.168.1.255"
}
}

Failure response

{
"code": -1,
"message": "unknown IP 1.2.3.4"
}

ip/get_ptr¶

Retrieves the PTR record for a specific IP address belonging to a given server ID.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `get_ptr`
id	✅	int	The server ID.
ip	✅	string	The IP address to retrieve the PTR record for.
location	❌	mixed	Location identifier.

Example Request

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

Example of a successful response

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

Failure response

{
"code": -1,
"message": "invalid request"
}

ip/get_traffic¶

Returns network traffic statistics (in/out) for a specific IP address within a given time period.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
ip	✅	string	IP to report
period_start	✅	int	Start timestamp
period_stop	✅	int	End timestamp
summary	❌	int	1/0 return only summary {ip, in, out} in GB, otherwise return all ticks with stamps for graphics
unbilled	❌	int	1 return only unbilled ticks, 0 - all ticks

Example Request

curl -s "https://invapi.hostkey.com/ip.php" -X POST \
--data "action=get_traffic" \
--data "ip=1.2.3.4" \
--data "period_start=1704096000" \
--data "period_stop=1704600000"

Example of a successful response

{
"result": "OK",
"traffic": [
{
"ip": "1.2.3.4",
"in": 0.5,
"out": 1.2,
"timestamp": "2024-01-01T12:00:00Z"
}
]
}

Failure response

{
"code": -1,
"message": "module/get_traffic: no significant traffic detected for 1.2.3.4 in the period 01-01-2024 - 05-01-2024",
"error": "module/get_traffic: no significant traffic detected for 1.2.3.4 in the period 01-01-2024 - 05-01-2024"
}

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

HTTP Method: POST|GET

Parameters:

Parameter	Required	Type	Description
id	✅	integer	Subnet ID or location ID
exclude_special	❌	string	Whether to exclude special IP addresses

Example Request

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

Example of a successful response

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

Failure response

{
"code": -1,
"message": "general failure"
}

ip/set_main¶

Sets a specific IP as the primary (main) address for a given server interface and updates billing data if necessary.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `set_main`
id	✅	int	Server ID
ip	✅	string	IP address to set as main
main	❌	int	Main flag/status
description	❌	string	Description for the IP

Example Request

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

Example of a successful response

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

Failure response

{
"code": -1,
"message": "invalid request or invalid IP for server ID"
}

ip/update_ptr¶

Updates the PTR (Reverse DNS) record for a specific IP address assigned to a server.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
id	✅	int	The ID of the resource
ip	✅	string	The IP address
ptr	✅	string	The PTR record (FQDN)
location	❌	int\|string	Location identifier

Example Request

curl -s "https://invapi.hostkey.com/ip.php" -X POST \
--data "action=update_ptr" \
--data "id=123" \
--data "ip=192.168.1.1" \
--data "ptr=host.example.com." \
--data "location=1"

Example of a successful response

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

Failure response

{
"code": -1,
"message": "Error message from pdns service"
}