ClickUpClient

clickup_client

ClickUp REST API client.

This module provides a client for interacting with the ClickUp REST API v2. All API errors are converted to appropriate exception types from the exceptions module.

ClickUpClient

Client for interacting with ClickUp via REST API.

This client wraps the ClickUp REST API v2 and provides methods for common operations like creating, updating, and fetching tasks.

Example

client = ClickUpClient() task = client.get_task("task_id") client.update_task("task_id", name="New name")

Source code in beads_clickup/clickup_client.py

class ClickUpClient:
    """Client for interacting with ClickUp via REST API.

    This client wraps the ClickUp REST API v2 and provides methods for
    common operations like creating, updating, and fetching tasks.

    Example:
        >>> client = ClickUpClient()
        >>> task = client.get_task("task_id")
        >>> client.update_task("task_id", name="New name")
    """

    BASE_URL = "https://api.clickup.com/api/v2"

    # Timeout for API requests in seconds
    DEFAULT_TIMEOUT = 30

    def __init__(
        self,
        api_token: Optional[str] = None,
        timeout: int = DEFAULT_TIMEOUT,
    ):
        """Initialize ClickUp REST API client.

        Args:
            api_token: ClickUp API token. If not provided, will look for
                       CLICKUP_API_TOKEN env var or ~/.config/beads/env
            timeout: Request timeout in seconds (default: 30)

        Raises:
            ConfigurationError: If no API token is found
        """
        self.api_token = (
            api_token
            or os.getenv("CLICKUP_API_TOKEN")
            or self._load_token_from_config()
        )

        if not self.api_token:
            raise ConfigurationError(
                "ClickUp API token is required. "
                "Set CLICKUP_API_TOKEN env var or save to ~/.config/beads/env. "
                "Get token from: https://app.clickup.com/settings/apps"
            )

        # Personal API tokens use direct token format (not "Bearer")
        self.headers = {
            "Authorization": self.api_token,
            "Content-Type": "application/json",
        }

        self.timeout = timeout

    @staticmethod
    def _load_token_from_config() -> Optional[str]:
        """Load API token from ~/.config/beads/env file.

        Returns:
            API token string or None if not found
        """
        env_file = Path.home() / ".config" / "beads" / "env"
        if env_file.exists():
            try:
                content = env_file.read_text()
                match = re.search(r'CLICKUP_API_TOKEN[="\s\']+([^"\']+)', content)
                if match:
                    return match.group(1).strip("\"'")
            except OSError as e:
                logger.debug("Failed to read token from config: %s", e)
        return None

    def _request(
        self,
        method: str,
        endpoint: str,
        **kwargs: Any,
    ) -> dict[str, Any]:
        """Make a request to ClickUp REST API.

        Args:
            method: HTTP method (GET, POST, PUT, DELETE)
            endpoint: API endpoint (without base URL)
            **kwargs: Additional arguments for requests

        Returns:
            Response JSON as dictionary

        Raises:
            ClickUpAPIError: If request fails with API error
            AuthenticationError: If authentication fails (401)
            ResourceNotFoundError: If resource not found (404)
            RateLimitError: If rate limit exceeded (429)
        """
        url = f"{self.BASE_URL}/{endpoint}"

        try:
            response = requests.request(
                method,
                url,
                headers=self.headers,
                timeout=self.timeout,
                **kwargs,
            )

            # Handle error responses
            if not response.ok:
                self._handle_error_response(response, endpoint)

            # DELETE requests may return empty response
            if method == "DELETE" or not response.content:
                return {}

            return response.json()

        except requests.exceptions.Timeout as e:
            raise ClickUpAPIError(
                f"Request timed out after {self.timeout}s",
                endpoint=endpoint,
            ) from e
        except requests.exceptions.ConnectionError as e:
            raise ClickUpAPIError(
                f"Connection failed: {e}",
                endpoint=endpoint,
            ) from e
        except requests.exceptions.RequestException as e:
            raise ClickUpAPIError(
                f"Request failed: {e}",
                endpoint=endpoint,
            ) from e

    def _handle_error_response(
        self,
        response: requests.Response,
        endpoint: str,
    ) -> None:
        """Handle an error response from the API.

        Args:
            response: The error response
            endpoint: API endpoint that was called

        Raises:
            Appropriate ClickUpAPIError subclass
        """
        status_code = response.status_code

        # Try to parse error body
        try:
            error_body = response.json()
        except ValueError:
            error_body = {"error": response.text}

        # Use factory method to create appropriate exception
        raise ClickUpAPIError.from_response(
            status_code=status_code,
            response_body=error_body,
            endpoint=endpoint,
        )

    # ========== Task Operations ==========

    def create_task(
        self,
        list_id: str,
        name: str,
        description: Optional[str] = None,
        status: Optional[str] = None,
        priority: Optional[int] = None,
        tags: Optional[list[str]] = None,
        assignees: Optional[list[str]] = None,
        custom_fields: Optional[list[dict[str, Any]]] = None,
        parent: Optional[str] = None,
        start_date: Optional[int] = None,
        due_date: Optional[int] = None,
        time_estimate: Optional[int] = None,
    ) -> dict[str, Any]:
        """Create a task in ClickUp.

        Args:
            list_id: ClickUp list ID
            name: Task name/title
            description: Task description
            status: Task status
            priority: Priority (1=Urgent, 2=High, 3=Normal, 4=Low)
            tags: List of tag names
            assignees: List of assignee user IDs
            custom_fields: List of custom field dicts with 'id' and 'value'
            parent: Parent task ID (makes this a subtask)
            start_date: Start date (Unix timestamp in milliseconds)
            due_date: Due date (Unix timestamp in milliseconds)
            time_estimate: Time estimate in milliseconds

        Returns:
            Created task information including id and url

        Raises:
            ClickUpAPIError: If task creation fails
        """
        task_data: dict[str, Any] = {"name": name}

        if description:
            task_data["description"] = description
        if status:
            task_data["status"] = status
        if priority is not None:
            task_data["priority"] = priority
        if tags:
            task_data["tags"] = tags
        if parent:
            task_data["parent"] = parent
        if assignees:
            task_data["assignees"] = assignees
        if start_date is not None:
            task_data["start_date"] = start_date
        if due_date is not None:
            task_data["due_date"] = due_date
        if time_estimate is not None:
            task_data["time_estimate"] = time_estimate
        if custom_fields:
            task_data["custom_fields"] = custom_fields

        result = self._request("POST", f"list/{list_id}/task", json=task_data)

        # Add task URL for convenience
        task_id = result.get("id", "")
        if task_id and "url" not in result:
            result["url"] = f"https://app.clickup.com/t/{task_id}"

        return result

    def update_task(
        self,
        task_id: str,
        name: Optional[str] = None,
        description: Optional[str] = None,
        status: Optional[str] = None,
        priority: Optional[int] = None,
        tags: Optional[list[str]] = None,
        start_date: Optional[int] = None,
        due_date: Optional[int] = None,
        parent: Optional[str] = None,
        assignees: Optional[list[str]] = None,
        time_estimate: Optional[int] = None,
        custom_fields: Optional[list[dict[str, Any]]] = None,
    ) -> dict[str, Any]:
        """Update a ClickUp task.

        Args:
            task_id: ClickUp task ID
            name: New task name
            description: New description
            status: New status
            priority: New priority
            tags: New tags
            start_date: Start date (Unix timestamp in milliseconds)
            due_date: Due date (Unix timestamp in milliseconds)
            parent: Parent task ID (makes this a subtask)
            assignees: List of assignee user IDs
            time_estimate: Time estimate in milliseconds
            custom_fields: List of custom field dicts with 'id' and 'value'

        Returns:
            Updated task information

        Raises:
            ClickUpAPIError: If update fails
            ResourceNotFoundError: If task not found
        """
        task_data: dict[str, Any] = {}

        if name is not None:
            task_data["name"] = name
        if description is not None:
            task_data["description"] = description
        if status is not None:
            task_data["status"] = status
        if priority is not None:
            task_data["priority"] = priority
        if tags is not None:
            task_data["tags"] = tags
        if start_date is not None:
            task_data["start_date"] = start_date
        if due_date is not None:
            task_data["due_date"] = due_date
        if parent is not None:
            task_data["parent"] = parent
        if assignees is not None:
            task_data["assignees"] = {"add": assignees}
        if time_estimate is not None:
            task_data["time_estimate"] = time_estimate
        if custom_fields is not None:
            task_data["custom_fields"] = custom_fields

        if not task_data:
            raise ValueError("At least one field to update must be provided")

        return self._request("PUT", f"task/{task_id}", json=task_data)

    def get_task(self, task_id: str) -> dict[str, Any]:
        """Get a ClickUp task by ID.

        Args:
            task_id: ClickUp task ID

        Returns:
            Task information

        Raises:
            ResourceNotFoundError: If task not found
        """
        return self._request("GET", f"task/{task_id}")

    def delete_task(self, task_id: str) -> bool:
        """Delete a ClickUp task.

        Args:
            task_id: ClickUp task ID

        Returns:
            True if successful

        Raises:
            ResourceNotFoundError: If task not found
        """
        self._request("DELETE", f"task/{task_id}")
        return True

    def list_tasks(
        self,
        list_id: str,
        include_closed: bool = False,
        date_updated_gt: Optional[int] = None,
    ) -> list[dict[str, Any]]:
        """List tasks from a ClickUp list, fetching all pages.

        Args:
            list_id: ClickUp list ID
            include_closed: Include closed/archived tasks
            date_updated_gt: Only return tasks updated after this Unix timestamp (ms)

        Returns:
            List of tasks across all pages
        """
        params: dict[str, str] = {
            "subtasks": "true",
        }
        if include_closed:
            params["include_closed"] = "true"
        if date_updated_gt is not None:
            params["date_updated_gt"] = str(date_updated_gt)

        all_tasks: list[dict[str, Any]] = []
        page = 0
        while True:
            params["page"] = str(page)
            result = self._request("GET", f"list/{list_id}/task", params=params)
            page_tasks = result.get("tasks", [])
            all_tasks.extend(page_tasks)
            if len(page_tasks) < _CLICKUP_PAGE_SIZE:
                break
            page += 1

        return all_tasks

    # ========== Custom Fields ==========

    def set_custom_field(
        self,
        task_id: str,
        field_id: str,
        value: Any,
    ) -> dict[str, Any]:
        """Set a custom field value on a task.

        Args:
            task_id: ClickUp task ID
            field_id: Custom field UUID
            value: Value to set (format depends on field type)

        Returns:
            Response from ClickUp API
        """
        return self._request(
            "POST",
            f"task/{task_id}/field/{field_id}",
            json={"value": value},
        )

    def add_task_link(self, task_id: str, links_to: str) -> dict[str, Any]:
        """Link this task to another task (Task Links in ClickUp).

        Args:
            task_id: ClickUp task ID to add the link to
            links_to: ClickUp task ID this task links to

        Returns:
            Response from ClickUp API
        """
        return self._request(
            "POST",
            f"task/{task_id}/link/{links_to}",
        )

    def delete_task_link(self, task_id: str, links_to: str) -> dict[str, Any]:
        """Remove a task link between two tasks.

        Args:
            task_id: ClickUp task ID to remove the link from
            links_to: ClickUp task ID this task links to

        Returns:
            Response from ClickUp API
        """
        return self._request(
            "DELETE",
            f"task/{task_id}/link/{links_to}",
        )

    # ========== Dependencies ==========

    def add_dependency(
        self,
        task_id: str,
        depends_on: Optional[str] = None,
        dependency_of: Optional[str] = None,
    ) -> dict[str, Any]:
        """Add dependency relationship between tasks.

        Args:
            task_id: Task that is waiting or blocking
            depends_on: Task ID that task_id depends on (task_id waits for this)
            dependency_of: Task ID that depends on task_id (this task blocks it)

        Returns:
            Response from ClickUp API

        Raises:
            ValueError: If neither depends_on nor dependency_of is provided
            ClickUpAPIError: If API request fails

        Note:
            You can only use one parameter per request (depends_on OR dependency_of).
            - depends_on: task_id is waiting for depends_on to be completed
            - dependency_of: task_id is blocking dependency_of
        """
        if depends_on is None and dependency_of is None:
            raise ValueError("Must provide either depends_on or dependency_of")

        if depends_on is not None and dependency_of is not None:
            raise ValueError(
                "Can only use one of depends_on or dependency_of per request"
            )

        body = {}
        if depends_on:
            body["depends_on"] = depends_on
        if dependency_of:
            body["dependency_of"] = dependency_of

        return self._request(
            "POST",
            f"task/{task_id}/dependency",
            json=body,
        )

    def remove_dependency(
        self,
        task_id: str,
        depends_on: Optional[str] = None,
        dependency_of: Optional[str] = None,
    ) -> dict[str, Any]:
        """Remove dependency relationship between tasks.

        Args:
            task_id: Task that is waiting or blocking
            depends_on: Task ID that task_id depends on
            dependency_of: Task ID that depends on task_id

        Returns:
            Response from ClickUp API

        Raises:
            ValueError: If neither depends_on nor dependency_of is provided
        """
        if depends_on is None and dependency_of is None:
            raise ValueError("Must provide either depends_on or dependency_of")

        params = {}
        if depends_on:
            params["depends_on"] = depends_on
        if dependency_of:
            params["dependency_of"] = dependency_of

        return self._request(
            "DELETE",
            f"task/{task_id}/dependency",
            params=params,
        )

    def get_task_dependencies(self, task_id: str) -> dict[str, list[str]]:
        """Get all dependencies for a task.

        Args:
            task_id: ClickUp task ID

        Returns:
            Dictionary with 'depends_on' and 'blocking' keys containing lists of task IDs

        Note:
            This extracts dependency information from the task data returned by get_task().
            The task response includes:
            - dependencies: list of tasks this task depends on (waiting for)
            - blocking: list of tasks this task is blocking
        """
        task = self.get_task(task_id)

        # Parse dependencies from task response
        depends_on = []
        blocking = []

        # Dependencies are tasks this task is waiting for
        if "dependencies" in task:
            for dep in task["dependencies"]:
                if "task_id" in dep:
                    depends_on.append(dep["task_id"])

        # Blocking are tasks waiting for this task
        if "blocking" in task:
            for block in task["blocking"]:
                if "task_id" in block:
                    blocking.append(block["task_id"])

        return {
            "depends_on": depends_on,
            "blocking": blocking,
        }

    def get_list_custom_fields(self, list_id: str) -> list[dict[str, Any]]:
        """Get custom fields available on a list.

        Args:
            list_id: ClickUp list ID

        Returns:
            List of custom field definitions with id, name, type, options, etc.
        """
        result = self._request("GET", f"list/{list_id}/field")
        return result.get("fields", [])

    def get_list_statuses(self, list_id: str) -> list[dict[str, Any]]:
        """Get all statuses from a ClickUp list.

        Args:
            list_id: The ClickUp list ID

        Returns:
            List of status dictionaries with keys: id, status, type, orderindex, color
        """
        result = self._request("GET", f"list/{list_id}")
        return result.get("statuses", [])

    def create_custom_field(
        self,
        list_id: str,
        name: str,
        field_type: str,
        type_config: Optional[dict[str, Any]] = None,
        required: bool = False,
    ) -> dict[str, Any]:
        """Create a custom field on a list.

        Args:
            list_id: List ID to add field to
            name: Display name for the field
            field_type: Type (drop_down, text, url, users, labels, etc.)
            type_config: Type-specific configuration (e.g., dropdown options)
            required: Whether field is required

        Returns:
            Created field information including field ID

        Example:
            >>> client.create_custom_field(
            ...     list_id="123",
            ...     name="Priority",
            ...     field_type="drop_down",
            ...     type_config={"options": [{"name": "High"}, {"name": "Low"}]},
            ...     required=True
            ... )
        """
        payload: dict[str, Any] = {
            "name": name,
            "type": field_type,
        }
        if type_config:
            payload["type_config"] = type_config
        if required:
            payload["required"] = required

        return self._request("POST", f"list/{list_id}/field", json=payload)

    def update_list_statuses(
        self,
        list_id: str,
        statuses: list[dict[str, Any]],
    ) -> dict[str, Any]:
        """Update the statuses/columns for a list.

        Args:
            list_id: List ID
            statuses: List of status configurations with name, type, color

        Returns:
            Updated list information

        Example:
            >>> client.update_list_statuses(
            ...     list_id="123",
            ...     statuses=[
            ...         {"status": "TO DO", "type": "open", "color": "#d3d3d3"},
            ...         {"status": "IN PROGRESS", "type": "custom", "color": "#4194f6"},
            ...         {"status": "COMPLETE", "type": "closed", "color": "#6bc950"},
            ...     ]
            ... )
        """
        return self._request("PUT", f"list/{list_id}", json={"statuses": statuses})

    # ========== Comments ==========

    def add_comment(self, task_id: str, comment_text: str) -> dict[str, Any]:
        """Add a comment to a ClickUp task.

        Args:
            task_id: ClickUp task ID
            comment_text: Comment text

        Returns:
            Comment information
        """
        comment_data = {"comment_text": comment_text}
        return self._request("POST", f"task/{task_id}/comment", json=comment_data)

    def get_comments(self, task_id: str) -> list[dict[str, Any]]:
        """Get all comments for a ClickUp task.

        Args:
            task_id: ClickUp task ID

        Returns:
            List of comment dictionaries with id, comment, user, date_added, etc.
        """
        result = self._request("GET", f"task/{task_id}/comment")
        return result.get("comments", [])

    # ========== Lists, Folders, Spaces ==========

    def get_lists(self, folder_id: str) -> list[dict[str, Any]]:
        """Get lists from a ClickUp folder.

        Args:
            folder_id: Folder ID

        Returns:
            List of lists
        """
        result = self._request("GET", f"folder/{folder_id}/list")
        return result.get("lists", [])

    def get_folders(self, space_id: str) -> list[dict[str, Any]]:
        """Get folders from a ClickUp space.

        Args:
            space_id: Space ID

        Returns:
            List of folders
        """
        result = self._request("GET", f"space/{space_id}/folder")
        return result.get("folders", [])

    def get_folderless_lists(self, space_id: str) -> list[dict[str, Any]]:
        """Get lists that are not in any folder (folderless lists).

        Args:
            space_id: Space ID

        Returns:
            List of folderless lists
        """
        result = self._request("GET", f"space/{space_id}/list")
        return result.get("lists", [])

    def get_spaces(self, team_id: str) -> list[dict[str, Any]]:
        """Get spaces from a ClickUp workspace.

        Args:
            team_id: Team/workspace ID

        Returns:
            List of spaces
        """
        result = self._request("GET", f"team/{team_id}/space")
        return result.get("spaces", [])

    def create_space(
        self,
        team_id: str,
        name: str,
        multiple_assignees: bool = True,
        features: Optional[dict[str, Any]] = None,
    ) -> dict[str, Any]:
        """Create a new space in a ClickUp workspace.

        Args:
            team_id: Team/workspace ID
            name: Name of the space
            multiple_assignees: Allow multiple assignees on tasks
            features: Optional features configuration

        Returns:
            Created space information including space ID
        """
        space_data = {
            "name": name,
            "multiple_assignees": multiple_assignees,
        }
        if features:
            space_data["features"] = features

        return self._request("POST", f"team/{team_id}/space", json=space_data)

    def create_list(
        self,
        space_id: str,
        name: str,
        content: Optional[str] = None,
        due_date: Optional[int] = None,
        priority: Optional[int] = None,
    ) -> dict[str, Any]:
        """Create a new list (folderless) in a ClickUp space.

        Args:
            space_id: Space ID where the list will be created
            name: Name of the list
            content: Description/content for the list
            due_date: Due date in Unix milliseconds
            priority: Priority level (1-4)

        Returns:
            Created list information including list ID
        """
        list_data: dict[str, Any] = {"name": name}

        if content:
            list_data["content"] = content
        if due_date:
            list_data["due_date"] = due_date
        if priority:
            list_data["priority"] = priority

        return self._request("POST", f"space/{space_id}/list", json=list_data)

    def get_workspace(self) -> dict[str, Any]:
        """Get workspace/team information.

        Returns:
            Workspace information including team ID
        """
        return self._request("GET", "team")

    def search_tasks(
        self,
        query: str,
        team_id: Optional[str] = None,
    ) -> list[dict[str, Any]]:
        """Search for tasks across workspace.

        Args:
            query: Search query
            team_id: Team ID to search within

        Returns:
            List of matching tasks
        """
        params: dict[str, str] = {"query": query}
        if team_id:
            params["team_id"] = team_id

        result = self._request("GET", "search", params=params)
        return result.get("tasks", [])

    # ========== Webhook Management ==========

    def create_webhook(
        self,
        team_id: str,
        endpoint: str,
        events: Optional[list[str]] = None,
    ) -> dict[str, Any]:
        """Create a webhook in ClickUp.

        Args:
            team_id: Team/workspace ID
            endpoint: URL to receive webhook events
            events: List of event types to subscribe to

        Returns:
            Created webhook information including webhook ID
        """
        default_events = [
            "taskCreated",
            "taskUpdated",
            "taskDeleted",
            "taskStatusUpdated",
            "taskAssigneeUpdated",
            "taskPriorityUpdated",
            "taskDueDateUpdated",
            "taskMoved",
            "taskCommentPosted",
        ]

        webhook_data = {
            "endpoint": endpoint,
            "events": events or default_events,
        }

        return self._request("POST", f"team/{team_id}/webhook", json=webhook_data)

    def get_webhooks(self, team_id: str) -> list[dict[str, Any]]:
        """Get all webhooks for a workspace.

        Args:
            team_id: Team/workspace ID

        Returns:
            List of webhook dictionaries
        """
        result = self._request("GET", f"team/{team_id}/webhook")
        return result.get("webhooks", [])

    def update_webhook(
        self,
        webhook_id: str,
        endpoint: Optional[str] = None,
        events: Optional[list[str]] = None,
        status: Optional[str] = None,
    ) -> dict[str, Any]:
        """Update a webhook.

        Args:
            webhook_id: Webhook ID to update
            endpoint: New endpoint URL (optional)
            events: New list of events (optional)
            status: New status ('active' or 'inactive') (optional)

        Returns:
            Updated webhook information
        """
        webhook_data: dict[str, Any] = {}
        if endpoint:
            webhook_data["endpoint"] = endpoint
        if events:
            webhook_data["events"] = events
        if status:
            webhook_data["status"] = status

        return self._request("PUT", f"webhook/{webhook_id}", json=webhook_data)

    def delete_webhook(self, webhook_id: str) -> bool:
        """Delete a webhook.

        Args:
            webhook_id: Webhook ID to delete

        Returns:
            True if deletion succeeded
        """
        self._request("DELETE", f"webhook/{webhook_id}")
        return True

__init__(api_token=None, timeout=DEFAULT_TIMEOUT)

Initialize ClickUp REST API client.

Parameters:

Name	Type	Description	Default
api_token	Optional[str]	ClickUp API token. If not provided, will look for CLICKUP_API_TOKEN env var or ~/.config/beads/env	None
timeout	int	Request timeout in seconds (default: 30)	DEFAULT_TIMEOUT

Raises:

Type	Description
ConfigurationError	If no API token is found

Source code in beads_clickup/clickup_client.py

def __init__(
    self,
    api_token: Optional[str] = None,
    timeout: int = DEFAULT_TIMEOUT,
):
    """Initialize ClickUp REST API client.

    Args:
        api_token: ClickUp API token. If not provided, will look for
                   CLICKUP_API_TOKEN env var or ~/.config/beads/env
        timeout: Request timeout in seconds (default: 30)

    Raises:
        ConfigurationError: If no API token is found
    """
    self.api_token = (
        api_token
        or os.getenv("CLICKUP_API_TOKEN")
        or self._load_token_from_config()
    )

    if not self.api_token:
        raise ConfigurationError(
            "ClickUp API token is required. "
            "Set CLICKUP_API_TOKEN env var or save to ~/.config/beads/env. "
            "Get token from: https://app.clickup.com/settings/apps"
        )

    # Personal API tokens use direct token format (not "Bearer")
    self.headers = {
        "Authorization": self.api_token,
        "Content-Type": "application/json",
    }

    self.timeout = timeout

add_comment(task_id, comment_text)

Add a comment to a ClickUp task.

Parameters:

Name	Type	Description	Default
task_id	str	ClickUp task ID	required
comment_text	str	Comment text	required

Returns:

Type	Description
dict[str, Any]	Comment information

Source code in beads_clickup/clickup_client.py

def add_comment(self, task_id: str, comment_text: str) -> dict[str, Any]:
    """Add a comment to a ClickUp task.

    Args:
        task_id: ClickUp task ID
        comment_text: Comment text

    Returns:
        Comment information
    """
    comment_data = {"comment_text": comment_text}
    return self._request("POST", f"task/{task_id}/comment", json=comment_data)

add_dependency(task_id, depends_on=None, dependency_of=None)

Add dependency relationship between tasks.

Parameters:

Name	Type	Description	Default
task_id	str	Task that is waiting or blocking	required
depends_on	Optional[str]	Task ID that task_id depends on (task_id waits for this)	None
dependency_of	Optional[str]	Task ID that depends on task_id (this task blocks it)	None

Returns:

Type	Description
dict[str, Any]	Response from ClickUp API

Raises:

Type	Description
ValueError	If neither depends_on nor dependency_of is provided
ClickUpAPIError	If API request fails

Note

You can only use one parameter per request (depends_on OR dependency_of). - depends_on: task_id is waiting for depends_on to be completed - dependency_of: task_id is blocking dependency_of

Source code in beads_clickup/clickup_client.py

def add_dependency(
    self,
    task_id: str,
    depends_on: Optional[str] = None,
    dependency_of: Optional[str] = None,
) -> dict[str, Any]:
    """Add dependency relationship between tasks.

    Args:
        task_id: Task that is waiting or blocking
        depends_on: Task ID that task_id depends on (task_id waits for this)
        dependency_of: Task ID that depends on task_id (this task blocks it)

    Returns:
        Response from ClickUp API

    Raises:
        ValueError: If neither depends_on nor dependency_of is provided
        ClickUpAPIError: If API request fails

    Note:
        You can only use one parameter per request (depends_on OR dependency_of).
        - depends_on: task_id is waiting for depends_on to be completed
        - dependency_of: task_id is blocking dependency_of
    """
    if depends_on is None and dependency_of is None:
        raise ValueError("Must provide either depends_on or dependency_of")

    if depends_on is not None and dependency_of is not None:
        raise ValueError(
            "Can only use one of depends_on or dependency_of per request"
        )

    body = {}
    if depends_on:
        body["depends_on"] = depends_on
    if dependency_of:
        body["dependency_of"] = dependency_of

    return self._request(
        "POST",
        f"task/{task_id}/dependency",
        json=body,
    )

add_task_link(task_id, links_to)

Link this task to another task (Task Links in ClickUp).

Parameters:

Name	Type	Description	Default
task_id	str	ClickUp task ID to add the link to	required
links_to	str	ClickUp task ID this task links to	required

Returns:

Type	Description
dict[str, Any]	Response from ClickUp API

Source code in beads_clickup/clickup_client.py

def add_task_link(self, task_id: str, links_to: str) -> dict[str, Any]:
    """Link this task to another task (Task Links in ClickUp).

    Args:
        task_id: ClickUp task ID to add the link to
        links_to: ClickUp task ID this task links to

    Returns:
        Response from ClickUp API
    """
    return self._request(
        "POST",
        f"task/{task_id}/link/{links_to}",
    )

create_custom_field(list_id, name, field_type, type_config=None, required=False)

Create a custom field on a list.

Parameters:

Name	Type	Description	Default
list_id	str	List ID to add field to	required
name	str	Display name for the field	required
field_type	str	Type (drop_down, text, url, users, labels, etc.)	required
type_config	Optional[dict[str, Any]]	Type-specific configuration (e.g., dropdown options)	None
required	bool	Whether field is required	False

Returns:

Type	Description
dict[str, Any]	Created field information including field ID

Example

client.create_custom_field( ... list_id="123", ... name="Priority", ... field_type="drop_down", ... type_config={"options": [{"name": "High"}, {"name": "Low"}]}, ... required=True ... )

Source code in beads_clickup/clickup_client.py

def create_custom_field(
    self,
    list_id: str,
    name: str,
    field_type: str,
    type_config: Optional[dict[str, Any]] = None,
    required: bool = False,
) -> dict[str, Any]:
    """Create a custom field on a list.

    Args:
        list_id: List ID to add field to
        name: Display name for the field
        field_type: Type (drop_down, text, url, users, labels, etc.)
        type_config: Type-specific configuration (e.g., dropdown options)
        required: Whether field is required

    Returns:
        Created field information including field ID

    Example:
        >>> client.create_custom_field(
        ...     list_id="123",
        ...     name="Priority",
        ...     field_type="drop_down",
        ...     type_config={"options": [{"name": "High"}, {"name": "Low"}]},
        ...     required=True
        ... )
    """
    payload: dict[str, Any] = {
        "name": name,
        "type": field_type,
    }
    if type_config:
        payload["type_config"] = type_config
    if required:
        payload["required"] = required

    return self._request("POST", f"list/{list_id}/field", json=payload)

create_list(space_id, name, content=None, due_date=None, priority=None)

Create a new list (folderless) in a ClickUp space.

Parameters:

Name	Type	Description	Default
space_id	str	Space ID where the list will be created	required
name	str	Name of the list	required
content	Optional[str]	Description/content for the list	None
due_date	Optional[int]	Due date in Unix milliseconds	None
priority	Optional[int]	Priority level (1-4)	None

Returns:

Type	Description
dict[str, Any]	Created list information including list ID

Source code in beads_clickup/clickup_client.py

def create_list(
    self,
    space_id: str,
    name: str,
    content: Optional[str] = None,
    due_date: Optional[int] = None,
    priority: Optional[int] = None,
) -> dict[str, Any]:
    """Create a new list (folderless) in a ClickUp space.

    Args:
        space_id: Space ID where the list will be created
        name: Name of the list
        content: Description/content for the list
        due_date: Due date in Unix milliseconds
        priority: Priority level (1-4)

    Returns:
        Created list information including list ID
    """
    list_data: dict[str, Any] = {"name": name}

    if content:
        list_data["content"] = content
    if due_date:
        list_data["due_date"] = due_date
    if priority:
        list_data["priority"] = priority

    return self._request("POST", f"space/{space_id}/list", json=list_data)

create_space(team_id, name, multiple_assignees=True, features=None)

Create a new space in a ClickUp workspace.

Parameters:

Name	Type	Description	Default
team_id	str	Team/workspace ID	required
name	str	Name of the space	required
multiple_assignees	bool	Allow multiple assignees on tasks	True
features	Optional[dict[str, Any]]	Optional features configuration	None

Returns:

Type	Description
dict[str, Any]	Created space information including space ID

Source code in beads_clickup/clickup_client.py

def create_space(
    self,
    team_id: str,
    name: str,
    multiple_assignees: bool = True,
    features: Optional[dict[str, Any]] = None,
) -> dict[str, Any]:
    """Create a new space in a ClickUp workspace.

    Args:
        team_id: Team/workspace ID
        name: Name of the space
        multiple_assignees: Allow multiple assignees on tasks
        features: Optional features configuration

    Returns:
        Created space information including space ID
    """
    space_data = {
        "name": name,
        "multiple_assignees": multiple_assignees,
    }
    if features:
        space_data["features"] = features

    return self._request("POST", f"team/{team_id}/space", json=space_data)

create_task(list_id, name, description=None, status=None, priority=None, tags=None, assignees=None, custom_fields=None, parent=None, start_date=None, due_date=None, time_estimate=None)

Create a task in ClickUp.

Parameters:

Name	Type	Description	Default
list_id	str	ClickUp list ID	required
name	str	Task name/title	required
description	Optional[str]	Task description	None
status	Optional[str]	Task status	None
priority	Optional[int]	Priority (1=Urgent, 2=High, 3=Normal, 4=Low)	None
tags	Optional[list[str]]	List of tag names	None
assignees	Optional[list[str]]	List of assignee user IDs	None
custom_fields	Optional[list[dict[str, Any]]]	List of custom field dicts with 'id' and 'value'	None
parent	Optional[str]	Parent task ID (makes this a subtask)	None
start_date	Optional[int]	Start date (Unix timestamp in milliseconds)	None
due_date	Optional[int]	Due date (Unix timestamp in milliseconds)	None
time_estimate	Optional[int]	Time estimate in milliseconds	None

Returns:

Type	Description
dict[str, Any]	Created task information including id and url

Raises:

Type	Description
ClickUpAPIError	If task creation fails

Source code in beads_clickup/clickup_client.py

def create_task(
    self,
    list_id: str,
    name: str,
    description: Optional[str] = None,
    status: Optional[str] = None,
    priority: Optional[int] = None,
    tags: Optional[list[str]] = None,
    assignees: Optional[list[str]] = None,
    custom_fields: Optional[list[dict[str, Any]]] = None,
    parent: Optional[str] = None,
    start_date: Optional[int] = None,
    due_date: Optional[int] = None,
    time_estimate: Optional[int] = None,
) -> dict[str, Any]:
    """Create a task in ClickUp.

    Args:
        list_id: ClickUp list ID
        name: Task name/title
        description: Task description
        status: Task status
        priority: Priority (1=Urgent, 2=High, 3=Normal, 4=Low)
        tags: List of tag names
        assignees: List of assignee user IDs
        custom_fields: List of custom field dicts with 'id' and 'value'
        parent: Parent task ID (makes this a subtask)
        start_date: Start date (Unix timestamp in milliseconds)
        due_date: Due date (Unix timestamp in milliseconds)
        time_estimate: Time estimate in milliseconds

    Returns:
        Created task information including id and url

    Raises:
        ClickUpAPIError: If task creation fails
    """
    task_data: dict[str, Any] = {"name": name}

    if description:
        task_data["description"] = description
    if status:
        task_data["status"] = status
    if priority is not None:
        task_data["priority"] = priority
    if tags:
        task_data["tags"] = tags
    if parent:
        task_data["parent"] = parent
    if assignees:
        task_data["assignees"] = assignees
    if start_date is not None:
        task_data["start_date"] = start_date
    if due_date is not None:
        task_data["due_date"] = due_date
    if time_estimate is not None:
        task_data["time_estimate"] = time_estimate
    if custom_fields:
        task_data["custom_fields"] = custom_fields

    result = self._request("POST", f"list/{list_id}/task", json=task_data)

    # Add task URL for convenience
    task_id = result.get("id", "")
    if task_id and "url" not in result:
        result["url"] = f"https://app.clickup.com/t/{task_id}"

    return result

create_webhook(team_id, endpoint, events=None)

Create a webhook in ClickUp.

Parameters:

Name	Type	Description	Default
team_id	str	Team/workspace ID	required
endpoint	str	URL to receive webhook events	required
events	Optional[list[str]]	List of event types to subscribe to	None

Returns:

Type	Description
dict[str, Any]	Created webhook information including webhook ID

Source code in beads_clickup/clickup_client.py

def create_webhook(
    self,
    team_id: str,
    endpoint: str,
    events: Optional[list[str]] = None,
) -> dict[str, Any]:
    """Create a webhook in ClickUp.

    Args:
        team_id: Team/workspace ID
        endpoint: URL to receive webhook events
        events: List of event types to subscribe to

    Returns:
        Created webhook information including webhook ID
    """
    default_events = [
        "taskCreated",
        "taskUpdated",
        "taskDeleted",
        "taskStatusUpdated",
        "taskAssigneeUpdated",
        "taskPriorityUpdated",
        "taskDueDateUpdated",
        "taskMoved",
        "taskCommentPosted",
    ]

    webhook_data = {
        "endpoint": endpoint,
        "events": events or default_events,
    }

    return self._request("POST", f"team/{team_id}/webhook", json=webhook_data)

delete_task(task_id)

Delete a ClickUp task.

Parameters:

Name	Type	Description	Default
task_id	str	ClickUp task ID	required

Returns:

Type	Description
bool	True if successful

Raises:

Type	Description
ResourceNotFoundError	If task not found

Source code in beads_clickup/clickup_client.py

def delete_task(self, task_id: str) -> bool:
    """Delete a ClickUp task.

    Args:
        task_id: ClickUp task ID

    Returns:
        True if successful

    Raises:
        ResourceNotFoundError: If task not found
    """
    self._request("DELETE", f"task/{task_id}")
    return True

delete_task_link(task_id, links_to)

Remove a task link between two tasks.

Parameters:

Name	Type	Description	Default
task_id	str	ClickUp task ID to remove the link from	required
links_to	str	ClickUp task ID this task links to	required

Returns:

Type	Description
dict[str, Any]	Response from ClickUp API

Source code in beads_clickup/clickup_client.py

def delete_task_link(self, task_id: str, links_to: str) -> dict[str, Any]:
    """Remove a task link between two tasks.

    Args:
        task_id: ClickUp task ID to remove the link from
        links_to: ClickUp task ID this task links to

    Returns:
        Response from ClickUp API
    """
    return self._request(
        "DELETE",
        f"task/{task_id}/link/{links_to}",
    )

delete_webhook(webhook_id)

Delete a webhook.

Parameters:

Name	Type	Description	Default
webhook_id	str	Webhook ID to delete	required

Returns:

Type	Description
bool	True if deletion succeeded

Source code in beads_clickup/clickup_client.py

def delete_webhook(self, webhook_id: str) -> bool:
    """Delete a webhook.

    Args:
        webhook_id: Webhook ID to delete

    Returns:
        True if deletion succeeded
    """
    self._request("DELETE", f"webhook/{webhook_id}")
    return True

get_comments(task_id)

Get all comments for a ClickUp task.

Parameters:

Name	Type	Description	Default
task_id	str	ClickUp task ID	required

Returns:

Type	Description
list[dict[str, Any]]	List of comment dictionaries with id, comment, user, date_added, etc.

Source code in beads_clickup/clickup_client.py

def get_comments(self, task_id: str) -> list[dict[str, Any]]:
    """Get all comments for a ClickUp task.

    Args:
        task_id: ClickUp task ID

    Returns:
        List of comment dictionaries with id, comment, user, date_added, etc.
    """
    result = self._request("GET", f"task/{task_id}/comment")
    return result.get("comments", [])

get_folderless_lists(space_id)

Get lists that are not in any folder (folderless lists).

Parameters:

Name	Type	Description	Default
space_id	str	Space ID	required

Returns:

Type	Description
list[dict[str, Any]]	List of folderless lists

Source code in beads_clickup/clickup_client.py

def get_folderless_lists(self, space_id: str) -> list[dict[str, Any]]:
    """Get lists that are not in any folder (folderless lists).

    Args:
        space_id: Space ID

    Returns:
        List of folderless lists
    """
    result = self._request("GET", f"space/{space_id}/list")
    return result.get("lists", [])

get_folders(space_id)

Get folders from a ClickUp space.

Parameters:

Name	Type	Description	Default
space_id	str	Space ID	required

Returns:

Type	Description
list[dict[str, Any]]	List of folders

Source code in beads_clickup/clickup_client.py

def get_folders(self, space_id: str) -> list[dict[str, Any]]:
    """Get folders from a ClickUp space.

    Args:
        space_id: Space ID

    Returns:
        List of folders
    """
    result = self._request("GET", f"space/{space_id}/folder")
    return result.get("folders", [])

get_list_custom_fields(list_id)

Get custom fields available on a list.

Parameters:

Name	Type	Description	Default
list_id	str	ClickUp list ID	required

Returns:

Type	Description
list[dict[str, Any]]	List of custom field definitions with id, name, type, options, etc.

Source code in beads_clickup/clickup_client.py

def get_list_custom_fields(self, list_id: str) -> list[dict[str, Any]]:
    """Get custom fields available on a list.

    Args:
        list_id: ClickUp list ID

    Returns:
        List of custom field definitions with id, name, type, options, etc.
    """
    result = self._request("GET", f"list/{list_id}/field")
    return result.get("fields", [])

get_list_statuses(list_id)

Get all statuses from a ClickUp list.

Parameters:

Name	Type	Description	Default
list_id	str	The ClickUp list ID	required

Returns:

Type	Description
list[dict[str, Any]]	List of status dictionaries with keys: id, status, type, orderindex, color

Source code in beads_clickup/clickup_client.py

def get_list_statuses(self, list_id: str) -> list[dict[str, Any]]:
    """Get all statuses from a ClickUp list.

    Args:
        list_id: The ClickUp list ID

    Returns:
        List of status dictionaries with keys: id, status, type, orderindex, color
    """
    result = self._request("GET", f"list/{list_id}")
    return result.get("statuses", [])

get_lists(folder_id)

Get lists from a ClickUp folder.

Parameters:

Name	Type	Description	Default
folder_id	str	Folder ID	required

Returns:

Type	Description
list[dict[str, Any]]	List of lists

Source code in beads_clickup/clickup_client.py

def get_lists(self, folder_id: str) -> list[dict[str, Any]]:
    """Get lists from a ClickUp folder.

    Args:
        folder_id: Folder ID

    Returns:
        List of lists
    """
    result = self._request("GET", f"folder/{folder_id}/list")
    return result.get("lists", [])

get_spaces(team_id)

Get spaces from a ClickUp workspace.

Parameters:

Name	Type	Description	Default
team_id	str	Team/workspace ID	required

Returns:

Type	Description
list[dict[str, Any]]	List of spaces

Source code in beads_clickup/clickup_client.py

def get_spaces(self, team_id: str) -> list[dict[str, Any]]:
    """Get spaces from a ClickUp workspace.

    Args:
        team_id: Team/workspace ID

    Returns:
        List of spaces
    """
    result = self._request("GET", f"team/{team_id}/space")
    return result.get("spaces", [])

get_task(task_id)

Get a ClickUp task by ID.

Parameters:

Name	Type	Description	Default
task_id	str	ClickUp task ID	required

Returns:

Type	Description
dict[str, Any]	Task information

Raises:

Type	Description
ResourceNotFoundError	If task not found

Source code in beads_clickup/clickup_client.py

def get_task(self, task_id: str) -> dict[str, Any]:
    """Get a ClickUp task by ID.

    Args:
        task_id: ClickUp task ID

    Returns:
        Task information

    Raises:
        ResourceNotFoundError: If task not found
    """
    return self._request("GET", f"task/{task_id}")

get_task_dependencies(task_id)

Get all dependencies for a task.

Parameters:

Name	Type	Description	Default
task_id	str	ClickUp task ID	required

Returns:

Type	Description
dict[str, list[str]]	Dictionary with 'depends_on' and 'blocking' keys containing lists of task IDs

Note

This extracts dependency information from the task data returned by get_task(). The task response includes: - dependencies: list of tasks this task depends on (waiting for) - blocking: list of tasks this task is blocking

Source code in beads_clickup/clickup_client.py

def get_task_dependencies(self, task_id: str) -> dict[str, list[str]]:
    """Get all dependencies for a task.

    Args:
        task_id: ClickUp task ID

    Returns:
        Dictionary with 'depends_on' and 'blocking' keys containing lists of task IDs

    Note:
        This extracts dependency information from the task data returned by get_task().
        The task response includes:
        - dependencies: list of tasks this task depends on (waiting for)
        - blocking: list of tasks this task is blocking
    """
    task = self.get_task(task_id)

    # Parse dependencies from task response
    depends_on = []
    blocking = []

    # Dependencies are tasks this task is waiting for
    if "dependencies" in task:
        for dep in task["dependencies"]:
            if "task_id" in dep:
                depends_on.append(dep["task_id"])

    # Blocking are tasks waiting for this task
    if "blocking" in task:
        for block in task["blocking"]:
            if "task_id" in block:
                blocking.append(block["task_id"])

    return {
        "depends_on": depends_on,
        "blocking": blocking,
    }

get_webhooks(team_id)

Get all webhooks for a workspace.

Parameters:

Name	Type	Description	Default
team_id	str	Team/workspace ID	required

Returns:

Type	Description
list[dict[str, Any]]	List of webhook dictionaries

Source code in beads_clickup/clickup_client.py

def get_webhooks(self, team_id: str) -> list[dict[str, Any]]:
    """Get all webhooks for a workspace.

    Args:
        team_id: Team/workspace ID

    Returns:
        List of webhook dictionaries
    """
    result = self._request("GET", f"team/{team_id}/webhook")
    return result.get("webhooks", [])

get_workspace()

Get workspace/team information.

Returns:

Type	Description
dict[str, Any]	Workspace information including team ID

Source code in beads_clickup/clickup_client.py

def get_workspace(self) -> dict[str, Any]:
    """Get workspace/team information.

    Returns:
        Workspace information including team ID
    """
    return self._request("GET", "team")

list_tasks(list_id, include_closed=False, date_updated_gt=None)

List tasks from a ClickUp list, fetching all pages.

Parameters:

Name	Type	Description	Default
list_id	str	ClickUp list ID	required
include_closed	bool	Include closed/archived tasks	False
date_updated_gt	Optional[int]	Only return tasks updated after this Unix timestamp (ms)	None

Returns:

Type	Description
list[dict[str, Any]]	List of tasks across all pages

Source code in beads_clickup/clickup_client.py

def list_tasks(
    self,
    list_id: str,
    include_closed: bool = False,
    date_updated_gt: Optional[int] = None,
) -> list[dict[str, Any]]:
    """List tasks from a ClickUp list, fetching all pages.

    Args:
        list_id: ClickUp list ID
        include_closed: Include closed/archived tasks
        date_updated_gt: Only return tasks updated after this Unix timestamp (ms)

    Returns:
        List of tasks across all pages
    """
    params: dict[str, str] = {
        "subtasks": "true",
    }
    if include_closed:
        params["include_closed"] = "true"
    if date_updated_gt is not None:
        params["date_updated_gt"] = str(date_updated_gt)

    all_tasks: list[dict[str, Any]] = []
    page = 0
    while True:
        params["page"] = str(page)
        result = self._request("GET", f"list/{list_id}/task", params=params)
        page_tasks = result.get("tasks", [])
        all_tasks.extend(page_tasks)
        if len(page_tasks) < _CLICKUP_PAGE_SIZE:
            break
        page += 1

    return all_tasks

remove_dependency(task_id, depends_on=None, dependency_of=None)

Remove dependency relationship between tasks.

Parameters:

Name	Type	Description	Default
task_id	str	Task that is waiting or blocking	required
depends_on	Optional[str]	Task ID that task_id depends on	None
dependency_of	Optional[str]	Task ID that depends on task_id	None

Returns:

Type	Description
dict[str, Any]	Response from ClickUp API

Raises:

Type	Description
ValueError	If neither depends_on nor dependency_of is provided

Source code in beads_clickup/clickup_client.py

def remove_dependency(
    self,
    task_id: str,
    depends_on: Optional[str] = None,
    dependency_of: Optional[str] = None,
) -> dict[str, Any]:
    """Remove dependency relationship between tasks.

    Args:
        task_id: Task that is waiting or blocking
        depends_on: Task ID that task_id depends on
        dependency_of: Task ID that depends on task_id

    Returns:
        Response from ClickUp API

    Raises:
        ValueError: If neither depends_on nor dependency_of is provided
    """
    if depends_on is None and dependency_of is None:
        raise ValueError("Must provide either depends_on or dependency_of")

    params = {}
    if depends_on:
        params["depends_on"] = depends_on
    if dependency_of:
        params["dependency_of"] = dependency_of

    return self._request(
        "DELETE",
        f"task/{task_id}/dependency",
        params=params,
    )

search_tasks(query, team_id=None)

Search for tasks across workspace.

Parameters:

Name	Type	Description	Default
query	str	Search query	required
team_id	Optional[str]	Team ID to search within	None

Returns:

Type	Description
list[dict[str, Any]]	List of matching tasks

Source code in beads_clickup/clickup_client.py

def search_tasks(
    self,
    query: str,
    team_id: Optional[str] = None,
) -> list[dict[str, Any]]:
    """Search for tasks across workspace.

    Args:
        query: Search query
        team_id: Team ID to search within

    Returns:
        List of matching tasks
    """
    params: dict[str, str] = {"query": query}
    if team_id:
        params["team_id"] = team_id

    result = self._request("GET", "search", params=params)
    return result.get("tasks", [])

set_custom_field(task_id, field_id, value)

Set a custom field value on a task.

Parameters:

Name	Type	Description	Default
task_id	str	ClickUp task ID	required
field_id	str	Custom field UUID	required
value	Any	Value to set (format depends on field type)	required

Returns:

Type	Description
dict[str, Any]	Response from ClickUp API

Source code in beads_clickup/clickup_client.py

def set_custom_field(
    self,
    task_id: str,
    field_id: str,
    value: Any,
) -> dict[str, Any]:
    """Set a custom field value on a task.

    Args:
        task_id: ClickUp task ID
        field_id: Custom field UUID
        value: Value to set (format depends on field type)

    Returns:
        Response from ClickUp API
    """
    return self._request(
        "POST",
        f"task/{task_id}/field/{field_id}",
        json={"value": value},
    )

update_list_statuses(list_id, statuses)

Update the statuses/columns for a list.

Parameters:

Name	Type	Description	Default
list_id	str	List ID	required
statuses	list[dict[str, Any]]	List of status configurations with name, type, color	required

Returns:

Type	Description
dict[str, Any]	Updated list information

Example

client.update_list_statuses( ... list_id="123", ... statuses=[ ... {"status": "TO DO", "type": "open", "color": "#d3d3d3"}, ... {"status": "IN PROGRESS", "type": "custom", "color": "#4194f6"}, ... {"status": "COMPLETE", "type": "closed", "color": "#6bc950"}, ... ] ... )

Source code in beads_clickup/clickup_client.py

def update_list_statuses(
    self,
    list_id: str,
    statuses: list[dict[str, Any]],
) -> dict[str, Any]:
    """Update the statuses/columns for a list.

    Args:
        list_id: List ID
        statuses: List of status configurations with name, type, color

    Returns:
        Updated list information

    Example:
        >>> client.update_list_statuses(
        ...     list_id="123",
        ...     statuses=[
        ...         {"status": "TO DO", "type": "open", "color": "#d3d3d3"},
        ...         {"status": "IN PROGRESS", "type": "custom", "color": "#4194f6"},
        ...         {"status": "COMPLETE", "type": "closed", "color": "#6bc950"},
        ...     ]
        ... )
    """
    return self._request("PUT", f"list/{list_id}", json={"statuses": statuses})

update_task(task_id, name=None, description=None, status=None, priority=None, tags=None, start_date=None, due_date=None, parent=None, assignees=None, time_estimate=None, custom_fields=None)

Update a ClickUp task.

Parameters:

Name	Type	Description	Default
task_id	str	ClickUp task ID	required
name	Optional[str]	New task name	None
description	Optional[str]	New description	None
status	Optional[str]	New status	None
priority	Optional[int]	New priority	None
tags	Optional[list[str]]	New tags	None
start_date	Optional[int]	Start date (Unix timestamp in milliseconds)	None
due_date	Optional[int]	Due date (Unix timestamp in milliseconds)	None
parent	Optional[str]	Parent task ID (makes this a subtask)	None
assignees	Optional[list[str]]	List of assignee user IDs	None
time_estimate	Optional[int]	Time estimate in milliseconds	None
custom_fields	Optional[list[dict[str, Any]]]	List of custom field dicts with 'id' and 'value'	None

Returns:

Type	Description
dict[str, Any]	Updated task information

Raises:

Type	Description
ClickUpAPIError	If update fails
ResourceNotFoundError	If task not found

Source code in beads_clickup/clickup_client.py

def update_task(
    self,
    task_id: str,
    name: Optional[str] = None,
    description: Optional[str] = None,
    status: Optional[str] = None,
    priority: Optional[int] = None,
    tags: Optional[list[str]] = None,
    start_date: Optional[int] = None,
    due_date: Optional[int] = None,
    parent: Optional[str] = None,
    assignees: Optional[list[str]] = None,
    time_estimate: Optional[int] = None,
    custom_fields: Optional[list[dict[str, Any]]] = None,
) -> dict[str, Any]:
    """Update a ClickUp task.

    Args:
        task_id: ClickUp task ID
        name: New task name
        description: New description
        status: New status
        priority: New priority
        tags: New tags
        start_date: Start date (Unix timestamp in milliseconds)
        due_date: Due date (Unix timestamp in milliseconds)
        parent: Parent task ID (makes this a subtask)
        assignees: List of assignee user IDs
        time_estimate: Time estimate in milliseconds
        custom_fields: List of custom field dicts with 'id' and 'value'

    Returns:
        Updated task information

    Raises:
        ClickUpAPIError: If update fails
        ResourceNotFoundError: If task not found
    """
    task_data: dict[str, Any] = {}

    if name is not None:
        task_data["name"] = name
    if description is not None:
        task_data["description"] = description
    if status is not None:
        task_data["status"] = status
    if priority is not None:
        task_data["priority"] = priority
    if tags is not None:
        task_data["tags"] = tags
    if start_date is not None:
        task_data["start_date"] = start_date
    if due_date is not None:
        task_data["due_date"] = due_date
    if parent is not None:
        task_data["parent"] = parent
    if assignees is not None:
        task_data["assignees"] = {"add": assignees}
    if time_estimate is not None:
        task_data["time_estimate"] = time_estimate
    if custom_fields is not None:
        task_data["custom_fields"] = custom_fields

    if not task_data:
        raise ValueError("At least one field to update must be provided")

    return self._request("PUT", f"task/{task_id}", json=task_data)

update_webhook(webhook_id, endpoint=None, events=None, status=None)

Update a webhook.

Parameters:

Name	Type	Description	Default
webhook_id	str	Webhook ID to update	required
endpoint	Optional[str]	New endpoint URL (optional)	None
events	Optional[list[str]]	New list of events (optional)	None
status	Optional[str]	New status ('active' or 'inactive') (optional)	None

Returns:

Type	Description
dict[str, Any]	Updated webhook information

Source code in beads_clickup/clickup_client.py

def update_webhook(
    self,
    webhook_id: str,
    endpoint: Optional[str] = None,
    events: Optional[list[str]] = None,
    status: Optional[str] = None,
) -> dict[str, Any]:
    """Update a webhook.

    Args:
        webhook_id: Webhook ID to update
        endpoint: New endpoint URL (optional)
        events: New list of events (optional)
        status: New status ('active' or 'inactive') (optional)

    Returns:
        Updated webhook information
    """
    webhook_data: dict[str, Any] = {}
    if endpoint:
        webhook_data["endpoint"] = endpoint
    if events:
        webhook_data["events"] = events
    if status:
        webhook_data["status"] = status

    return self._request("PUT", f"webhook/{webhook_id}", json=webhook_data)