ClickUp

Connecting ClickUp lets you pick the Lists you want nima to watch. Tasks and comments from those Lists become signals in the loop. nima never changes your tasks: the only thing it writes to ClickUp is one webhook per picked List.

Connect ClickUp

Connecting ClickUp is done by a nima owner or admin from Integrations in the admin panel: on the ClickUp row press + (Connect ClickUp), choose the ClickUp Workspaces nima may see, and approve. You return to Integrations with ClickUp connected. If ClickUp later rejects the token, the row reads Needs reconnect and offers Reconnect.

• ClickUp's authorization has no scopes. The Workspaces you pick at consent are the access, and the token acts as the person who connected. nima uses it to read and to register one webhook per picked List.
• A nima workspace has one ClickUp connection. Connecting again replaces it, and that is the way to add a Workspace later, because the set of Workspaces is fixed at authorization.
• The ClickUp token does not expire, so there is nothing to renew. If ClickUp rejects the token, the connection is marked invalid and you reconnect.
• Connecting starts no ingestion by itself. Nothing flows until you pick Lists.

The same steps over the REST API: POST /v1/integrations/clickup/connect returns the ClickUp authorization URL, and GET /v1/clickup/app/status returns installed, the authorized teams, the connecting user's email and connectionInvalid. Every ClickUp route needs a signed-in session of a nima owner or admin (the manage-integrations permission). API keys and OAuth access tokens are refused with 403 INSUFFICIENT_PERMISSIONS, so there is no key or MCP route for ClickUp setup.

Pick ClickUp Lists to monitor

Picking a ClickUp List tells nima to ingest its tasks and comments. In the admin panel, open Integrations, select the connected ClickUp row, and tick Lists under Pick lists. Picked Lists appear under Monitored lists with their webhook and backfill status. Untick a List and confirm Stop monitoring to unpick it. Over the REST API (signed-in owner or admin session only), GET /v1/clickup/hierarchy returns your Workspaces as Space, Folder and List. A List that is already monitored carries a monitoredListId, the id you use to unpick it. Subfolders nested inside Folders show one level only.

• Pick a List with POST /v1/clickup/monitored-lists and the body fields listId, teamId, spaceId, folderId (nullable), listName and path. teamId must be a Workspace you connected. Picking a List that is already monitored returns the existing row.
• Limit: 200 Lists per nima workspace. Past that the request fails with 400.
• Unpick a List with DELETE /v1/clickup/monitored-lists/:id. It returns 204, removes the ClickUp webhook for that List and stops ingestion.
• List your picks with GET /v1/clickup/monitored-lists. Each row shows webhookStatus (pending, active or failed), backfillStatus (pending, running, done or failed), lastBackfillAt and lastEventAt.

Picking a List registers one ClickUp webhook scoped to that List and queues a backfill. If registering the webhook fails, the row stays at webhookStatus: failed. The backfill still runs, but no live events arrive. Unpick the List and pick it again to retry.

Reading the hierarchy costs ClickUp API calls, about 1 + 2 x spaces + folders, against ClickUp's own rate limit.

What arrives from ClickUp

Each picked List sends nine ClickUp events to nima: taskCreated, taskUpdated, taskDeleted, taskStatusUpdated, taskPriorityUpdated, taskTagUpdated, taskMoved, taskCommentPosted and taskCommentUpdated.

• One signal per task. Every task event creates or updates the single signal for that task, so a task edited ten times is still one signal. The signal's text and metadata are refreshed, and an edit does not trigger a fresh extraction. An edit never touches a signal that is already dismissed, merged or resolved.
• One signal per comment. A posted or edited comment becomes its own signal, linked to its task through the task id in its metadata.
• A deleted task is dismissed. taskDeleted dismisses the task's signal with the reason deleted in ClickUp. A task signal that is not already dismissed is dismissed, even if it was merged or resolved. Comment signals from that task stay.
• Signal content. The task signal carries the task name with its Space, Folder and List, the description, and facts: status, priority, tags, assignees, creator, due date and custom fields. The signal's channel is clickup: plus the List path.
• Origin. A ClickUp signal is internal by default. If the task has a custom field whose name contains customer, account, client or company (any case), whose type can hold a name (text, short text, drop-down, labels, users or email), and which has a value, the signal's origin is customer and that value seeds the stakeholder.

ClickUp backfill

Picking a List backfills its existing open tasks once, so signals do not start from zero. The backfill reads open (not closed) tasks, subtasks included, up to 2000 tasks per List, and only creates signals. It does not backfill comments.

A List with more than 2000 open tasks backfills its 2000 oldest by task id, then follows live events. Status moves from running to done or failed; a failed backfill page is attempted up to 3 times, with exponential backoff starting at 30 seconds. To retry after a final failure, unpick and pick the List again.

ClickUp limits

ClickUp rate-limits each token (100 requests per minute on its lower plans), and nima shares that budget between the hierarchy view, backfills and event handling. When ClickUp rate-limits a job, nima reschedules it past the window rather than dropping it.

• Comments: a comment event reads one page of the task's thread, the 25 newest comments, and ingests the comment named by the event, or the newest.
• Lists: 200 per nima workspace.
• Workspaces: fixed at authorization; reconnect to add one.
• No task writes: nima never changes tasks, statuses, comments or assignments in ClickUp. It only creates and deletes the per-List webhooks.
• Paused is a label. The Integrations toggle marks ClickUp Paused, but it does not stop ingestion. To stop a List, unpick it.
• Permanent read errors (403 or 404 from ClickUp) are dropped, not retried.

To read the original ClickUp task or comment behind a signal, use get_signal_source (owner or admin, sources:read); see get_signal_source. Signal fields are documented under signals.

Disconnect ClickUp

Disconnect ClickUp from its row in Integrations with Disconnect, or call DELETE /v1/integrations/clickup from a signed-in owner or admin session. It removes the stored connection and all monitored Lists, so ingestion stops. Signals already created stay in nima.

ClickUp has no revoke endpoint, and the per-List webhooks remain registered at ClickUp. nima drops any delivery that arrives for a removed List, but to clean up fully, unpick your Lists first and then remove the nima app in ClickUp's own settings.