Butlr Developer Docs
  • Welcome
  • What is Butlr
  • Spatial Metrics
  • Getting Started
    • Authentication
    • Making your first query
    • Mint Client Credentials
  • Changelog
  • Asset Management
    • GraphQL API Overview
      • Sites
      • Buildings
      • Floors
      • Rooms
      • Zones
      • Hives
      • Sensors
      • Asset Tags
    • GraphQL API Introsepction
  • Historical Occupancy
    • Reporting API Overview
      • Floor Occupancy
      • Room Occupancy
      • Zone Occupancy
      • Query Occupancy by Tag
      • Traffic
      • Presence Time
      • Statistic Overview
    • FAQs
  • Real-time occupancy
    • Webhooks Overview
      • Area Detections
      • Entryway Traffic
      • Floor Occupancy
      • Room Occupancy
      • Zone Occupancy
      • Motion Detection
      • No Motion Detection
    • Manage Webhooks
      • Create Webhooks
      • Update Webhooks
      • Delete Webhooks
      • List Webhooks
  • LINKS
    • Butlr Postman Collection
    • Butlr Website
    • Status
    • Support
    • Log In
Powered by GitBook
On this page
  • Use Cases for Tags
  • Creating a Tag
  • Associating a Tag
  • Querying by Tag
  • Accessing Tag Details
  • Query for Tags
  1. Asset Management
  2. GraphQL API Overview

Asset Tags

PreviousSensorsNextReporting API Overview

Last updated 4 months ago

Tags are a powerful way to manage and search for , , and . The GraphQL API allows you to assign, manage, and query tags, efficiently categorizing spaces and retrieving relevant data.

Use Cases for Tags

  • Organizing Spaces: Categorize rooms, floors, and zones (e.g., meeting room, bathroom, kitchen) for better management.

  • Simplifying Search: Quickly locate assets by filtering tags like conference room or workstation.

  • Aggregating Data: Group assets with shared tags (e.g., windows, dual-monitor) for detailed analysis.

Creating a Tag

To create a new tag, use the createTag mutation. Tags are associated by their unique ID, allowing you to update tag names without affecting associations.

mutation CreateTag($input: CreateTagInput!) {
  createTag(input: $input) {
    name
    id
  }
}

input CreateTagInput {
  name: String!
}

Associating a Tag

After creating a tag, associate it with Zones, Rooms, or Floors using their IDs. Use the associateTag mutation to define these relationships.

mutation AssociateTag($input: AssociateTagInput!) {
  associateTag(input: $input) {
    tag {
      name
      id
    }
    zones {
      name
    }
    rooms {
      name
    }
    floors {
      name
    }
  }
}


input AssociateTagInput {
  # The list of ids to associate the tag with (any combination of floors/rooms/zones)
  ids: [String!]
  # The tag id
  tag_id: String!
}

The ids field is an array of Rooms, Zones and Floors that you want to tag, for example:

"ids": [
  "space_lvgwckxar9ddupm40768mkfq",
  "room_2mALGwh4NLWDyaY7ORteOICBNYK"
]

You can also disassociate a tag:

mutation DisassociateTag($input: DisassociateTagInput!) {
  disassociateTag(input: $input) {
    tag {
      name
      id
    }
    zones {
      name
    }
    rooms {
      name
    }
    floors {
      name
    }
  }
}


input DisassociateTagInput {
  # The list of ids to disassociate the tag with (any combination of floors/rooms/zones)
  ids: [String!]
  # The tag id
  tag_id: String!
}

Querying by Tag

Once tags are assigned, you can query for objects associated with specific tags, such as Floor, Rooms, or Zones.

query ItemsFromTags($tagIds: [String!]!) {
  tags(ids: $tagIds) {
      id
      name
      floors {
        # full floor object – can pull any field normally on a floor
        id
        name
      }
      rooms {
        # full room object
        id
        name
      }
      zones {
        # full zone object
        id
        name
      }
    }
}

Or you can get information about associated Tags from a Floor, Room, or Zone object:

query ItemsFromTags($tagIds: [String!]!) {
  floors {
    data {
      id
      name
      tags {
        id
        name
      }
    }
  }
}

Accessing Tag Details

Tags are accessible as objects containing a name and an id. From a tag object, you can retrieve the associated Zones, Rooms, and Floors.

Query for Tags

Retrieve all tags in your organization:

query Tags() {
  tags {
    id
    name
  }
}

Tag History Not Supported: Our system currently does not retain a history of tag changes. For example, if Zones 1–5 are tagged as "Marketing" in September and updated to "Finance" in December, the original tag ("Marketing") will no longer be available for queries. Only the current tag assignment ("Finance") can be queried. Historical comparisons or analyses based on previous tags must be managed outside the system. We plan to extend tagging to additional assets (e.g., site, building, sensor, hive) in the near future to enhance its capabilities further.

floors
rooms
zones