A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The ClickUp API is how an app or AI agent works with a ClickUp workspace: reading and creating tasks, organizing them into lists, folders, and spaces, posting comments, tracking time, and updating goals. Access is granted through a personal token or an OAuth connection, and an agent is limited to the workspaces and items the authorizing person can already see, since the API carries no per-method scopes of its own. ClickUp can also push events to a webhook URL when something changes in a workspace.
How an app or AI agent connects to ClickUp determines what it can reach. There are a few routes, each governed by the token behind it and the workspaces and items the person who authorized it can already see.
The REST API answers at https://api.clickup.com/api/v2. It is a single, continuously updated version with no dated version to pin, covering tasks, lists, folders, spaces, comments, time tracking, and goals.
ClickUp's hosted MCP server at https://mcp.clickup.com/mcp lets an AI assistant work with tasks, lists, comments, time tracking, and search through natural language. It is in public beta, available on all plans, and authenticates with OAuth 2.1 and PKCE only, not a personal token.
Webhooks deliver the chosen events to a destination URL, and each delivery is signed with an HMAC SHA-256 hash in the X-Signature header, checked against the webhook's shared secret to confirm it came from ClickUp.
A personal API token is generated in ClickUp's settings, begins with pk_, and never expires. It is sent as the raw token in the Authorization header and carries the full access of the user who created it.
OAuth 2.0 uses the authorization code flow: an app sends a user to ClickUp to authorize the workspaces they choose, then exchanges the returned code for a Bearer access token. There are no per-endpoint scopes, so the token reaches whatever that user can in the authorized workspaces.
The ClickUp API is split into areas an agent can act on, such as tasks, lists, folders, spaces, comments, time tracking, and goals. Each area has its own methods, and writes here change real workspace data.
List, read, create, update, delete, and move tasks, and list tasks filtered across a whole workspace.
Create lists inside a folder or directly in a space, and read, update, and delete a list.
List, read, create, update, and delete folders inside a space.
List, read, create, update, and delete the spaces inside a workspace.
Read and post comments on a task, a list, or a chat view, and update or delete a comment.
List, read, create, update, and delete time entries, and start or stop a running timer.
List, read, create, update, and delete goals in a workspace.
List the workspaces a token can reach and read a workspace's plan.
List a workspace's webhooks, create one, update it, and delete it.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
TasksList, read, create, update, delete, and move tasks, and list tasks filtered across a whole workspace.7 | ||||||
| GET | /api/v2/list/{list_id}/task | View the tasks in a list, up to 100 per page. | read | — | Current | |
Returns the tasks the token's user can see in that list. ClickUp has no per-method scopes; access is whatever that user can already reach. Acts ontask Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/task/{task_id} | Get a single task by its id. | read | — | Current | |
Access is whatever the token's user can see. ClickUp has no per-method scopes. Acts ontask Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/list/{list_id}/task | Create a task in a list. | write | — | Current | |
Creates real task data in the list. ClickUp has no per-method scopes; the token acts with its user's permissions. Acts ontask Permission (capability)None required VersionAvailable since the API’s base version Webhook event taskCreatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/v2/task/{task_id} | Update a task, such as its name, description, status, assignees, or due date. | write | — | Current | |
Changing status fires taskStatusUpdated as well as taskUpdated. ClickUp has no per-method scopes. Acts ontask Permission (capability)None required VersionAvailable since the API’s base version Webhook event taskUpdatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/task/{task_id} | Delete a task. | write | — | Current | |
Removes the task. ClickUp has no per-method scopes, so the same token that reads can also delete. Acts ontask Permission (capability)None required VersionAvailable since the API’s base version Webhook event taskDeletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/v2/task/{task_id}/move | Move a task to a different list. | write | — | Current | |
Moves the task between lists. ClickUp has no per-method scopes. Acts ontask Permission (capability)None required VersionAvailable since the API’s base version Webhook event taskMovedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/team/{team_id}/task | List tasks across a whole workspace, filtered by space, list, assignee, status, and more. | read | — | Current | |
team_id here is a workspace id. Returns tasks across the workspace that the token's user can see. Acts ontask Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ListsCreate lists inside a folder or directly in a space, and read, update, and delete a list.5 | ||||||
| POST | /api/v2/folder/{folder_id}/list | Create a list inside a folder. | write | — | Current | |
Creates real list data in the folder. ClickUp has no per-method scopes. Acts onlist Permission (capability)None required VersionAvailable since the API’s base version Webhook event listCreatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/space/{space_id}/list | Create a list directly in a space, without a folder. | write | — | Current | |
Creates a folderless list in the space. ClickUp has no per-method scopes. Acts onlist Permission (capability)None required VersionAvailable since the API’s base version Webhook event listCreatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/list/{list_id} | Get a single list by its id. | read | — | Current | |
Access is whatever the token's user can see. ClickUp has no per-method scopes. Acts onlist Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/v2/list/{list_id} | Update a list's name, content, due date, assignee, or status. | write | — | Current | |
Changes real list data. ClickUp has no per-method scopes. Acts onlist Permission (capability)None required VersionAvailable since the API’s base version Webhook event listUpdatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/list/{list_id} | Delete a list and the tasks inside it. | write | — | Current | |
Removes the list and its tasks. ClickUp has no per-method scopes. Acts onlist Permission (capability)None required VersionAvailable since the API’s base version Webhook event listDeletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
FoldersList, read, create, update, and delete folders inside a space.3 | ||||||
| POST | /api/v2/space/{space_id}/folder | Create a folder inside a space. | write | — | Current | |
Creates real folder data in the space. ClickUp has no per-method scopes. Acts onfolder Permission (capability)None required VersionAvailable since the API’s base version Webhook event folderCreatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/folder/{folder_id} | Get a single folder by its id. | read | — | Current | |
Access is whatever the token's user can see. ClickUp has no per-method scopes. Acts onfolder Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/folder/{folder_id} | Delete a folder and the lists inside it. | write | — | Current | |
Removes the folder and its lists. ClickUp has no per-method scopes. Acts onfolder Permission (capability)None required VersionAvailable since the API’s base version Webhook event folderDeletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SpacesList, read, create, update, and delete the spaces inside a workspace.3 | ||||||
| GET | /api/v2/team/{team_id}/space | List the spaces in a workspace. | read | — | Current | |
team_id here is a workspace id. Returns the spaces the token's user can see. Acts onspace Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/team/{team_id}/space | Create a space in a workspace. | write | — | Current | |
team_id here is a workspace id. Creates a real space. ClickUp has no per-method scopes. Acts onspace Permission (capability)None required VersionAvailable since the API’s base version Webhook event spaceCreatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/space/{space_id} | Delete a space and everything inside it. | write | — | Current | |
Removes the space, its folders, lists, and tasks. ClickUp has no per-method scopes. Acts onspace Permission (capability)None required VersionAvailable since the API’s base version Webhook event spaceDeletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CommentsRead and post comments on a task, a list, or a chat view, and update or delete a comment.4 | ||||||
| GET | /api/v2/task/{task_id}/comment | Get the comments on a task. | read | — | Current | |
Returns the comments on a task the token's user can see. ClickUp has no per-method scopes. Acts oncomment Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/task/{task_id}/comment | Add a comment to a task. | write | — | Current | |
Posts a real comment people see. ClickUp has no per-method scopes. Acts oncomment Permission (capability)None required VersionAvailable since the API’s base version Webhook event taskCommentPostedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/v2/comment/{comment_id} | Update a comment's text, assignee, or resolved state. | write | — | Current | |
Edits an existing comment. ClickUp has no per-method scopes. Acts oncomment Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/comment/{comment_id} | Delete a comment. | write | — | Current | |
Removes the comment. ClickUp has no per-method scopes. Acts oncomment Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Time trackingList, read, create, update, and delete time entries, and start or stop a running timer.5 | ||||||
| GET | /api/v2/team/{team_id}/time_entries | List time entries in a workspace within a date range. | read | — | Current | |
team_id here is a workspace id. Returns time entries the token's user can see. Acts ontime entry Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/team/{team_id}/time_entries | Create a time entry on a task. | write | — | Current | |
team_id here is a workspace id. Records real tracked time. ClickUp has no per-method scopes. Acts ontime entry Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/team/{team_id}/time_entries/start | Start a running timer for the authenticated user. | write | — | Current | |
team_id here is a workspace id. Starts tracking time live. ClickUp has no per-method scopes. Acts ontime entry Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/team/{team_id}/time_entries/stop | Stop the running timer for the authenticated user. | write | — | Current | |
team_id here is a workspace id. Stops live time tracking. ClickUp has no per-method scopes. Acts ontime entry Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/team/{team_id}/time_entries/{timer_id} | Delete a time entry. | write | — | Current | |
team_id here is a workspace id. Removes tracked time. ClickUp has no per-method scopes. Acts ontime entry Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
GoalsList, read, create, update, and delete goals in a workspace.4 | ||||||
| GET | /api/v2/team/{team_id}/goal | List the goals in a workspace. | read | — | Current | |
team_id here is a workspace id. Returns goals the token's user can see. Acts ongoal Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/team/{team_id}/goal | Create a goal in a workspace. | write | — | Current | |
team_id here is a workspace id. Creates a real goal. ClickUp has no per-method scopes. Acts ongoal Permission (capability)None required VersionAvailable since the API’s base version Webhook event goalCreatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/v2/goal/{goal_id} | Update a goal's name, due date, owners, or color. | write | — | Current | |
Changes real goal data. ClickUp has no per-method scopes. Acts ongoal Permission (capability)None required VersionAvailable since the API’s base version Webhook event goalUpdatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/goal/{goal_id} | Delete a goal. | write | — | Current | |
Removes the goal. ClickUp has no per-method scopes. Acts ongoal Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WorkspacesList the workspaces a token can reach and read a workspace's plan.2 | ||||||
| GET | /api/v2/team | List the workspaces the token is authorized to act in. | read | — | Current | |
The API calls a workspace a team. This returns the workspaces the token can reach, the usual starting point for a call. Acts onworkspace Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/team/{team_id}/plan | Get a workspace's current plan. | read | — | Current | |
team_id here is a workspace id. The plan also sets the token's rate limit. Acts onworkspace Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WebhooksList a workspace's webhooks, create one, update it, and delete it.3 | ||||||
| GET | /api/v2/team/{team_id}/webhook | List the webhooks registered in a workspace. | read | — | Current | |
team_id here is a workspace id. Lists the webhooks the token's user created in the workspace. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/team/{team_id}/webhook | Create a webhook that posts chosen events to a destination URL. | write | — | Current | |
team_id here is a workspace id. Returns a shared secret used to sign each delivery in the X-Signature header. ClickUp has no per-method scopes. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/webhook/{webhook_id} | Delete a webhook. | write | — | Current | |
Stops event delivery for that webhook. ClickUp has no per-method scopes. Acts onwebhook Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ClickUp can notify an app or AI agent when something happens in a workspace, instead of the app repeatedly asking. ClickUp posts the event to a webhook URL that has been registered, and signs each delivery so the receiver can confirm it came from ClickUp.
| Event | What it signals | Triggered by |
|---|---|---|
taskCreated | Fires when a task is created. | /api/v2/list/{list_id}/task |
taskUpdated | Fires when a task is updated, such as a change to its name, description, or fields. | /api/v2/task/{task_id} |
taskDeleted | Fires when a task is deleted. | /api/v2/task/{task_id} |
taskStatusUpdated | Fires when a task's status changes. | /api/v2/task/{task_id} |
taskMoved | Fires when a task is moved to a different list. | /api/v2/task/{task_id} |
taskCommentPosted | Fires when a comment is posted on a task. | /api/v2/task/{task_id}/comment |
listCreated | Fires when a list is created. | /api/v2/folder/{folder_id}/list/api/v2/space/{space_id}/list |
listUpdated | Fires when a list is updated. | /api/v2/list/{list_id} |
listDeleted | Fires when a list is deleted. | /api/v2/list/{list_id} |
folderCreated | Fires when a folder is created. | /api/v2/space/{space_id}/folder |
folderDeleted | Fires when a folder is deleted. | /api/v2/folder/{folder_id} |
spaceCreated | Fires when a space is created. | /api/v2/team/{team_id}/space |
spaceDeleted | Fires when a space is deleted. | /api/v2/space/{space_id} |
goalCreated | Fires when a goal is created. | /api/v2/team/{team_id}/goal |
goalUpdated | Fires when a goal is updated. | /api/v2/goal/{goal_id} |
ClickUp limits how fast an app or AI agent can call, through a per-minute request quota on each token that rises with the workspace plan.
ClickUp meters each token by requests per minute, and the ceiling rises with the workspace plan: 100 requests per minute per token on Free Forever, Unlimited, and Business; 1,000 per minute on Business Plus; and 10,000 per minute on Enterprise. Exceeding the limit returns HTTP 429. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers, where Reset is a Unix timestamp for when the window clears, so a caller can pace itself rather than wait for a rejection.
List endpoints that can return many items page through a page query parameter, which is 0-based. Get Tasks returns at most 100 tasks per page, and a response is the last page when it holds fewer than 100. Some list endpoints return their full set without paging.
Requests and responses are JSON. Direct calls from a browser are blocked by ClickUp's CORS policy, so a server-side caller is required. ClickUp does not document a single payload size ceiling across the whole API.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | OAUTH_017 | The authorization token was missing from the Authorization header, so the request was not authenticated. | Send a valid personal token or OAuth Bearer token in the Authorization header. |
| 401 | OAUTH_027 | The workspace was not authorized by the user for this token, so the token cannot act in it. | Have the user authorize the workspace, or call against a workspace the token already covers. |
| 400 | OAUTH_007 | The redirect URI sent in the OAuth flow does not match a redirect URI registered on the app. | Register the redirect URI on the OAuth app, or send one that is already registered. |
| 429 | Rate limit exceeded | The token sent more requests in the current minute than its plan allows. | Wait until the X-RateLimit-Reset time, then retry, and pace calls using the X-RateLimit-Remaining header. |
ClickUp serves a single, continuously updated API under the v2 path. There is no dated version to pin, and new fields and events are added without a version bump.
The v2 path is ClickUp's documented and supported public API. It is not dated or pinned: ClickUp adds fields, endpoints, and webhook events to it over time without minting a new version, so an integration tracks a single continuously updated surface. The older v1 path is retired and v2 is the only version to build against.
ClickUp launched a first-party Model Context Protocol server at mcp.clickup.com, letting AI assistants act on workspace data through natural language. It is available on all plans, authenticates with OAuth 2.1 and PKCE only, and remains in public beta with a per-day call allowance that depends on the plan and the Everything AI add-on.
The v2 path is the documented, supported API; the older v1 path is retired.
ClickUp changelog ↗Bollard AI sits between a team's AI agents and ClickUp. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.