# Connect ClickUp

> Know what is yours and what is late. Tasks assigned to you, their status and due dates, and new tasks in a list reach your Mac's notch, read with your own ClickUp token.

Source: https://coisland.app/docs/connect-clickup/

## What you need

- **You need:** Personal API token, from Your avatar › Settings › Apps
- **The form asks:** Connector name, Personal API token
- **You can watch:** Assigned to me, Due and overdue, New tasks in a list
- **Access:** GET requests only; it never changes a task or its status

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).

```text
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.

```text
assignee:me within:1d
```

### New tasks in a list

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

```text
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

```sql
-- 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](https://coisland.app/docs/getting-started/), or the [ClickUp connector](https://coisland.app/clickup/) for everything it can watch.