ClickUp Setup Guide
Enables your agent to create, read, update, and manage tasks, lists, and comments in your ClickUp workspace.
Prerequisites
- A ClickUp account with access to the workspace you want the agent to use
- At least Member permissions on the spaces/lists the agent should access
Step 1: Generate a Personal API Token
- Go to app.clickup.com
- Click your avatar (bottom left) > Settings
- In the left sidebar, click Apps
- Under API Token, click Generate (or copy if one already exists)
- Copy the token (starts with
pk_)
Note: Personal API tokens have the same permissions as your account. The agent can only access workspaces, spaces, and lists that your account can access.
Step 2: Connect in Carapace
- Go to Dashboard > Connections
- Find ClickUp and click Connect
- Paste your personal API token (
pk_...) - Click Save Credentials
Carapace verifies the token by calling the ClickUp Teams endpoint. If validation fails, double-check that you copied the full token.
Credential Fields Reference
| Field | Required | Format | Description |
|---|---|---|---|
api_token | Yes | Starts with pk_ | Personal API Token — used for all ClickUp API calls |
Available Actions
Once connected, your agent can:
| Action | Description |
|---|---|
clickup_get_spaces | List all spaces in your workspace |
clickup_get_lists | List task lists within a space |
clickup_get_task | Get full details of a task by ID |
clickup_create_task | Create a new task in a list |
clickup_update_task | Update task name, description, status, priority, or assignees |
clickup_get_comments | Read comments on a task |
clickup_add_comment | Add a comment to a task |
clickup_get_members | List members of a list (for assigning tasks) |
Finding Your List ID
To create tasks, the agent needs a List ID. To find it:
- Open the list in ClickUp
- Look at the URL:
https://app.clickup.com/12345/v/li/678901 - The number after
/li/is the List ID (e.g.,678901)
Alternatively, use the clickup_get_spaces and clickup_get_lists tools to discover IDs programmatically.
Gotchas
Token permissions match your account: The personal API token inherits your account's permissions. If you can't access a space or list in the ClickUp UI, the agent can't either.
No OAuth flow: ClickUp supports OAuth for third-party apps, but Carapace uses personal API tokens for simplicity. This means the token is tied to a single user's account.
Rate limits: ClickUp enforces rate limits (100 requests per minute per token). The agent respects these limits, but high-frequency operations may result in temporary throttling.
Custom fields: The clickup_create_task and clickup_update_task tools support standard fields (name, description, priority, status, assignees). Custom fields are not currently supported.
Task ID format: ClickUp task IDs are alphanumeric (e.g., abc123). The ID shown in the URL (#CU-xxx) is a display ID — use the API ID returned by clickup_get_task or clickup_create_task.
Troubleshooting
"Authorization failed" or 401 error
The API token is invalid or expired. Generate a new token in ClickUp Settings > Apps and update it in the Carapace dashboard.
Agent can't find spaces or lists
Your account may not have access to those resources. Verify you can see them in the ClickUp UI, then check that the correct workspace is selected.
Task creation fails with "invalid list"
The List ID is incorrect. Verify it from the ClickUp URL (the number after /li/), or use clickup_get_lists to discover valid list IDs.
Rate limit errors (429)
The agent is making too many requests. This usually resolves automatically. If persistent, check that the agent isn't in a retry loop.
Triage Agent Integration
ClickUp works seamlessly with the Slack Triage Agent Template. The triage agent monitors Slack for bug reports and feature requests, gathers structured info, gets dev approval, then automatically creates ClickUp tasks with proper priority, description, and assignees.
See the Slack guide for the full triage workflow setup.