A production-ready, high-performance Python client for the ClickUp API with first-class async support. Built for developers who need robust, type-safe, and efficient ClickUp integration in their Python applications.
🎉 Version 1.0.0 Now Available! - First stable release with complete API coverage and production-ready features.
Transform your ClickUp workflow automation with a library that prioritizes developer experience and performance:
| Feature | ClickUp Async | Other Libraries |
|---|---|---|
| Async Support | ✅ Full async/await with concurrent operations | ❌ Synchronous only |
| Type Safety | ✅ Comprehensive type hints & Pydantic validation | ❌ Limited or none |
| Rate Limiting | ✅ Smart handling with exponential backoff | ❌ Basic or none |
| Fluent Interface | ✅ Intuitive, chainable API design | ❌ Verbose calls |
| Modern Python | ✅ Leverages Python 3.9+ features | ❌ Legacy compatibility |
| Error Handling | ✅ Detailed exceptions with context | ❌ Basic exceptions |
| Pagination | ✅ Automatic with async iterators | ❌ Manual handling |
| Documentation | ✅ Comprehensive with examples | ❌ Limited coverage |
| Maintenance | ✅ Active development & support | ❌ Irregular updates |
pip install clickup-asyncimport asyncio
from clickup_async import ClickUp
from clickup_async.models import Priority, Task
async def main():
async with ClickUp(api_token="your_token_here") as client:
# Get user info
user = await client.get_authenticated_user()
print(f"👋 Welcome, {user.username}!")
# Create a task with rich metadata
task = await client.list("list_id").tasks.create_task(
name="Launch New Feature",
description="## Objective\nImplement the new feature with following requirements:\n\n- High performance\n- User friendly\n- Well tested",
priority=Priority.HIGH,
due_date="next Friday",
tags=["feature", "backend"],
notify_all=True
)
print(f"✨ Created task: {task.name} (ID: {task.id})")
if __name__ == "__main__":
asyncio.run(main())from clickup_async import ClickUp
# Basic setup
client = ClickUp(api_token="your_token")
# Advanced configuration
client = ClickUp(
api_token="your_token",
retry_rate_limited_requests=True,
rate_limit_buffer=5,
timeout=30,
base_url="https://api.clickup.com/api/v2"
)Create, update, and manage tasks with rich functionality:
# Create a task with custom fields
task = await client.list("list_id").tasks.create_task(
name="New Feature Implementation",
description="Implement the new feature",
assignees=["user_id"],
tags=["feature"],
custom_fields=[{
"id": "field_id",
"value": "High Impact"
}]
)
# Update task status
updated_task = await client.task(task.id).update(
status="In Progress",
priority=Priority.URGENT
)
# Add time tracking
await client.task(task.id).time.add_time_entry(
duration=3600, # 1 hour in seconds
description="Initial implementation"
)
# Add a comment with attachments
await client.task(task.id).comments.create_comment(
text="Please review the implementation",
assignee="user_id",
notify_all=True
)Manage task lists and custom views efficiently:
# Create a new list
new_list = await client.folder("folder_id").lists.create_list(
name="Q4 Projects",
content="Strategic projects for Q4",
due_date="end of quarter"
)
# Get tasks with advanced filtering
tasks = await client.list("list_id").tasks.get_tasks(
due_date_gt="today",
due_date_lt="next month",
assignees=["user_id"],
include_closed=False,
subtasks=True,
order_by="due_date"
)
# Create a custom view
view = await client.list("list_id").views.create_view(
name="High Priority Tasks",
type="list",
filters={
"priority": [Priority.HIGH, Priority.URGENT]
}
)Navigate and manage your ClickUp hierarchy with ease:
# Get all workspaces
workspaces = await client.workspaces.get_workspaces()
# Working with Spaces
# Create a new space
space = await client.workspace("workspace_id").spaces.create_space(
name="Product Development",
features={"due_dates", "time_tracking", "tags"},
private=True
)
# Update space settings
updated_space = await client.space(space.id).update(
name="Product Development 2023",
features={"due_dates", "time_tracking", "tags", "priorities"}
)
# Get all spaces in a workspace
spaces = await client.workspace("workspace_id").spaces.get_spaces()
# Working with Folders
# Create a folder in a space
folder = await client.space("space_id").folders.create_folder(
name="Q4 Projects",
description="All projects for Q4 2023"
)
# Update folder
updated_folder = await client.folder(folder.id).update(
name="Q4 Strategic Projects"
)
# Get all folders in a space
folders = await client.space("space_id").folders.get_folders()
# Working with Lists
# Create a list in a folder
task_list = await client.folder("folder_id").lists.create_list(
name="Backend Development",
description="Backend tasks and features",
assignee="user_id",
due_date="next month"
)
# Create a folderless list in a space
space_list = await client.space("space_id").lists.create_list(
name="Quick Tasks",
description="Tasks without folder organization"
)
# Update list
updated_list = await client.list(task_list.id).update(
name="Backend Development Sprint 1",
due_date="next friday",
priority=Priority.HIGH
)
# Get all lists
folder_lists = await client.folder("folder_id").lists.get_lists()
space_lists = await client.space("space_id").lists.get_lists(include_archived=False)
# Advanced folder operations
# Move a folder to a different space
moved_folder = await client.folder("folder_id").move(
destination_space="new_space_id"
)
# Advanced list operations
# Move a list to a different folder
moved_list = await client.list("list_id").move(
destination_folder="new_folder_id"
)
# Bulk operations
# Create multiple lists in a folder
lists = await asyncio.gather(*[
client.folder("folder_id").lists.create_list(
name=f"Sprint {i}",
description=f"Tasks for Sprint {i}"
) for i in range(1, 4)
])Set up and track goals with key results:
# Create a new goal
goal = await client.team("team_id").goals.create_goal(
name="Increase Performance",
due_date="end of quarter",
description="Improve system performance metrics"
)
# Add key results
key_result = await client.goal(goal.id).key_results.create_key_result(
name="Reduce Response Time",
steps=100,
unit="ms",
start_value=200,
target_value=50
)Set up real-time notifications and automation:
# Create a webhook
webhook = await client.workspace("workspace_id").webhooks.create_webhook(
endpoint="https://your-domain.com/webhook",
events=["taskCreated", "taskUpdated"],
space_id="space_id"
)
# Get webhook history
history = await client.webhook(webhook.id).get_webhook_history()Handle large datasets efficiently with automatic pagination:
async def get_all_tasks(list_id: str) -> list[Task]:
tasks_page = await client.list(list_id).tasks.get_tasks()
all_tasks = []
while True:
all_tasks.extend(tasks_page.items)
if not tasks_page.has_more:
break
tasks_page = await tasks_page.next_page()
return all_tasks-
Clone the repository
git clone https://github.com/catorch/clickup-async.git cd clickup-async -
Create virtual environment
python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate
-
Install development dependencies
pip install -e ".[dev,test]"
# Set up environment variables
export CLICKUP_API_KEY=your_token_here
# Run tests with coverage
pytest --cov=clickup_asyncFirst stable release! 🎉
- Complete coverage of ClickUp API
- Fully typed interface with Pydantic models
- Comprehensive documentation with examples
- Production-ready with extensive test coverage
- Smart rate limiting and error handling
- Async-first design with concurrent operation support
- Fluent interface for intuitive API navigation
- Enhanced error messages and debugging support
- Optimized performance for large-scale operations
- Comprehensive test suite with 90%+ coverage
- Extended documentation with real-world examples
- Stable API interface established
- Minimum Python version: 3.8+
- All core features implemented and tested
MIT License - See LICENSE for details.
⭐ If you find this library helpful, please consider starring it on GitHub!
💡 Need help? Open an issue.