ip.php¶

IP address and network infrastructure management module: get IP information, manage PTR records, track traffic, work with subnets and VLANs.

API Methods¶

Method	Action	Description
`get_client_ip`	get client IP	Returns the current IP address of the client making the request to the API
`get_ip`	get IP information	Returns full network configuration information for a specific IP address (mask, network, etc.)
`get_ptr`	get PTR record	Checks if the IP address belongs to the server and returns the current PTR record for this IP in the specified location.
`get_traffic`	get traffic	Returns inbound and outbound traffic data for a specified IP address for a selected period. Can return both summary information and detailed timestamps.
`list_free_ip`	get list of free IPs	Returns a list of unused IP addresses for a specific location based on Route Reflector tags. For clients, it is only available within their own subnets.
`set_main`	set main IP for server	Sets the specified IP address as the primary (main) for the server's network interface.
`update_ptr`	update PTR record for IP	Updates the reverse DNS record (PTR) for a specified IP address, provided that this IP is assigned to a server with the given ID.

ip/get_client_ip¶

Returns the current IP address of the client making the request to the API

HTTP-method: GET

Parameters:

Parameter	Required	Type	Description
action	✅	string	Action name: `get_client_ip`
token	✅	string	Authorization token

Example Request

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

Example of a successful response

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

Failure response

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

```

ip/get_ip¶

Returns full network configuration information for a specific IP address (mask, network, etc.)

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `get_ip`
token	✅	string	Authorization token
ip	✅	string	IP address to get information for

Example Request

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

Example of a successful response

{
"result": "OK",
"module": "ip",
"action": "get_ip",
"data": {
"network": "192.168.0.0",
"netmask": "255.255.255.0",
"gateway": "192.168.0.1",
"broadcast": "192.168.0.255"
}
}

Failure response

``` { "code": -1, "message": "malformed IP=127.0.0.1 for token 12345" }

```

ip/get_ptr¶

Checks if the IP address belongs to the server and returns the current PTR record for this IP in the specified location.

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `get_ptr`
token	✅	string	Authorization token
id	✅	int	Server ID (must be > 0)
ip	✅	string	IP address to check PTR record
location	❌	string	Location (used in 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": "example.domain.com"
}

Failure response

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

```

ip/get_traffic¶

Returns inbound and outbound traffic data for a specified IP address for a selected period. Can return both summary information and detailed timestamps.

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
token	✅	string	Authentication token
ip	✅	string	IP to report
period_start	❌	int	Start timestamp (default: current time - 86400)
period_stop	❌	int	End timestamp (default: current time)
summary	❌	int	1 - return only summary {ip, in, out} in GB, 0 - all ticks with stamps
unbilled	❌	int	1 - return only unbilled ticks, 0 - all ticks

Example Request

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

Example of a successful response

{
"result": "OK",
"traffic": [
{
"timestamp": "2024-05-20T12:00:00Z",
"in": 1.25,
"out": 0.85
}
]
}

Failure response

``` { "code": -1, "message": "no significant traffic detected for [ip] in the period [date] - [date]" }

```

ip/list_free_ip¶

Returns a list of unused IP addresses for a specific location based on Route Reflector tags. For clients, it is only available within their own subnets.

HTTP-method: POST|GET

Parameters:

Parameter	Required	Type	Description
action	✅	string	Action name (list_free_ip)
token	✅	string	Authorization token
exclude_special	❌	int	Exclude special addresses (0 or 1)
location	✅	string	Location to search for free IPs

Example Request

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

Example of a successful response

{
"result": "OK",
"ip": [
"192.168.1.1",
"10.0.0.5"
]
}

Failure response

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

```

ip/set_main¶

Sets the specified IP address as the primary (main) for the server's network interface.

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `set_main`
token	✅	string	Authorization token
id	✅	int	Server ID
ip	✅	string	IP address
main	❌	int	Main IP flag (0 or 1)
description	❌	string	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": "data"
}

Failure response

``` { "code": -1, "message": "invalid IP $ip for server $id" }

```

ip/update_ptr¶

Updates the reverse DNS record (PTR) for a specified IP address, provided that this IP is assigned to a server with the given ID.

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
token	✅	string	Authorization token
id	✅	int	Server ID
ip	✅	string	IP address
ptr	✅	string	PTR record value
location	❌	string	Location

Example Request

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

Example of a successful response

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

Failure response

{
"code": -1,
"message": "IP 1.2.3.4 is not assigned for server id 5"
}