介绍
# ClickUp
通过托管的 OAuth 身份验证访问 ClickUp API。管理工作管理所需的任务、列表、文件夹、空间、工作区、用户和 Webhook。
## 快速开始
```bash # List workspaces (teams) python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/clickup/api/v2/team') 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/clickup/{native-api-path} ```
将 `{native-api-path}` 替换为实际的 ClickUp API 端点路径。网关会将请求代理到 `api.clickup.com` 并自动注入您的 OAuth 令牌。
## 身份验证
所有请求都需要在 Authorization 请求头中包含 Maton API 密钥：
``` Authorization: Bearer $MATON_API_KEY ```
**环境变量：** 将您的 API 密钥设置为 `MATON_API_KEY`：
```bash export MATON_API_KEY="YOUR_API_KEY" ```
### 获取 API 密钥
1. 在 [maton.ai](https://maton.ai) 登录或创建一个账户 2. 访问 [maton.ai/settings](https://maton.ai/settings) 3. 复制您的 API 密钥
## 连接管理
在 `https://ctrl.maton.ai` 管理您的 ClickUp OAuth 连接。
### 列出连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=clickup&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 ```
### 创建连接
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'clickup'}).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 ```
### 获取连接
```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 ```
**响应：** ```json { "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": "clickup", "metadata": {} } } ```
在浏览器中打开返回的 `url` 以完成 OAuth 授权。
### 删除连接
```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 ```
### 指定连接
如果您有多个 ClickUp 连接，请使用 `Maton-Connection` 请求头指定要使用的连接：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/clickup/api/v2/team') 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 ```
如果省略，网关将使用默认（最旧的）活动连接。
## ClickUp 层级结构
ClickUp 按层级组织数据： - **工作区** (team) → **空间** → **文件夹** → **列表** → **任务**
注意：在 API 中，工作区被称为“teams”。
## API 参考
### 工作区 (Teams)
#### 获取已授权的工作区
```bash GET /clickup/api/v2/team ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/clickup/api/v2/team') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "teams": [ { "id": "1234567", "name": "Acme Corp", "color": "#7B68EE", "avatar": null, "members": [ { "user": { "id": 123, "username": "Alice Johnson", "email": "[email protected]" } } ] } ] } ```
### 空间
#### 获取空间
```bash GET /clickup/api/v2/team/{team_id}/space ```
查询参数： - `archived` - 包含已归档的空间 (true/false)
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/clickup/api/v2/team/1234567/space') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "spaces": [ { "id": "90120001", "name": "Engineering", "private": false, "statuses": [ {"status": "to do", "type": "open"}, {"status": "in progress", "type": "custom"}, {"status": "done", "type": "closed"} ] } ] } ```
#### 获取空间
```bash GET /clickup/api/v2/space/{space_id} ```
#### 创建空间
```bash POST /clickup/api/v2/team/{team_id}/space ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'name': 'New Space', 'multiple_assignees': True, 'features': {'due_dates': {'enabled': True}, 'time_tracking': {'enabled': True}}}).encode() req = urllib.request.Request('https://gateway.maton.ai/clickup/api/v2/team/1234567/space', 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 ```
#### 更新空间
```bash PUT /clickup/api/v2/space/{space_id} ```
#### 删除空间
```bash DELETE /clickup/api/v2/space/{space_id} ```
### 文件夹
#### 获取文件夹
```bash GET /clickup/api/v2/space/{space_id}/folder ```
查询参数： - `archived` - 包含已归档的文件夹 (true/false)
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/clickup/api/v2/space/90120001/folder') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "folders": [ { "id": "456789", "name": "Sprint 1", "orderindex": 0, "hidden": false, "space": {"id": "90120001", "name": "Engineering"}, "task_count": "12", "lists": [] } ] } ```
#### 获取文件夹
```bash GET /clickup/api/v2/folder/{folder_id} ```
#### 创建文件夹
```bash POST /clickup/api/v2/space/{space_id}/folder ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'name': 'New Folder'}).encode() req = urllib.request.Request('https://gateway.maton.ai/clickup/api/v2/space/90120001/folder', 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 ```
#### 更新文件夹
```bash PUT /clickup/api/v2/folder/{folder_id} ```
#### 删除文件夹
```bash DELETE /clickup/api/v2/folder/{folder_id} ```
### 列表
#### 获取列表
```bash GET /clickup/api/v2/folder/{folder_id}/list ```
查询参数： - `archived` - 包含已归档的列表 (true/false)
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/clickup/api/v2/folder/456789/list') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "lists": [ { "id": "901234", "name": "Backlog", "orderindex": 0, "status": {"status": "active", "color": "#87909e"}, "task_count": 25, "folder": {"id": "456789", "name": "Sprint 1"} } ] } ```
#### 获取无文件夹列表
```bash GET /clickup/api/v2/space/{space_id}/list ```
#### 获取列表
```bash GET /clickup/api/v2/list/{list_id} ```
#### 创建列表
```bash POST /clickup/api/v2/folder/{folder_id}/list ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'name': 'New List'}).encode() req = urllib.request.Request('https://gateway.maton.ai/clickup/api/v2/folder/456789/list', 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 ```
#### 创建无文件夹列表
```bash POST /clickup/api/v2/space/{space_id}/list ```
#### 更新列表
```bash PUT /clickup/api/v2/list/{list_id} ```
#### 删除列表
```bash DELETE /clickup/api/v2/list/{list_id} ```
### 任务
#### 获取任务
```bash GET /clickup/api/v2/list/{list_id}/task ```
查询参数： - `archived` - 包含已归档的任务 (true/false) - `page` - 页码（从 0 开始索引） - `order_by` - 排序字段 (created, updated, due_date) - `reverse` - 反向排序 (true/false) - `subtasks` - 包含子任务 (true/false) - `statuses[]` - 按状态筛选 - `include_closed` - 包含已关闭的任务 (true/false) - `assignees[]` - 按负责人 ID 筛选 - `due_date_gt` - 截止日期大于 (Unix 毫秒) - `due_date_lt` - 截止日期小于 (Unix 毫秒)
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/clickup/api/v2/list/901234/task?include_closed=true') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "tasks": [ { "id": "abc123", "name": "Implement login feature", "status": {"status": "in progress", "type": "custom", "color": "#4194f6"}, "priority": {"id": "2", "priority": "high", "color": "#f9d900"}, "due_date": "1709251200000", "assignees": [{"id": 123, "username": "Alice Johnson", "email": "[email protected]"}], "description": "Add OAuth login flow", "date_created": "1707436800000", "date_updated": "1708646400000" } ] } ```
#### 获取任务
```bash GET /clickup/api/v2/task/{task_id} ```
查询参数： - `custom_task_ids` - 使用自定义任务 ID (true/false) - `team_id` - 使用 custom_task_ids 时必须提供 - `include_subtasks` - 包含子任务 (true/false)
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/clickup/api/v2/task/abc123') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
#### 创建任务
```bash POST /clickup/api/v2/list/{list_id}/task Content-Type: application/json
{ "name": "Task name", "description": "Task description", "assignees": [123], "status": "to do", "priority": 2, "due_date": 1709251200000, "tags": ["api", "backend"], "parent": null } ```
字段： - `name` (必填) - 任务标题 - `description` - 任务描述（支持 markdown） - `assignees` - 用户 ID 数组 - `status` - 状态名称（必须与列表中的状态匹配） - `priority` - 优先级 (1=urgent, 2=high, 3=normal, 4=low, null=none) - `due_date` - Unix 时间戳（毫秒） - `due_date_time` - 在截止日期中包含时间 (true/false) - `start_date` - Unix 时间戳（毫秒） - `time_estimate` - 时间估算（毫秒） - `tags` - 标签名称数组 - `parent` - 父任务 ID（用于子任务） - `custom_fields` - 自定义字段对象数组
**示例：**
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'name': 'Complete API integration', 'description': 'Integrate with the new payment API', 'priority': 2, 'due_date': 1709251200000, 'assignees': [123]}).encode() req = urllib.request.Request('https://gateway.maton.ai/clickup/api/v2/list/901234/task', 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 ```
#### 更新任务
```bash PUT /clickup/api/v2/task/{task_id} ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'status': 'complete', 'priority': None}).encode() req = urllib.request.Request('https://gateway.maton.ai/clickup/api/v2/task/abc123', data=data, method='PUT') 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 ```
#### 删除任务
```bash DELETE /clickup/api/v2/task/{task_id} ```
#### 获取已筛选的团队任务
```bash GET /clickup/api/v2/team/{team_id}/task ```
查询参数： - `page` - 页码（从 0 开始索引） - `order_by` - 排序字段 - `statuses[]` - 按状态筛选 - `assignees[]` - 按负责人筛选 - `list_ids[]` - 按列表 ID 筛选 - `space_ids[]` - 按空间 ID 筛选 - `folder_ids[]` - 按文件夹 ID 筛选
### 用户
#### 获取当前用户
```bash GET /clickup/api/v2/user ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/clickup/api/v2/user') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "user": { "id": 123, "username": "Alice Johnson", "email": "[email protected]", "color": "#7B68EE", "profilePicture": "https://...", "initials": "AJ", "week_start_day": 0, "timezone": "America/New_York" } } ```
### Webhooks
#### 获取 Webhooks
```bash GET /clickup/api/v2/team/{team_id}/webhook ```
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/clickup/api/v2/team/1234567/webhook') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
#### 创建 Webhook
```bash POST /clickup/api/v2/team/{team_id}/webhook Content-Type: application/json
{ "endpoint": "https://example.com/webhook", "events": ["taskCreated", "taskUpdated", "taskDeleted"], "space_id": "90120001", "folder_id": "456789", "list_id": "901234", "task_id": "abc123" } ```
事件： - `taskCreated`, `taskUpdated`, `taskDeleted` - `taskPriorityUpdated`, `taskStatusUpdated` - `taskAssigneeUpdated`, `taskDueDateUpdated` - `taskTagUpdated`, `taskMoved` - `taskCommentPosted`, `taskCommentUpdated` - `taskTimeEstimateUpdated`, `taskTimeTrackedUpdated` - `listCreated`, `listUpdated`, `listDeleted` - `folderCreated`, `folderUpdated`, `folderDeleted` - `spaceCreated`, `spaceUpdated`, `spaceDeleted` - `goalCreated`, `goalUpdated`, `goalDeleted` - `keyResultCreated`, `keyResultUpdated`, `keyResultDeleted`
**示例：**
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'endpoint': 'https://example.com/webhook', 'events': ['taskCreated', 'taskUpdated']}).encode() req = urllib.request.Request('https://gateway.maton.ai/clickup/api/v2/team/1234567/webhook', 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 ```
**响应：** ```json { "id": "webhook123", "webhook": { "id": "webhook123", "userid": 123, "team_id": "1234567", "endpoint": "https://example.com/webhook", "client_id": "...", "events": ["taskCreated", "taskUpdated"], "health": {"status": "active", "fail_count": 0}, "secret": "..." } } ```
#### 更新 Webhook
```bash PUT /clickup/api/v2/webhook/{webhook_id} ```
#### 删除 Webhook
```bash DELETE /clickup/api/v2/webhook/{webhook_id} ```
## 分页
ClickUp 使用基于页面的分页。使用 `page` 参数（从 0 开始索引）：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/clickup/api/v2/list/901234/task?page=0') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
每页响应限制为 100 个任务。响应包含一个布尔字段 `last_page`。继续递增页码，直到 `last_page` 为 `true`。
## 代码示例
### JavaScript
```javascript const response = await fetch( 'https://gateway.maton.ai/clickup/api/v2/list/901234/task', { headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` } } ); const data = await response.json(); ```
### Python
```python import os import requests
response = requests.get( 'https://gateway.maton.ai/clickup/api/v2/list/901234/task', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'} ) data = response.json() ```
## 注意事项
- 任务 ID 是字符串 - 时间戳为 Unix 毫秒 - 优先级值：1=urgent, 2=high, 3=normal, 4=low, null=none - 工作区在 API 中被称为“teams” - 状态值必须与列表中配置的确切状态名称匹配 - 响应限制为每页 100 个项目 - 重要：使用 curl 命令时，如果 URL 包含括号（`statuses[]`、`assignees[]`、`list_ids[]`），请使用 `curl -g` 以禁用 glob 解析 - 重要：当将 curl 输出通过管道传递给 `jq` 或其他命令时，某些 shell 环境中 `$MATON_API_KEY` 等环境变量可能无法正确展开。在通过管道传递时，您可能会遇到“Invalid API key”错误。
## 错误处理
| 状态 | 含义 | |--------|---------| | 400 | 错误的请求或缺少 ClickUp 连接 | | 401 | 无效或缺少 Maton API 密钥 | | 403 | 禁止访问 - 权限不足 | | 404 | 资源未找到 | | 429 | 速率受限 | | 4xx/5xx | 来自 ClickUp API 的透传错误 |
### 故障排除：API 密钥问题
1. 检查是否设置了 `MATON_API_KEY` 环境变量：
```bash echo $MATON_API_KEY ```
2. 通过列出连接来验证 API 密钥是否有效：
```bash 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 路径以 `clickup` 开头。例如：
- 正确：`https://gateway.maton.ai/clickup/api/v2/team` - 错误：`https://gateway.maton.ai/api/v2/team`
## 资源
- [ClickUp API 概览](https://developer.clickup.com/docs/Getting%20Started.md) - [获取任务](https://developer.clickup.com/reference/gettasks.md) - [创建任务](https://developer.clickup.com/reference/createtask.md) - [更新任务](https://developer.clickup.com/reference/updatetask.md) - [删除任务](https://developer.clickup.com/reference/deletetask.md) - [获取空间](https://developer.clickup.com/reference/getspaces.md) - [获取列表](https://developer.clickup.com/reference/getlists.md) - [创建 Webhook](https://developer.clickup.com/reference/createwebhook.md) - [自定义字段](https://developer.clickup.com/docs/customfields.md) - [速率限制](https://developer.clickup.com/docs/rate-limits.md) - [LLM 参考](https://developer.clickup.com/llms.txt) - [Maton 社区](https://discord.com/invite/dBfFAcefs2) - [Maton 支持](mailto:[email protected])