Announcing new monday apps challenge

Register to compete and build amazing apps
to help teams work better. We are giving away
over $180,000 in prizes including 3 Teslas!

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

If you are already familiar with the monday.com building blocks, check out our API playground to explore our GraphQL schema. 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.

All requests should be POST requests to our API endpoint, with the query string inside the request body. All queries, including mutations, should be sent in the "query" key. All requests except file uploads must set the content-type header to "application/json".

Your JSON request body should look like this:

{
   "query": "query {...}," 
   "variables": {"var1":"value1", "var2":"value2", ...}
}

Code examples in different programming languages can be found in our Developers 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 {

}

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 {

}

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]) {

items {

}

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 {

}

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 {

}

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) {

}

query variables:

{

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

}

Errors supported by Monday GraphQL API

Our GraphQL API returns the set of predefined errors, which are listed here. All the handled exceptions are returned with the status 200 and next structure

{
   "error_code": "SomeKindOfException", 
   "status_code": 200, 
   "error_message": "Some error happened", 
   "errorData": {...}
}

401 - Unauthorized (Not authenticated)

Ensure your API key is valid and passed in the “Authorization” header.

400 - Bad Request (No query string was present)

Ensure your query string is passed with the “query” key. Ensure your request is a POST with JSON body. Ensure your query does not contain unterminated strings.

500 - Internal Server Error (No query string was present)

Check the format of any JSON strings in your query. If you are updating a column, check that you are using the right data structure for each column value.

Parse error on...

Ensure your query is a valid string, and all parens and braces are balanced.

200 - UserUnauthroizedException (User unauthorized to perform action)

Check if the user has permission to access or edit the given resource.

200 - InvalidColumnIdException

Ensure the column ID exists and you have access to the resource.

200 - InvalidBoardIdException

Ensure the board ID exists and you have access to the resource.

200 - CreateBoardException

If you’re creating a board from a template, ensure the template ID is a valid monday template or a board that has template status. Learn more about making a board a template here. If you’re duplicating a board, ensure the board ID exists.

200 - ResourceNotFoundException

Ensure the ID of the item, group or board you’re querying exists.

200 - ItemsLimitationException

To prevent abuse, each board has a limit of 10,000 items created via the API. This error is thrown when you have reached the limit.

200 - ItemNameTooLongException

Ensure your item name is between 1 and 255 characters long.

200 - ColumnValueException

If you are updating a column value, ensure the value conforms with each column’s data structure. Learn more here. If you’re retrieving a column value, ensure the column is supported by our API and not calculated in the client (eg, formula column).

If you get an error: "The column has no connected boards" - Ensure the link to item column is connected to a board via the monday.com UI.

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 {

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 {

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:

Field	Arguments
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:

Field	Arguments
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
workspaceWorkspace The workspace that contains this board (null for main workspace).
workspace_idInt The board's workspace unique identifier (null for main workspace).

query {

boards (ids: 157244624) {

name

state

board_folder_id

owner {

}

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 {

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 {

}

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) {

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:

Field	Arguments
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]) {

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]) {

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:

Field	Arguments
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:

Field	Arguments
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:

Field	Arguments
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) {

name

board {

}

creator {

}

Items By Column Values

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:

Field	Arguments
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") {

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.

Field	Arguments
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") {

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

}

Field	Arguments
tags[Tag] Get a collection of tags.	ids[Int] A list of tags unique identifiers.

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

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:

Field	Arguments
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	Arguments
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.	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 {

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:

Field	Arguments
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) {

}

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

}

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:

Field	Arguments
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) {

}

User fields

Each user contains the following fields:

Field	Arguments
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.	ids[Int] A list of teams unique identifiers.
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

account {

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.

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.

Field	Arguments
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) {

}

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.

Field	Arguments
archive_boardBoard Archive a board.	board_id!Int The board's unique identifier

mutation {

archive_board (board_id: 20178755) {

}

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.

Field	Arguments
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) {

}

Delete subscribers from a board

Required scope: boards:write

Allows you to delete subscribers from a board.

Field	Arguments
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]) {

}

Columns

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.

Field	Arguments
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) {

}

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.

Field	Arguments
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}") {

}

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.

Field	Arguments
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}}") {

}

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.

Field	Arguments
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) {

}

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.

Field	Arguments
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") {

}

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.

Field	Arguments
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") {

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.

Field	Arguments
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") {

deleted

}

Items

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.

Field	Arguments
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") {

}

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.

Field	Arguments
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 {

}

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.

Field	Arguments
clear_item_updatesItem Clear an item's updates.	item_id!Int The item's unique identifier.

mutation {

clear_item_updates (item_id: 20178755) {

}

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.

Field	Arguments
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") {

}

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.

Field	Arguments
archive_itemItem Archive an item.	item_idInt The item's unique identifier.

mutation {

archive_item (item_id: 20178755) {

}

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.

Field	Arguments
delete_itemItem Delete an item.	item_idInt The item's unique identifier.

mutation {

delete_item (item_id: 20178755) {

}

Duplicate item

Required scope: boards:write

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

Field	Arguments
duplicate_itemJSON Duplicate an item.	board_id!Int The board's unique identifier. item_idInt The item's unique identifier. *Required

mutation {

duplicate_item (board_id: 12593, item_id: 20178755)

}

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.

Field	Arguments
create_updateUpdate Create a new update.	body!String The update text. item_idInt The item's unique identifier. parent_idInt The parent post identifier.

mutation {

create_update (item_id: 20178755, body: "This update will be added to the item") {

}

Delete update

Required scope: updates:write

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

Field	Arguments
delete_updateUpdate Delete an update.	id!Int The update's unique identifier.

mutation {

delete_update (id: 20178755) {

}

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

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.

Field	Arguments
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

}

Field	Arguments
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)

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.

Field	Arguments
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!) {

}

Add a file to a file column value

Required scope: boards:write

Add a file to a file column value.

Field	Arguments
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!) {

}

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.

Field	Arguments
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) {

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.

Field	Arguments
delete_webhookWebhook Delete a new webhook.	id!Int The webhook's unique identifier.

mutation {

delete_webhook ( id: 12) {

board_id

}

Workspaces

monday.com workspaces are used by teams to organize and manage their accounts by departments/teams/projects. Workspaces can contain boards, dashboards, and folders.

Create a workspace

Required scope: workspaces:write

Allows you to create a new workspace. After the mutation runs you can create boards in it as shown in the Creating boards section.

Field	Arguments
create_workspaceWorkspace Create a new workspace.	name!String The Workspace's name kind!WorkspaceKind The workspace's kind (open / closed) descriptionString The Workspace's description

mutation {

create_workspace ( name: "My worksapce", kind: public, description: "My workspace description") {

}

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

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

Link column

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

Item link column

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!

16.09.2020

Added

Duplicate item mutation - allowing to duplicate exiting item

07.09.2020

Added

Delete update mutation - allowing to delete existing update

25.08.2020

Added

Create workspace mutation - allowing to add new workspace

15.06.2020

Added

Create subitem mutation - allowing to add new subitems under the specific parent item

01.06.2020

Added

Add subscribers to a board - allowing to add subscribers/owners to a board
Delete subscribers from a board - allowing to remove subscribers/owners from a board
Item Link column support - allowing to mutate Item Link columns

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

Support clearing of file column

12.03.2020

Added

Added changelog to our API!

Introduction

What is the monday.com API exactly?

How does it work?

How to get started?

Set up a monday.com account

Authenticate with the API

Using the API

Developer Mode

How to get help?

Webhooks

Authentication

API v2 Token & API Tokens

Accessing your tokens

Using tokens

Rate Limits

Rates defaults

What happens when exceeding the limit?

Complexity limiting

Complexity nesting

Finding out complexity level

Using GraphQL

Operations

Object Types

Fields

Arguments

GraphQL visual interface - GraphiQL

Variables

Errors supported by Monday GraphQL API

401 - Unauthorized (Not authenticated)

400 - Bad Request (No query string was present)

500 - Internal Server Error (No query string was present)

Parse error on...

200 - UserUnauthroizedException (User unauthorized to perform action)

200 - InvalidColumnIdException

200 - InvalidBoardIdException

200 - CreateBoardException

200 - ResourceNotFoundException

200 - ItemsLimitationException

200 - ItemNameTooLongException

200 - ColumnValueException

Querying monday.com entities (object types)

Activity Logs

ActivityLogType fields

Board Views

BoardView fields

Boards

Querying boards

Board fields

Column Values

ColumnValue fields

Columns

Column fields

Complexity

Querying complexity

Complexity fields

Files

Querying files

Asset fields

Groups

Group fields

Items

Querying items

Item fields

Items By Column Values

Querying items by column values

Item fields

Me

Querying me

Tags

Querying tags

Tag fields

Teams

Querying teams

Team fields

Updates

Querying updates

Update fields

Users

Querying users

User fields