monday

What this skill does

# Monday.com

Access the Monday.com API with managed OAuth authentication. Manage boards, items, columns, groups, users, and workspaces using GraphQL.

## Quick Start

```bash
# Get current user
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'query': '{ me { id name email } }'}).encode()
req = urllib.request.Request('https://gateway.maton.ai/monday/v2', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

## Base URL

```
https://gateway.maton.ai/monday/v2
```

All requests use POST to the GraphQL endpoint. The gateway proxies requests to `api.monday.com` and automatically injects your OAuth token.

## Authentication

All requests require the Maton API key in the Authorization header:

```
Authorization: Bearer $MATON_API_KEY
```

**Environment Variable:** Set your API key as `MATON_API_KEY`:

```bash
export MATON_API_KEY="YOUR_API_KEY"
```

### Getting Your API Key

1. Sign in or create an account at [maton.ai](https://maton.ai)
2. Go to [maton.ai/settings](https://maton.ai/settings)
3. Copy your API key

## Connection Management

Manage your Monday.com OAuth connections at `https://ctrl.maton.ai`.

### List Connections

```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=monday&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

### Create Connection

```bash
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'monday'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

### Get Connection

```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

**Response:**
```json
{
  "connection": {
    "connection_id": "ca93f2c5-5126-4360-b293-4f05f7bb6c8c",
    "status": "ACTIVE",
    "creation_time": "2026-02-05T20:10:47.585047Z",
    "last_updated_time": "2026-02-05T20:11:12.357011Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "monday",
    "metadata": {}
  }
}
```

Open the returned `url` in a browser to complete OAuth authorization.

### Delete Connection

```bash
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

### Specifying Connection

If you have multiple Monday.com connections, specify which one to use with the `Maton-Connection` header:

```bash
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'query': '{ me { id name } }'}).encode()
req = urllib.request.Request('https://gateway.maton.ai/monday/v2', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
req.add_header('Maton-Connection', 'ca93f2c5-5126-4360-b293-4f05f7bb6c8c')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF
```

If omitted, the gateway uses the default (oldest) active connection.

## API Reference

Monday.com uses a GraphQL API. All operations are sent as POST requests with a JSON body containing the `query` field.

### Current User (me)

```bash
POST /monday/v2
Content-Type: application/json

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

**Response:**
```json
{
  "data": {
    "me": {
      "id": "72989582",
      "name": "Chris",
      "email": "[email protected]"
    }
  }
}
```

### Users

```bash
POST /monday/v2
Content-Type: application/json

{"query": "{ users(limit: 20) { id name email } }"}
```

### Workspaces

```bash
POST /monday/v2
Content-Type: application/json

{"query": "{ workspaces(limit: 10) { id name kind } }"}
```

**Response:**
```json
{
  "data": {
    "workspaces": [
      { "id": "10136488", "name": "Main workspace", "kind": "open" }
    ]
  }
}
```

### Boards

#### List Boards

```bash
POST /monday/v2
Content-Type: application/json

{"query": "{ boards(limit: 10) { id name state board_kind workspace { id name } } }"}
```

**Response:**
```json
{
  "data": {
    "boards": [
      {
        "id": "8614733398",
        "name": "Welcome to your developer account",
        "state": "active",
        "board_kind": "public",
        "workspace": { "id": "10136488", "name": "Main workspace" }
      }
    ]
  }
}
```

#### Get Board with Columns, Groups, and Items

```bash
POST /monday/v2
Content-Type: application/json

{"query": "{ boards(ids: [BOARD_ID]) { id name columns { id title type } groups { id title } items_page(limit: 20) { cursor items { id name state } } } }"}
```

#### Create Board

```bash
POST /monday/v2
Content-Type: application/json

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

**Response:**
```json
{
  "data": {
    "create_board": {
      "id": "18398921201",
      "name": "New Board"
    }
  }
}
```

#### Update Board

```bash
POST /monday/v2
Content-Type: application/json

{"query": "mutation { update_board(board_id: BOARD_ID, board_attribute: description, new_value: \"Board description\") }"}
```

#### Delete Board

```bash
POST /monday/v2
Content-Type: application/json

{"query": "mutation { delete_board(board_id: BOARD_ID) { id } }"}
```

### Items

#### Get Items by ID

```bash
POST /monday/v2
Content-Type: application/json

{"query": "{ items(ids: [ITEM_ID]) { id name created_at updated_at state board { id name } group { id title } column_values { id text value } } }"}
```

**Response:**
```json
{
  "data": {
    "items": [
      {
        "id": "11200791874",
        "name": "Test item",
        "created_at": "2026-02-05T20:12:42Z",
        "updated_at": "2026-02-05T20:12:42Z",
        "state": "active",
        "board": { "id": "8614733398", "name": "Welcome to your developer account" },
        "group": { "id": "topics", "title": "Group Title" }
      }
    ]
  }
}
```

#### Create Item

```bash
POST /monday/v2
Content-Type: application/json

{"query": "mutation { create_item(board_id: BOARD_ID, group_id: \"GROUP_ID\", item_name: \"New item\") { id name } }"}
```

#### Create Item with Column Values

```bash
POST /monday/v2
Content-Type: application/json

{"query": "mutation { create_item(board_id: BOARD_ID, group_id: \"GROUP_ID\", item_name: \"New task\", column_values: \"{\\\"status\\\": {\\\"label\\\": \\\"Working on it\\\"}}\") { id name column_values { id text } } }"}
```

#### Update Item Name

```bash
POST /monday/v2
Content-Type: application/json

{"query": "mutation { change_simple_column_value(board_id: BOARD_ID, item_id: ITEM_ID, column_id: \"name\", value: \"Updated name\") { id name } }"}
```

#### Update Column Value

```bash
POST /monday/v2
Content-Type: application/json

{"query": "mutation { change_column_value(board_id: BOARD_ID, item_id: ITEM_ID, column_id: \"status\", value: \"{\\\"label\\\": \\\"Done\\\"}\") { id name } }"}
```

#### Delete Item

```bash
POST /monday/v2
Content-Type: application/json

{"query": "mutation { delete_item(item_id: ITEM_ID) { id } }"}
```

### Columns

#### Create Column

```bash
POST /monday/v2
Content-Type: application/json

{"query": "mutation { create_column(board_id: BOARD_ID, title: \"Status\", column_type: status) { id title type } }"}
```

**Response: