API v2

Introduction

Welcome to monday.com, a collaborative work management platform. monday.com can help you and your team plan and keep track of all tasks or projects, communicate with one another more effectively, and increase transparency amongst your team.

monday.com’s mission is to help teams fulfill their potential and collaborate better. The monday.com API is one of the ways to help your team achieve more together!

What is the monday.com API exactly?

The monday.com API supports read and write (mutating) access to boards, items, and more. It gives you the ability to both view and use any data you have in monday.com outside of the platform. You can use the API to import external data into your monday.com account or trigger actions in monday.com in response to a change in an external software or service.

We’re also working on adding an “app market place” into the monday.com platform. This would give you the ability to build and add entire applications into monday.com. These apps would then be available for all monday.com users to integrate into the platform. This option is not yet supported but it is in our roadmap. If you plan on building a full app, that others can also use within monday.com, please contact us at support@monday.com

How does it work?

The monday.com API is based on the GraphQL structure (an alternative to REST based API), which operates on a single URL/endpoint. The monday.com API v2 url is: api.monday.com/v2. As a result, you can use the API to pull and/or alter data about Users, Updates, Items, Boards, Tags and more.

How to get started?

Set up a monday.com account

If you’re not already a monday.com user, the first step is to sign up and create your account.

Authenticate with the API

Once you set up your account, the next step to setting up the API is to authenticate with the Access Tokens. For more information, see the authentication section below.

Using the API

Browse our endpoints and start to query the API. If you’re new to the monday.com API, it’s best to start by learning the basics about Boards, Items, Updates, Users, and Tags.

Using the API can be done by a simple POST request with the query in the request body. We also have code examples in different programming languages in the developers forum of our community.

A simple example of how to access monday.com API using a CURL command:

curl -X POST -H "Content-Type:application/json" -H "Authorization:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -d '{"query":"{boards(limit:1){id name}}"}' "https://api.monday.com/v2/"

Authentication

Before you can start querying the monday.com account with the API, you’ll need to provide valid authentication through an access token. Each user has their own API token, which grants API access to all the boards to which the user has access (i.e they’re subscribed to).

API v2 Token & API Tokens

Currently, monday.com has two active APIs - our “old” (REST-based) and our “new” one (GraphQL). We will gradually deprecate the old version, but for now both of them are available and have different tokens. When using our GraphQL API make sure you’re using the right token which is available under “API v2 Token”.

Accessing your tokens

  • Log into your monday.com account.
  • Click on your avatar (picture icon) in the bottom left corner.
  • Select Admin from the resulting menu (this requires you to have admin permissions).
  • Go to the API section.
  • Generate a “API v2 Token”
  • Copy your token.

*You can always regenerate a new token. Keep in mind it will cause the existing one to expire.

Using tokens

Once you retrieve the token from your monday.com account, you can start making requests with the API. You will need to pass the token to the API in the header of your requests.

Send the API v2 token in the "Authorization" header:

"Authorization:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Rate Limits

The API rate limits are based on complexity level, which is limited to 10,000,000 / minute per account.

Complexity levels are calculated based on the query itself. Each call will have a different level of complexity dependending on the structure of the query. Lower complexity queries are those that query specific objects.

For example, a query for all boards and all users would be calculated by adding together the complexity levels of each of those queries.

For example, a query for all boards and their items returns 1000 boards and 1000 items per board. Complexity would be calculated by multiplying 1000x1000 to get a complexity of 1,000,000.

query {
boards {
items {
id
}
}
}

Rates defaults

Certain queries have default complexities regardless of the results of the query. For example, querying most objects without limits (i.e all boards, items, groups etc.) is calculated as a complexity of 1000. However, there are specific objects, like updates, which have a default complexity of 25.

query {
updates {
id
}
}

What happens when exceeding the limit?

The complexity limit starts at 10,000,000 and decreases with each query. Each minute the complexity limit resets to 10,000,000. If an account has exceeded the limit in a certain minute, the query will return an error 4XX which indicated that the account reached the limit.

Complexity limiting

To work efficiently and avoid reaching the limit, it’s recommended to add limits to each part of the query to extract only the data you need and lower the complexity level.

Following up on the example above, you could limit the boards to certain IDs which will decrease the number of results significantly.

query {
updates (ids: [157244624, 9539475, 3209345]) {
id
items {
id
}
}
}

Complexity nesting

Multiple nesting will also increase the level of complexity in a query. Currently, the maximum number of nested queries allowed is 6.

When calculating complexity of nested queries, the complexity level of each query will be multiplied together. As a result, it is very important to add limits to each query to prevent exceeding the complexity limit.

query {
updates (ids: [157244624, 9539475, 3209345]) {
board_folder_id
permissions
items {
name
creator {
birthday
teams {
name
users {
id
}
}
}
}
}
}

Finding out complexity level

Since accounts are limited by complexity level per minute, understanding the complexity level of each query plays a large role in planning the right queries. The best way to calculate the complexity is to query for complexity as part of your queries.

To see how to query complexity, please see the Querying complexity section.

Using GraphQL

Unlike REST APIs where there is a clearly defined structure of information returned from each endpoint, GraphQL always exposes one endpoint, allowing you to determine the structure of the data that is returned.

The result of each query will be formatted in the same way as the query itself.

In the following section we’re going to have a quick look into to GraphQL components.

Operations

Query - A GraphQL query performs the READ operation and does not change data.

Mutation - To perform all other operations to modify data you will need mutations. You can think of mutations as CUD (Create, Update, Delete) in REST.

Object Types

Object types are a collection of fields, which are used to describe the set of possible data you can query from the API.

query {
}
mutation {
}

Fields

Fields are used to ask for specific properties in objects.

Each object has fields that can be queried by name in order to query for specific properties.

query {
boards {
id
>
}
}

Arguments

You can pass arguments to a query to determine the return value (eg. filtering search results) and narrow down the results to the specific ones you’re after.

In the following example, the object is “boards”, the requested field is “owner”, the argument is “ids”, and the argument value is 201781755.

query {
boards (ids: 157244624){
title
}
}

GraphQL visual interface - GraphiQL

One of the most powerful parts of GraphQL is its visual interface. GraphiQL is an in-browser tool for writing, validating, and testing GraphQL queries.

Before diving in and starting querying the API, it’s highly recommended to run your queries through the visual interface to make sure they are correct and the data being returned is the data you expect. GraphiQL is available in the Try It Yourself tab.

Variables

Variables can be used to pass dynamic values to our arguments. Variables are written outside of the query string itself, in the variables section, and passed to the arguments.

When we start working with variables, we need to do three things:

  • Replace the static value in the query with $variableName
  • Declare $variableName as one of the variables accepted by the query
  • Pass variableName: value in the separate, transport-specific (usually JSON) variables dictionary
mutation change_column_value($value: JSON!) {
change_column_value (board_id: 157244624,item_id: 9539475, column_id: "status", value: $value) {
id
}
}

query variables:
{
"value": "{\"index\": 1}"
}

Querying monday.com entities (object types)

Querying is the way to ask for data, it’s similar to the GET action in REST-based APIs.

In the following sections we’re going to discuss each of the entities you can query and the different data you can extract from each of them. Here is a list of the monday.com entities you can query through the API:

  • Boards
  • Items
  • Items by column values
  • Updates
  • Tags
  • Users
  • Teams

Boards

monday.com boards are where our users input all of their data and as such it is one of the core components of the platform and one of the main objects with which you will need to be familiar.

The board’s structure is composed of rows (called items), groups of rows (called groups), and columns. The data of the board is stored in the items of the board and in the updates sections of each item. Each board has one or more owners and subscribers.

Additionally, there are three different board types (main, shareable, private) and each board can have different sets of permissions.

Querying boards

Querying boards returns one board or a collection of boards. Boards can receive the following arguments:

FieldArguments
boards[Board]
Get a collection of boards.
limitInt
Number of items to get, the default is 25.
pageInt
Page number to get, starting at 1.
ids[Int]
A list of boards unique identifiers.
board_kindBoardKind
public/private/share.
stateState
The state of the board, the default is ACTIVE.
newest_firstBoolean
Get the recently created boards at the top of the list
query {
boards (ids: 157244624) {
permissions
}
}

Board fields

As mentioned above, boards are comprised of different components and when querying a board you can request specific fields to be returned. Each board contains the following fields:

FieldArguments
board_folder_idInt
The board's folder unique identifier.
board_kind!BoardKind
The board's kind (public/private/shareable).
columns[Column]
The board's visible columns.
descriptionString
The board's description.
groups[Group]
The board's visible groups.
ids[String]
A list of group unique identifiers.
id!ID
The unique identifier of the board.
items[Item]
The board's items (rows).
ids[Int]
A list of items unique identifiers.
name!String
The board's name.
owner!User
The owner of the board.
permissions!String
The board's permissions.
posString
The board's position.
state!State
The board's state.
subscribers![User]
The board's subscribers.
tags[Tag]
The board's specific tags.
updates[Update]
The board's updates.
limitInt
Number of items to get, the default is 25.
pageInt
Page number to get, starting at 1.
query {
boards (ids: 157244624) {
name
state
board_folder_id
owner {
id
}
}
}

Columns

Columns and items are two core elements of a board. A board is formatted as a table where there are columns and rows called items. In monday.com each column has a specific functionality it enables (ex. a numbers column, a text column, a time tracking column, etc.)

Column fields

Querying columns returns one or a collection of columns. Columns are available for querying through boards and contain the following fields:

Field
archived!Boolean
Is the column archived or not.
id!ID
The column's unique identifier.
settings_str!String
The column's settings in a string form.
title!String
The column's title.
type!String
The column's type.
widthInt
The column's width.
query {
boards (ids: 157244624) {
owner {
id
}
columns {
title
type
}
}
}

Groups

Items are grouped together in units called groups. Each board contains one or multiple groups, and each group can hold one or many items.

Group fields

Querying groups returns one group or a collection of groups in a specific board. Groups are available for querying through boards and contain the following fields:

FieldArguments
archivedBoolean
Is the group archived or not.
color!String
The group's color.
deletedBoolean
Is the group deleted or not.
id!ID
The group's unique identifier.
items[Item]
The items in the group.
ids[Int]
A list of items unique identifiers.
position!String
The group's position in the board.
title!String
The group's title.
query {
boards (ids: 157244624) {
groups (ids: status) {
title
color
position
}
}
}

Items

monday.com items are another core object in the platform. Items are the objects that hold the actual data within the board, to better illustrate this, you can think of a board as a table and a item as a single row in that table.

Querying items

Querying items returns one or a collection of items. Items can receive the following arguments:

FieldArguments
items[Item]
Get a collection of items.
limitInt
Number of items to get, the default is 25.
pageInt
Page number to get, starting at 1.
ids[Int]
A list of items unique identifiers.
newest_firstBoolean
Get the recently created items at the top of the list
query {
items (ids: [157244624, 201781760, 239164869]) {
name
}
}

Item fields

As mentioned above, items hold the actual data within the board. Each item contains columns in which the different values are stored. Each item contains the following fields:

FieldArguments
boardBoard
The board that contains this item.
column_values[ColumnValue]
The item's column values.
ids[String]
A list of column ids to return
created_atString
The item's create date.
creatorUser
The item's creator.
creator_id!String
The unique identifier of the item creator.
groupGroup
The group that contains this item.
id!ID
The item's unique identifier.
name!String
The item's name.
stateState
The board's state.
subscribers![User]
The pulses's subscribers.
updates[Update]
The item's updates.
limitInt
Number of items to get, the default is 25.
pageInt
Page number to get, starting at 1.
query {
items (limit: 50) {
id
name
board {
id
}
creator {
id
}
}
}

Items By Column Values

monday.com items are another core object in the platform. Items are the objects that hold the actual data within the board, to better illustrate this, you can think of a board as a table and a item as a single row in that table.

Just like in a table, the different values of each item are stored in columns.

Querying items by column values

Querying items by column values searches for items based on their column values and returns data about those specific items.

Unlike other queries, when querying items by column values there are some arguments that must be included, and some arguments that are optional:

FieldArguments
items_by_column_values[Item]
Seach items by their column values.
limitInt
Number of items to get, the default is 25.
pageInt
Page number to get, starting at 1.
board_id!Int
The board's unique identifier.
column_id!String
The column's unique identifier.
column_value!String
The column value to search items by.
column_typeString
The column type.
stateState
The state of the item, the default is ACTIVE.
query {
items_by_column_values (board_id: 20178755, column_id: "date", column_value: "2019-02-06") {
id
name
}
}

Item fields

As mentioned above, items hold the actual data within the board, while the different values of each item are stored in columns. Each item contains the following fields:

The fields available in items by column values are exactly the same as the fields available in “Items”. You can see them here.

FieldArguments
boardBoard
The board that contains this item.
column_values[ColumnValue]
The item's column values.
ids[String]
A list of column ids to return
created_atString
The item's create date.
creatorUser
The item's creator.
creator_id!String
The unique identifier of the item creator.
groupGroup
The group that contains this item.
id!ID
The item's unique identifier.
name!String
The item's name.
stateState
The board's state.
subscribers![User]
The pulses's subscribers.
updates[Update]
The item's updates.
limitInt
Number of items to get, the default is 25.
pageInt
Page number to get, starting at 1.
query {
items_by_column_values (board_id: 20178755, column_id: "date", column_value: "2019-02-06") {
id
name
column_values_str
board {
state
board_kind
}
}
}

Updates

monday.com updates are additional notes and information added to items outside of the structure of the board. The main form of communication within the platform takes place in the updates section.

Querying updates

Querying updates returns one or a collection of updates. Updates can receive the following arguments:

FieldArguments
updates[Update]
Get a collection of updates.
limitInt
Number of items to get, the default is 25.
pageInt
Page number to get, starting at 1.
query {
updates (limit: 100) {
id
}
}

Update fields

As mentioned above, updates are additional information within the items. Each update contains the following fields:

Field
body!String
The update's text.
id!ID
The update's unique identifier.
query {
updates (limit: 100) {
body
id
}
}

Tags

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.

Querying tags

Querying tags returns one or a collection of the account's public tags. Public tags are the tags that appear in public boards. If you want to find tags of private boards you can use the boards query. Tags can receive only one argument:

FieldArguments
tags[Tag]
Get a collection of tags.
ids[Int]
A list of tags unique identifiers.
Public tags:
query {
tags (ids: [1, 2, 4, 10]) {
name
}
}
Private tags (board specific):
query {
boards {
tags {
id
}
}
}

Tag fields

Each tag contains the following fields:

Field
color!String
The tag's color.
id!Int
The tag's unique identifier.
name!String
The tag's name.
query {
tags {
name
color
id
}
}

Users

Every user in monday.com is a part of an account (i.e an organization) and could be a member or a guest in that account.

Querying users

Querying users returns one or multiple users. Users can receive the following arguments:

FieldArguments
users[User]
Get a collection of users.
ids[Int]
A list of users unique identifiers.
kindUserKind
The kind to search users by.
newest_firstBoolean
Get the recently created users at the top of the list
limitInt
Number of users to get
query {
users (kind: non_guests) {
id
}
}

User fields

Each user contains the following fields:

Field
account!Account
The user's account.
birthdayDate
The user's birthday.
country_codeString
The user's country code.
created_atDate
The user's creation date.
email!String
The user's email.
enabled!Boolean
Is the user enabled or not.
id!Int
The user's unique identifier.
is_guestBoolean
Is the user a guest or not.
is_pendingBoolean
Is the user a pending user
join_dateDate
The date the user joined the account.
locationString
The user's location.
mobile_phoneString
The user's mobile phone number.
name!String
The user's name.
phoneString
The user's phone number.
photo_originalString
The user's photo in the original size.
photo_thumbString
The user's photo in thumbnail size.
teams![Team]
The teams the user is a member in.
titleString
The user's title.
url!String
The user's profile url.
utc_hours_diffInt
The user’s utc hours difference.
query {
users (ids: [3332456, 8375782, 9304582]) {
created_at
email
account {
name
id
}
}
}

Teams

Teams are the most efficient way to manage groups of users in monday.com. Teams are comprised of one or multiple users, and every user can be a part of multiple teams (or none).

Querying teams

Querying teams returns one or several of teams. Users can receive the following arguments:

FieldArguments
teams[Team]
Get a collection of teams.
ids[Int]
A list of teams unique identifiers.
query {
teams (ids: [9834, 33, 20595]) {
name
}
}

Team fields

Each team contains the following fields:

Field
id!Int
The team's unique identifier.
name!String
The team's name.
picture_urlString
The team's picture url.
users[User]
The users in the team.
query {
teams {
name
picture_url
users {
created_at
phone
}
}
}

Me

There is also an option to query the user details of the user whose API key is being used if the API is the personal API key. This is the fastest way to query for the user details (same as users query) of the connected user.

Querying me

The “me field” has the same fields as the Users field.

Field
meUser
Get the connected user's information.
query {
me {
is_guest
join_date
}
}

Complexity

As mentioned in the rate limits section, the amount of API calls each account can perform is limited by complexity per minute. Querying for complexity allows you to determine the complexity of your query and how much of your 1 minute cap will be used.

Querying complexity

Simply add the complexity query to your query and you’ll receive another field which represents the complexity level.

Field
complexityComplexity
Get the complexity data of your queries.

Complexity fields

Complexity contains the following fields:

Field
after!Int
The remainder of complexity after the query's execution.
before!Int
The remainder of complexity before the query's execution.
query!Int
The specific query's complexity.
query {
complexity {
query
after
}
users(kind: non_guests) {
id
name
}
}

Mutating monday.com entities (object types)

Mutating in GraphQL is the way to modify data, it is the term used to include all non API functions otha than GET. This includes functions such as put, post, and delete that you may be familiar with from REST-based APIs.

Unlike querying, mutating requires adding all the arguments to the mutation. After it runs, you can query the values of the object after the mutation took place.

There are different types of monday.com entities that can be mutated through the API. In the following sections we’re going to dive into each of them, the different data you can mutate, and additional details about how to do so.

Here is a list of the monday.com entities that can be mutated:

  • Boards
  • Columns
  • Groups
  • Items
  • Updates
  • Notifications
  • Statuses
  • Tags

Boards

monday.com boards are where our users input all of their data and as such it is one of the core components of the platform and one of the main objects with which you will need to be familiar.

The board’s structure is composed of rows (called items), groups of rows (called groups), and columns. The data of the board is stored in the items of the board and in the updates sections of each item. Each board has one or more owners and subscribers.

Additionally, there are three different board types (main, shareable, private) and each board can have different sets of permissions.

Create board

Allows you to create a new board. After the mutation runs you can query back all the board data as shown in the Querying boards section.

FieldArguments
create_boardBoard
Create a new board.
board_name!String
The board's name
board_kind!BoardKind
The board's kind
mutation {
create_board (board_name: "my board", board_kind: public) {
id
}
}

Archive board

Below are the list of options to mutate a board. After the mutation runs you can query back all the board data as shown in the Querying boards section.

FieldArguments
archive_boardBoard
Archive a board.
board_id!Int
The board's unique identifier
mutation {
archive_board (board_id: 20178755) {
id
}
}

Columns

Columns and items are two core elements of a board. A board is formatted as a table where there are columns and rows called items. In monday.com each column has a specific functionality it enables (ex. a numbers column, a text column, a time tracking column, etc.)

Create column

Allows to add a new column to the different board through the API. After the mutation runs you can query back all the board data as shown in the Querying columns section.

FieldArguments
create_columnColumn
Create a new column in board.
board_id!Int
The board's unique identifier.
title!String
The new column's title.
column_typeColumnType
The type of column to create.
mutation {
create_column (board_id: 20178755, title: "Work status", column_type: status) {
id
}
}

Change column value

The data of each item is stored in columns. The change column value mutation allows you to change the value of a column in a specific item (row).

Each column has a certain type, and different column types expect a different set of parameters to update their values. When sending data to a particular column, use a JSON-formatted string (if you’re using Javascript, you can use JSON.stringify() to convert a JSON object into a string). To check how to send the data for each column please see changing column values section.

After the mutation runs you can query back all the board data as shown in the Querying columns section.

FieldArguments
change_column_valueItem
Change an item's column value.
item_idInt
The item's unique identifier.
column_id!String
The column's unique identifier.
board_id!Int
The board's unique identifier.
value!JSON
The new value of the column.
mutation {
change_column_value (board_id: 20178755, item_id: 200819371, column_id: "status", value: "{\"index\": 1}") {
id
}
}

Change multiple column values

This mutation allows you to update multiple columns values of a specific Item (row).

Each column has a certain type, and different column types expect a different set of parameters to update their values. When sending data in the column_values argument, use a JSON-formatted string (if you’re using Javascript, you can use JSON.stringify() to convert a JSON object into a string).

The column_values argument is built in the following form (example with text and status columns):

{\"text\": \"New text\", \"status\": {\"label\": \"Done\"}}
To check how to send the data for each column please see changing column values section.

After the mutation runs you can query back all the board data as shown in the Querying columns section.

FieldArguments
change_multiple_column_valuesItem
Changes the column values of a specific item.
item_idInt
The item's unique identifier.
board_id!Int
The board's unique identifier.
column_values!JSON
The column values updates.
mutation {
change_multiple_column_values (board_id: 20178755, item_id: 200819371, column_values: "{\"status\": {\"index\": 1}}") {
id
}
}

Groups

Items are grouped together in units called groups. Each board contains one or multiple groups, and each group can hold one or many items.

Duplicate group

The duplicate group mutation duplicates a group with all of its items. After the mutation runs you can query back all the group data as shown in the Querying groups section.

FieldArguments
duplicate_groupGroup
Duplicate a group.
board_id!Int
The board's unique identifier.
group_id!String
The group's unique identifier.
add_to_topBoolean
Should the new group be added to the top.
group_titleString
The group's title.
mutation {
duplicate_group (board_id: 20178755, group_id: "today", add_to_top: true) {
id
}
}

Create group

The create group mutation creates a new empty group. After the mutation runs you can query back all the group data as shown in the Querying groups section.

FieldArguments
create_groupGroup
Creates a new group in a specific board.
board_id!Int
The board's unique identifier.
group_name!String
The name of the new group.
mutation {
create_group (board_id: 20178755, group_name: "new group") {
id
}
}

Archive group

The archive group mutation archives a group with all of its items. After the mutation runs you can query back all the group data as shown in the Querying groups section.

FieldArguments
archive_groupGroup
Archives a group in a specific board.
board_id!Int
The board's unique identifier.
group_id!String
The group's unique identifier.
mutation {
archive_group (board_id: 20178755, group_id: "today") {
id
archived
}
}

Delete group

The delete group mutation deletes a group with all of its items. After the mutation runs you can query back all the group data as shown in the Querying groups section.

FieldArguments
delete_groupGroup
Deletes a group in a specific board.
board_id!Int
The board's unique identifier.
group_id!String
The group's unique identifier.
mutation {
delete_group (board_id: 20178755, group_id: "today") {
id
deleted
}
}

Items

monday.com items are another core object in the platform. Items are the objects that hold the actual data within the board, to better illustrate this, you can think of a board as a table and a item as a single row in that table.

Create item

You can create a new item in the different boards through the API with the create item mutation.

The data of each item is stored in the board’s columns, each of which holds a particular piece of information. Each column has a certain type, and different column types expect a different set of parameters to update their values. When sending data to a particular column, use a JSON-formatted string (if you’re using Javascript, you can use JSON.stringify() to convert a JSON object into a string). To check how to send the data for each column please see changing column values section.

After the mutation runs you can query back all the board data as shown in the Querying items section.

FieldArguments
create_itemItem
Create a new item.
item_nameString
The new item's name.
board_id!Int
The board's unique identifier.
group_idString
The group's unique identifier.
column_valuesJSON
The column values of the new item.
mutation {
create_item (board_id: 20178755, group_id: "today", item_name: "new item") {
id
}
}

Move item to group

This mutation allows one to move a item between groups in the same board. After the mutation runs you can query back all the board data as shown in the Querying items section.

FieldArguments
move_item_to_groupItem
Move an item to a different group.
item_idInt
The item's unique identifier.
group_id!String
The group's unique identifier.
mutation {
move_item_to_group (item_id: 20178755, group_id: "today") {
id
}
}

Archive item

This mutation allows one to archive a single item. After the mutation runs you can query back all the board data as shown in the Querying items section.

FieldArguments
archive_itemItem
Archive an item.
item_idInt
The item's unique identifier.
mutation {
archive_item (item_id: 20178755) {
id
}
}

Delete item

This mutation allows one to delete a single item. After the mutation runs you can query back all the board data as shown in the Querying items section.

FieldArguments
delete_itemItem
Delete an item.
item_idInt
The item's unique identifier.
mutation {
delete_item (item_id: 20178755) {
id
}
}

Updates

monday.com updates are additional notes and information added to items outside of the structure of the board. The main form of communication within the platform takes place in the Querying updates section.

Create update

The create update mutation allows one to add an update to a item. After the mutation runs you can query back all the board data as shown in the Querying updates section.

FieldArguments
create_updateUpdate
Create a new update.
body!String
The update text.
item_idInt
The item's unique identifier.
mutation {
create_update (item_id: 20178755, body: "This update will be added to the item") {
id
}
}

Notifications

Notifications are sent in the platform in response to various triggers such as due dates, updates, and more. By default, each notification within the platform will also be sent out as an email to the recipient (this can be customized in the user’s profile settings).

Create notification

Notifications are sent in the platform in response to various triggers such as due dates, updates, and more. By default, each notification within the platform will also be sent out as an email to the recipient (this can be customized in the user’s profile settings).

The create notification mutation allows to trigger a notification within the platform (will also send out an email if the recipient's email preferences allow). Keep in mind that notifications are async and you will not be able to query their ID's back after sending then out.

FieldArguments
create_notificationNotification
Create a new notification.
text!String
The notification text.
user_id!Int
The user's unique identifier.
target_id!Int
The target's unique identifier.
target_type!NotificationTargetType
The target's type.
payloadJSON
The notification payload.
mutation {
create_notification (user_id: "105939", target_id: "674387", text: "This is a notification", target_type: project) {
text
}
}

Tags

monday.com tags are objects that help you group items from different groups or different boards throughout your account by a consistent keyword.

Create or get tag

The tags mutation allows you to create new tags or recieve their data if they already exist. Private boards require seperate tags so if you wish to use your tags in a private board use the 'board_id' argument. No need to send this argument for public boards.

FieldArguments
create_or_get_tagTag
Create a new tag or get it if it already exists.
tag_nameString
The new tag's name.
board_idInt
The private board id to create the tag at (not needed for public boards)
mutation {
create_or_get_tag (tag_name: "amazing") {
id
}
}

Changing item column values

Every monday.com board has one or more columns, each of which holds a particular piece of information. Each column has a certain type, and different column types expect a different set of parameters to update their values. When sending data to a particular column, use a JSON-formatted string (if you’re using Javascript, you can use JSON.stringify() to convert a JSON object into a string).

You will mainly need to change item column values in 2 scenarios - when updating the value of an item using the change_column_value mutation, or when creating a new item by using the create_item mutation and setting its values on creation.

Item name column

To update the item's name, send a string of 1 to 255 characters.

Raw JSON - use this in your column values variables:

JSON.stringify("My item");

JSON string - use this in the GraphiQL editor:

"\"My item\""

Text column

To update the text column send a string.

Raw JSON - use this in your column values variables:

JSON.stringify("Sample text");

JSON string - use this in the GraphiQL editor:

"\"Sample text\""

Long text column

To update the long text column, send a string up to 2000 characters with the key “text”.

Raw JSON - use this in your column values variables:

JSON.stringify({
  "text": "Sample text"
});

JSON string - use this in the GraphiQL editor:

"{\"text\":\"Sample text\"}"

Number column

To update the number column send a string containing a float or int.

Raw JSON - use this in your column values variables:

JSON.stringify("3");

JSON string - use this in the GraphiQL editor:

"\"3\""

Status column

Each status column is a collection of indexes and their corresponding label. To update a status column, send the index of the status you want to set. If you don’t know the index of the label you’re trying to set, you can send the label instead. You can only use existing statuses, and if the label you sent doesn’t exist you will get an error containing all the existing statuses and their indexes.

Raw JSON - use this in your column values variables:

JSON.stringify({
  "index": 0
});

JSON string - use this in the GraphiQL editor:

"{\"index\":0}"

Raw JSON - use this in your column values variables:

JSON.stringify({
  "label": "Done"
});

JSON string - use this in the GraphiQL editor:

"{\"label\":\"Done\"}"

Dropdown column

Each dropdown column is a collection of ids and their corresponding label. To update a dropdown column, send the id of the label you want to set. If you don’t know the id of the label you’re trying to set, you can send the label text instead. You can only use existing labels, and if the label you sent doesn’t exist you will get an error containing all the existing labels and their ids.

Raw JSON - use this in your column values variables:

JSON.stringify({
  "id": 1
});

JSON string - use this in the GraphiQL editor:

"{\"id\":1}"

Raw JSON - use this in your column values variables:

JSON.stringify({
  "label": "My label"
});

JSON string - use this in the GraphiQL editor:

"{\"label\":\"My label\"}"

Person column

To update a person column, send the ID of the user.

Raw JSON - use this in your column values variables:

JSON.stringify({
  "id": 235326
});

JSON string - use this in the GraphiQL editor:

"{\"id\":235326}"

Team column

To update a team column send the ID of the team. The ID of a specific team can be found by using the teams query, checking which teams a particular user is a part of (with the User object), or opening the team’s page in monday.com and copying the number at the end of the URL.

Raw JSON - use this in your column values variables:

JSON.stringify({
  "team_id": 51166
});

JSON string - use this in the GraphiQL editor:

"{\"team_id\":51166}"

People column

To update a people column, send an array with the people or teams you want to add to the column. Each item in the array should include the ID of the person/team, and a string signifying whether the item is a person or a team.

Raw JSON - use this in your column values variables:

JSON.stringify({
  "personsAndTeams": [
    {
      "id": 4616627,
      "kind": "person"
    },
    {
      "id": 4616666,
      "kind": "person"
    },
    {
      "id": 51166,
      "kind": "team"
    }
  ]
});

JSON string - use this in the GraphiQL editor:

"{\"personsAndTeams\":[{\"id\":4616627,\"kind\":\"person\"},{\"id\":4616666,\"kind\":\"person\"},{\"id\":51166,\"kind\":\"team\"}]}"

World clock column

To update a world clock column, send the timezone of the user as a string in continent/city form. You can get the list of available timezones here.

Raw JSON - use this in your column values variables:

JSON.stringify({
  "timezone": "Europe/London"
});

JSON string - use this in the GraphiQL editor:

"{\"timezone\":\"Europe/London\"}"

Country column

To update a country column send the iso-2 country code (2 letter code) and the country name. You can get the list of available countries here.

Raw JSON - use this in your column values variables:

JSON.stringify({
  "countryCode": "US",
  "countryName": "United States"
});

JSON string - use this in the GraphiQL editor:

"{\"countryCode\":\"US\",\"countryName\":\"United States\"}"

Email column

To update an email column, send the email address in the email field. You can also pass display text in the text field.

Raw JSON - use this in your column values variables:

JSON.stringify({
  "email": "itsmyemail@mailserver.com",
  "text": "my email"
});

JSON string - use this in the GraphiQL editor:

"{\"email\":\"itsmyemail@mailserver.com\",\"text\":\"my email\"}"

Phone column

To update a phone column send the phone number (digits only) in a string and the iso-2 country code (2 letter code). You can get the list of available countries here.

Raw JSON - use this in your column values variables:

JSON.stringify({
  "phone": "11231234567",
  "countryShortName": "US"
});

JSON string - use this in the GraphiQL editor:

"{\"phone\":\"11231234567\",\"countryShortName\":\"US\"}"

To update a link column, write the URL (including http/https) in the url field. You can also pass display text in the text field.

Raw JSON - use this in your column values variables:

JSON.stringify({
  "url": "http://monday.com",
  "text": "go to monday!"
});

JSON string - use this in the GraphiQL editor:

"{\"url\":\"http://monday.com\",\"text\":\"go to monday!\"}"

Date column

To update a date column, send the date as a string in a YYYY-MM-DD format. You can also add a time by passing a “time” field in HH:MM:SS format.

Raw JSON - use this in your column values variables:

JSON.stringify({
  "date": "2019-06-03",
  "time": "13:25:00"
});

JSON string - use this in the GraphiQL editor:

"{\"date\":\"2019-06-03\",\"time\":\"13:25:00\"}"

Timeline column

To update a timeline column, send the start and end dates in a YYYY-MM-DD format, where the start date is “from” and the end date is “to”.

Raw JSON - use this in your column values variables:

JSON.stringify({
  "from": "2019-06-03",
  "to": "2019-06-07"
});

JSON string - use this in the GraphiQL editor:

"{\"from\":\"2019-06-03\",\"to\":\"2019-06-07\"}"

Tags column

To update a tags column, send the tag ID’s in an array.

Raw JSON - use this in your column values variables:

JSON.stringify({
  "tag_ids": [
    295026,
    295064
  ]
});

JSON string - use this in the GraphiQL editor:

"{\"tag_ids\":[295026,295064]}"

Hour column

To update an hour column, send the hour and minute in 24-hour format.

Raw JSON - use this in your column values variables:

JSON.stringify({
  "hour": 16,
  "minute": 42
});

JSON string - use this in the GraphiQL editor:

"{\"hour\":16,\"minute\":42}"

Week column

To update a week column send the start and end dates in a YYYY-MM-DD format. Date must be 7 days apart (inclusive of the first and last date) and start at the beginning of the work week defined in the account.

Raw JSON - use this in your column values variables:

JSON.stringify({
  "week": {
    "startDate": "2019-06-10",
    "endDate": "2019-06-16"
  }
});

JSON string - use this in the GraphiQL editor:

"{\"week\":{\"startDate\":\"2019-06-10\",\"endDate\":\"2019-06-16\"}}"

Checkbox column

To check the box in the checkbox column, send a 'checked' field with true. To uncheck the box remove the column value.

Raw JSON - use this in your column values variables:

JSON.stringify({
  "checked": "true"
});

JSON string - use this in the GraphiQL editor:

"{\"checked\":\"true\"}"

Rating column

To update a rating column send a number between 1 and your rating scale (can be updated in the column settings).

Raw JSON - use this in your column values variables:

JSON.stringify({
  "rating": 5
});

JSON string - use this in the GraphiQL editor:

"{\"rating\":5}"

Auto calculated columns

Some of the columns in monday.com are auto calculated based on other properties. You cannot update the following columns:

  • Progress tracking column
  • Auto number column
  • Item ID column
  • Last updated column
  • Creation log column
  • Formula column

Removing column values

To remove a column value (delete the excisting value) send an empty string for text or number columns or an empty object for more complex columns.

Raw JSON - use this in your column values variables:

JSON.stringify({});

JSON string - use this in the GraphiQL editor:

"{}"