ClickUp

2026-03-24 新闻来源：网淘吧围观:89

电脑广告

手机广告

ClickUp

通过托管的 OAuth 认证访问 ClickUp API。管理工作管理的任务、列表、文件夹、空间、工作区、用户和 webhooks。

快速开始

# 列出工作区（团队）
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：

export MATON_API_KEY="YOUR_API_KEY"

获取您的 API 密钥

登录或创建账户于maton.ai
前往maton.ai/settings
复制您的API密钥

连接管理

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

列出连接

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

创建连接

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

获取连接

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": "clickup",
    "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

指定连接

如果您有多个 ClickUp 连接，请通过Maton-Connection标头指定要使用的连接：

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 按以下层级结构组织数据：

工作区（团队）→空间→文件夹→列表→任务

注意：在 API 中，工作区被称为"团队"。

API 参考

工作区（团队）

获取授权的工作区

GET /clickup/api/v2/team

示例：

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

响应：

{
  "teams": [
    {
      "id": "1234567",
      "name": "Acme Corp",
      "color": "#7B68EE",
      "avatar": null,
      "members": [
        {
          "user": {
            "id": 123,
            "username": "Alice Johnson",
            "email": "alice@acme.com"
          }
        }
      ]
    }
  ]
}

空间

获取空间列表

GET /clickup/api/v2/team/{team_id}/space

查询参数：

archived- 是否包含已归档空间（true/false）

示例：

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

响应：

{
  "spaces": [
    {
      "id": "90120001",
      "name": "Engineering",
      "private": false,
      "statuses": [
        {"status": "to do", "type": "open"},
        {"status": "in progress", "type": "custom"},
        {"status": "done", "type": "closed"}
      ]
    }
  ]
}

获取单个空间

GET /clickup/api/v2/space/{space_id}

创建一个空间

POST /clickup/api/v2/team/{team_id}/space

示例:

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

更新一个空间

PUT /clickup/api/v2/space/{space_id}

删除一个空间

DELETE /clickup/api/v2/space/{space_id}

文件夹

获取文件夹

GET /clickup/api/v2/space/{space_id}/folder

查询参数:

archived- 包含已归档的文件夹 (true/false)

示例:

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

响应:

{
  "folders": [
    {
      "id": "456789",
      "name": "Sprint 1",
      "orderindex": 0,
      "hidden": false,
      "space": {"id": "90120001", "name": "Engineering"},
      "task_count": "12",
      "lists": []
    }
  ]
}

获取一个文件夹

GET /clickup/api/v2/folder/{folder_id}

创建一个文件夹

POST /clickup/api/v2/space/{space_id}/folder

示例：

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

更新一个文件夹

PUT /clickup/api/v2/folder/{folder_id}

删除一个文件夹

DELETE /clickup/api/v2/folder/{folder_id}

列表

获取列表

GET /clickup/api/v2/folder/{folder_id}/list

查询参数：

archived- 包含已归档的列表 (true/false)

示例：

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

响应：

{
  "lists": [
    {
      "id": "901234",
      "name": "Backlog",
      "orderindex": 0,
      "status": {"status": "active", "color": "#87909e"},
      "task_count": 25,
      "folder": {"id": "456789", "name": "Sprint 1"}
    }
  ]
}

获取无文件夹的列表

GET /clickup/api/v2/space/{space_id}/list

获取列表

GET /clickup/api/v2/list/{list_id}

创建列表

POST /clickup/api/v2/folder/{folder_id}/list

示例：

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

创建无文件夹列表

POST /clickup/api/v2/space/{space_id}/list

更新列表

PUT /clickup/api/v2/list/{list_id}

删除列表

DELETE /clickup/api/v2/list/{list_id}

任务

获取任务

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毫秒）

示例：

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

响应：

{
  "tasks": [
    {
      "id": "abc123",
      "name": "实现登录功能",
      "status": {"status": "进行中", "type": "custom", "color": "#4194f6"},
      "priority": {"id": "2", "priority": "高", "color": "#f9d900"},
      "due_date": "1709251200000",
      "assignees": [{"id": 123, "username": "Alice Johnson", "email": "alice@acme.com"}],
      "description": "添加OAuth登录流程",
      "date_created": "1707436800000",
      "date_updated": "1708646400000"
    }
  ]
}

获取任务

GET /clickup/api/v2/task/{task_id}

查询参数：

custom_task_ids- 使用自定义任务ID（true/false）
team_id- 使用 custom_task_ids 时必需
include_subtasks- 包含子任务（true/false）

示例：

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

创建任务

POST /clickup/api/v2/list/{list_id}/task
Content-Type: application/json

{
  "name": "任务名称",
  "description": "任务描述",
  "assignees": [123],
  "status": "待办",
  "priority": 2,
  "due_date": 1709251200000,
  "tags": ["api", "后端"],
  "parent": null
}

字段：

name（必需）- 任务标题
description- 任务描述（支持markdown）
assignees- 用户ID数组
status- 状态名称（必须匹配列表中的状态）
priority- 优先级（1=紧急，2=高，3=普通，4=低，null=无）
due_date- Unix时间戳，单位为毫秒
due_date_time- 截止日期是否包含时间（true/false）
start_date- Unix时间戳，单位为毫秒
time_estimate- 时间预估，单位为毫秒
tags- 标签名称数组
parent- 父任务ID（用于子任务）
custom_fields- 自定义字段对象数组

示例：

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'name': '完成API集成', 'description': '集成新的支付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

更新任务

PUT /clickup/api/v2/task/{task_id}

示例：

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

删除任务

DELETE /clickup/api/v2/task/{task_id}

获取筛选后的团队任务

GET /clickup/api/v2/team/{team_id}/task

查询参数：

page- 页码（从0开始）
order_by- 排序字段
statuses[]- 按状态筛选
assignees[]- 按负责人筛选
list_ids[]- 按列表ID筛选
space_ids[]- 按空间ID筛选
folder_ids[]- 按文件夹ID筛选

用户

获取当前用户

GET /clickup/api/v2/user

示例：

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

响应：

{
  "user": {
    "id": 123,
    "username": "Alice Johnson",
    "email": "alice@acme.com",
    "color": "#7B68EE",
    "profilePicture": "https://...",
    "initials": "AJ",
    "week_start_day": 0,
    "timezone": "America/New_York"
  }
}

Webhooks

获取Webhooks

GET /clickup/api/v2/team/{team_id}/webhook

示例：

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

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
任务时间预估已更新,任务时间跟踪已更新
列表已创建,列表已更新,列表已删除
文件夹已创建,文件夹已更新,文件夹已删除
空间已创建,空间已更新,空间已删除
目标已创建,目标已更新,目标已删除
关键成果已创建,关键结果已更新,关键结果已删除

示例：

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

响应：

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

PUT /clickup/api/v2/webhook/{webhook_id}

删除 Webhook

DELETE /clickup/api/v2/webhook/{webhook_id}

分页

ClickUp 使用基于页面的分页。使用page参数（从0开始索引）：

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

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

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=紧急，2=高，3=普通，4=低，null=无优先级
API中将工作空间称为"团队"
状态值必须与列表中配置的精确状态名称匹配
响应结果每页限制100条项目
重要提示：使用curl命令时，若URL包含方括号（statuses[]、assignees[]、list_ids[]），请使用curl -g以禁用通配符解析
重要提示：当通过管道将curl输出传递给jq或其他命令时，环境变量如$MATON_API_KEY在某些shell环境中可能无法正确展开。通过管道传输时，您可能会收到"无效API密钥"的错误。

错误处理

状态码	含义
400	错误请求或缺少ClickUp连接
401	无效或缺少Maton API密钥
403	禁止访问 - 权限不足
404	未找到资源
429	请求频率受限
4xx/5xx	来自ClickUp API的透传错误

故障排除：API密钥问题

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

echo $MATON_API_KEY

通过列出连接来验证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

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

请确保您的URL路径以clickup开头。例如：

正确示例：https://gateway.maton.ai/clickup/api/v2/team
错误示例：https://gateway.maton.ai/api/v2/team

资源

免责申明

部分文章来自各大搜索引擎，如有侵权，请与我联系删除。

打赏

文章底部电脑广告

手机广告位-内容正文底部

标签

上一篇：Tavily Search 下一篇：Google Meet

ClickUp

ClickUp

快速开始

基础 URL

认证

获取您的 API 密钥

连接管理

列出连接

创建连接

获取连接

删除连接

指定连接

ClickUp 层级结构

API 参考

工作区（团队）

获取授权的工作区

空间

获取空间列表

获取单个空间

创建一个空间

更新一个空间

删除一个空间

文件夹

获取文件夹

获取一个文件夹

创建一个文件夹

更新一个文件夹

删除一个文件夹

列表

获取列表

获取无文件夹的列表

获取列表

创建列表

创建无文件夹列表

更新列表

删除列表

任务

获取任务

获取任务

创建任务

更新任务

删除任务

获取筛选后的团队任务

用户

获取当前用户

Webhooks

获取Webhooks

创建Webhook

更新 Webhook

删除 Webhook

分页

代码示例

JavaScript

Python

注意事项

错误处理

故障排除：API密钥问题

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

资源

相关文章

推荐文章

热门浏览

标签列表