Getting started overview

Integrating with the Monday.com API allows developers to automate tasks, sync data, and extend the platform's functionality programmatically. The API is built on GraphQL, providing a flexible interface for querying and modifying data across various Monday.com entities like boards, items, and users. To begin, you will need a Monday.com account, an API token for authentication, and a basic understanding of GraphQL concepts.

This guide provides a structured approach to making your initial API call, covering account setup, API key generation, and executing a simple GraphQL query. Monday.com provides official API and SDK documentation to support developers through the integration process.

Quick Reference Guide

Step What to Do Where
1. Sign Up/Log In Access your Monday.com account. Monday.com homepage
2. Get API Token Generate a Personal API Token. Monday.com Admin > Developers > My Access Tokens
3. Understand GraphQL Familiarize yourself with GraphQL basics. GraphQL official documentation
4. Construct Request Formulate your first GraphQL query. Local development environment or API client
5. Execute Request Send the authenticated query. cURL, Postman, or preferred programming language
6. Interpret Response Parse the JSON response. Local development environment

Create an account and get keys

Before making any API calls, you need an active Monday.com account and a Personal API Token. If you do not have an account, Monday.com offers an individual free tier that supports up to two users, which is suitable for development and testing purposes.

1. Sign up or log in to Monday.com

Navigate to the Monday.com website and either log in to your existing account or sign up for a new one. Ensure you have administrative access or permissions to generate API tokens.

2. Locate the Developer section

Once logged in, click on your profile avatar in the bottom-left corner of the Monday.com interface. From the menu that appears, select Admin. Within the Admin section, navigate to the Developers tab on the left sidebar.

3. Generate a Personal API Token

Under the Developers section, click on My Access Tokens. You will see an option to generate a new token. Click Generate. Monday.com will display your unique API token. It is critical to copy this token immediately and store it securely, as it will only be shown once. Treat your API token like a password; it grants full access to your Monday.com account data.

For security best practices, avoid hardcoding API tokens directly into your application code. Instead, use environment variables or a secure configuration management system. Monday.com's API security documentation provides further guidance on protecting your credentials.

Your first request

The Monday.com API uses GraphQL for all interactions. This means you will send HTTP POST requests to a single endpoint with a GraphQL query or mutation in the request body. Your API token will be included in the HTTP headers for authentication.

API Endpoint

The primary GraphQL API endpoint for Monday.com is: https://api.monday.com/v2

For more specific details on versioning, refer to the Monday.com API v2 reference.

Request Structure

Every request will have two main components:

  1. HTTP Header: Contains your API token.
  2. HTTP Body: Contains your GraphQL query or mutation.

Example: Retrieve the name of a board

Let's make a simple query to fetch the name of a specific board. For this example, you will need the ID of a board from your Monday.com account. You can find a board ID by navigating to the board, then checking the URL (e.g., https://youraccount.monday.com/boards/1234567890, where 1234567890 is the board ID).

Using cURL (Command Line)

Open your terminal or command prompt and execute the following cURL command. Replace YOUR_API_TOKEN with your actual Monday.com API token and YOUR_BOARD_ID with the ID of a board from your account.


curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_API_TOKEN" \
  -d '{"query": "query { boards (ids: YOUR_BOARD_ID) { name } }"}' \
  https://api.monday.com/v2

Explanation:

  • -X POST: Specifies that this is an HTTP POST request.
  • -H "Content-Type: application/json": Informs the server that the request body is JSON.
  • -H "Authorization: YOUR_API_TOKEN": This is where you pass your API token for authentication.
  • -d '{"query": "query { boards (ids: YOUR_BOARD_ID) { name } }"}': This is the request body, containing the GraphQL query. The query asks for the name of boards with the specified ids.

Expected Response

A successful response will return a JSON object containing the board's name:


{
  "data": {
    "boards": [
      {
        "name": "My First Monday Board"
      }
    ]
  },
  "account_id": 12345678
}

If you receive an error, double-check your API token, board ID, and the syntax of your GraphQL query.

Common next steps

After successfully making your first API call, consider these next steps to deepen your integration:

  1. Explore the GraphQL Schema: Use the Monday.com API reference to understand the full range of available queries and mutations. GraphQL allows you to request exactly what you need, making efficient data retrieval possible.
  2. Implement with an SDK: Monday.com provides SDKs for JavaScript, Python, and Ruby. These SDKs simplify API interactions by handling authentication, request formatting, and response parsing, which can accelerate development.
  3. Webhooks for Real-time Updates: To react to changes in Monday.com in real-time (e.g., when an item is created or updated), set up webhooks. This pushes data to your application, reducing the need for constant polling.
  4. Error Handling: Implement robust error handling in your application. The API returns specific error codes and messages that can help diagnose issues. Refer to the Monday.com API error codes documentation for a comprehensive list.
  5. Rate Limit Management: Understand the API rate limits to ensure your application operates smoothly without hitting usage caps. Implement retry mechanisms with exponential backoff for rate-limited requests.
  6. OAuth Integration: For applications that will be used by multiple Monday.com users or published on the Monday.com marketplace, consider implementing OAuth 2.0. This provides a secure way for users to grant your application access to their Monday.com data without sharing their personal API tokens.

Troubleshooting the first call

When encountering issues with your initial API request, here are common areas to check:

  • Incorrect API Token: Ensure your API token is correctly copied and included in the Authorization header. Even a single character mismatch will result in an authentication failure. Verify that the token has not expired or been revoked.
  • Invalid Board ID: Confirm that the board ID used in your query (e.g., YOUR_BOARD_ID in the example) corresponds to an existing board in your Monday.com account and that the API token has permission to access it.
  • GraphQL Syntax Errors: GraphQL queries are case-sensitive and require precise syntax. Check for typos, missing braces {}, or incorrect field names. Tools like the Monday.com API Playground can help validate your queries before sending them via cURL or code.
  • HTTP Method: All Monday.com API requests are HTTP POST requests. Using GET or any other method will result in an error.
  • Content-Type Header: The Content-Type header must be set to application/json. Incorrectly setting this header can cause the server to misinterpret your request body.
  • Network Issues: Verify your internet connection and ensure no firewalls or proxies are blocking your outgoing requests to https://api.monday.com/v2.
  • Permissions: The API token's permissions are tied to the user who generated it. If the user does not have access to a particular board or data entity, the API call will fail with a permission error. Ensure the generating user has the necessary permissions.
  • Rate Limiting: While unlikely for a first call, repeated failed attempts in a short period could trigger temporary rate limiting. If you suspect this, wait a few minutes and try again. The API will return specific headers with rate limit information on subsequent requests.

For persistent issues, consult the Monday.com developer documentation or reach out to Monday.com support channels for assistance.