clickup
Interact with the ClickUp HTTP API using a Personal Access Token in CLICKUP_PAT. Covers v2 core resources plus v3 Docs, Chat, attachments, ACLs, and audit logs. Use the API directly, not MCP.
SKILL.mdvar/agents/skills/apis/clickup/SKILL.md
GitHubUse ClickUp's HTTP API directly, not MCP.
This skill is PAT-only:
- Use a ClickUp Personal Access Token in
CLICKUP_PAT - Send it as
Authorization: $CLICKUP_PAT(do not useBearerfor PAT auth) - Personal tokens begin with
pk_
Canonical references
- Main docs:
https://developer.clickup.com/ - Authentication:
https://developer.clickup.com/docs/authentication - Raw OpenAPI v2:
https://developer.clickup.com/openapi/clickup-api-v2-reference.json - Raw OpenAPI v3:
https://developer.clickup.com/openapi/ClickUp_PUBLIC_API_V3.yaml
Base URLs
- v2 core API:
https://api.clickup.com/api/v2 - v3 API:
https://api.clickup.com/api/v3
Quick auth check
[ -z "$CLICKUP_PAT" ] && echo "Error: CLICKUP_PAT not set" || echo "OK: CLICKUP_PAT is set"
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/user" | jq .
API coverage map
ClickUp exposes two public API surfaces:
v2: core work management
Use v2 for most existing ClickUp resources:
- Authorized user + workspaces
- Spaces, folders, lists, views
- Tasks, task relationships, checklists, attachments
- Comments
- Members, users, guests, user groups, roles
- Custom fields, tags, custom task types
- Goals
- Time tracking
- Templates
- Shared hierarchy
- Webhooks
v3: newer resources
Use v3 for the newer resource families:
- Docs
- Chat
- Generic attachments endpoints
- Privacy/access control lists (ACLs)
- Audit logs
- A few workspace-scoped task helpers
Important ID note
ClickUp uses both team_id and workspace_id across docs/specs; both refer to the same top-level workspace identifier. The v2 spec also inconsistently uses both team_id and team_Id in path templates. Treat them as the same value.
Recommended discovery flow
When IDs are unknown, discover them in this order:
- Get the authorized user
- List workspaces
- List spaces in a workspace
- List folders and folderless lists in a space
- List lists in a folder
- List views if needed
- Query tasks, comments, docs, chat, time entries, etc.
Authorized user and workspaces
Get authorized user
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/user" | jq .
List authorized workspaces
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/team" | jq '.teams'
Get workspace plan
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/team/TEAM_ID/plan" | jq .
Get workspace seats
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/team/TEAM_ID/seats" | jq .
Hierarchy: spaces, folders, lists, views
List spaces in a workspace
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/team/TEAM_ID/space?archived=false" | jq .
Get a space
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/space/SPACE_ID" | jq .
List folders in a space
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/space/SPACE_ID/folder?archived=false" | jq .
Get a folder
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/folder/FOLDER_ID" | jq .
List folderless lists in a space
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/space/SPACE_ID/list?archived=false" | jq .
List lists in a folder
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/folder/FOLDER_ID/list?archived=false" | jq .
Get a list
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/list/LIST_ID" | jq .
List views
# Workspace / Everything views
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/team/TEAM_ID/view" | jq .
# Space views
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/space/SPACE_ID/view" | jq .
# Folder views
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/folder/FOLDER_ID/view" | jq .
# List views
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/list/LIST_ID/view" | jq .
Get a view or its tasks
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/view/VIEW_ID" | jq .
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/view/VIEW_ID/task" | jq .
Tasks
Get a task
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/task/TASK_ID" | jq .
Useful query parameters:
include_subtasks=trueinclude_markdown_description=truecustom_fields=truecustom_task_ids=true&team_id=TEAM_IDwhen using custom task IDs
Example:
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/task/TASK_ID?include_subtasks=true&include_markdown_description=true" | jq .
List tasks in a list
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/list/LIST_ID/task?archived=false&subtasks=true&include_closed=false" | jq .
Common filters supported by GET /list/{list_id}/task:
pageorder_byreversestatuses[]assignees[]watchers[]tags[]subtasksinclude_closeddue_date_gt,due_date_ltdate_created_gt,date_created_ltdate_updated_gt,date_updated_ltdate_done_gt,date_done_ltcustom_fieldscustom_items[]
Get filtered workspace tasks
This is the main workspace-level task query in v2. It filters tasks across spaces, folders, and lists.
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/team/TEAM_ID/task?include_closed=false&page=0" | jq .
Common filters supported by GET /team/{team_Id}/task:
pageorder_byreversesubtasksspace_ids[]project_ids[]list_ids[]statuses[]assignees[]tags[]parentinclude_closedinclude_markdown_descriptioncustom_fieldscustom_items[]due_date_gt,due_date_ltdate_created_gt,date_created_ltdate_updated_gt,date_updated_ltdate_done_gt,date_done_lt
Create or update tasks
Always use
markdown_content(create) ormarkdown_description(update) for task descriptions. Thedescriptionfield treats content as plain text and does not render Markdown, whereasmarkdown_contentandmarkdown_descriptionrender rich text in the ClickUp UI. If both are provided,markdown_contenttakes precedence.
# Create task in a list (with Markdown description)
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
-H "Content-Type: application/json" \
-X POST \
"https://api.clickup.com/api/v2/list/LIST_ID/task" \
-d '{"name":"New task","markdown_content":"## Overview\nDetails here."}' | jq .
# Update task (with Markdown description)
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
-H "Content-Type: application/json" \
-X PUT \
"https://api.clickup.com/api/v2/task/TASK_ID" \
-d '{"name":"Updated task name","markdown_description":"## Updated\nNew details."}' | jq .
Task relationships
# Add dependency
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
-H "Content-Type: application/json" \
-X POST \
"https://api.clickup.com/api/v2/task/TASK_ID/dependency" \
-d '{"depends_on":"OTHER_TASK_ID"}' | jq .
# Link tasks
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
-X POST "https://api.clickup.com/api/v2/task/TASK_ID/link/OTHER_TASK_ID" | jq .
Checklists
# Create checklist
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
-H "Content-Type: application/json" \
-X POST \
"https://api.clickup.com/api/v2/task/TASK_ID/checklist" \
-d '{"name":"Checklist"}' | jq .
Task members
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/task/TASK_ID/member" | jq .
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/list/LIST_ID/member" | jq .
Task attachment upload (v2)
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
-F "attachment=@/path/to/file" \
"https://api.clickup.com/api/v2/task/TASK_ID/attachment" | jq .
Comments
Get task comments
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/task/TASK_ID/comment" | jq .
Optional pagination-style params:
startstart_idcustom_task_ids=true&team_id=TEAM_IDif using custom task IDs
Get list comments
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/list/LIST_ID/comment" | jq .
Get view comments
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/view/VIEW_ID/comment" | jq .
Get threaded replies for a comment
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/comment/COMMENT_ID/reply" | jq .
Create comments
# Task comment
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
-H "Content-Type: application/json" \
-X POST \
"https://api.clickup.com/api/v2/task/TASK_ID/comment" \
-d '{"comment_text":"Hello from the API","notify_all":true}' | jq .
# Threaded reply
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
-H "Content-Type: application/json" \
-X POST \
"https://api.clickup.com/api/v2/comment/COMMENT_ID/reply" \
-d '{"comment_text":"Replying in thread","notify_all":true}' | jq .
Custom fields, tags, custom task types, roles
Custom fields
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/team/TEAM_ID/field" | jq .
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/space/SPACE_ID/field" | jq .
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/folder/FOLDER_ID/field" | jq .
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/list/LIST_ID/field" | jq .
Set a task custom field value
The body shape depends on the field type. For simple text-like fields:
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
-H "Content-Type: application/json" \
-X POST \
"https://api.clickup.com/api/v2/task/TASK_ID/field/FIELD_ID" \
-d '{"value":"example"}' | jq .
Tags
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/space/SPACE_ID/tag" | jq .
# Add tag to task
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
-X POST "https://api.clickup.com/api/v2/task/TASK_ID/tag/TAG_NAME" | jq .
# Remove tag from task
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
-X DELETE "https://api.clickup.com/api/v2/task/TASK_ID/tag/TAG_NAME" | jq .
Custom task types
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/team/TEAM_ID/custom_item" | jq .
Custom roles
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/team/TEAM_ID/customroles?include_members=true" | jq .
Goals
List goals
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/team/TEAM_ID/goal?include_completed=false" | jq .
Get a goal
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/goal/GOAL_ID" | jq .
Key results
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/key_result/KEY_RESULT_ID" | jq .
Time tracking
Get time entries in a date range
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/team/TEAM_ID/time_entries?start_date=START_MS&end_date=END_MS" | jq .
Useful filters:
assigneespace_idfolder_idlist_idtask_idis_billableinclude_task_tags=trueinclude_location_names=trueinclude_approval_history=trueinclude_approval_details=true
Get the currently running time entry
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/team/TEAM_ID/time_entries/current" | jq .
Get a single time entry or its history
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/team/TEAM_ID/time_entries/TIMER_ID" | jq .
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/team/TEAM_ID/time_entries/TIMER_ID/history" | jq .
Start or stop a timer
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
-H "Content-Type: application/json" \
-X POST \
"https://api.clickup.com/api/v2/team/TEAM_ID/time_entries/start" \
-d '{"description":"Working on task"}' | jq .
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
-H "Content-Type: application/json" \
-X POST \
"https://api.clickup.com/api/v2/team/TEAM_ID/time_entries/stop" \
-d '{}' | jq .
Legacy task time tracking endpoints
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/task/TASK_ID/time" | jq .
Templates, shared hierarchy, members, users, guests, groups
Shared hierarchy
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/team/TEAM_ID/shared" | jq .
Templates
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/team/TEAM_ID/taskTemplate?page=0" | jq .
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/team/TEAM_ID/list_template" | jq .
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/team/TEAM_ID/folder_template" | jq .
Users, guests, groups
# User details in workspace
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/team/TEAM_ID/user/USER_ID" | jq .
# Guest details in workspace
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/team/TEAM_ID/guest/GUEST_ID" | jq .
# List user groups
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/group" | jq .
Webhooks
List workspace webhooks
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v2/team/TEAM_ID/webhook" | jq .
Create a webhook
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
-H "Content-Type: application/json" \
-X POST \
"https://api.clickup.com/api/v2/team/TEAM_ID/webhook" \
-d '{"endpoint":"https://example.com/clickup-webhook","events":["taskCreated"]}' | jq .
Docs API (v3)
Docs live in v3. Avoid using incorrect /workflow/.../doc style URLs, and use workspace-scoped v3 endpoints instead.
Search docs in a workspace
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v3/workspaces/WORKSPACE_ID/docs?archived=false&deleted=false&limit=50" | jq .
Useful filters:
idcreatordeletedarchivedparent_idparent_typelimitcursornext_cursor
Fetch a doc
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v3/workspaces/WORKSPACE_ID/docs/DOC_ID" | jq .
Get doc page listing
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v3/workspaces/WORKSPACE_ID/docs/DOC_ID/page_listing?max_page_depth=10" | jq .
Get doc pages
content_format supports text/md and text/plain.
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v3/workspaces/WORKSPACE_ID/docs/DOC_ID/pages?content_format=text/md" | jq .
Get a specific page
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v3/workspaces/WORKSPACE_ID/docs/DOC_ID/pages/PAGE_ID?content_format=text/md" | jq .
Create docs/pages
# Create a doc
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
-H "Content-Type: application/json" \
-X POST \
"https://api.clickup.com/api/v3/workspaces/WORKSPACE_ID/docs" \
-d '{"name":"New doc"}' | jq .
# Create a page
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
-H "Content-Type: application/json" \
-X POST \
"https://api.clickup.com/api/v3/workspaces/WORKSPACE_ID/docs/DOC_ID/pages" \
-d '{"name":"New page"}' | jq .
Chat API (v3)
List chat channels
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v3/workspaces/WORKSPACE_ID/chat/channels?limit=50" | jq .
Useful filters:
description_format=text/md|text/plaincursorlimitis_follower=trueinclude_closed=truewith_message_since=<timestamp>channel_types=<value>
Get a channel
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v3/workspaces/WORKSPACE_ID/chat/channels/CHANNEL_ID" | jq .
Get channel followers or members
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v3/workspaces/WORKSPACE_ID/chat/channels/CHANNEL_ID/followers" | jq .
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v3/workspaces/WORKSPACE_ID/chat/channels/CHANNEL_ID/members" | jq .
Get channel messages
content_format supports text/md and text/plain.
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v3/workspaces/WORKSPACE_ID/chat/channels/CHANNEL_ID/messages?limit=50&content_format=text/md" | jq .
Get replies or reactions for a message
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v3/workspaces/WORKSPACE_ID/chat/messages/MESSAGE_ID/replies?content_format=text/md" | jq .
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v3/workspaces/WORKSPACE_ID/chat/messages/MESSAGE_ID/reactions" | jq .
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v3/workspaces/WORKSPACE_ID/chat/messages/MESSAGE_ID/tagged_users" | jq .
Send a message
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
-H "Content-Type: application/json" \
-X POST \
"https://api.clickup.com/api/v3/workspaces/WORKSPACE_ID/chat/channels/CHANNEL_ID/messages" \
-d '{"type":"message","content":"Hello from the API","content_format":"text/plain"}' | jq .
Generic attachments API (v3)
List attachments for a supported entity
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
"https://api.clickup.com/api/v3/workspaces/WORKSPACE_ID/ENTITY_TYPE/ENTITY_ID/attachments?limit=50" | jq .
Upload an attachment to a supported entity
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
-F "attachment=@/path/to/file" \
"https://api.clickup.com/api/v3/workspaces/WORKSPACE_ID/ENTITY_TYPE/ENTITY_ID/attachments" | jq .
Privacy / ACLs (v3)
Update access control on an object or location
The v3 schema supports private and entries.
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
-H "Content-Type: application/json" \
-X PATCH \
"https://api.clickup.com/api/v3/workspaces/WORKSPACE_ID/OBJECT_TYPE/OBJECT_ID/acls" \
-d '{"private":true}' | jq .
See the v3 spec for the exact body shape for the target object type.
Audit logs (v3)
Query workspace audit logs
The audit logs endpoint is a POST in v3.
curl -fsS \
-H "Authorization: $CLICKUP_PAT" \
-H "Content-Type: application/json" \
-X POST \
"https://api.clickup.com/api/v3/workspaces/WORKSPACE_ID/auditlogs" \
-d '{}' | jq .
Common URL / ID patterns
- Workspace IDs are numeric strings
- Space, folder, list, and view IDs are numeric strings
- Task IDs can be short alphanumeric IDs
- Custom task IDs require
custom_task_ids=true&team_id=TEAM_ID - Docs and chat resources use
workspace_idin v3
Extract a task ID from a ClickUp task URL
echo "https://app.clickup.com/t/123456/86abc4d12" | sed 's#.*/##'
# => 86abc4d12
Pagination patterns
v2
v2 commonly uses page-based pagination:
page=0page=1- plus resource-specific filters
v3
v3 commonly uses cursor pagination:
limitcursor- sometimes
next_cursor
Error handling
| Status | Meaning |
|---|---|
200 |
Success |
201 |
Created |
400 |
Bad request / invalid params |
401 |
Unauthorized / invalid PAT |
403 |
Forbidden |
404 |
Not found |
429 |
Rate limited |
5xx |
Server error |
Prefer curl -fsS so HTTP failures surface immediately.
Best practices
- Use PAT auth only for this skill:
Authorization: $CLICKUP_PAT - Use the HTTP API directly, not MCP
- Start with hierarchy discovery: workspace → space → folder/list → task/view/doc/channel
- Use v2 for core work items and v3 for Docs/Chat/ACLs/Audit Logs
- Default to incomplete tasks unless the user explicitly asks for completed/closed ones
- When using custom task IDs, add
custom_task_ids=true&team_id=TEAM_ID - Free-text task search is not a general v2 endpoint: use workspace/list filtering or fetch and filter client-side
- Docs content and chat message content support
text/mdandtext/plain - Use
markdown_content(create) ormarkdown_description(update) for task descriptions —descriptionis plain text only and will not render Markdown - Be careful with mutations: creating, editing, deleting, ACL changes, and webhook changes should only be done when explicitly requested