home / skills / vm0-ai / vm0-skills / monday

monday skill

safe

This skill helps you manage Monday.com boards, items, and projects via GraphQL curl calls, enabling quick automation and data sync.

npx playbooks add skill vm0-ai/vm0-skills --skill monday

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

8.3 KB

---
name: monday
description: Monday.com GraphQL API via curl. Use this skill to manage boards, items, and projects.
vm0_secrets:
  - MONDAY_API_KEY
---

# Monday.com API

Use the Monday.com GraphQL API via direct `curl` calls to **manage boards, items, and project data**.

> Official docs: `https://developer.monday.com/api-reference/`

---

## When to Use

Use this skill when you need to:

- **Query boards and items** from Monday.com
- **Create, update, or delete items** in boards
- **Manage board columns and groups**
- **Sync data** between Monday.com and other systems
- **Automate project workflows**

---

## Prerequisites

1. Log in to [Monday.com](https://monday.com/)
2. Go to your avatar → Developers → My Access Tokens
3. Generate a new API token
4. Store it in the environment variable `MONDAY_API_KEY`

```bash
export MONDAY_API_KEY="your-api-token"
```

### API Info

- GraphQL endpoint: `https://api.monday.com/v2`
- All requests are POST
- Requires `Authorization` header with API token
- Requires `API-Version` header (use `2024-10`)

---


> **Important:** When using `$VAR` in a command that pipes to another command, wrap the command containing `$VAR` in `bash -c '...'`. Due to a Claude Code bug, environment variables are silently cleared when pipes are used directly.
> ```bash
> bash -c 'curl -s "https://api.example.com" -H "Authorization: Bearer $API_KEY"'
> ```

## How to Use

All examples below assume you have `MONDAY_API_KEY` set.

---

### 1. Get Current User

Query the authenticated user's info:

Write to `/tmp/monday_request.json`:

```json
{
  "query": "query { me { id name email } }"
}
```

Then run:

```bash
bash -c 'curl -s -X POST "https://api.monday.com/v2" --header "Authorization: ${MONDAY_API_KEY}" --header "API-Version: 2024-10" --header "Content-Type: application/json" -d @/tmp/monday_request.json'
```

---

### 2. List All Boards

Get all boards in your account:

Write to `/tmp/monday_request.json`:

```json
{
  "query": "query { boards (limit: 10) { id name state items_count } }"
}
```

Then run:

```bash
bash -c 'curl -s -X POST "https://api.monday.com/v2" --header "Authorization: ${MONDAY_API_KEY}" --header "API-Version: 2024-10" --header "Content-Type: application/json" -d @/tmp/monday_request.json'
```

---

### 3. Get Board Details

Get a specific board with its groups and columns:

Write to `/tmp/monday_request.json`:

```json
{
  "query": "query { boards (ids: <your-board-id>) { id name groups { id title } columns { id title type } } }"
}
```

Replace `<your-board-id>` with an actual board ID from the "List All Boards" response (example 2).

Then run:

```bash
bash -c 'curl -s -X POST "https://api.monday.com/v2" --header "Authorization: ${MONDAY_API_KEY}" --header "API-Version: 2024-10" --header "Content-Type: application/json" -d @/tmp/monday_request.json'
```

---

### 4. Get Items from a Board

Get items (rows) from a specific board:

Write to `/tmp/monday_request.json`:

```json
{
  "query": "query { boards (ids: <your-board-id>) { items_page (limit: 10) { items { id name column_values { id text value } } } } }"
}
```

Replace `<your-board-id>` with an actual board ID from the "List All Boards" response (example 2).

Then run:

```bash
bash -c 'curl -s -X POST "https://api.monday.com/v2" --header "Authorization: ${MONDAY_API_KEY}" --header "API-Version: 2024-10" --header "Content-Type: application/json" -d @/tmp/monday_request.json'
```

---

### 5. Create a New Item

Create a new item in a board:

Write to `/tmp/monday_request.json`:

```json
{
  "query": "mutation { create_item (board_id: <your-board-id>, group_id: \"<your-group-id>\", item_name: \"<your-item-name>\") { id name } }"
}
```

Replace the following values:
- `<your-board-id>`: An actual board ID from the "List All Boards" response (example 2)
- `<your-group-id>`: A group ID from the "Get Board Details" response (example 3, groups array)
- `<your-item-name>`: Your desired name for the new item

Then run:

```bash
bash -c 'curl -s -X POST "https://api.monday.com/v2" --header "Authorization: ${MONDAY_API_KEY}" --header "API-Version: 2024-10" --header "Content-Type: application/json" -d @/tmp/monday_request.json'
```

---

### 6. Create Item with Column Values

Create an item with specific column values:

Write to `/tmp/monday_request.json`:

```json
{
  "query": "mutation ($boardId: ID!, $groupId: String!, $itemName: String!, $columnValues: JSON!) { create_item (board_id: $boardId, group_id: $groupId, item_name: $itemName, column_values: $columnValues) { id name } }",
  "variables": {
    "boardId": "<your-board-id>",
    "groupId": "<your-group-id>",
    "itemName": "<your-item-name>",
    "columnValues": "{\"status\": {\"label\": \"Working on it\"}, \"date\": {\"date\": \"2025-01-15\"}}"
  }
}
```

Replace the following values:
- `<your-board-id>`: An actual board ID from the "List All Boards" response (example 2)
- `<your-group-id>`: A group ID from the "Get Board Details" response (example 3, groups array)
- `<your-item-name>`: Your desired name for the new item

Then run:

```bash
bash -c 'curl -s -X POST "https://api.monday.com/v2" --header "Authorization: ${MONDAY_API_KEY}" --header "API-Version: 2024-10" --header "Content-Type: application/json" -d @/tmp/monday_request.json'
```

---

### 7. Update an Item

Update an existing item's column values:

Write to `/tmp/monday_request.json`:

```json
{
  "query": "mutation ($boardId: ID!, $itemId: ID!, $columnValues: JSON!) { change_multiple_column_values (board_id: $boardId, item_id: $itemId, column_values: $columnValues) { id name } }",
  "variables": {
    "boardId": "<your-board-id>",
    "itemId": "<your-item-id>",
    "columnValues": "{\"status\": {\"label\": \"Done\"}}"
  }
}
```

Replace the following values:
- `<your-board-id>`: An actual board ID from the "List All Boards" response (example 2)
- `<your-item-id>`: An item ID from the "Get Items from a Board" response (example 4)

Then run:

```bash
bash -c 'curl -s -X POST "https://api.monday.com/v2" --header "Authorization: ${MONDAY_API_KEY}" --header "API-Version: 2024-10" --header "Content-Type: application/json" -d @/tmp/monday_request.json'
```

---

### 8. Delete an Item

Delete an item from a board:

Write to `/tmp/monday_request.json`:

```json
{
  "query": "mutation { delete_item (item_id: <your-item-id>) { id } }"
}
```

Replace `<your-item-id>` with an actual item ID from the "Get Items from a Board" response (example 4).

Then run:

```bash
bash -c 'curl -s -X POST "https://api.monday.com/v2" --header "Authorization: ${MONDAY_API_KEY}" --header "API-Version: 2024-10" --header "Content-Type: application/json" -d @/tmp/monday_request.json'
```

---

### 9. Create a New Board

Create a new board:

Write to `/tmp/monday_request.json`:

```json
{
  "query": "mutation { create_board (board_name: \"My New Board\", board_kind: public) { id name } }"
}
```

Then run:

```bash
bash -c 'curl -s -X POST "https://api.monday.com/v2" --header "Authorization: ${MONDAY_API_KEY}" --header "API-Version: 2024-10" --header "Content-Type: application/json" -d @/tmp/monday_request.json'
```

---

### 10. Search Items

Search for items across boards:

Write to `/tmp/monday_request.json`:

```json
{
  "query": "query { items_page_by_column_values (limit: 10, board_id: <your-board-id>, columns: [{column_id: \"name\", column_values: [\"Task\"]}]) { items { id name } } }"
}
```

Replace `<your-board-id>` with an actual board ID from the "List All Boards" response (example 2).

Then run:

```bash
bash -c 'curl -s -X POST "https://api.monday.com/v2" --header "Authorization: ${MONDAY_API_KEY}" --header "API-Version: 2024-10" --header "Content-Type: application/json" -d @/tmp/monday_request.json'
```

---

## Common Column Types

| Column Type | Value Format |
|-------------|--------------|
| Status | `{"label": "Done"}` |
| Date | `{"date": "2025-01-15"}` |
| Text | `"Your text here"` |
| Number | `"123"` |
| Person | `{"id": 12345678}` |
| Dropdown | `{"labels": ["Option1", "Option2"]}` |
| Checkbox | `{"checked": true}` |

---

## Guidelines

1. **Use variables for complex queries**: GraphQL variables make escaping easier
2. **Check column IDs**: Use the board query to get exact column IDs before updating
3. **API versioning**: Always include `API-Version` header for consistent behavior
4. **Rate limits**: API has rate limits; add delays for bulk operations
5. **Column values are JSON strings**: When using `column_values`, pass as escaped JSON string

Overview

This skill lets you call the Monday.com GraphQL API directly from shell using curl to manage boards, items, groups, and columns. It focuses on practical, scriptable operations: query data, create or update items with column values, delete items, and create boards. Examples assume an API token in MONDAY_API_KEY and show safe curl usage when piping.

How this skill works

The skill builds GraphQL queries and mutations as JSON files and posts them to https://api.monday.com/v2 with the Authorization and API-Version headers. It wraps curl calls in bash -c to avoid environment-variable loss when piping, and uses GraphQL variables for complex payloads and escaped JSON strings for column_values. Typical flows include listing boards, fetching board details, reading items, creating/updating items, and deleting items.

When to use it

Automate creating or updating items in Monday.com boards from scripts
Sync tasks or project data between Monday.com and other systems
Inspect boards, groups, and column schemas before bulk updates
Build CI/CD hooks or cron jobs that adjust boards programmatically
Quick ad-hoc queries and mutations from a terminal or remote server

Best practices

Store the API token in MONDAY_API_KEY and never hard-code it
Always include API-Version header (use 2024-10) to avoid breaking changes
Use GraphQL variables for payloads to simplify escaping and reuse
Query board columns and groups first to get exact column and group IDs
Rate-limit bulk operations and add retries to respect API limits
When sending column_values, pass them as escaped JSON strings to the GraphQL variable

Example use cases

List all boards to find a target board_id and inspect available columns
Create a new item in a specified group with status and date column values
Update multiple column values on an existing item (status -> Done, set date)
Delete stale or test items as part of a cleanup script
Create a new board programmatically as part of a client onboarding flow

FAQ

What headers are required for every request?

Include Authorization: ${MONDAY_API_KEY} and API-Version: 2024-10, and set Content-Type: application/json.

How do I pass column values when creating or updating items?

Provide column_values as an escaped JSON string (for example: "{\"status\":{\"label\":\"Done\"}}") or use GraphQL variables to avoid manual escaping.