ClickUp

What your agents can doCopy Anchor Link

Agents can call ClickUp API v2 and v3. v2 covers tasks, lists, comments, time tracking, and goals. v3 covers Docs, Chat, and moving tasks between lists. Access depends on the connected user's permissions and ClickUp plan. Helios attaches your API token or OAuth token to API calls.

• Create tasks from a request, with a list, priority, assignee, and due date
• Move tasks between statuses and update their fields
• Log time on tasks in Spaces that have the Time Tracking ClickApp turned on
• Comment on tasks and reply to comments
• Attach files to tasks, and read files attached to tasks
• Report on a list's tasks by status or assignee

The agent can send and download files up to 16 MB. Requests must start at ClickUp's API at https://api.clickup.com/api, https://attachments-public.clickup.com, or a workspace attachment host matching https://*.p.clickup-attachments.com, such as t123.p.clickup-attachments.com. The attachment host pattern is not restricted to your connected workspace. Downloads from attachments-public.clickup.com do not receive your API or OAuth token.

AuthenticationCopy Anchor Link

See Integration authentication for how credentials are stored and injected.

ClickUp API TokenCopy Anchor Link

Connect with a personal API token from the ClickUp user whose permissions the agent should use.

1. In ClickUp, click your avatar in the upper-right corner and select Settings.
2. In the sidebar, click Apps. The page may be named ClickUp API.
3. Under API Token, click Generate, then Copy. The token starts with pk_.
4. In Helios, choose ClickUp API Token and paste the token into API Token.
5. If you belong to more than one ClickUp workspace, enter the workspace that triggers should watch in Workspace ID. It is the number after app.clickup.com/ in your ClickUp URL.
6. Save.

If you regenerate the token in ClickUp, enter the new one through Manage and save.

Your own ClickUp OAuth appCopy Anchor Link

Only workspace owners and admins can create an OAuth app in ClickUp.

1. In ClickUp, click your avatar, select Settings, and click Apps in the sidebar.

2. Click Create new app.

3. Name the app and add this redirect URL:

   Copy Text

   https://api.heliosapp.com/integrations/clickup/oauth_callback

   After you save, ClickUp shows only the domain, https://api.heliosapp.com.

4. Copy the app's client ID and secret.

5. In Helios, choose Your own ClickUp OAuth app and enter them in Client ID and Client Secret. If you will authorize more than one workspace, enter the one for triggers in Workspace ID.

6. Save, then approve access in ClickUp and pick the workspaces Helios can use.

Helios requests no OAuth scopes. The connection uses the approving user's access to the workspaces they authorize.

TriggersCopy Anchor Link

ClickUp can start a Workflow when something happens in your workspace. Helios registers a webhook in ClickUp when you save the connection, so there is nothing to set up in ClickUp. Helios requests the events below and reports any that ClickUp does not subscribe to. Deleting the connection removes the webhook.

The webhook belongs to the token's user. ClickUp sends an event only when that user can still reach the item.

All filters are optional.

• List matches events for tasks and comments in the lists you pick. For task.moved, it is the list the task moved to. For list.updated and list.deleted, it is the list itself.
• Moved to status matches only updates that changed the task's status, when the new status matches, such as in progress or complete. It is a pattern, and case is ignored.
• Changed field matches updates that changed a field whose ClickUp name matches. It is a pattern, and case is ignored. Use it to match one kind of change, such as a new priority or due date.

These are the field names in ClickUp's docs:

Use a pattern such as assignee* to match every field whose name starts with assignee.

ClickUp sends one change as more than one event:

• Each task change that ClickUp also reports as its own event, such as a status change, a new or edited comment, or a move to another list, also arrives as task.updated.
• Deleting a folder or a space also sends list.deleted for each of its lists.

An event carries the IDs and the change, not the whole item. Folder, space, goal, and target events carry only the item's ID. The agent reads the item through the API when it needs the name or other fields.

Deliveries are verified with the HMAC-SHA256 X-Signature header, using the secret ClickUp returns when Helios creates the webhook.

Check that it worksCopy Anchor Link

• The connection: after you save, the connection's status shows Connected. Error means the connection test failed. Open the connection to see the error.
• A trigger:
  1. Add task.created to a workflow with no filters.
  2. Create a test task in the workspace.
  3. Check that a run starts. Then open the connection in Helios and click Webhook events to see the event.

Common errorsCopy Anchor Link

LimitsCopy Anchor Link

• Workspaces: each connection watches one workspace for triggers. Agents can still call the API in every workspace the token can see.