Connecting to Monday#
First Steps with Monday#
Set up an account with Monday.
Cost
There are both free and paid options for this API.
Rate Limits
This API uses a construct called complexity points to determine rate limits. Monday's documentation explains the implications of these complexity points.
How to Connect DataDistillr to Monday#
To set up a data source connect for Monday, you will need to have:
- A unique name for your data source connection to be used in queries
- An API token generated through your Monday.com account
Data Source Form#
To locate the JIRA form, follow the steps in Connecting Your Data to DataDistillr. When you get to the window to choose the data source type, select API as shown below.
On the API screen, select Monday from the list of API forms.
The following form will appear. Instructions are below on how to find the information required to fill each on the Monday API form.
Once you have filled out all the fields, press the green 'Save' button, and your API will be connected!
Name#
Enter any name that will help you recognize this data source within your query window.
Acceptable Characters Include
- lowercase alphanumeric characters
- underscores
API Key#
You will need valid authentication through an access token. Each user has their own API token, this grants API access to all the boards to which the user has access (i.e. they're subscribed to).
Currently, monday.com only offers V2 API tokens, which are all personal tokens. To access your API tokens, you can use one of two methods depending on your user level.
NOTE
Admin users are able to utilize both methods to acquire their API tokens. Member users can access their API tokens from their Developer tabs.
Admin users are able to utilize both methods to acquire their API tokens.
Admin only Method:
Log into your monday.com account. Click on your avatar (picture icon) in the bottom left corner of your screen
Select Admin from the resulting menu (this requires you to have admin permissions).
Go to the API section. Your API token will be located here. If you haven't created an API token you will be able to 'Generate a "API v2 Token"'. If you already have an API token you can also create a new one to replace your current token by clicking Regenerate.
NOTE
You can always regenerate a new token, however doing so will cause the previous token to expire.
Developer Method:
Click on your avatar (picture icon) in the bottom left corner of your screen.
Select Developers from the resulting menu.
In the top menu, click on the Developer dropdown menu. Select the first option on the dropdown menu titled My Access Tokens.
Click on the blue Show button to expose your API token and copy it.
Endpoints#
The table below shows a list of endpoints available to connect within the DataDistillr application. If you need to connect to any endpoints not listed in the table below, please use the Custom API Form.
| Endpoint | Required | Optional | Description |
|---|---|---|---|
items |
Returns the items where the user has access | ||
users |
Returns the users where the user has access | ||
boards |
Returns the boards where the user has access | ||
updates |
Returns the updates where the user has access |
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.
Unlike REST APIs, the API of monday.com 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).
Nav Tree#
The endpoints above will display as follows in the nav tree once your API has successfully connected.
Sample Queries#
The following queries are intended to help you get started, and make life simpler querying within your API.
For the following examples, suppose that my Monday API data source was called mymondayapi and I want to query an
endpoint. In the FROM clause, the endpoint goes after the Monday data source name.
Items#
monday.com items are a 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 an item as a single row in that table.
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 returns one or multiple users.
Boards#
monday.com boards are where users input all of their data. As such it is one of the core components of the platform, and one of the main objects you will need to be familiar with.
A 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 on the board as well as 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 can return one board, or a collection of boards.
Updates#
monday.com updates contain additional notes and information added to items outside their columns. The main form of communication within the platform takes place in the updates section.