Clickup API

ClickUp API Integration

Integrates with the ClickUp API v2 to programmatically manage tasks, lists, spaces, folders, goals, time tracking entries, dashboards, tags, teams, and custom fields using clickup-python-sdk.

TL;DR for Code Generation

• Use ClickupClient.init(user_token=...) from clickup_python_sdk for REST-based access
• ClickUp API is hierarchical: Teams → Spaces → Folders → Lists → Tasks
• Always specify include_closed and subtasks parameters for accurate task listing
• Use custom field APIs to read/write typed task metadata beyond standard fields
• Time tracking requires both start/stop time and duration — use ISO 8601 durations
• Handle clickup_python_sdk.exceptions.ClickUpException for API-level errors
• The API uses standard REST pagination with page and limit query params

When to Use

Use this skill when:

• Creating, updating, assigning, closing, or deleting ClickUp tasks
• Managing list structure: custom fields, tags, statuses, priorities, and assignees
• Organizing spaces and folders for team/project hierarchy
• Tracking time entries against tasks with start, stop, and duration
• Creating dashboards and views for reporting
• Automating recurring task creation from templates
• Syncing ClickUp tasks with external calendars, CRMs, or databases

When NOT to Use

• Real-time collaborative editing (ClickUp is a task/project manager, not a real-time doc editor)
• Large-scale data export (use ClickUp's CSV/Excel export or dedicated ETL integration)
• Anonymous or unauthenticated access (every request requires a valid API token)
• Replacing ClickUp Automations (use ClickUp's built-in automation rules where possible)

Core Workflow

1. Generate an API Token — Go to https://app.clickup.com/settings/apps and create a Personal API Token. Copy the pk_xxxxxxxx token. Checkpoint: Verify the token with client.get_teams().

2. Initialize the Client — client = ClickupClient.init(user_token=os.environ["CLICKUP_TOKEN"]). The SDK provides both sync and async client access. Checkpoint: Call client.get_teams() and print team names.

3. Navigate Hierarchy — From team → spaces → folders → lists → tasks. Use client.get_spaces(team_id=...), client.get_folders(space_id=...), client.get_lists(folder_id=...), client.get_tasks(list_id=...). Checkpoint: Confirm each level returns the expected resources.

4. Create or Update Tasks — Use client.create_task(list_id=..., name=..., ...) for new tasks. Use client.update_task(task_id=..., ...) for partial updates. Custom fields require client.set_custom_field(). Checkpoint: Re-fetch the task to confirm the mutation persisted.

5. Track Time — Use client.start_timer(task_id=...) and client.stop_timer(task_id=...) for time tracking. Create manual time entries with client.create_time_entry(). Checkpoint: Verify the time entry appears in the ClickUp task.

6. Handle Errors — Wrap API calls in try/except ClickUpException. Check the status_code for 401 (auth), 403 (permissions), 404 (not found), 429 (rate limit). Checkpoint: Log response.json() when available for API-side errors.

Implementation Patterns

Pattern 1: List Tasks with Custom Fields

import os
from clickup_python_sdk.api import ClickupClient

client = ClickupClient.init(user_token=os.environ["CLICKUP_TOKEN"])

def list_open_tasks(list_id: str) -> list[dict]:
    """Fetch all open tasks from a ClickUp list."""
    tasks = client.get_tasks(
        list_id=list_id,
        include_closed=False,
        subtasks=True,
        order_by="due_date",
    )
    return tasks if tasks else []

tasks = list_open_tasks("123456789")
for task in tasks:
    print(f"Task: {task.name} | Due: {task.due_date} | Assignee: {task.assignees}")

Pattern 2: Create a Task with Custom Fields

def create_tracked_task(
    list_id: str,
    name: str,
    description: str,
    priority: int = 3,
    assignees: list[int] | None = None,
    due_date: int | None = None,
) -> dict:
    """Create a ClickUp task with priority, assignees, and due date."""
    params = {
        "name": name,
        "description": description,
        "priority": priority,  # 1=urgent, 2=high, 3=normal, 4=low
        "assignees": assignees or [],
    }
    if due_date:
        params["due_date"] = due_date  # Unix timestamp in milliseconds
    task = client.create_task(list_id=list_id, **params)
    return task

# Create a high-priority task due tomorrow (Unix ms)
import time
due = int((time.time() + 86400) * 1000)
task = create_tracked_task(
    list_id="123456789",
    name="Fix login timeout bug",
    description="Users report 502 errors on login after 60s idle.",
    priority=2,
    assignees=[12345],
    due_date=due,
)
print(f"Created task: {task.id} — {task.url}")

Pattern 3: Time Tracking

from datetime import datetime, timezone

def log_time_entry(
    task_id: str,
    duration_minutes: int,
    description: str,
    billable: bool = True,
) -> dict:
    """Log a manual time entry against a ClickUp task."""
    start_ms = int(datetime.now(timezone.utc).timestamp() * 1000)
    duration_ms = duration_minutes * 60 * 1000

    try:
        entry = client.create_time_entry(
            task_id=task_id,
            start=start_ms,
            duration=duration_ms,
            description=description,
            billable=billable,
        )
        return entry
    except Exception as e:
        print(f"Failed to log time: {e}")
        raise

log_time_entry("abc123_task", 45, "Code review and merge", billable=True)

Pattern 4: BAD vs GOOD — Task Updates

# ❌ BAD — fetches entire task object, modifies, re-posts
task = client.get_task(task_id="abc123")
task.name = "Updated Name"
task.description = "Updated desc"
client.update_task(task_id="abc123", name=task.name, description=task.description)

# ✅ GOOD — partial update with only changed fields
client.update_task(
    task_id="abc123",
    name="Updated Name",
    description="Updated desc",
)

Pattern 5: BAD vs GOOD — Error Handling

# ❌ BAD — bare except, loses API error details
try:
    client.get_task(task_id="nonexistent")
except Exception as e:
    print("Error:", e)

# ✅ GOOD — typed ClickUp exception
from clickup_python_sdk.exceptions import ClickUpException

def safe_get_task(task_id: str) -> dict | None:
    """Fetch a task with resilient error handling."""
    try:
        return client.get_task(task_id=task_id)
    except ClickUpException as e:
        status = getattr(e, "status_code", 0)
        if status == 404:
            print(f"Task {task_id} not found.")
            return None
        if status == 429:
            print("Rate limited — retry later.")
            return None
        print(f"ClickUp API error (status {status}): {e}")
        return None

Constraints

MUST DO

• Use environment variables for the API token — never hardcode it
• Always set include_closed=False unless you specifically need archived tasks
• Use Unix timestamps in milliseconds for all date/time parameters
• Paginate task lists with page and limit params (max 100 per page)
• Verify custom field IDs and types before writing values

MUST NOT DO

• Assume task IDs are human-readable — they are opaque strings
• Poll tasks for real-time updates (use ClickUp webhooks instead)
• Create duplicate tagging structures — check existing tags first
• Use personal tokens in client-side or public applications

Output Template

Every integration function should expose:

1. Client Initialization — ClickupClient.init(user_token=...) with token from env
2. Hierarchy Navigation — Team → Space → Folder → List → Task resolution
3. Mutation — Task creation/update with typed parameters
4. Time Tracking — Start/stop or manual time entry with ISO 8601 duration
5. Error Handling — try/except ClickUpException with status-specific recovery

Related Skills

| Skill | Purpose | |