ClickUp Tasks
Lets an agent work in ClickUp: browse workspaces, spaces, folders and lists, find and read tasks, create and update tasks (status, assignees, due dates, priority), and read or post task comments. Curated from ClickUp's official OpenAPI specification.
Connect this API to an AI agent Browse all specs
What you can do with ClickUp Tasks via MCP
Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.
| Method | Path | Operation | Description |
|---|---|---|---|
| GET | /v2/user |
getAuthorizedUser | Get the ClickUp user the token belongs to |
| GET | /v2/team |
getWorkspaces | List the workspaces (teams) you belong to, with their members |
| GET | /v2/team/{team_id}/space |
getSpaces | List the spaces in a workspace |
| GET | /v2/space/{space_id}/folder |
getFolders | List the folders in a space |
| GET | /v2/folder/{folder_id}/list |
getLists | List the lists inside a folder |
| GET | /v2/space/{space_id}/list |
getFolderlessLists | List the lists that sit directly in a space (no folder) |
| GET | /v2/list/{list_id} |
getList | Get a list, including its available statuses |
| GET | /v2/list/{list_id}/member |
getListMembers | List the people who can access a list (for assigning) |
| GET | /v2/list/{list_id}/task |
getTasks | List tasks in a list, filtered by status, assignee or due date |
| POST | /v2/list/{list_id}/task |
createTask | Create a task in a list |
| GET | /v2/team/{team_Id}/task |
searchWorkspaceTasks | Find tasks across a whole workspace with filters |
| GET | /v2/task/{task_id} |
getTask | Get one task with its details |
| PUT | /v2/task/{task_id} |
updateTask | Update a task (name, status, assignees, due date, priority) |
| GET | /v2/task/{task_id}/comment |
getTaskComments | List the comments on a task |
| POST | /v2/task/{task_id}/comment |
createTaskComment | Post a comment on a task |
| POST | /v2/task/{task_id}/tag/{tag_name} |
addTagToTask | Add a tag to a task |
Authentication
Authorization_Token
API key — sent as the Authorization header
Send a ClickUp personal API token (pk_...) as the raw Authorization header value (no Bearer prefix). OAuth app access tokens also work here.
How to get a credential
- In ClickUp, click your avatar (bottom left) > Settings > Apps.
- Under API Token, click Generate (or Copy if one exists).
- Copy the token that starts with
pk_. - The token acts as you: the agent sees and changes everything your user can. Use a dedicated member account to limit access.
Permissions used
Personal tokens have no scopes; access follows the user's workspace role and sharing.
| Access | Operations |
|---|---|
| Read | getAuthorizedUser, getWorkspaces, getSpaces, getFolders, getLists, getFolderlessLists, getList, getListMembers, getTasks, searchWorkspaceTasks, getTask, getTaskComments |
| Create/edit tasks in the list | createTask, updateTask, addTagToTask |
| Comment | createTaskComment |
Common errors
- 401 Unauthorized (
OAUTH_017/OAUTH_019): token missing, mistyped or regenerated. Paste the currentpk_token with noBearerprefix. - 403 Forbidden: the user cannot access that space, list or task.
- 400 Bad Request: invalid status name, assignee id or timestamp. Status must match one from getList; dates are Unix milliseconds.
- 429 Too Many Requests: 100 requests/minute per token on Free to Business plans; wait until
X-RateLimit-Reset.
Store the token as a VX Agents credential (API key) for this spec; never paste it into chat.
Usage guide
Setup
- Credential: a ClickUp personal API token (
pk_..., Settings > Apps > API Token), sent as the rawAuthorizationheader (noBearer). The agent acts as that user. - Worth pinning:
team_id(workspace id fromgetWorkspaces) and thelist_idyou usually add tasks to.
Find the right list
getWorkspacesreturns workspace ids and members (user ids for assigning).getSpaces(team_id) ->getFolders(space_id) ->getLists(folder_id); lists outside folders come fromgetFolderlessLists.getListshows the list'sstatuses; status names must match one of them exactly.
Work tasks
- Find tasks:
getTasksfor one list (statuses,assignees,due_date_lt,include_closed), orsearchWorkspaceTasksacross the workspace (list_ids[],space_ids[],statuses[],assignees[],tags[]). Both return 100 tasks perpage(0-based); stop whenlast_pageis true. getTaskandgetTaskCommentsto read a task before acting.createTaskin a list withnameplus optionalmarkdown_content,assignees(user ids),status,priority(1 urgent, 2 high, 3 normal, 4 low),due_date,tags.updateTaskto changename,status,priority,due_dateormarkdown_content; assignees use{"assignees": {"add": [123], "rem": [456]}}.addTagToTaskadds an existing space tag;createTaskCommentwithcomment_textandnotify_all(true emails everyone on the task).
Confirm before writing: show the user the new task, the fields you will change, or the comment text, and wait for approval before createTask, updateTask, addTagToTask or createTaskComment. Comments and assignments notify people.
Good to know
- Dates (
due_date,start_date,date_*_gt/lt) are Unix time in milliseconds; setdue_date_time: truewhen the time of day matters. - Task ids look like
86a1b2c3d. To use custom ids (ENG-42) passcustom_task_ids=trueandteam_id. getTasksexcludes subtasks and closed tasks unlesssubtasks=true/include_closed=true.- Rate limit is 100 requests/minute per token (higher on Enterprise); on 429 wait until
X-RateLimit-Reset.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “ClickUp Tasks” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.