Monday.com

通过托管的OAuth认证访问Monday.com API。使用GraphQL管理看板、项目、列、组、用户和工作区。

快速开始

# 获取当前用户信息
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

基础URL

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

所有请求都使用POST方法发送到GraphQL端点。网关会将请求代理到api.monday.com并自动注入您的OAuth令牌。

认证

所有请求都要求在Authorization头部中包含Maton API密钥：

Authorization: Bearer $MATON_API_KEY

环境变量：请将您的API密钥设置为MATON_API_KEY：

export MATON_API_KEY="YOUR_API_KEY"

获取您的API密钥

1. 请登录或前往maton.ai
2. 前往maton.ai/settings
3. 复制您的 API 密钥

连接管理

请在https://ctrl.maton.ai管理您的 Monday.com OAuth 连接。

列出连接

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

创建连接

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

获取连接

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

响应：

{
  "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": {}
  }
}

在浏览器中打开返回的url以完成 OAuth 授权。

删除连接

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

指定连接

如果您有多个Monday.com连接，请通过Maton-Connection请求头指定要使用哪一个：

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

如果省略此请求头，网关将使用默认（最早创建的）活跃连接。

API 参考

Monday.com 使用 GraphQL API。所有操作都以 POST 请求形式发送，请求体为包含query字段的 JSON。

当前用户 (me)

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

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

响应：

{
  "data": {
    "me": {
      "id": "72989582",
      "name": "Chris",
      "email": "chris.kim.2332@gmail.com"
    }
  }
}

用户

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

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

工作区

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

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

响应：

{
  "data": {
    "workspaces": [
      { "id": "10136488", "name": "主工作区", "kind": "open" }
    ]
  }
}

看板

列出看板

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

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

响应：

{
  "data": {
    "boards": [
      {
        "id": "8614733398",
        "name": "欢迎使用您的开发者账户",
        "state": "active",
        "board_kind": "public",
        "workspace": { "id": "10136488", "name": "主工作区" }
      }
    ]
  }
}

获取包含列、组和项目的看板

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 } } } }"}

创建看板

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

{"query": "mutation { create_board(board_name: \"新建看板\", board_kind: public) { id name } }"}

响应：

{
  "data": {
    "create_board": {
      "id": "18398921201",
      "name": "新建看板"
    }
  }
}

更新看板

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

{"query": "mutation { update_board(board_id: BOARD_ID, board_attribute: description, new_value: \"看板描述\") }"}

删除看板

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

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

项目

根据ID获取项目

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 } } }"}

响应：

{
  "data": {
    "items": [
      {
        "id": "11200791874",
        "name": "测试项目",
        "created_at": "2026-02-05T20:12:42Z",
        "updated_at": "2026-02-05T20:12:42Z",
        "state": "active",
        "board": { "id": "8614733398", "name": "欢迎来到您的开发者账户" },
        "group": { "id": "topics", "title": "分组标题" }
      }
    ]
  }
}

创建项目

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

{"query": "mutation { create_item(board_id: BOARD_ID, group_id: \"GROUP_ID\", item_name: \"新项目\") { id name } }"}

创建包含列值的项目

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

{"query": "mutation { create_item(board_id: BOARD_ID, group_id: \"GROUP_ID\", item_name: \"新任务\", column_values: \"{\\\"status\\\": {\\\"label\\\": \\\"处理中\\\"}}\") { id name column_values { id text } } }"}

更新项目名称

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: \"更新后的名称\") { id name } }"}

更新列值

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\\\": \\\"已完成\\\"}\") { id name } }"}

删除项目

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

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

列

创建列

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

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

响应：

{
  "data": {
    "create_column": {
      "id": "color_mm09e48w",
      "title": "状态",
      "type": "status"
    }
  }
}

列类型

常见列类型：状态，文本,数字,日期,人员,下拉菜单,复选框,电子邮件,电话,链接,时间线,标签,评分

分组

创建分组

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

{"query": "mutation { create_group(board_id: BOARD_ID, group_name: \"New Group\") { id title } }"}

响应：

{
  "data": {
    "create_group": {
      "id": "group_mm0939df",
      "title": "New Group"
    }
  }
}

分页

Monday.com 对包含items_page和next_items_page的项目使用基于游标的分页。

# 第一页
POST /monday/v2
{"query": "{ boards(ids: [BOARD_ID]) { items_page(limit: 50) { cursor items { id name } } } }"}

# 使用游标的下一页
POST /monday/v2
{"query": "{ next_items_page(cursor: \"CURSOR_VALUE\", limit: 50) { cursor items { id name } } }"}

响应包含cursor（当存在更多项目时；如果没有更多页面则为 null）：

{
  "data": {
    "boards": [{
      "items_page": {
        "cursor": "MSw5NzI4...",
        "items": [...]
      }
    }]
  }
}

代码示例

JavaScript

const response = await fetch('https://gateway.maton.ai/monday/v2', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.MATON_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: `{ boards(limit: 10) { id name items_page(limit: 20) { items { id name } } } }`
  })
});
const data = await response.json();

Python

import os
import requests

response = requests.post(
    'https://gateway.maton.ai/monday/v2',
    headers={
        'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}',
        'Content-Type': 'application/json'
    },
    json={
        'query': '{ boards(limit: 10) { id name items_page(limit: 20) { items { id name } } } }'
    }
)
data = response.json()

注意事项

• Monday.com 仅使用 GraphQL（无 REST API）
• 看板 ID、项目 ID 和用户 ID 是数字字符串
• 列 ID 是字母数字字符串（例如，color_mm09e48w）
• 组 ID 是字母数字字符串（例如，group_mm0939df、topics）
• 创建/更新项目时，列值必须作为 JSON 字符串传递
• `account`查询可能需要额外的 OAuth 范围。如果您收到范围错误，请联系 Maton 技术支持：support@maton.aisupport@maton.ai根据你需要的具体操作/API以及你的使用场景
• 看板类型：公开、私有、共享
• 看板状态：活跃、已归档、已删除、全部
• 每个游标在初始请求后的60分钟内有效
• 默认限制为25条，大多数查询的最大限制为100条

错误处理

GraphQL错误会在errors数组中返回：

{
  "data": {},
  "errors": [
    {
      "message": "未授权的字段或类型",
      "path": ["account"],
      "extensions": { "code": "UNAUTHORIZED_FIELD_OR_TYPE" }
    }
  ]
}

故障排除：API密钥问题

1. 检查MATON_API_KEY环境变量是否已设置：

echo $MATON_API_KEY

2. 通过列出连接来验证API密钥是否有效：

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

故障排除：无效的应用名称

1. 确保您的URL路径以monday开头。例如：

• 正确：https://gateway.maton.ai/monday/v2
• 错误：https://gateway.maton.ai/v2

资源

• Monday.com API 基础
• GraphQL 概述
• 看板参考
• 项目参考
• 列参考
• API 更新日志
• Maton 社区
• Maton 支持