The XorMon Public API fully supports retrieving tags and their associations with devices.

Tags in XorMon can be organized in two ways:

1. A tag on its own (e.g. "production", "critical")
2. A tag under a category (e.g. category "environment" -> tag "production")

Categories are optional. A device can be assigned to a tag regardless of whether that tag belongs to a category or not.

How to retrieve tags via the Public API:

You are already using GET /api/public/v1/hostcfg to get your devices.
The hostcfg_id returned for each device is the same as the item_id used in the Tags API.
Here is the step-by-step workflow:

1. Get your devices (you already do this):

   GET /api/public/v1/hostcfg
   apiKey: {your-api-key}
   

   Each device in the response has a hostcfg_id which equals the item_id.
   
   
2. Get all tag categories (optional grouping keys):

   GET /api/public/v1/tags/categories
   apiKey: {your-api-key}
   
   Returns:
   {
     "statusCode": 200,
     "data": [
       { "category_id": "cat-uuid-1", "label": "location" },
       { "category_id": "cat-uuid-2", "label": "environment" }
     ]
   }
   

3. Get all tags:

   GET /api/public/v1/tags
   apiKey: {your-api-key}
   

   Returns all tags. Some may belong to a category, others may be standalone.
   
   
4. Get which devices are assigned to each tag:

   GET /api/public/v1/tags/{tag_id}/items
   apiKey: {your-api-key}
   

   Returns the list of items (item_id = hostcfg_id), or just filter out for subsystem device) assigned to that tag.
   
   

Alternative — Search items by tag label, optionally filtered by category:

• By tag only (tags with or without a category):

  GET /api/public/v1/tags/search-items?tag=production
  apiKey: {your-api-key}
  

• By tag within a specific category:

  GET /api/public/v1/tags/search-items?tag=production&category=environment
  apiKey: {your-api-key}
  

Creating tags:

If you have not yet created tags and categories, you can do so both via the XorMon
GUI or via the API:

• Create a category (optional):

    POST /api/public/v1/tags/categories
    { "category_label": "environment" }
  

• Create a tag (with or without a category):

    POST /api/public/v1/tags
    { "label": "production", "category_label": "environment" }
  
    POST /api/public/v1/tags
    { "label": "critical" }
  

• Assign devices to a tag:

    POST /api/public/v1/tags/{tag_id}/items
    { "item_ids": ["hostcfg-id-1", "hostcfg-id-2"] }
  

SUMMARY OF ENDPOINTS

  GET  /api/public/v1/hostcfg                           -> list devices
  GET  /api/public/v1/tags                              -> list all tags
  GET  /api/public/v1/tags/categories                   -> list all categories
  GET  /api/public/v1/tags/{tag_id}/items               -> items assigned to a tag
  GET  /api/public/v1/tags/search-items?tag=            -> search by tag label
  GET  /api/public/v1/tags/search-items?tag=&category=  -> search by tag + category
  POST /api/public/v1/tags                              -> create a tag
  POST /api/public/v1/tags/categories                   -> create a category
  POST /api/public/v1/tags/{tag_id}/items               -> assign items to a tag

All endpoints require the apiKey header.
An API key can be generated via 'POST /api/public/v1/auth' with your username and password.