Trello

通过托管的OAuth身份验证访问Trello API。管理看板、列表、卡片、检查清单、标签和成员，用于项目和任务管理。

快速开始

# 获取当前用户的看板
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/trello/1/members/me/boards')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

基础URL

https://gateway.maton.ai/trello/{原生-api-路径}

将{native-api-path}替换为实际的Trello API端点路径。网关将请求代理到api.trello.com并自动注入您的OAuth令牌。

身份验证

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

Authorization: Bearer $MATON_API_KEY

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

export MATON_API_KEY="您的_API_密钥"

获取您的API密钥

1. 登录或在maton.ai
2. 创建账户前往
3. 复制您的 API 密钥

连接管理

请在以下地址管理您的 Trello OAuth 连接https://ctrl.maton.ai.

列出连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=trello&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': 'trello'}).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": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
    "status": "ACTIVE",
    "creation_time": "2025-12-08T07:20:53.488460Z",
    "last_updated_time": "2026-01-31T20:03:32.593153Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "trello",
    "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

指定连接

如果您有多个 Trello 连接，请使用Maton-Connection请求头来指定要使用哪一个：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/trello/1/members/me/boards')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

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

API 参考

成员

获取当前成员

GET /trello/1/members/me

获取成员的看板

GET /trello/1/members/me/boards

查询参数：

• filter- 筛选看板：all,open,closed,members,organization,starred
• fields- 要包含的字段，以逗号分隔

看板

获取看板

GET /trello/1/boards/{id}

查询参数：

• fields- 以逗号分隔的字段
• lists- 包含列表：all,open,closed,none
• cards- 包含卡片：all,open,closed,none
• members- 包含成员：all无示例：

python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/trello/1/boards/BOARD_ID?lists=open&cards=open') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF

创建看板

POST /trello/1/boards Content-Type: application/json { "name": "项目阿尔法", "desc": "主项目看板", "defaultLists": false, "prefs_permissionLevel": "private" }

更新看板

PUT /trello/1/boards/{id} Content-Type: application/json { "name": "项目阿尔法 - 已更新", "desc": "更新后的描述" }

删除看板

DELETE /trello/1/boards/{id}

获取看板列表

GET /trello/1/boards/{id}/lists

查询参数：

filter

• - 过滤器：所有,打开,已关闭,无获取看板卡片

GET /trello/1/boards/{id}/cards

GET /trello/1/boards/{id}/cards

获取看板成员

GET /trello/1/boards/{id}/members

列表

获取列表

GET /trello/1/lists/{id}

创建列表

POST /trello/1/lists
Content-Type: application/json

{
  "name": "待办事项",
  "idBoard": "看板ID",
  "pos": "顶部"
}

更新列表

PUT /trello/1/lists/{id}
Content-Type: application/json

{
  "name": "进行中"
}

归档列表

PUT /trello/1/lists/{id}/closed
Content-Type: application/json

{
  "value": true
}

获取列表中的卡片

GET /trello/1/lists/{id}/cards

移动列表中所有卡片

POST /trello/1/lists/{id}/moveAllCards
Content-Type: application/json

{
  "idBoard": "看板ID",
  "idList": "目标列表ID"
}

卡片

获取卡片

GET /trello/1/cards/{id}

查询参数：

• 字段- 逗号分隔的字段
• 成员- 包含成员（true/false）
• 检查清单- 包含检查清单：全部,无
• 附件- 包含附件（是/否）

创建卡片

POST /trello/1/cards
Content-Type: application/json

{
  "name": "实施功能X",
  "desc": "任务描述",
  "idList": "LIST_ID",
  "pos": "bottom",
  "due": "2025-03-30T12:00:00.000Z",
  "idMembers": ["MEMBER_ID"],
  "idLabels": ["LABEL_ID"]
}

更新卡片

PUT /trello/1/cards/{id}
Content-Type: application/json

{
  "name": "更新后的卡片名称",
  "desc": "更新后的描述",
  "due": "2025-04-15T12:00:00.000Z",
  "dueComplete": false
}

将卡片移至列表

PUT /trello/1/cards/{id}
Content-Type: application/json

{
  "idList": "NEW_LIST_ID",
  "pos": "top"
}

删除卡片

DELETE /trello/1/cards/{id}

向卡片添加评论

POST /trello/1/cards/{id}/actions/comments
Content-Type: application/json

{
  "text": "这是一条评论"
}

向卡片添加成员

POST /trello/1/cards/{id}/idMembers
Content-Type: application/json

{
  "value": "MEMBER_ID"
}

从卡片移除成员

DELETE /trello/1/cards/{id}/idMembers/{idMember}

向卡片添加标签

POST /trello/1/cards/{id}/idLabels
Content-Type: application/json

{
  "value": "LABEL_ID"
}

清单

获取清单

GET /trello/1/checklists/{id}

创建清单

POST /trello/1/checklists
Content-Type: application/json

{
  "idCard": "CARD_ID",
  "name": "任务清单"
}

创建清单项目

POST /trello/1/checklists/{id}/checkItems
Content-Type: application/json

{
  "name": "子任务 1",
  "pos": "bottom",
  "checked": false
}

更新清单项目

PUT /trello/1/cards/{cardId}/checkItem/{checkItemId}
Content-Type: application/json

{
  "state": "complete"
}

删除清单

DELETE /trello/1/checklists/{id}

标签

获取看板标签

GET /trello/1/boards/{id}/labels

创建标签

POST /trello/1/labels
Content-Type: application/json

{
  "name": "高优先级",
  "color": "red",
  "idBoard": "BOARD_ID"
}

颜色：黄色、紫色、蓝色、红色、绿色、橙色黑色天空粉色柠檬绿空值（无颜色）更新标签PUT /trello/1/labels/{id} Content-Type: application/json { "name": "Critical", "color": "red" }删除标签DELETE /trello/1/labels/{id}搜索

全部搜索

GET /trello/1/search?query=keyword&modelTypes=cards,boards

查询参数：

query

- 搜索查询（必填）

modelTypes

- 逗号分隔：

actions

• ,boards
• ,cardsactions,boards,cards成员组织board_fields- 看板要返回的字段
• card_fields- 卡片要返回的字段
• cards_limit- 返回卡片的最大数量（1-1000）
• 代码示例JavaScript

const headers = { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` }; // 获取看板 const boards = await fetch( 'https://gateway.maton.ai/trello/1/members/me/boards', { headers } ).then(r => r.json()); // 创建卡片 await fetch( 'https://gateway.maton.ai/trello/1/cards', { method: 'POST', headers: { ...headers, 'Content-Type': 'application/json' }, body: JSON.stringify({ name: '新任务', idList: 'LIST_ID', desc: '任务描述' }) } );

Python

import os
import requests

headers = {'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}

# 获取看板
boards = requests.get(
    'https://gateway.maton.ai/trello/1/members/me/boards',
    headers=headers
).json()

# 创建卡片
response = requests.post(
    'https://gateway.maton.ai/trello/1/cards',
    headers=headers,
    json={
        'name': '新任务',
        'idList': 'LIST_ID',
        'desc': '任务描述'
    }
)

注意事项

ID 是 24 位字母数字字符串

使用

• me
• 来指代认证用户日期使用 ISO 8601 格式pos
• 可以是
• top、bottom或一个正数列表内卡片的位置是浮点数使用
• Card positions within lists are floating point numbers
• Use字段用于限制返回数据并提升性能的参数
• 归档项目可通过filter=closed
• 检索重要提示：使用curl命令时，若URL包含括号（fields[]、sort[]、records[]），请使用curl -g
• 以禁用通配符解析重要提示：将curl输出通过管道传递给jq或其他命令时，某些shell环境中$MATON_API_KEY

等环境变量可能无法正确展开。通过管道传递时可能出现“无效API密钥”错误。

故障排除：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路径以trello开头。例如：

• 正确示例：https://gateway.maton.ai/trello/1/members/me/boards
• 错误示例：https://gateway.maton.ai/1/members/me/boards

资源

• Trello API概览
• 看板
• 列表
• 卡片
• 检查清单
• 标签
• 成员
• 搜索
• Maton社区
• Maton技术支持