Connect ClickUp

To connect ClickUp to CoIsland you need one thing: your personal API token, which starts with pk_. No admin, no app to register, no OAuth. CoIsland calls ClickUp’s API v2 straight from your Mac, keeps the token in your login Keychain, and only ever reads.

Generate a ClickUp personal API token

1. Sign in to ClickUp.
2. Click your avatar at the top right, then Settings.
3. In the sidebar, click Apps.
4. Under API Token, click Generate (or Regenerate), then Copy.

The token never expires and acts as you in every Workspace you belong to. Regenerating it ends the old one. In ClickUp, using a personal API token is a permission of your role: members and limited members have it by default, and Workspace owners and admins can remove it from a role.

Connect ClickUp in CoIsland

Open Settings › Connectors, click +, and choose ClickUp.

Field	What to enter
Connector name	What monitors call it: clickup.
Personal API token	The pk_… token you copied.

Test connector saves nothing. It calls GET /api/v2/user and GET /api/v2/team and shows your name and your Workspaces. The token is only ever sent to https://api.clickup.com, in the Authorization header.

Choose what to watch: the three ClickUp monitor kinds

Every kind but the list one starts with assignee:me: the monitor watches your own tasks. With one Workspace, CoIsland uses it; with several, pick one (workspace:). Spaces and lists are picked by name and saved as IDs. A status with spaces is written with _: in_progress.

Assigned to me

An open task alerts when it is assigned to you. With status:, a task of yours alerts when it enters one of those statuses (closed ones included).

assignee:me status:review

Due and overdue

Your tasks overdue or due within the window: within:0d is today, up to 14d. A task alerts again when its due date moves.

assignee:me within:1d

New tasks in a list

A task created in one list in the last 7 days, subtasks too, by anyone.

list:901412345

What a ClickUp alert shows

The notch lists each task as Sprint 42 ENG-42 · In progress · Overdue, Tue 22 Sep · Urgent: list and ID, status, due, and urgent or high priority. Clicking it opens the alert in CoIsland, where the task fills in live: its description, assignees, tags and comments, and Open in ClickUp.

What a ClickUp monitor’s watch file looks like

-- name: Due today or overdue
-- kind: clickup.due
-- connector: clickup
-- every: 15m
-- alert: new-rows

assignee:me within:0d

The kinds are clickup.assigned, clickup.due and clickup.list.

Rate limits

ClickUp allows 100 requests a minute per token on the Free Forever, Unlimited and Business plans, 1,000 on Business Plus and 10,000 on Enterprise. A check of your tasks costs three requests (who you are, your Workspace, the tasks), one more per 100 tasks; the examples check every five minutes. When ClickUp answers 429, checks back off on their own and the error says when the limit lifts.

Troubleshooting ClickUp connector errors

• The token was refused. ClickUp answered 401 (OAUTH_025 and the like): the token was mistyped or regenerated. Copy it again.
• Workspace …: not authorized for this token. ClickUp answered OAUTH_027 or a neighbour: you left the Workspace, or its admins removed your role’s permission to use a personal API token.
• You are in several Workspaces: pick one in the monitor. Add workspace: or pick it in the editor.
• This task no longer exists in ClickUp, or you can no longer see it.
• Rate limited; retry after 14:05. The next check tries again.

Common questions

Does CoIsland need a ClickUp admin?

No, as long as your role may use a personal API token, which it may by default.

Can CoIsland change a task’s status?

No. It only reads.

Next: Getting started, or the ClickUp connector for everything it can watch.