A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The monday.com API is how an app or AI agent works with a monday account: reading boards and items, creating items, changing column values, posting updates, and managing groups and workspaces. Access is granted through a token and a set of permission scopes, each naming a resource and whether the call reads or writes, and an agent is limited to what those scopes and the user's own visibility allow. Versions are dated and selected per call, and monday can push board events to a registered webhook.
How an app or AI agent connects to monday.com determines what it can reach. There is a route for making calls, a route for receiving events, and a first-party server that exposes monday.com tools to agents, and each is governed by the token behind it and the permissions that token carries.
The monday.com Platform API is a single GraphQL endpoint at https://api.monday.com/v2. An app sends a query to read or a mutation to write, and selects a dated version through the API-Version header. A call authenticates with a token in the Authorization header.
monday.com publishes a first-party MCP server that lets an agent call monday.com through the Model Context Protocol. The hosted remote server connects through OAuth 2.0 with monday.com as the identity provider, and does not store customer tokens, while a local server is run from the npm package @mondaydotcomorg/monday-api-mcp with an API token. It exposes over 50 tools across boards, items, columns, workspaces, users, and more. The source is at github.com/mondaycom/mcp.
Webhooks deliver the events that have been chosen on a board, like an item created or a column value changed, to a receiver URL. On creation, monday.com sends a challenge that the receiver must echo back to confirm the URL.
An app uses the OAuth 2.0 authorization-code flow, sending the user to auth.monday.com to approve a chosen set of scopes, then exchanging the code for an access token. The token carries only the scopes the user granted, so the app reaches only what those scopes allow. Tokens do not expire and stay valid until the user uninstalls the app.
An installed app receives a token that carries an explicit set of permission scopes, set when the app is configured, which restrict the queries and mutations it can call. It is the least-privilege choice, because the scopes bound to the token cap what it can reach.
A personal token is tied to one user and inherits all of that user's permissions in the monday.com UI, with no extra scope restriction. If the user cannot see a board in the UI, the token cannot reach it through the API either. It suits scripts and a single user's own automations.
The monday.com API is split into areas an agent can act on, like boards, items, columns, updates, and workspaces. Each operation is either a query that reads or a mutation that writes, and each one names the permission it needs.
Read boards and their structure, and create, duplicate, archive, and delete boards.
Read items, create items on a board, and archive, delete, and move items between groups.
Read a board's columns, create a column, and change the values stored against an item.
Read a board's groups, and create, duplicate, and delete groups.
Read the updates posted on items, post a new update, like an update, and delete one.
Read the authenticated user, read other users in the account, and read teams.
Read workspaces, and create and delete a workspace.
Read the webhooks registered on a board, create a webhook, and delete one.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
BoardsRead boards and their structure, and create, duplicate, archive, and delete boards.5 | ||||||
| POST | query boards | Read boards and their fields, with filters for ids, state, and pagination. | read | boards:read | Current | |
A query reaches only the boards the connected user can already see in the monday.com UI. Acts onboard Permission (capability) boards:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation create_board | Create a board, setting its name, kind, and optional workspace and template. | write | boards:write | Current | |
Creates a real board in the account. Acts onboard Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation duplicate_board | Duplicate an existing board, optionally with its items and updates. | write | boards:write | Current | |
Duplicating with content can be a large operation under the complexity budget. Acts onboard Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation archive_board | Archive a board so it no longer appears in the active list. | write | boards:write | Current | |
Archiving is reversible from the monday.com UI. Acts onboard Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation delete_board | Delete a board. | write | boards:write | Current | |
Removes the board and the items it holds. Acts onboard Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ItemsRead items, create items on a board, and archive, delete, and move items between groups.6 | ||||||
| POST | query items | Read items by id, including their column values, group, and updates. | read | boards:read | Current | |
Item reads, including column values, are governed by the boards:read scope. Acts onitem Permission (capability) boards:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | query items_page | Read a page of items on a board, with cursor-based pagination and filtering rules. | read | boards:read | Current | |
items_page is the paginated way to read a board's items in bulk. Acts onitem Permission (capability) boards:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation create_item | Create an item on a board, in a chosen group, with initial column values. | write | boards:write | Current | |
An item name longer than 255 characters returns ItemNameTooLongException. Acts onitem Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook event create_itemRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation archive_item | Archive an item so it leaves the active board view. | write | boards:write | Current | |
Archiving is reversible from the monday.com UI. Acts onitem Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook event item_archivedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation delete_item | Delete an item from a board. | write | boards:write | Current | |
Removes the item and its column values. Acts onitem Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook event item_deletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation move_item_to_group | Move an item to a different group on the same board. | write | boards:write | Current | |
Changes the item's group within its board. Acts onitem Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Columns & valuesRead a board's columns, create a column, and change the values stored against an item.5 | ||||||
| POST | query columns | Read the columns defined on a board, including their type and settings. | read | boards:read | Current | |
Columns are read as part of the board they belong to. Acts oncolumn Permission (capability) boards:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation create_column | Create a column on a board, setting its title and type. | write | boards:write | Current | |
Adds a new column to the board's structure. Acts oncolumn Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation change_column_value | Change one column's value on an item, passing the value as JSON. | write | boards:write | Current | |
An incorrectly formatted value returns ColumnValueException. Acts oncolumn value Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook event change_column_valueRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation change_simple_column_value | Change one column's value using a plain string rather than JSON. | write | boards:write | Current | |
The simple form covers the common column types without JSON formatting. Acts oncolumn value Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook event change_column_valueRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation change_multiple_column_values | Change several column values on an item in a single call. | write | boards:write | Current | |
Batching values into one call reduces the number of mutations. Acts oncolumn value Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook event change_column_valueRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
GroupsRead a board's groups, and create, duplicate, and delete groups.3 | ||||||
| POST | query groups | Read the groups on a board, the rows that organize its items. | read | boards:read | Current | |
Groups are read as part of the board they belong to. Acts ongroup Permission (capability) boards:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation create_group | Create a group on a board. | write | boards:write | Current | |
Adds a new group to the board's structure. Acts ongroup Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation delete_group | Delete a group from a board. | write | boards:write | Current | |
Deleting a board's only group returns DeleteLastGroupException. Acts ongroup Permission (capability) boards:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
UpdatesRead the updates posted on items, post a new update, like an update, and delete one.4 | ||||||
| POST | query updates | Read the updates, the comment-style posts, on items and boards. | read | updates:read | Current | |
Reads only the updates the connected user can already see. Acts onupdate Permission (capability) updates:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation create_update | Post an update on an item, optionally as a reply to another update. | write | updates:write | Current | |
Anything posted is visible to everyone who can see the item. Acts onupdate Permission (capability) updates:writeVersionAvailable since the API’s base version Webhook event create_updateRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation like_update | Add a like to an existing update. | write | updates:write | Current | |
Records a like from the connected user. Acts onupdate Permission (capability) updates:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation delete_update | Delete an update. | write | updates:write | Current | |
Removes the update and its replies. Acts onupdate Permission (capability) updates:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Users & teamsRead the authenticated user, read other users in the account, and read teams.3 | ||||||
| POST | query me | Read the profile of the connected user, including id, name, and email. | read | me:read | Current | |
Returns the identity behind the token, which is the lowest-level read. Acts onuser Permission (capability) me:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | query users | Read other users in the account, with filters and cursor-based pagination. | read | users:read | Current | |
Returns people in the account, including their names and email addresses. Acts onuser Permission (capability) users:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | query teams | Read the teams in the account and their members. | read | teams:read | Current | |
Reads team structure, separate from the users:read scope for people. Acts onteam Permission (capability) teams:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WorkspacesRead workspaces, and create and delete a workspace.3 | ||||||
| POST | query workspaces | Read the workspaces in the account, the containers that hold boards. | read | workspaces:read | Current | |
Reads only the workspaces the connected user can already see. Acts onworkspace Permission (capability) workspaces:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation create_workspace | Create a workspace to hold boards. | write | workspaces:write | Current | |
Adds a new top-level container to the account. Acts onworkspace Permission (capability) workspaces:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation delete_workspace | Delete a workspace. | write | workspaces:write | Current | |
Removes the workspace and affects the boards inside it. Acts onworkspace Permission (capability) workspaces:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WebhooksRead the webhooks registered on a board, create a webhook, and delete one.3 | ||||||
| POST | query webhooks | Read the webhooks registered on a board. | read | webhooks:read | Current | |
Lists the event subscriptions on a board. Acts onwebhook Permission (capability) webhooks:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation create_webhook | Create a webhook on a board for a chosen event, with a URL to receive it. | write | webhooks:write | Current | |
monday.com sends a challenge to the URL on creation, which must be echoed back. Acts onwebhook Permission (capability) webhooks:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | mutation delete_webhook | Delete a webhook from a board. | write | webhooks:write | Current | |
Stops the event subscription it removes. Acts onwebhook Permission (capability) webhooks:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
monday.com can notify an app or AI agent when something happens on a board, like an item being created or a column value changing, instead of the app repeatedly asking. monday.com posts the event payload to a webhook URL that has been registered for the chosen events.
| Event | What it signals | Triggered by |
|---|---|---|
create_item | Fires when an item is created on a board the webhook is registered to. | mutation create_item |
change_column_value | Fires when any column value on an item changes. | mutation change_column_valuemutation change_simple_column_valuemutation change_multiple_column_values |
change_status_column_value | Fires when a status column value on an item changes, a narrower signal than the general column change. | mutation change_column_valuemutation change_simple_column_valuemutation change_multiple_column_values |
create_update | Fires when an update is posted on an item. | mutation create_update |
item_archived | Fires when an item is archived. | mutation archive_item |
item_deleted | Fires when an item is deleted. | mutation delete_item |
monday.com limits how much an app or AI agent can call, through a complexity budget that meters the size of each query and a daily cap on the number of calls, both varying by account plan.
monday.com meters each call by complexity, a cost that reflects how much work the query asks for, rather than counting requests alone. Reads and writes draw on a combined per-minute complexity budget that follows a sliding 60-second window: a personal token has 10M points per minute (1M on trial or free accounts), and an app token has 5M points per minute. A query can add the complexity field to see its cost and the remaining budget before and after it runs. On top of that, each account has a daily call cap that varies by plan, from 1,000 calls on lower tiers up to 10,000 on Pro and 25,000 on Enterprise as soft limits, resetting at midnight UTC. A per-IP limit of 5,000 requests per 10 seconds and a concurrency limit of 40 to 250 simultaneous requests by tier also apply. Going over returns HTTP 429, and the RateLimit and RateLimit-Policy response headers report the current state.
List-style reads page with a cursor. The items_page query returns a page of items along with a cursor that fetches the next page, and queries like users use cursor-based pagination with a limit. As of the 2026-07 and 2026-10 versions, the users query defaults to 200 results per page with a maximum of 1,000. Exceeding a page limit returns InvalidArgumentException.
An item name is capped at 255 characters, returning ItemNameTooLongException above it, and a board is capped at around 10,000 items, returning ItemsLimitationException. A single GraphQL call is bounded by the per-minute complexity budget rather than a fixed byte size, so a very large query fails on complexity rather than length.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 200 | ColumnValueException | A successful HTTP request carrying an application error in the body. monday.com returns HTTP 200 with an errors array for problems like a wrongly formatted column value, an invalid board, column, or user id (InvalidColumnIdException, InvalidBoardIdException, InvalidUserIdException), a missing resource (ResourceNotFoundException), or an item name over 255 characters (ItemNameTooLongException). | Inspect the errors array in the 200 response, not just the HTTP status, and correct the named field before resending. |
| 400 | Bad request / JsonParseException | The query is malformed or the JSON body could not be parsed. | Fix the query structure or the JSON and resend. |
| 401 | Unauthorized | The API token is missing or invalid, or the calling IP address is restricted by an account admin. | Send a valid token in the Authorization header, and check any account IP restrictions. |
| 403 | UserUnauthorizedException | The user behind the token lacks permission for the operation, or the account is inactive or view-only. A missing OAuth scope surfaces as missingRequiredPermissions. | Grant the missing scope or the UI permission the operation needs, then retry. |
| 404 | ResourceNotFoundException | The resource id in the request does not exist or is not visible to the token. | Confirm the id is correct and the token has access to the resource. |
| 429 | COMPLEXITY_BUDGET_EXHAUSTED | A rate limit was hit. This covers the per-minute complexity budget being spent (COMPLEXITY_BUDGET_EXHAUSTED), too many simultaneous requests (maxConcurrencyExceeded), the per-IP limit (IP_RATE_LIMIT_EXCEEDED), and the overall request rate (Rate Limit Exceeded). | Read the RateLimit headers, wait for the window to reset, and reduce the size or rate of the calls. |
| 500 | Internal Server Error | An error on monday.com's side. | Retry after a brief delay, and contact support if it persists. |
monday.com versions its API by date through the API-Version header. The current default is 2026-04, with newer versions on a release-candidate track and older ones in maintenance before they are deprecated.
The 2026-04 version is the current default, carrying only bug fixes with no breaking changes, and can be used in production. monday.com versions the API by date through the API-Version header on a quarterly cycle: a release candidate becomes current after three months, then moves to maintenance, then is deprecated with at least six months notice. monday.com recommends passing a version name in every call rather than relying on the default.
The 2026-01 version is in maintenance, still usable but no longer the default. It is scheduled to transition to deprecated on 15 February 2027, with at least six months notice given.
The 2026-07 and 2026-10 versions, on the release-candidate and preview track, restructure the User entity. Photo fields are consolidated into a nested PhotoUrl object, kind and status are replaced with new enums, and the users query pagination defaults to 200 results with a 1,000 maximum. Legacy User fields are scheduled for removal in 2026-10. These were announced on 19 April 2026.
An integration can pin a version and move up on a schedule that suits it.
monday.com API changelog ↗Bollard AI sits between a team's AI agents and monday.com. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.