monday.com tags are objects that help you group items from different groups or different boards throughout your account by a consistent keyword. Tag entities are created and presented through the Tags column.

As a developer working with monday.com, it is important to familiarize yourself with the tags API so you know how to access tag data. This document will walk you through the available queries and mutations to read and modify the tags object via the API.

Queries

Required scope: tags:read

Querying tags will return metadata about one or a collection of the account's public tags. Public tags appear on main boards and are accessible to all member and viewer-level users by default, while private tags only appear on private or shareable boards. This method accepts one argument and returns an array.

You can query tags directly at the root to return public tags. If you do so and use the ids argument of a private tag, you will get an empty result.

query {
  tags (ids: [1, 2, 4, 10]) {
    name
  }
}
let query = "query { tags (ids: 1, 2, 4, 10) { name } }";

fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YOUR_API_KEY_HERE'
   },
   body: JSON.stringify({
     query : query
   })
  })
   .then(res => res.json())
   .then(res => console.log(JSON.stringify(res, null, 2)));

To return tags stored on private or shareable boards, you can nest tags within aboards query.

query {
  boards (ids: 1234567890) {
    tags {
      id
    }	
  }
}
let query = "query { boards (ids: 1234567890) { tags { ids } } }";

fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YOUR_API_KEY_HERE'
   },
   body: JSON.stringify({
     query : query
   })
  })
   .then(res => res.json())
   .then(res => console.log(JSON.stringify(res, null, 2)));

πŸ‘

Pro tip

Before assigning a tag to an item, use the tags query to ensure it exists.

Arguments

You can use the following argument(s) to reduce the number of results returned in your tags query.

ArgumentDescription
ids [Int]The unique identifiers of the specific tags to return.

Fields

You can use the following field(s) to specify what information your tags query will return.

FieldDescription
color String!The tag's color.
id Int!The tag's unique identifier.
name String!The tag's name.

Mutations

Required scope: boards:write

Create or get a tag

The create_or_get_tag mutation allows you to create new tags or receive their data if they already exist via the API. You can also specify what fields to query back from the tag when you run the mutation.

Check out this mutation in action in our Postman library or follow along with these code samples!

mutation {
  create_or_get_tag (tag_name: "amazing") {
    id
  }
}
let query = "mutation { create_or_get_tag (tag_name: \"amazing\") { id } }";

fetch ("https://api.monday.com/v2", {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
    'Authorization' : 'YOUR_API_KEY_HERE'
   },
   body: JSON.stringify({
     query : query
   })
  })
   .then(res => res.json())
   .then(res => console.log(JSON.stringify(res, null, 2)));

Arguments

You can use the following argument(s) to define the new or existing tag's characteristics.

ArgumentDescription
board_id IDThe unique identifier of the shareable or private board where the tag should be created. This argument is not required for main boards.
tag_name StringThe new tag's name.

Update a tags column

The change_column_value mutation allows you to change a column value via the API. Check out the tags column type reference for the correct formatting!

πŸ“˜

Join our developer community!

We've created a community specifically for our devs where you can search through previous topics to find solutions, ask new questions, hear about new features and updates, and learn tips and tricks from other devs. Come join in on the fun! 😎