Introduction
The monday.com API
How does it work?
How to get started?
Set up an account
Authenticate with the API
Using the API
Developer Mode
How to get help?
Webhooks
Authentication
API v2 Token
Accessing your tokens
Using tokens
Rate Limits
Rates defaults
Exceeding the limit
Complexity limiting
Complexity nesting
Finding complexity level
Using GraphQL
Operations
Object Types
Fields
Arguments
GraphQL visual interface
Variables
Querying monday.com
Activity Logs
Board Views
Boards
Column Values
Columns
Complexity
Files
Groups
Items
Items By Column Values
Me
Tags
Teams
Updates
Users
Mutating monday.com
Boards
Create board
Archive board
Add subscribers to a board
Delete subscribers from a board
Columns
Create column
Change column value
Change multiple column values
Groups
Duplicate group
Create group
Archive group
Delete group
Items
Create item
Create subitem
Clear item's updates
Move item to group
Archive item
Delete item
Updates
Create update
Notifications
Create notification
Tags
Create or get tag
Files
Add a file to an update
Add a file to a file column value
Webhooks
Create a webhook
Delete a webhook
Changing column values
Checkbox column
Country column
Date column
Dropdown column
Email column
File column
Hour column
Item name column
Link column
Long text column
Number column
People column
Person column
Phone column
Rating column
Status column
Tags column
Team column
Text column
Timeline column
Week column
World clock column
Item link column
Auto calculated columns
Removing column values
Removing column values - File column
Changelog
15.06.2020
01.06.2020
05.05.2020
16.04.2020
14.04.2020
16.03.2020
12.03.2020
monday Apps Challenge
Join the monday Apps Challenge to build
any app you can imagine and win a Tesla X
Register Now
API V2 Documentation

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/"

Developer Mode

You can use monday.labs to activate "Developer mode" to see template IDs and column IDs:

How to get help?

If you need further support with our API or apps platform, check out our monday.com community. There are a ton of helpful resources and threads in the community, and it’s a great place to connect with other monday.com users with similar use cases.

The community is managed by members of the monday.com team, but not every topic is guaranteed to get a response from our team.

Our Customer Experience team is here to help with:

  • Bug reports
  • Feature feedback
  • Any issue that deals with sensitive information not suitable for the public community

Webhooks

If your application needs real-time updates from monday.com boards, you can use our webhooks. They're great for being notified when something changes on your boards, instead of needing to poll the API constantly. To learn more about creating webhooks through monday.com, click here. To learn more about creating webhooks through our API click here.

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 exceeds the limit in a given minute, the query will return an error in the "errors" field.

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.

For a deep-dive into what you can do with GraphQL, check out the GraphQL Foundation's incredible introduction here.

If you want to know more about why we decided to use GraphQL for our API, check out this article.

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 “title”, the argument is “ids”, and the argument value is 157244624.

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

Activity Logs

monday.com activiy logs are records of all activites done on a board, use it to know what happend in your board.

ActivityLogType fields

Querying activity logs returns a collection of activity logs in a specific board. Activity logs are available for querying through boards and contain the following fields:

Field
account_id!String
created_at!String
data!String
The item's column values in string form.
entity!String
event!String
id!String
user_id!String
query {
boards (ids: 157244624) {
activity_logs {
id
event
data
}
}
}

Board Views

monday.com board views are records of all views added to a board.

BoardView fields

Querying views returns a collection of board views in a specific board. Board views are available for querying through boards and contain the following fields:

Field
id!ID
The view's unique identifier.
name!String
The view's name.
settings_str!String
The view's settings in a string form.
type!String
The view's type.
query {
boards (ids: 157244624) {
views {
id
name
type
}
}
}

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

Required scope: boards:read

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
The board's kind (public / private / share)
stateState
The state of the board (all / active / archived / deleted), 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
activity_logs[ActivityLogType]
The board log events.
limitInt
Number of items to get, the default is 25.
pageInt
Page number to get, starting at 1.
user_ids[Int]
User ids to filter.
column_ids[String]
Column ids to filter
group_ids[String]
Group ids to filter
item_ids[Int]
Item id to filter
fromISO8601DateTime
From timestamp (ISO8601)
toISO8601DateTime
To timestamp (ISO8601)
board_folder_idInt
The board's folder unique identifier.
board_kind!BoardKind
The board's kind (public / private / share).
columns[Column]
The board's visible columns.
ids[String]
A list of column unique identifiers.
communicationJSON
Get the board communication value - typically meeting ID
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.
limitInt
Number of items to get
pageInt
Page number to get, starting at 1.
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 (all / active / archived / deleted).
subscribers![User]
The board's subscribers.
tags[Tag]
The board's specific tags.
top_group!Group
The top group at this board.
updated_atISO8601DateTime
The last time the board was updated at.
updates[Update]
The board's updates.
limitInt
Number of items to get, the default is 25.
pageInt
Page number to get, starting at 1.
views[BoardView]
The board's views.
ids[Int]
A list of view unique identifiers.
typeString
The view's type
query {
boards (ids: 157244624) {
name
state
board_folder_id
owner {
id
}
}
}

Column Values

Every monday.com board has one or more columns, each of which holds a particular piece of information. These column values are essentially the content of the board. Their inner value structure varies by type, details can be found here.

ColumnValue fields

Column values are available for querying through items. Each column value contains the following fields:

Field
additional_infoJSON
The column value's additional information.
id!ID
The column's unique identifier.
textString
The column's textual value in string form.
title!String
The column's title.
type!String
The column's type.
valueJSON
The column's value in json format.
query {
items (limit: 50) {
column_values {
id
value
}
}
}

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.
posString
The column's position in the board.
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
}
}
}

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
}
}

Files

Any file you upload in monday is saved as an asset. You can query for this assets by id or get them throgh the updates and items queries.

Querying files

Required scope: assets:read

Querying files returns one or a collection of assets. Assets can receive the following arguments:

FieldArguments
assets[Asset]
Get a collection of assets by ids.
ids![Int]
Ids of the assets/files you want to get
query {
assets (ids: [1,2,3]) {
id
public_url
}
}

Asset fields

Files are saved as assets in monday.com. Each asset contains the following fields:

Field
file_extension!String
The file's extention type.
id!ID
The file's unique identifier.
name!String
The file's name.
public_url!String
public url to the asset, valid for 1 hour.
url!String
url to view the asset.
url_thumbnailString
url to view the asset in thumbnail mode. Only available for images.
query {
assets (ids: [1,2,3]) {
id
name
url
}
}

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.
limitInt
Number of items to get
pageInt
Page number to get, starting at 1.
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

Required scope: boards:read

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
assets[Asset]
The item's assets/files.
column_ids[String]
Ids of the columns you want to get assets from.
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 (all / active / archived / deleted).
subscribers![User]
The pulses's subscribers.
updated_atString
The item's last update date.
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

Required scope: boards:read

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]
Search items by their column values.
limitInt
Number of items to get
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 (all / active / archived / deleted), 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
assets[Asset]
The item's assets/files.
column_ids[String]
Ids of the columns you want to get assets from.
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 (all / active / archived / deleted).
subscribers![User]
The pulses's subscribers.
updated_atString
The item's last update date.
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
}
}
}

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

Required scope: me:read

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
}
}

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

Required scope: tags:read

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
}
}

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

Required scope: teams:read

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
}
}
}

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

Required scope: updates:read

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
assets[Asset]
The update's assets/files.
body!String
The update's html formatted body.
created_atDate
The update's creation date.
creatorUser
The update's creator.
creator_idString
The unique identifier of the update creator.
id!ID
The update's unique identifier.
item_idString
The update's item ID.
replies[Reply]
The update's replies.
text_bodyString
The update's text body.
updated_atDate
The update's last edit date.
query {
updates (limit: 100) {
body
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

Required scope: users:read

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 (all / non_guests / guests / non_pending).
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
is_view_onlyBoolean
Is the user a view only user or not.
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_smallString
The user's photo in small size (150x150).
photo_thumbString
The user's photo in thumbnail size (100x100).
photo_thumb_smallString
The user's photo in small thumbnail size (50x50).
photo_tinyString
The user's photo in tiny size (30x30).
teams![Team]
The teams the user is a member in.
time_zone_identifierString
The user's timezone identifier.
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
}
}
}

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

Required scope: boards:write

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.

To see all the available template ID's go to monday.labs and activate the "Developer mode" feature. You will then be able to see the template ID's in the create board from template screen.

FieldArguments
create_boardBoard
Create a new board.
board_name!String
The board's name
board_kind!BoardKind
The board's kind (public / private / share)
workspace_idInt
Optional workspace id
template_idInt
Optional board template id
mutation {
create_board (board_name: "my board", board_kind: public) {
id
}
}

Archive board

Required scope: boards:write

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
}
}

Add subscribers to a board

Required scope: boards:write

Allows you to add subscribers to a board. You can define if users will be added as regular subscribers or as owners of the board.

FieldArguments
add_subscribers_to_board[User]
Add subscribers to a board.
board_id!Int
The board's unique identifier.
user_ids![Int]
User ids to subscribe to a board
kindSubscriberKind
Subscribers kind (subscriber / owner)
mutation {
add_subscribers_to_board (board_id: 20178755, user_ids: [105939, 105940, 105941], kind: owner) {
id
}
}

Delete subscribers from a board

Required scope: boards:write

Allows you to delete subscribers from a board.

FieldArguments
delete_subscribers_from_board[User]
Remove subscribers from the board.
board_id!Int
The board's unique identifier.
user_ids![Int]
User ids to subscribe to a board
mutation {
delete_subscribers_from_board(board_id: 20178755, user_ids: [105939, 105940, 105941]) {
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

Required scope: boards:write

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.
defaultsJSON
The new column's defaults.
mutation {
create_column (board_id: 20178755, title: "Work status", column_type: status) {
id
}
}

Change column value

Required scope: boards:write

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

Required scope: boards:write

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

Required scope: boards:write

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

Required scope: boards:write

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

Required scope: boards:write

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

Required scope: boards:write

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

Required scope: boards:write

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
}
}

Create subitem

Required scope: boards:write

You can create a new subitem for any parent item through the API with the create subitem mutation.

Subitems are technically created under a different board, which is NOT the same board as parent item's board. You can query the identifier of this board through the regular Board resolver of the subitem. Using this board ID and subitem ID you can apply any actions to the subitem as to a regular item, f.e. archive it, delete, change column_values, etc.

NOTE: For creating subitems via the API, the board should already have subitems column or at least one subitem created, otherwise you will receive an error.

After the mutation runs you can query back all the subitem data the same as for a regular item as shown in the Querying items section.

FieldArguments
create_subitemItem
Create subitem.
parent_item_idInt
The parent item's unique identifier.
item_nameString
The new item's name.
column_valuesJSON
The column values of the new item.
mutation {
create_subitem (parent_item_id: 20178785, item_name: "new subitem") {
id,
board {
id
}
}
}

Clear item's updates

Required scope: boards:write

This mutation allows one to clear all updates on a specific item, inlcuding replies and likes. After the mutation runs you can query back all the board data as shown in the Querying items section.

FieldArguments
clear_item_updatesItem
Clear an item's updates.
item_id!Int
The item's unique identifier.
mutation {
clear_item_updates (item_id: 20178755) {
id
}
}

Move item to group

Required scope: boards:write

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

Required scope: boards:write

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

Required scope: boards:write

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

Required scope: updates:write

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

Required scope: notifications:write

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 (Project / Post)
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

Required scope: boards:write

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
}
}

Files

You can upload files to monday.com. Files are saved as "assets" and always belong to a parent object.

NOTE: file requests has different endpoint: api.monday.com/v2/file and are limited to 500MB.

Add a file to an update

Required scope: updates:write

Add a file to an existing update. The file will be appended to the bottom of the update.

FieldArguments
add_file_to_updateAsset
Add a file to an update.
update_id!Int
The update to add the file to.
file!File
The file to upload.
mutation {
add_file_to_update (update_id: 17, $file: File!) {
id
}
}

Add a file to a file column value

Required scope: boards:write

Add a file to a file column value.

FieldArguments
add_file_to_columnAsset
Add a file to a column value.
item_id!Int
The item to add the file to.
column_id!String
The column to add the file to.
file!File
The file to upload.
mutation {
add_file_to_column (item_id: 143, column_id: 'files_03', $file: File!) {
id
}
}

Webhooks

monday.com webhooks integration allows you to subscribe to events on your boards, and get notified by an HTTP post request to a specified URL with the event information as a payload.

For more information about webhooks, and the webhooks payload Click here.

Create a webhook

Required scope: webhooks:write

The mutation allows you to create a new webhook. After the mutation runs, the webhook will report the wanted event on the specific board given to the wanted URL.

The URL will have to pass a verification test, where we will send a json POST body request containing a challenge field. We expect you to return the token as a challenge field on your response json body to that request.

FieldArguments
create_webhookWebhook
Create a new webhook.
board_id!Int
The board's unique identifier.
url!String
The webhook URL.
event!WebhookEventType
The event to listen to (incoming_notification / change_column_value / change_specific_column_value / create_item / create_update)
configJSON
The webhook config
mutation {
create_webhook ( board_id: 12593, url: "https://www.webhooks.my-webhook/test", event: create_item) {
id
board_id
}
}

Delete a webhook

Required scope: webhooks:write

The delete webhook mutation deletes a webhook. After the mutation runs it will no longer report events to the URL given.

FieldArguments
delete_webhookWebhook
Delete a new webhook.
id!Int
The webhook's unique identifier.
mutation {
delete_webhook ( id: 12) {
id
board_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.

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\"}"

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\"}"

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.

NOTE: enter the date and time in UTC and it will be converted to the user's timezone when they look at the board.

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\"}"

Dropdown column

Each dropdown column is a collection of ids and their corresponding label. To update a dropdown column, send the ids of the labels you want to set. If you don’t know the ids of the labels you’re trying to set, you can send the labels text instead. You can only use existing labels, and if the labels 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({
  "ids": [
    1
  ]
});

JSON string - use this in the GraphiQL editor:

"{\"ids\":[1]}"

Raw JSON - use this in your column values variables:

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

JSON string - use this in the GraphiQL editor:

"{\"labels\":[\"My label\"]}"

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\"}"

File column

We currently support clearing the File column, details here.

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}"

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\""

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!\"}"

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\""

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 an int representing the ID of the person/team, and a string signifying whether the item is a person or a team.

NOTE: This section refers to the multiple-person/people column. If you are trying to update the person column, check out this section.

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\"}]}"

Person column

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

NOTE: This section refers to the (deprecated) person column. If you are trying to update the people column, check out this section.

Raw JSON - use this in your column values variables:

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

JSON string - use this in the GraphiQL editor:

"{\"id\":235326}"

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\"}"

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}"

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\"}"

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]}"

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}"

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\""

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\"}"

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\"}}"

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\"}"

To update an item link column, send linked items ID's as an array. If items will not belong to the linked board/boards, the exception will be raised.

Raw JSON - use this in your column values variables:

JSON.stringify({
  "item_ids": [
    4616627,
    4616628,
    4616629
  ]
});

JSON string - use this in the GraphiQL editor:

"{\"item_ids\":[4616627,4616628,4616629]}"

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 existing value) send an empty string for text or number columns or an empty object for more complex columns.

Note: To remove the column value of a File column see the following.

Raw JSON - use this in your column values variables:

JSON.stringify({});

JSON string - use this in the GraphiQL editor:

"{}"

Removing column values - File column

Removing the value of a File column requires explicitly setting the clear_all flag because this action can not be undone.

Raw JSON - use this in your column values variables:

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

JSON string - use this in the GraphiQL editor:

"{\"clear_all\":true}"

Changelog

Here you can see all the changes we made to our API!

15.06.2020


Added

01.06.2020


Added

05.05.2020


Changed
  • Changed exception handling to be better aligned with the GraphQL specification. The following exceptions will now return status code 200 instead of a 400 error, and the error message will be in the “errors” key of the response: InvalidBoardIdException, InvalidColumnIdException, ColumnValueException, ItemNameTooLongException

16.04.2020


Added
  • Activity Logs - show log events on the board
  • Board communication field - query board zoom call configuration
  • Board Views - get board views
  • Column pos field - get the column position in the board

14.04.2020


Added
  • New mutation to add a file to an update
  • New mutation to add a file to a file column value

16.03.2020


Added

12.03.2020


Added
  • Added changelog to our API!
By continuing to use the website, you consent to the use of cookies.
✕