The Basics

Welcome to monday.com, a work OS where teams create and shape their own workflows in minutes, code-free. Our mission is to help teams outdo their best -- that is, fulfill their potential and collaborate more effectively.

The monday GraphQL API is part of the monday apps framework and allows developers to programmatically access and update data inside a monday.com account.

If you want to get started right away, check out these frequently-used links:

• Get Started
• Authentication
• Introduction to GraphQL

Why use the API?

The GraphQL API is one component of the larger monday apps framework and is the data access layer for all custom monday apps.

Use cases for the API include:

• Accessing board data to render a custom report inside a monday.com dashboard
• Creating a new item on a board when a record is created on another system
• Importing data from another source programmatically

With the monday apps framework, developers can package their own web apps and integrations as native monday.com building blocks. Check out the monday apps documentation to learn more.

What is the monday.com API?

The monday GraphQL API is an application layer to allow apps to read and update data inside a monday.com account. It supports operations boards, items, column values, users, workspaces and more.

Check out the API Reference section to learn more about the objects you can interact with via the API.

Who can use the monday.com API?

At this time, admin, member, and guest users are all able to utilize the monday.com API. Admins and members also have access to their own API tokens as stated in the Authentication section.

While guest users do not have access to an API key, they can utilize API features via other authentication methods such as OAuth or a shortLivedToken.

Viewer users, users who have been deactivated and/or disabled, users with unconfirmed emails, and users on student accounts do not have access to our API.

How does GraphQL work?

This API is built with GraphQL, a flexible query language that allows you to return as much or as little data as you need. Read the Overview of GraphQL article for a deep dive into the fundamentals fo GraphQL.

Unlike REST APIs, our API uses a single endpoint: https://api.monday.com/v2

GraphQL relies on a type system, where each object is a type and contains fields that define it. These fields can be scalars (such as integers) or can be objects themselves. Some fields also take arguments, which can be used to limit, filter, or sort the data that is returned.

For example, the Board type contains scalar fields like name, id and description. It also contains an items field, which defines the items on that specific board and contains its own fields (like name, id, state).

Mutations are a special kind of field that update data. Learn more about them here.

When you make a query, you define what objects (and fields) you want to return. If you're returning a object that itself contains other fields, you need to define what data you want to return on that nested object.

Here's an example of a query that returns the items on a board and their column values. Notice how the query keeps nesting until all the returned data are scalars:

query {
  boards (limit:3) { // the limit argument tells the API to return 3 boards
    id      // scalar
    name    // scalar
    items { // object, so we need to write a subquery
      id    //scalar
      name  // scalar
      column_values { // object, needs a subquery
        id            // scalar
        text          // scalar
      }
    }
  }
}

Making multiple queries in a single request

You can also make multiple API calls in a single request. They will execute one at a time (top to bottom) and then return data:

query {
  checkBoard1: boards(ids:12345678){
    id
    name
  }
  checkBoard2: boards(ids:87654321){
    id
    name
  }
}

📘

Do you have questions?

Join our developer community! You can share your questions and learn from fellow users and monday.com product experts.

Don’t forget to search before opening a new topic!