moncli

A Python Client and CLI tool for Monday.com

Table of Contents

• Setup.
• Getting Started...
  • Introducing the MondayClient
  • Managing Boards
  • Working with Columns, Groups, and Items
  • Changing Column Values
  • Posting Updates
  • Uploading Files
• Moncli Entities
  • MondayClient
  • Board
  • Group
  • Item
  • Update
  • File/Asset
  • User
  • Account
  • Other Entities
• Column Values
• Using the API v2 Client
• Creating Custom GraphQL Queries

Setup

To add the moncli package to your project, simply execute the following command within your Python 3 environment using pip. Please note that this package is currently available for Python 3

$ pip3 install moncli

Getting Started...

Introducing the MondayClient

Getting started with the moncli Python package is simple. To begin, create a MondayClient istance using the following code below:

>>> from moncli import MondayClient
>>> client = MondayClient(user_name='[email protected]', api_key_v1='api_key_v1', api_key_v2='api_key_v2')

The MondayClient object is the entry point for all client activities and includes functionality for board, item, tag, and user management.

The api_key_v1 and api_key_v2 parameters represent the user/account monday.com API access keys and can be found by navigating to https://<your_instance_name>.monday.com/admin/integrations/api and copying both the API v1 (personal or company) and API v2 keys.

Additional information regarding MondayClient properties/methods can be found in the MondayClient section below.

Managing Boards

Boards are cornerstones for any Monday.com setup, and Board objects are no exception containing functionality for general data management with columns, groups, and items. The next sections below will provide some general tools regarding Board management.

New boards are created with the MondayClient instance using the create_board method as shown in the example below.

>>> # Import Boardkind enum for parameter input.
>>> from moncli import BoardKind
>>>
>>> # Create a new public board
>>> board_name = 'New Public Board'
>>> board_kind = BoardKind.public
>>> new_board = client.create_board(board_name, board_kind)

Existing boards are also retrieved with the MondayClient using the get_boards method using the ids keyword argument as shown below.

>>> board_ids = ['12345']
>>> retrieved_boards = client.get_boards(ids=[board_ids])

When looking to retrieve only a single board by either id or name, the get_board method is also available on the MondayClient instance using either the id or name keyword argument as shown below.

>>> # Retrieve a board by ID.
>>> board_id = '12345'
>>> board_by_id = client.get_board(id=board_id)
>>>
>>> # Retrieve a board by Name
>>> board_name = 'Existing Public Board'
>>> retrieved_board = client.get_board(name='board_name')

PLEASE NOTE: Querying boards by name is not a built-in feature for Monday.com and may be less performant that searching for a board by ID.

Finally, boards are archived using the archive_board method on the MondayClient instance as shown below.

>>> board_id = '12345'
>>> archived_board = client.archive_board(board_id)

Additional information regarding the Board object can be found in the Board section below.

Working with Columns, Groups, and Items

Adding and Getting Columns

Columns contain metadata that pertains to the data types available to current and future board items. Board columns are represented by the Column object. A new column is created from a Board instance using the add_column method and returned as a Column object as shown below.

>>> from moncli import ColumnType
>>>
>>> new_column = board.add_column(title='New Text Column', column_type=ColumnType.text)

Columns are retrieved from a Board instance using the get_columns method as shown below.

>>> columns = board.get_columns('id', 'title', 'type')

Managing Groups

Groups contain lists of items within a board. In moncli, these groups are realized as Group objects are are retrieved from a Board in the following way.

>>> groups = board.get_groups('id','name')

Groups are also created via a Board instance, as shown below.

>>> group_name = 'New Group'
>>> group = board.add_group(group_name, 'id', 'name')

Once created a group may be duplicated, archived or deleted in the following ways.

>>> # Duplicate a group.
>>> duplicate_group = group.duplicate()
>>>
>>> # Archive a group.
>>> archived_group = group.archive()
>>>
>>> # Delete a group.
>>> deleted_group = group.delete()

Using Items

Items in monday.com represent individual records containing column value data. These items exist inside of the various board groups. Items are created by either a Board or Group instance as shown below. Please note that when creating items from a Board instance, the item is placed into the topmost group if the group_id parameter is not specified.

>>> item_name = 'New Item 1'
>>>
>>> # Add item via board.
>>> group_id = 'group_1'
>>> item = board.add_item(item_name, group_id=group_id)
>>>
>>> # Add item via group.
>>> item = group.add_item(item_name)

An Item object can be created with column values using the optional column_values parameter. Values for this parameter can be input as a dictionary in which each key represents the ID of the column to update and the value represents the value to add.

>>> column_values = {'text_column_1': 'New Text Value'}
>>> new_item_with_values = board.add_item(item_name='New Item With Text Value', column_values=column_values)

Items are also retrieved by either a Client, Board, or Group instance via the get_items methods. It is important to note that the Client instance has access to all items created within the account that are accessible to the user. When using a Board or a Group instance, only items accessible to the user within the respective board or group are available to query.

Once an Item instance is retrieved, it can be moved between groups, duplicated, archived, or deleted as shown in the example below.

>>> # Move item to group.
>>> item.move_to_group('group_2')
>>>
>>> # Duplicate item with updates
>>> item.duplicate(with_updates=True)
>>>
>>> # Archive an item.
>>> item.archive()
>>> 
>>> # Delete an item.
>>> item.delete()

Changing Column Values

The column values of an item may also be retrieved and updated from an Item instance in the following way as shown below.

>>> # First get the column value.
>>> column_value = item.get_column_value(id='text_colunn_1')
>>> # Update the column text
>>> column_value.text = 'Update Text'
>>> # Now update the column value in the item.
>>> item.change_column_value(column_value)

Multiple column values are retrieved and updated from the Item instance using the change_multiple_column_values and get_column_values methods respectively. More information on these methods can be found below in the Item section of this document.

Posting Updates

Updates represent interactions between users within a monday.com account with respect to a given item and are represented in moncli as an Update object. Update instances are retrieved using the get_updates method from either a MondayClient instance, which can retrieve all updates within the account accessible to the login user, or an Item instance, which only has access to updates within the particular item.

Updates are added to an item using the add_update method from the Item instance as shown below.

>>> update = item.add_update('Hello, World!')

Once created, replies are also added to an update using the add_reply method from the Update instance as shown below.

>>> reply = update.add_reply('Right back at you!')

Finally updates are removed from the Item instance using either the delete_update method for removing a specific update, or the clear_all_updates method to remove all updates on the item as shown below.

>>> # Remove one update
>>> item.delete_update(update.id)
>>>
>>> # Remove all updates
>>> item.clear_all_updates()

More information regarding Updates and Replies can be found in the Update and Reply sections in the documentation below.

Uploading Files

Files, or assets, represent files uploaded to items via a file-type column or updates via the add_file method on both Item and Update objects.

When adding files to an item, a file column via the FileColumn object must be identified as the column in which to place the newly uploaded file. This is demonstrated in the example below.

>>> # First get the file column.
>>> file_column = item.get_column_value(id='file_column_1')
>>> # Then upload the file.
>>> asset = item.add_file(file_column, '/users/test/monday_files/test.jpg')

Adding files to an update only requires the file path of the file to upload as shown below.

>>> asset = update.add_file('/users/test/monday_files/test.jpg')

Files are retrieved using the get_files method available on any MondayClient, Item, or Update instance. It is important to note that all files within the account accessible to the user are retrieved from the MondayClient instance, while only files within the respective item or update are retrieved for Item and Update instances respectively.

Currently, the monday.com API only supports removing all files from a file column within an item. This is done using the remove_files method of the Item instance in the example shown below.

>>> # First get the file column.
>>> file_column = item.get_column_value(id='file_column_1')
>>> # Then clear all files.
>>> assets = item.remove_files(file_column)

To remove files from an update, the only option currently available is to delete the update containing the file. This is done using the delete_update method via an Item instance or directly on an Update instance with the delete method.

More information regarding the Asset object is found in the File/Asset section of the documentation below.

Moncli Entities

The moncli client returns entities representing Monday.com objects after executing a successful request to the API. These entities not only contain properties representing the return fields of the query/mutation, but also contain various methods for retrieving other related entities.

Aside from required parameters, entity methods also contain an *args parameter that allows for a collection of custom return field inputs. Simply add the name of the field to return (as defined by the monday.com query) as a string. To return nested fields, simply list out the full path of the field in dot notation (ex. 'items.id' will return items associated with the query with a populated id property.

Optional parameters for moncli entity methods are added as keyword arguments via the *kwargs variable.

MondayClient

This section contains all properties and methods contained within the MondayClient object.

Properties

Name	Type	Description
me	User	The client login user.

Methods

create_board
Create a new board. Returns: moncli.entities.Board

Parameters

Name	Type	Description
board_name	str	The board's name.
board_kind	moncli.enums.BoardKind	The board's kind (public / private / share).
workspace_id	str	Optional workspace id.
template_id	str	Optional board template id.

Example

>>> from moncli import BoardKind
>>> 
>>> board_name = 'New Public Board'
>>> board_kind = BoardKind.public
>>> new_board = client.create_board(board_name, board_kind, 'id', 'name')
>>> new_board
{'id': '12345', 'name': 'New Public Board'}

get_boards
Get a collection of boards.
Returns: list[moncli.entities.Board]

Parameters

Name	Type	Description
limit (Optional)	int	Number of boards to get; the default is 25.
page (Optional)	int	Page number to get, starting at 1.
ids (Optional)	list[str]	A list of boards unique identifiers.
board_kind (Optional)	moncli.enums.BoardKind	The board's kind (public / private / share)
state	moncli.enums.State	The state of the board (all / active / archived / deleted), the default is active.

Example

>>> ids = ['12345']
>>> boards = client.get_boards('id', 'name', ids=ids)
>>> boards
[{'id': '12345', 'name': 'New Public Board'}]

get_board
Get a board by unique identifier or name.
Returns: moncli.entities.Board

Parameters

Name	Type	Description
id	str	The unique identifier of the board to retrieve. NOTE: This parameter is mutually exclusive and cannot be used with 'name'.
name	str	The name of the board to retrieve. NOTE: This parameter is mutially exclusive and cannot be used with 'id'.

Example

>>> id = '12345
>>> board = client.get_board(id, None, 'id', 'name')
>>> board
{'id': '12345', 'name': 'New Public Board'}
>>>
>>> name = 'New Public Board'
>>> board = client.get_board(None, name, 'id', 'name')
>>> board
{'id': '12345', 'name': 'New Public Board'}

get_board_by_id
Get a board by unique identifier.
Returns: moncli.entities.Board

Parameters

Name	Type	Description
id	str	The unique identifier of the board.

Example

>>> id = '12345
>>> board = client.get_board_by_id(id, 'id', 'name')
>>> board
{'id': '12345', 'name': 'New Public Board'}

get_board_by_name
Get a board by name.
Returns: moncli.entities.Board

Parameters

Name	Type	Description
name	str	The name of the board to retrieve.

Example

>>> name = 'New Public Board
>>> board = client.get_board_by_name(name, 'id', 'name')
>>> board
{'id': '12345', 'name': 'New Public Board'}

archive_board
Archive a board.
Returns: moncli.entities.Board

Parameters

Name	Type	Description
board_id	str	The board's unique identifier.

Example

>>> id = '12345'
>>> archived_board = client.archive_board(id, 'id', 'name', 'state')
>>> archived_board
{'id': '12345', 'name': 'New Public Board', 'state': 'archived'}

get_assets
Get a collection of assets by IDs.
Returns: list[moncli.entities.Asset]

Parameters

Name	Type	Description
ids	list[str]	Ids of the assets/files you want to get.

Example

>>> assets_ids = ['12345678']
>>> assets = client.get_assets(assets_ids, 'id', 'name', 'public_url')
>>> assets
[{'id': '12345678', 'name': 'test.jpg', 'public_url': 'https://test.monday.com/files/test.jpg'}]

get_items
Get a collection of items.
Returns: list[moncli.entities.Item]

Parameters

Name	Type	Description
limit (Optional)	int	Number of items to get; the default is 25.
page (Optional)	int	Page number to get, starting at 1.
ids (Optional)	list[str]	A list of items unique identifiers.
newest_first (Optional)	bool	Get the recently created items at the top of the list.

Example

>>> item_ids = ['123456']
>>> items = client.get_items('id', 'name', ids=ids)
>>> items
[{'id': '123456', 'name': 'New Item'}]

get_updates
Get a collection of updates.
Returns: list[moncli.entities.Update]

Parameters

Name	Type	Description
limit (Optional)	int	Number of updates to get; the default is 25.
page (Optional)	int	Page number to get, starting at 1.

Example

>>> updates = client.get_updates('id', 'text_body')
>>> updates
[{'id': '1234567', 'text_body': 'Hello, World!'}]

delete_update
Delete an update.
Returns: moncli.entities.Update

Parameters

Name	Type	Description
id	str	The update's unique identifier.

Example

>>> update_id = '1234567'
>>> deleted_update = client.delete_update(update_id, 'id','text_body')
>>> deleted_update
{'id': '1234567', 'text_body': 'Hello, World!'}

clear_item_updates
Clear an item's updates.
Returns: moncli.entities.Item

Parameters

Name	Type	Description
item_id	str	The item's unique identifier.

Example

>>> item_id = '123456'
>>> item = client.clear_item_updates(item_id, 'id', 'name', 'updates.id')
>>> item
{'id': '123456', 'name': 'New Item', 'updates': []}

create_notification
Create a new notification.
Returns: moncli.entities.Notification

Parameters

Name	Type	Description
text	str	The notification text.
user_id	str	The user's unique identifier.
target_id	str	The target's unique identifier.
target_type	moncli.enums.NotificationTargetType	The target's type (Project / Post)
payload	json	The notification payload.

Example

>>> from moncli.enums import NotificationTargetType
>>>
>>> text = 'Hello, World!'
>>> user_id = '1234'
>>> target_id = '1235'
>>> notification_type = NotificationTargetType.Post
>>> notification = client.create_notification(text, user_id, target_id, notification_type, 'id', 'text')
>>> notification
{'id': '123456789', 'text': 'Hello, World!'}

create_or_get_tag
Create a new tag or get it if it already exists.
Returns: moncli.entities.Tag

Parameters

Name	Type	Description
tag_name	str	The new tag's name
board_id (Optional)	str	The private board id to create the tag at (not needed for public boards).

Example

>>> tag_name = 'New Tag'
>>> tag = client.create_or_get_tag(tag_name, 'id', 'name')
>>> tag
{'id': '1234567890', 'name': 'New Tag'}

get_tags
Get a collection of tags.
Returns: list[moncli.entities.Tag]

Parameters

Name	Type	Description
ids (Optional)	list[str]	The list of tags unique identifiers.

Example

>>> tags_ids = ['1234567890']
>>> tags = client.get_tags('id','name', ids=tags_ids)
>>> tags
[{'id': '1234567890', 'name': 'New Tag'}]

get_users
Get a collection of users.
Returns: list[moncli.entities.User]

Parameters

Name	Type	Description
ids (Optional)	list[str]	A list of users unique identifiers.
kind (Optional)	moncli.entities.UserKind	The kind to search users by (all / non_guests / guests / non_pending).
newest_first (Optional)	bool	Get the recently created users at the top of the list.
limit (Optional)	int	Number of users to get.

Example

>>> ids = ['1234']
>>> users = client.get_users('id', 'name', ids=ids)
>>> users
[{'id': '1234', 'name': 'Test User'}]

get_teams
Get a collection of teams.
Returns: list[moncli.entities.Team]

Parameters

Name	Type	Description
ids (Optional)	list[str]	A list of teams unique identifiers.

Example

>>> ids = ['123']
>>> teams = client.get_teams('id', 'name', ids=ids)
>>> teams
{'id': '123', 'name': 'Test Team'}

get_me
Get the conected user's information.
Returns: moncli.entities.User

Example

>>> user = client.get_me('id','name')
>>> user
{'id': '1234', 'name': 'Test User'}

get_account
Get the connected user's account.
Returns: moncli.entities.Account

Example

>>> account = client.get_account('name', 'first_day_of_the_week')
>>> account
{'name': 'Test Account', 'first_day_of_the_week': 'monday'}

create_workspace
Create a new workspace.
Returns: moncli.entities.Workspace

Parameters

Name	Type	Description
name	str	The workspace's name.
kind	moncli.enums.WorkspaceKind	The workspace's kind (open / closed)
description (Optional)	str	The workspace's description.

Example

>>> from moncli.enums import WorkspaceKind
>>>
>>> name = 'New Workspace'
>>> kind = WorkspaceKind.open
>>> workspace = client.create_workspace(name, kind, 'id', 'name')
>>> workspace
{'id': '12', 'name': 'New Workspace'}

Board

This section contains all properties and methods contained within the Board object.

Properties

Name	Type	Description
activity_logs	list[moncli.entities.ActivityLog]	The board log events.
board_folder_id	str	The board's folder unique identifier.
board_kind	str	The board's kind (public / private / share).
columns	list[moncli.entities.Column]	The board's visible columns.
communication	str	Get the board communication value - typically meeting ID.
description	str	The board's description.
groups	list[moncli.entities.Group]	The board's visible groups.
id	str	The unique identifier of the board.
items	list[moncli.entities.Item]	The board's items (rows).
name	str	The board's name.
owner	moncli.entities.User	The owner of the board.
permissions	str	The board's permissions.
pos	str	The board's position.
state	str	The board's state (all / active / archived / deleted).
subscribers	list[moncli.entities.User]	The board's subscribers.
tags	list[moncli.entities.Tag]	The board's specific tags.
top_group	moncli.entities.Group	The top group at this board.
updated_at	str	The last time the board was updated at (ISO8601 DateTime).
updates	list[moncli.entities.Update]	The board's updates.
views	list[moncli.entities.BoardView]	The board's views.
workspace	moncli.entities.Workspace	The workspace that contains this board (null for main workspace).
workspace_id	str	The board's workspace unique identifier (null for main workspace).

Methods

get_activity_logs
Get the board log events.
Returns: list[moncli.entities.ActivityLog]

Parameters

Name	Type	Description
limit	int	Number of items to get, the default is 25.
page	int	Page number to get, starting at 1.
user_ids	list[str]	User ids to filter.
column_ids	list[str]	Column ids to filter.
group_ids	list[str]	Group ids to filter.
item_ids	list[str]	Item id to filter
from	str	From timespamp (ISO8601).
to	str	To timespamp (ISO8601).

Example

>>> activity_logs = board.get_activity_logs('id','data')
>>> activity_logs
[{'id': '12345678901', 'data': 'INSERT_COLIMN_DATA_HERE'}]

get_views
Get the board's views.
Returns: list[moncli.entities.BoardView]

Parameters

Name	Type	Description
ids (Optional)	str	The list of view unique identifiers.
type (Optional)	str	The view's type.

Example

>>> views = board.get_views('id', 'name')
>>> views
[{'id': 'test_view_1', 'name': 'Test View 1'}]

add_subscribers
Add subscribers to this board.
Returns: list[moncli.entities.User]](#user)

Parameters

Name	Type	Description
user_ids	list[str]	User ids to subscribe to a board.
kind (Optional)	moncli.enums.SubscriberKind	Subscribers kind (subscriber / owner).

Example

>>> user_ids = ['1234']
>>> subscribers = board.add_subscribers(user_ids, 'id', 'name')
>>> subscribers
[{'id': '1234', 'name': 'Test User'}]

get_subscribers
Get board subscribers.
Returns: list[moncli.entities.User]](#user)

Example

>>> subscribers = board.get_subscribers('id', 'name')
>>> subscribers
[{'id': '1234', 'name': 'Test User'}]

delete_subscribers
Remove subscribers from the board.
Returns: list[moncli.entities.User]](#user)

Parameters

Name	Type	Description
user_ids	list[str]	User ids to unsubscribe from board.

Example

>>> user_ids = ['1234']
>>> subscribers = board.delete_subscribers(user_ids, 'id', 'name')
>>> subscribers
[{'id': '1234', 'name': 'Test User'}]

add_column
Create a new column in board.
Returns: moncli.entities.Column

Parameters

Name	Type	Description
title	str	The new column's title.
column_type	moncli.enums.ColumnType	The type of column to create.
defaults (Optional)	json	The new column's defaults.

Example

>>> from moncli.enums import ColumnType
>>>
>>> title = 'New Text Column'
>>> column_type = ColumnType.text
>>> column = board.add_column(title, column_type, 'id','name')
>>> column
{'id': 'text_column_1', 'name': 'New Text Column'}

get_columns
Get the board's visible columns.
Returns: list[moncli.entities.Column]

Parameters

Name	Type	Description
ids (Optional)	str	A list of column unique identifiers.

Example

>>> columns = board.get_columns()
>>> columns
{'id': 'text_column_1', 'name': 'New Text Column'}

add_group
Creates a new group in the board.
Returns: moncli.entities.Group

Parameters

Name	Type	Description
group_name	str	The name of the new group.

Example

>>> group_name = 'New Group'
>>> group = board.add_group(group_name, 'id', 'name')
{'id': 'group_1', 'name': 'New Group'}

get_groups
Get the board's visible groups.
Returns: list[moncli.entities.Group]

Parameters

Name	Type	Description
ids (Optional)	list[string]	A list of group unique identifiers.

Example

>>> groups = board.get_groups('id', 'name')
[{'id': 'group_1', 'name': 'New Group'}]

get_group
Get a group belonging to the board by ID or title.
Returns: moncli.entities.Group

Parameters

Name	Type	Description
id	str	The group's unique identifier. NOTE: This parameter is mutually exclusive and cannot be used with 'title'.
title	str	The group's title. NOTE: This parameter is mutually exclusive and cannot be used with 'id'.

Example

>>> # Get group by id.
>>> group_id = 'group_1'
>>> group = board.get_group(group_id, None, 'id', 'name')
{'id': 'group_1', 'name': 'New Group'}
>>>
>>> # Get group by name.
>>> group_name = 'New Group'
>>> group = board.get_group(None, group_name, 'id', 'name')
{'id': 'group_1', 'name': 'New Group'}

add_item
Create a new item in the board.
Returns: moncli.entities.Item

Parameters

Name	Type	Description
item_name	str	The new item's name.
group_id (Optional)	str	The group's unique identifier.
column_values (Optional)	json	The column values of the new item.

Example

>>> item_name = 'New Item'
>>> item = board.add_item(item_name, 'id', 'name')
>>> item
{'id': '1234567', 'name': 'New Item'}

get_items
Get the board's items (rows).
Returns: list[moncli.entities.Item]

Parameters

Name	Type	Description
ids (Optional)	list[str]	The list of items unique identifiers.
limit (Optional)	int	Number of items to get.
page (Optional)	int	Page number to get, starting at 1.

Example

>>> items = board.get_items('id', 'name')
>>> items
[{'id': '1234567', 'name': 'New Item'}]

get_items_by_column_values
Search items in this board by their column values.
Returns: list[moncli.entities.Item]

Parameters

Name	Type	Description
column_value	moncli.entites.ColumnValue	The column value to search on.
limit (Optional)	int	Number of items to get.
page (Optional)	int	Page number to get, starting at 1.
column_id (Optional)	str	The column's unique identifier.
column_value (Optional)	str	The column value to search items by.
column_type (Optional)	str	The column type.
state (Optional)	moncli.enumns.State	The state of the item (all / active / archived / deleted), the default is active.

Example

>>> column_id = 'test_column'
>>> column_value = board.get_column_value(column_id)
>>> column_value.text = 'Search Text'
>>> items = board.get_items_by_column_values(column_value, 'id', 'name')
>>> items
[{'id': '1234567', 'name': 'New Item'}]

get_column_value
Create a column value from a board's column.
Returns: moncli.entities.ColumnValue

Parameters

Name	Type	Description
id	str	The column's unique identifier. NOTE: This parameter is mutually exclusive and cannot be used with 'title'
title	str	The column's title. NOTE: This parameter is mutually exclusive and cannot be used with 'id'

Example

>>> column_value = board.get_column_value('test_column', 'Test Column')
>>> column_value
{'id': 'test_column', 'name': 'Test Column', 'value': '{\"text\": \"Test Value\"}'}

create_webhook
Create a new webhook.
Returns: moncli.entities.Webhook

Parameters

Name	Type	Description
url	str	The webhook URL.
event	moncli.enums.WebhookEventType	The event to listen to (incoming_notification / change_column_value / change_specific_column_value / create_item / create_update).
config (Optional)	dict	The webhook config.

Example

>>> from moncli.enums import WebhookEventType
>>>
>>> url = 'http://test.website.com/webhook/test'
>>> event = WebhookEventType.create_item
>>> webhook = board.create_webhook(url, event, 'id', 'board_id')
>>> webhook
{'id': '2345', 'board_id': '12345'}
>>>
>>> # Create a webhook using the config parameter.
>>> event = WebhookEventType.change_specific_column_value
>>> config = {'columnId': 'column_1'}
>>> webhook = board.create_webhook(url, event, 'id', 'board_id', config=config)
>>> webhook
{'id': '2346', 'board_id': '12345'}

delete_webhook
Delete a new webhook.
Returns: moncli.entities.Webhook

Parameters

Name	Type	Description
id	str	The webhook's unique identifier.

Example

>>> webhook_id = '2345'
>>> webhook = board.delete_webhook(webhook_id, 'id', 'board_id')
>>> webhook
{'id': '2345', 'board_id': '12345'}

get_workspace
Get the board's workspace that contains this board (null for main workspace).
Returns: moncli.entities.Workspace

Example

>>> workspace = board.get_workspace('name', 'kind')
>>> workspace
{'name': 'New Workspace', 'kind': 'open'}

Group

This section contains all properties and methods contained within the Group object.

Properties

Name	Type	Description
archived	bool	Is the group archived or not.
color	str	The group's color.
deleted	bool	Is the group deleted or not.
id	str	The group's unique identifier.
items	[list[moncli.entities.Item]]	The items in the group.
position	str	The group's position in the board.
title	str	The group's title.

Methods

duplicate
Duplicate this group.
Returns: moncli.entities.Group

Parameters

Name	Type	Description
add_to_top (default=False)	bool	Should the new group be added to the top.
group_title (Optional)	str	The group's title.

Example

>>> duplicate = group.duplicate('id', 'name')
>>> duplicate
{'id': 'group_2', 'name': 'New Group (Duplicate)'}

archive
Archives this group.
Returns: moncli.entities.Group

Example

>>> archived_group = group.archive('id', 'name', 'archived')
>>> archived_group
{'id': 'group_1', 'name': 'New Group', 'archived': True}

delete
Delete this group.
Returns: moncli.entities.Group

Example

>>> deleted_group = group.delete('id', 'name', 'deleted')
>>> archived_group
{'id': 'group_1', 'name': 'New Group', 'deleted': True}

add_item
Add item to this group.
Returns: moncli.entities.Item

Parameters

Name	Type	Description
item_name	str	The new item's name.
column_values (Optional)	json	The column values of the new item.

Example

>>> item_name = 'New Item 1'
>>> item = group.add_item(item_name, 'id', 'name')
>>> item
{'id': 1234567', 'name': 'New Item 1}

get_items
Get items from this group.
Returns: list[moncli.entities.Item]

Parameters

Name	Type	Description
limit (Optional)	int	Number of items to get; the default is 25.
page (Optional)	int	Page number to get, starting at 1.
ids (Optional)	list[str]	A list of items unique identifiers.
newest_first (Optional)	bool	Get the recently created items at the top of the list.

Example

>>> items = group.get_items('id', 'name')
>>> items
[{'id': '1234567', 'name': 'New Item 1'}]

Item

This section contains all properties and methods contained within the Board object.

Properties

Name	Type	Description
assets	list[moncli.entities.Asset]	The item's assets/files.
board	moncli.entities.Board	The board that contains this item.
column_values	list[moncli.entities.ColumnValue]	The item's column values.
created_at	str	The item's create date.
creator	moncli.entities.User	The item's creator.
creator_id	str	The item's unique identifier.
group	moncli.entities.Group	The group that contains this item.
id	str	The item's unique identifier.
name	str	The item's name.
state	str	The board's state (all / active / archived / deleted)
subscriber	moncli.entities.User	The pulse's subscribers.
updated_at	str	The item's last update date.
updates	moncli.entities.Update	The item's updates.

Methods

add_file
Add a file to a column value.
Returns: moncli.entities.Asset

Parameters

Name	Type	Description
file_column	moncli.entities.FileValue	The file column value to be updated.
file_path	str	The file path.

Example

>>> file_column = item.get_column_value(id='file_column_1')
>>> file_path = '/users/test/monday_files/test.jpg'
>>> asset = item.add_file(file_column, file_path, 'id', 'name', 'url')
>>> asset
{'id': '1234567890', 'name': 'test.jpg', 'url': 'https://test.monday.com/files/test.jpg'}

get_files
Retrieves the file assets for the login user's account.
Returns: list[moncli.entities.Asset]

Parameters

Name	Type	Description
column_ids (optional)	list[str]	A list of column IDs from which to retrieve file assets.

Example

>>> assets = item.get_files('id', 'name', 'url')
>>> assets
[{'id': '1234567890', 'name': 'test.jpg', 'url': 'https://test.monday.com/files/test.jpg'}]

remove_files
Removes files from a column value.
Returns: list[moncli.entities.Asset]

Parameters

Name	Type	Description
file_column	moncli.entities.FileValue	The file column value to be updated.

Example

>>> file_column = item.get_column_value(id='file_column_1')
>>> item = item.remove_files(file_column, 'id', 'name')
>>> item
{'id': '1234567', 'name': 'New Item 1'}

get_board
Get the board that contains this item.
Returns: moncli.entities.Board

Example

>>> board = item.get_board('id', 'name')
>>> board
{'id': '12345', 'name': 'New Public Board'}

get_creator
Get the item's creator.
Returns: moncli.entities.User

Example

>>> creator = item.get_creator('id', 'name')
>>> creator
{'id': '1234', 'name': 'Test User'}

get_column_values
Get the item's column values.
Returns: list[moncli.entities.ColumnValue]

Example

>>> column_values = item.get_column_values('id', 'title')
>>> column_values
[{'id': 'text_column_1', 'title': 'New Text Column'}]

get_column_value
Get an item's column value by ID or title.
Returns: moncli.entities.ColumnValue

Parameters

Name	Type	Description
id	str	The column's unique identifier. NOTE: This parameter is mutually exclusive and cannot be used with 'title'.
title	str	The column's title. NOTE: This parameter is mutually exclusive and cannot be used with 'id'.

Example

>>> # Get column value by id.
>>> column_id = 'text_column_1'
>>> column_value = item.get_column_value(id=column_id)
>>> column_value
{'id': 'text_column_1', 'title': 'New Text Column'}
>>> # Get column value by title.
>>> column_title = 'New Text Column'
>>> column_value = item.get_column_value(title=column_title)
>>> column_value
{'id': 'text_column_1', 'title': 'New Text Column'}

change_column_value
Change an item's column value.
Returns: moncli.entities.Item

Parameters

Name	Type	Description
column_value	moncli.entities.ColumnValue	The column value to update.

Example

>>> # Get and update column value before changing it.
>>> column_value = item.get_column_value(id='text_column_1')
>>> column_value.text = 'Updated Text'
>>> item.change_column_value(column_value)

change_multiple_column_values
Change the item's column values.
Returns: moncli.entities.Item

Parameters

Name	Type	Description
column_values	list[moncli.entities.ColumnValue] / dict	The column value to update. NOTE: This value can either be a list of moncli.entities.ColumnValue objects or a formatted dictionary.

Example

>>> # Get and update column value before changing it.
>>> column_value = item.get_column_value(id='text_column_1')
>>> column_value.text = 'Updated Text'
>>> # Update column value as ColumnValue list.
>>> item.change_multiple_column_values([column_value])
>>> # Update column value as dict.
>>> item.change_multiple_column_values({'text': 'Updated Text'})

create_subitem
Create subitem.
Returns: moncli.entities.Item

Parameters

Name	Type	Description
item_name	str	The new item's name.
column_values (Optional)	json	The column values of the new item.

Example

>>> item_name = 'New Subitem'
>>> subitem = item.create_subitem(item_name, 'id', 'name', 'board.name')
>>> subitem
{'id': '1234568', 'name': 'New Subitem', 'board': {'name': 'Some monday.com-generated Board'}}

move_to_group
Move item to a different group.
Returns: moncli.entities.Item

Parameters

Name	Type	Description
group_id	str	The group's unique identifier.

Example

>>> group_id = 'group_2'
>>> item = item.move_to_group(group_id, 'id', 'group.id', 'group.name')
>>> item
{'id': '1234567', 'group':{'id': 'group_2', 'name': New Group 2'}}

archive
Archive this item.
Returns: moncli.entities.Item

Example

>>> item = item.archive('id', 'state')
>>> item
{'id': '1234567', 'state': 'archived'}

delete
Delete this item.
Returns: moncli.entities.Item

Example

>>> item = item.delete('id', 'state')
>>> item
{'id': '1234567', 'state': 'deleted'}

duplicate
Duplicate this item.
Returns: moncli.entities.Item

Parameters

Name	Type	Description
with_updates (Optional)	bool	Duplicate with the item's updates.

Example

>>> duplicate = item.duplicate('id', 'name')
>>> duplicate
{'id': '1234568','name': 'New Item 2'}

add_update
Create a new update for this item.
Returns: moncli.entities.Update

Parameters

Name	Type	Description
body	str	The update text.
parent_id (Optional)	str	The parent post identifier.

Example

>>> body = 'Hello, World!'
>>> update = item.add_update(body, 'id', 'text_body')
>>> update
{'id': '123456781', 'text_body': 'Hello, World!'}

get_updates
Get updates for this item.
Returns: moncli.entities.Update

Parameters

Name	Type	Description
limit (Optional)	int	Number of updates to get; the default is 25.
page (Optional)	int	Page number to get, starting at 1.

Example

>>> updates = item.get_updates()
>>> updates 
[{'id': '123456781', 'text_body': 'Hello, World!'}]

delete_update
Delete item update.
Returns: moncli.entities.Update

Parameters

Name	Type	Description
update_id	str	The update's unique identifier.

Example

>>> update_id = '123456781'
>>> item.delete_update(update_id)

clear_updates
Clear all updates for item. Returns: moncli.entities.Item

Example

>>> item = item.clear_updates('id', 'updates.id')
>>> item
{'id': '123456781', 'updates': []}

Update

Properties

Name	Type	Description
assets	list[moncli.entities.Asset]	The update's assets/files.
body	str	The update's html formatted body.
created_at	str	The update's creation date.
creator	moncli.entities.User	The update's creator.
creator_id	str	The unique identifier of the update creator.
id	str	The update's unique identifier.
item_id	str	The update's item ID.
replies	list[moncli.entities.Reply]	The update's replies.
text_body	str	The update's text body.
updated_at	str	The update's last edit date.

Methods

get_creator
Get the update's creator.
Returns: moncli.entities.User

Example

>>> creator = update.get_creator('id', 'name')
>>> creator
{'id': '1234', 'name': 'Test User'}

add_reply
Add reply to update.
Returns: moncli.entities.Reply

Parameters

Name	Type	Description
body	str	The text body of the reply.

Example

>>> body = 'Right back at you!'
>>> update.add_reply(body)

get_replies
Add reply to update.
Returns: moncli.entities.Reply

Example

>>> replies = update.get_replies('text_body')
>>> replies
{'text_body': 'Right back at you!'}

add_file
Add a file to update.
Returns: moncli.entities.Reply

Parameters

Name	Type	Description
file_path	str	The path to the file to upload.

Example

>>> file_path = '/users/test/monday_files/test.jpg'
>>> asset = update.add_file(file_path, 'name', 'url')
>>> asset
{'name': 'test.jpg', 'url': 'https://test.monday.com/files/test.jpg'}

get_files
Get update's files.
Returns: moncli.entities.Reply

Example

>>> assets = update.get_files('name', 'url')
>>> assets
[{'name': 'test.jpg', 'url': 'https://test.monday.com/files/test.jpg'}]

delete Delete an update.
Returns: moncli.entities.Reply

Example

>>> update.delete()

File

Properties

Name	Type	Description
id	str	The file's unique identifier.
created_at	str	The file's creation date.
file_extension	str	The file's extension.
file_size	int	The file's size in bytes.
name	str	The file's name.
public_url	str	Public url to the asset, valid for 1 hour.
uploaded_by	moncli.entities.User	The user who uploaded the file.
url	str	The file url.
url_thumbnail	str	Url to view the asset in thumbnail mode. Only available for images.

Methods

get_uploaded_by_user
Get the user who uploaded the file.
Returns: moncli.entities.User

Example

>>> uploaded_by = asset.get_uploaded_by_user('id', 'name')
>>> uploaded_by
{'id': '1234', 'name': 'Test User'}

User

Properties

Name	Type	Description
account	moncli.entities.user.Account	The user's account.
birthday	str	The user's birthday.
country_code	str	The user's country code.
created_at	str	The user's creation date.
email	str	The user's email.
enabled	bool	Is the user enabled or not.
id	str	The user's unique identifier.
is_guest	bool	Is the user a guest or not.
is_pending	bool	Is the user a pending user.
is_view_only	bool	Is the user a view only user or not.
join_date	str	The date the user joined the account.
location	str	The user' location.
mobile_phone	str	The user's mobile phone number.
name	str	The user's name.
phone	str	The user's phone number.
photo_original	str	The user's photo in the original size.
photo_small	str	The user's photo in small size (150x150).
photo_thumb	str	The user's photo in thumbnail size (100x100).
photo_thumb_small	str	The user's photo in small thumbnail size (50x50).
photo_tiny	str	The user's photo in tiny size (30x30).
teams	list[moncli.entities.user.Team]	The teams the user is a member in.
time_zone_identifier	str	The user's time zone identifier.
title	str	The user's title.
url	str	The user's profile url.
utc_hours_diff	int	The user's UTC hours difference.

Methods

get_account
Get the user's account.
Returns: moncli.entities.Account

Example

>>> account = user.get_account('id', 'name')
>>> account
{'id': '1', 'name': 'Test Account'}

get_teams
Get teams the user is a member in.
Returns: list[moncli.entities.Team]

Example

>>> teams = user.get_teams('id', 'name')
>>> teams
[{'id': '12', 'name': 'Test Team'}]

send_notification
Create a new notification.
Returns: moncli.entities.Notification

Parameters

Name	Type	Description
text	str	The notification text.
target_id	str	The target's unique identifier.
target_type	moncli.enums.NotificationTargetType	The target's type (Project / Post)
payload (Optional)	json	The notification payload.

Example

>>> from moncli.enums import NotificationTargetType
>>>
>>> text = 'Hello, World!'
>>> target_id = '1235'
>>> notification_type = NotificationTargetType.Post
>>> notification = user.create_notification(text, target_id, notification_type, 'id', 'text')
>>> notification
{'id': '123456789', 'text': 'Hello, World!'}

Other Entities

This section contains property and method information of other entities available using moncli.

Board View

Properties

Name	Type	Description
account_id	str	The user's payment account.
created_at	str	The activity log's created date.
data	str	The item's column values in string form.
entity	str	The monday.com object being updated.
id	str	The activity log's unique identifier.
user_id	str	The user who performed the change.

Column

Properties

Name	Type	Description
archived	bool	Is the column archived or not.
id	str	The column's unique identifier.
pos	str	The column's position in the board.
settings_str	strThe column's settings in a string form.
settings	moncli.entities.Settings	The settings in entity form (status / dropdown)
title	str	The column's title.
type	str	The column's type.
column_type	moncli.entities.ColumnType	The column's type as an enum.
width	int	The column's width.

Notification

Properties

Name	Type	Description
id	str	The notification`s unique identifier.
text	str	the notification text.

Tag

Properties

Name	Type	Description
color	str	The tag's color.
id	str	The tag's unique identifier.
name	str	The tag's name.

Webhook

Properties

Name	Type	Description
board_id	str	The webhook's board id.
id	str	The webhook's unique identifier.
is_active	bool	If the webhook is still active.

Workspace

Properties

Name	Type	Description
description	str	The workspace's description.
id	int	The workspace`s unique identifier.
kind	moncli.enums.WorkspaceKind	The workspace's kind (open / closed).
name	str	The workspace's name.

Account

Properties

Name	Type	Description
first_day_of_the_week	str	The first day of the week for the account (sunday / monday).
id	int	The account's unique identifier.
logo	str	The account's logo.
name	str	The account's name.
plan	moncli.entities.Plan	The account's payment plan.
show_timeline_weekends	bool`	Show weekends in timeline.
slug	str	The account's slug.

Methods

get_plan
Get the account's payment plan.
Returns: list[moncli.entities.Plan]

Example

>>> plan = team.get_plan('version')
>>> plan
{'version': '33'}

Team

Properties

Name	Type	Description
id	int	The team's unique identifier.
name	str	The team's name.
picture_url	str	The team's picture url.
users	moncli.entities.User	The users in the team.

Methods

get_users
Get the users in the team.
Returns: list[moncli.entities.User]

Example

>>> users = team.get_users('id', 'name')
>>> users
[{'id': '1234', 'name': 'Test User}]

Plan

Properties

Name	Type	Description
max_users	int	The maximum users allowed in the plan.
period	str	The plan's time period.
tier	str	The plan's tier.
version	int	The plan's version.

Column Values

A ColumnValue can also be created without the need for Board or Item objects using the universal create_column_value function. This method creates a ColumnValue object from the input column id and column_type parameter (with an optional title field). The ColumnType enum is used for the column_type parameter, and all values available for column value updating are listed below:

• name
• text
• long_text
• numbers
• status
• dropdown
• people
• world_clock
• country
• email
• phone
• link
• date
• timeline
• tags
• hour
• week
• checkbox
• rating
• file

An example for creating a new ColumnValue object is shown below. Please note that the board column IDs must be pre-defined and know prior to using this function effectively.

>>> # Empty checkbox column value
>>> from moncli import create_column_value
>>>
>>> new_empty_checkbox_column_value = create_column_value(id='checkbox_column_1', column_type=ColumnType.checkbox)
>>> new_empty_checkbox_column.checked
False

ColumnValue objects are also created from Board objects using the get_column_value method. This method is especially useful when working with column values for columns with settings, status and dropdown columns in particular. The method above is used as shown below.

>>> # Get status column by column id.
>>> status_column_id = 'status'
>>> status = board.get_column_value('status')
>>> 
>>> # Or get status column by title.
>>> status = board.get_column_value(title='Status')
>>>
>>> status.label = 'Done'

For more information regarding the ColumnValue object type specific properties, please refer to the Available column value types section below.

Using column values

With access to the ColumnValue objects, item column values can effectively be updated using the API. Updating the value of the ColumnValue object is simply a matter of updating the value of the type-specific property for the column value to be updated. An example with a simple text column and more complex week column are shown below.

>>> # Updating the value of a text column
>>> text_column_value.text = 'Changed text here'
>>>
>>> # Updating the value of a week column
>>> week_column_value.start_date = '2019-09-09'
>>> week_column_value.end_date = '2019-09-15'

For more information regarding the ColumnValue object type specific properties, please refer to the Available column value types section below.

Available column value types

Column values are managed by various ColumnValue subclasses that contain the type-specific properties for updating. This section provides an exhastive list of all available ColumnValue subclasses that can be used for updating item column values.

TextValue

ColumnType: text

Properties:

• text (str) - input text string

NumberValue

ColumnType: numbers

Properties:

• number (int/flt) - input integer or float value

StatusValue

ColumnType: status

Properties:

• index (int) - the index of the status (required)
• label (str) - the label of the status (required)

Methods:

• change_status_by_index (index: int) - changes the status by the index according to status settings
• change_status_by_label (label: str) - changes the status by the label according to status settings

DropdownValue

ColumnType: dropdown

Properties:

• ids (list[int]) - dropdown value IDs (required)
• labels (list[str]) - dropdown value labels (required)

Notes:

• ids and labels properties are mutually exclusive and cannot both be used

PeopleColumn

ColumnType: people

Properties:

• persons_and_teams (list) - people by ID and kind ('person' or 'team')

Methods:

• add_people (id: int, kind: PeopleKind) - adds a person or team
• remove_people (id: int) - removes a person or team by id

Usage:

>>> # Adding people
>>> people_value.add_people(id=12345, kind=PeopleKind.person)
>>> people_value.add_people(id=67890, kind=PeopleKind.team)
>>> people_value.persons_and_teams
[{'id': 12345, 'kind': 'person'}, {'id': 67890, 'kind': 'team'}]
>>>
>>> # Removing people
>>> people_value.remove_people(id=67890)
>>> people_value.persons_and_teams 
[{'id': 12345, 'kind': 'person'}]

Timezone Value

ColumnType: world_clock

Properties:

• timezone (str) - input tz database timezone string

Notes:

• Full list of timezones avaliable here.

CountryValue

ColumnType: country

Properties:

• country_code (str) - input ISO2 country code string (required)
• country_name (str) - input country name (required)

Notes:

• Full list of country_code and country_name values available here

EmailValue

ColumnType: country

Properties:

• email (str) - input email address (required)
• text (str, default: email) - input email value label

PhoneValue

ColumnType: phone

Properties:

• phone (str) - input phone number string as only digits (required)
• country_short_name (str) - input ISO2 country code string (required)

Notes:

• Full list of country_code and country_name values available here

LinkValue

ColumnType: link

Properties:

• url (str) - input link url (required)
• text (str, default: url) - input link value label

DateValue

ColumnType: date

Properties:

• date (str) - UTC date string in 'YYYY-MM-dd' format (required)
• time (str, default: '00:00:00') - UTC time string in hh:mm:ss format

TimelineValue

ColumnType: timeline

Properties:

• from_date (str) - UTC date string in 'YYYY-MM-dd' format (required)
• to_date (str) - UTC date string in 'YYYY-MM-dd' format (required)

TagsValue

ColumnType: tags

Properties:

• tag_ids (list[int]) - tag IDs

HourValue

ColumnType: hour

Properties:

• hour (int) - hour value
• minute (int, default: 0) - minute value

WeekValue

ColumnType: week

Properties:

• start_date (str) - UTC date string in 'YYYY-MM-dd' format (required)
• end_date (str) - UTC date string in 'YYYY-MM-dd' format (required)

CheckboxColumn

ColumnType: checkbox

Properties:

• checked (bool) - is checked

RatingValue

ColumnType: rating

Properties:

• rating (int) - rating value (0-5)

Using the API v2 Client

(Coming soon...)

Creating Custom GraphQL Queries

(Coming soon...)

Additional Questions/Feature Requests:

Please feel free to log an issue or request a new feature by submitting a new issue or reaching out to me at [email protected]. Thank you and happy coding!!!