ClickUp: Full Project Management API Access for Your AI Agent

15,396 downloads, 8 stars. The ClickUp skill by @byungkyu gives your Claude agent direct access to the ClickUp API — the full hierarchy of workspaces, spaces, folders, lists, and tasks — through byungkyu's Maton OAuth gateway. No manual OAuth setup, no token refresh logic. If your team manages work in ClickUp, this skill makes Claude a first-class participant in those workflows.

The Problem It Solves

ClickUp has one of the most complete project management APIs available, but using it programmatically means handling OAuth 2.0, access token management, and navigating ClickUp's nested organizational hierarchy (workspace → space → folder → list → task). Most developers who need "Claude + ClickUp" end up writing more OAuth plumbing than actual business logic.

The Maton gateway pattern removes that friction. Connect your ClickUp account once at ctrl.maton.ai, and all subsequent API calls route through gateway.maton.ai/clickup/... with a single MATON_API_KEY. The gateway injects your OAuth token automatically.

ClickUp's Organizational Hierarchy

Before using the API, it helps to understand how ClickUp organizes work:

Workspace (Team)
└── Space
    └── Folder
        └── List
            └── Task
                └── Subtask

The API follows this hierarchy. Most operations start by getting the workspace ID, then drilling down to the specific space, folder, list, or task you want to work with.

Core Operations

Get Your Workspaces

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"]}')
 
teams = json.load(urllib.request.urlopen(req))
for team in teams.get('teams', []):
    print(f"Workspace: {team['name']} (ID: {team['id']})")
EOF

List Tasks in a Space or List

python <<'EOF'
import urllib.request, os, json
 
list_id = "YOUR_LIST_ID"
req = urllib.request.Request(
    f'https://gateway.maton.ai/clickup/api/v2/list/{list_id}/task'
)
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
 
tasks = json.load(urllib.request.urlopen(req))
for task in tasks.get('tasks', []):
    print(f"[{task['status']['status']}] {task['name']}")
    print(f"  Assignees: {[a['username'] for a in task.get('assignees', [])]}")
    print(f"  Due: {task.get('due_date')}")
EOF

Create a Task

python <<'EOF'
import urllib.request, os, json
 
list_id = "YOUR_LIST_ID"
data = json.dumps({
    "name": "Review API integration documentation",
    "description": "Ensure all Maton gateway endpoints are documented",
    "status": "to do",
    "priority": 2,  # 1=urgent, 2=high, 3=normal, 4=low
    "due_date": 1752883200000,  # Unix ms
    "assignees": [12345678]  # ClickUp user IDs
}).encode()
 
req = urllib.request.Request(
    f'https://gateway.maton.ai/clickup/api/v2/list/{list_id}/task',
    data=data, method='POST'
)
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
 
task = json.load(urllib.request.urlopen(req))
print(f"Created: {task['name']} (ID: {task['id']})")
print(f"URL: {task['url']}")
EOF

Update Task Status

python <<'EOF'
import urllib.request, os, json
 
task_id = "YOUR_TASK_ID"
data = json.dumps({"status": "in progress"}).encode()
req = urllib.request.Request(
    f'https://gateway.maton.ai/clickup/api/v2/task/{task_id}',
    data=data, method='PUT'
)
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
 
updated = json.load(urllib.request.urlopen(req))
print(f"Updated: {updated['name']} → {updated['status']['status']}")
EOF

Set Up Webhooks

For event-driven workflows — receive notifications when tasks are created, updated, or completed:

python <<'EOF'
import urllib.request, os, json
 
team_id = "YOUR_WORKSPACE_ID"
data = json.dumps({
    "endpoint": "https://your-server.com/clickup-webhook",
    "events": ["taskCreated", "taskUpdated", "taskStatusUpdated"]
}).encode()
 
req = urllib.request.Request(
    f'https://gateway.maton.ai/clickup/api/v2/team/{team_id}/webhook',
    data=data, method='POST'
)
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
 
webhook = json.load(urllib.request.urlopen(req))
print(f"Webhook ID: {webhook['id']}")
EOF

Setup

clawhub install clickup-api

1. Sign up at maton.ai and get your API key
2. Go to ctrl.maton.ai
3. Create a ClickUp connection — completes Google/ClickUp OAuth in browser
4. export MATON_API_KEY="your_maton_key"

Use Cases

Sprint tracking automation. At the end of each sprint, have Claude query all tasks in a given space, calculate completion rates, identify blocked tasks, and generate a sprint report — all from existing ClickUp data.

Client onboarding workflows. When a new client is signed, Claude creates a dedicated ClickUp space with pre-defined lists (Discovery, Kickoff, Delivery, Review) and populates standard onboarding tasks automatically.

Cross-tool data sync. When a GitHub PR is merged, Claude creates a ClickUp task to track deployment verification. When a Calendly meeting is booked, Claude creates a prep task. These cross-tool integrations work naturally when Claude has API access to both sides.

Standup digest. Each morning, Claude pulls all tasks assigned to you that are overdue or due today across all spaces, formats a clean summary, and surfaces it via Slack or email. No more forgetting what's on your plate.

Bulk task creation. When a large project scope is defined (as a document or spec), Claude parses it and creates structured ClickUp tasks with proper hierarchy — saving hours of manual entry for large project setups.

Practical Tips

Get workspace IDs first. Almost all ClickUp API calls require knowing your workspace (team) ID. Run the workspace list query once, save the ID in your environment or config, and hardcode it into your agent scripts.

Tasks have persistent URLs. Every created task returns a url field — a direct ClickUp link. Include this in notifications, Slack messages, or email digests so humans can click through directly.

Custom field updates are a separate API call. Unlike the main task properties, custom fields require their own endpoint: PUT /api/v2/task/{task_id}/field/{field_id}. Query the field definitions for a list first (GET /api/v2/list/{list_id}/field) to get the field IDs, then update them individually. Don't expect to set custom field values in the same call as task creation.

Filter tasks efficiently. The /api/v2/list/{list_id}/task endpoint supports query parameters: ?status=in progress&assignee=12345&due_date_lt=1752883200000 — use these to avoid retrieving all tasks when you only need a subset.

Webhooks are more efficient than polling. For workflows that react to task changes, set up webhooks rather than polling on a schedule. The webhook integration requires a publicly accessible endpoint on your server.

Considerations

• Hierarchy navigation can be verbose. Getting to a specific task requires knowing workspace → space → list → task IDs. Build a helper function that caches these IDs rather than re-querying them on every call.
• Status names are workspace-specific. ClickUp lets teams customize their status names. "In Progress" in one workspace might be "Active" in another. Query the available statuses per space before writing status-based logic.
• Very low install count (2) vs downloads (15,396). This pattern across byungkyu's skills reflects that users download to evaluate the pattern, but deployment requires a Maton account and ClickUp connection setup that not everyone completes. The skill works well for those who do.
• API rate limits apply. ClickUp's API has rate limits (typically 100 requests/minute per token). Bulk operations should include delays between requests.

The Bigger Picture

ClickUp is one of the most feature-complete project management platforms available, but its API has traditionally been an afterthought for AI tooling. Most AI integration layers target Jira or Asana for enterprise use.

The ClickUp skill positions it as an equal participant in the AI workflow automation stack. For teams who chose ClickUp specifically because of its flexibility and customization, having Claude-native access to the full API — hierarchy navigation, task management, webhook subscriptions — closes a meaningful gap.

Combined with byungkyu's other skills (Calendly for scheduling, Google Meet for video, WhatsApp Business for messaging), ClickUp becomes part of a complete AI-native workflow layer that spans the full meeting-to-task-to-delivery cycle.

View the skill on ClawHub: clickup-api