Tags

API Methods¶

Method	Action	Description
`add`	add tag	Adds a custom tag to a server or component. Supports adding to a list of IDs via id_list.
`list`	get tag list	Returns a list of all tags for the specified server or component.
`remove`	remove tag	Removes a tag by name from the specified server or component. Supports removal by ID list.

tags/add¶

Adds a custom tag to a server or component. Supports adding to a list of IDs via id_list.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `add`
token	✅	string	Authorization token
id	❌	int	Component (server) ID. Used if id_list is not provided
id_list	❌	string	Comma-separated list of component IDs for bulk addition
tag	✅	string	Tag name (alphanumeric characters and hyphens only, max 32 characters)
value	❌	string	Tag value (max 256 characters)
extra	❌	string	Additional tag data (max 16384 characters)
component	❌	string	Component type (default 'eq')
internal	❌	int	Internal tag flag (0 or 1)
no_log	❌	string	Logging disable flag (any value disables logging)

Example Request

curl -s "https://api.hostkey.com/tags.php" -X POST \
--data "action=add" \
--data "token=HOSTKEY_TOKEN" \
--data "id=101" \
--data "tag=hostname" \
--data "value=my_server"

Example of a successful response

{
"result": "OK",
"action": "add",
"id": 12345,
"component": "eq",
"component_id": 101,
"tag": "hostname",
"value": "my_server",
"extra": "",
"internal": 0
}

Failure response

{
"code": -1,
"message": "tag/add: invalid token data, too long",
"description": "Length of tag, value, or extra exceeds limits"
}

tags/list¶

Returns a list of all tags for the specified server or component.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `list`
token	✅	string	Authorization token
id	✅	int	Component (server) ID
component	❌	string	Component type ('eq' or 'vars')
internal	❌	int	Show internal tags (0 or 1)

Example Request

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

Example of a successful response

{
"result": "OK",
"action": "list",
"tags": [
  {
    "id": 1001,
    "component": "eq",
    "component_id": 101,
    "tag": "hostname",
    "value": "server-01",
    "extra": "",
    "internal": 0
  },
  {
    "id": 1002,
    "component": "eq",
    "component_id": 101,
    "tag": "location",
    "value": "NL",
    "extra": "",
    "internal": 0
  }
]
}

Failure response

{
"code": -1,
"message": "tag/list: invalid server id"
}

tags/remove¶

Removes a tag by name from the specified server or component. Supports removal by ID list.

HTTP Method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `remove`
token	✅	string	Authorization token
id	❌	int	Component (server) ID
id_list	❌	string	Comma-separated list of component IDs
tag	✅	string	Tag name to remove
component	❌	string	Component type
internal	❌	int	Internal tag flag

Example Request

curl -s "https://api.hostkey.com/tags.php" -X POST \
--data "action=remove" \
--data "token=HOSTKEY_TOKEN" \
--data "tag=hostname" \
--data "id=101"

Example of a successful response

{
"result": "OK",
"action": "remove",
"id": 1001,
"tag": "hostname",
"component": "eq",
"component_id": 101
}

Failure response

{
"code": -1,
"message": "tag/remove: tag hostname not found for element 101 on eq"
}