tags.php¶

Tag management module for infrastructure components: adding, removing, clearing, searching, and displaying tag lists for servers and variables.

API Methods¶

Method	Action	Description
`add`	add tag	Adds a custom tag to a server or component. Supports bulk addition via an ID list.
`clear`	clear tags	Clears all or non-essential tags from a component. For clients, only public tags are available.
`get`	get tags	Retrieves tags for a component. (Implementation is empty in code, method is in whitelist)
`list`	list tags	Returns a list of tags for a specific server or component. For clients, there is a restriction by component type (eq, vars).
`remove`	remove tag	Removes a tag by its name for a specific component or removes all specified tags from an ID list. If `id_list` is passed, the operation is performed in bulk.
`search`	search tags	Searches for components matching a specific tag and value.
`search_user`	search user equipment	Searches for user equipment by tag value. Used in global search form.
`show`	show possible tags	Shows possible tags for a component. (Implementation is empty in code, method is in whitelist)

tags/add¶

Adds a custom tag to a server or component. Supports bulk addition via an ID list.

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `add`
token	✅	string	Authorization token
id	❌	int	Server/component ID
tag	✅	string	Tag name (max. 32 characters, alphanumeric)
value	❌	string	Tag value
extra	❌	string	Additional information
id_list	❌	string	Comma-separated list of IDs for bulk addition

Example Request

curl -s "https://invapi.hostkey.com/tags.php" -X POST \
--data "action=add" \
--data "token=HOSTKEY_TOKEN" \
--data "id=123" \
--data "tag=my_tag" \
--data "value=my_value"

Example of a successful response

{
"result": "OK",
"action": "add",
"id": 123,
"component": "eq",
"component_id": 45,
"tag": "hostname",
"value": "my-server-01",
"extra": "additional info",
"internal": 0
}

Failure response

```json { "code": -1, "message": "tag/add: invalid token data, too long" }

```

tags/clear¶

Clears all or non-essential tags from a component. For clients, only public tags are available.

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `clear`
token	✅	string	Authorization token
id	✅	int	Server (component) ID
component	❌	string	Component type (default 'eq')
tag	❌	string	Clearing filter. If 'all', all tags are cleared, including excluded ones

Example Request

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

Example of a successful response

{
"result": "OK",
"action": "clear",
"id": 101,
"component": "eq",
"tags": [
{
"id": 501,
"tag": "preset",
"value": "standard"
}
]
}

Failure response

{
"code": -1,
"message": "tag/clear: invalid server status, can't clean tags from the rented server"
}

tags/get¶

Retrieves tags for a component. (Implementation is empty in code, method is in whitelist)

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `get`
token	✅	string	Authorization token
component	❌	string	Component type (eq, vars, etc.)
component_id	❌	int	Component ID
internal	❌	int	Internal tags visibility flag (0 or 1)

Example Request

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

Example of a successful response

{
"result": "OK",
"action": "get",
"data": []
}

Failure response

{
"code": -1,
"message": "Method not implemented"
}

tags/list¶

Returns a list of tags for a specific server or component. For clients, there is a restriction by component type (eq, vars).

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `list`
token	✅	string	Authorization token
id	❌	int	Server or component ID
component	❌	string	Component type (eq, vars)

Example Request

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

Example of a successful response

{
"result": "OK",
"action": "list",
"tags": [
{
"tag": "example_tag",
"value": "example_value",
"extra": "example_extra"
}
]
}

Failure response

```json { "code": -1, "message": "invalid server id" }

```

tags/remove¶

Removes a tag by its name for a specific component or removes all specified tags from an ID list. If id_list is passed, the operation is performed in bulk.

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Action (remove)
token	✅	string	Authorization token

Example Request

curl -s "https://invapi.hostkey.com/tags.php" -X POST \
--data "action=remove" \
--data "token=HOSTKEY_TOKEN" \
--data "tag=example_tag" \
--data "component=eq" \
--data "component_id=789"

Example of a successful response

{
"result": "OK",
"action": "remove",
"id": 12345,
"tag": "example_tag",
"component": "eq",
"component_id": 789
}

Failure response

```json { "code": -1, "message": "module/remove: tag example_tag not found for element 789 on eq" }

```

tags/search¶

Searches for components matching a specific tag and value.

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `search`
token	✅	string	Authorization token
tag	❌	string	Tag name for search
value	❌	string	Tag value for search (supports LIKE)
component	❌	string	Component type (default eq)
internal	❌	int	Internal tags visibility flag (0 or 1)

Example Request

curl -s "https://invapi.hostkey.com/tags.php" -X POST \
--data "action=search" \
--data "token=HOSTKEY_TOKEN" \
--data "tag=location" \
--data "value=NL"

Example of a successful response

{
"result": "OK",
"action": "search",
"tags": [
{
"id": 1001,
"component": "eq",
"component_id": 101,
"tag": "location",
"value": "NL",
"extra": "",
"internal": 0
}
]
}

Failure response

{
"code": -1,
"message": "tag/search: invalid token $token, logout"
}

tags/search_user¶

Searches for user equipment by tag value. Used in global search form.

HTTP-method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `search_user`
token	✅	string	Authorization token
value	✅	string	Tag value for searching user equipment

Example Request

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

Example of a successful response

{
"result": "OK",
"action": "search_user",
"servers": [
{
"id": 101,
"hostname": "server-01",
"ip": "192.168.1.1"
}
]
}

Failure response

{
"code": -1,
"message": "tag/search_user: Nothing found for value"
}

tags/show¶

Shows possible tags for a component. (Implementation is empty in code, method is in whitelist)

HTTP-method: POST

Parameters:

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

Example Request

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

Example of a successful response

{
"result": "OK",
"action": "show",
"data": []
}

Failure response

```json { "code": -1, "message": "Method not implemented" }