> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ClickUp

> Connect ClickUp to Serval with a Personal API Token so your workflows can manage tasks, spaces, docs, comments, and time tracking on demand.

## About ClickUp

ClickUp is a project management and productivity platform that organizes work as a hierarchy of Workspace > Space > Folder > List > Task. Serval connects to ClickUp using a Personal API Token that you generate in your ClickUp settings. Once connected, Serval workflows can work with nearly everything in ClickUp - tasks, comments, time entries, goals, Docs, Chat, and more - acting as the ClickUp user who created the token. Serval only ever sends the token to ClickUp's official API host (api.clickup.com).

**Authentication:** Personal API Token (API key)

**Data sync:** On demand only. There is no background sync, no data ingestion, and no pre-built workflows - all reads and writes happen when one of your workflows runs.

## What the ClickUp integration enables

| Capability                     | Description                                                                                                                                                                                                               |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Task automation                | List, read, create, update, and delete tasks in a list or across an entire workspace, including custom field values, tags, dependencies, links between tasks, merges, task members, attachments, and time-in-status data. |
| Workspace hierarchy management | Read and manage Spaces, Folders, and Lists, plus views and folder, list, and task templates at every level of the hierarchy.                                                                                              |
| Comments and checklists        | List and create comments on tasks, lists, and views; reply to comments; create and manage task checklists and checklist items.                                                                                            |
| Time tracking                  | Read, create, start, stop, and edit time entries at the workspace level, check the currently running timer, review entry history and tags, and read legacy per-task time data.                                            |
| Goals and custom fields        | Read and manage team goals and key results, and read custom field definitions at the list, folder, space, and workspace level.                                                                                            |
| People, guests, and groups     | Read workspace data, members, guests, user groups, custom roles, seats, and plan info; invite, edit, and remove users and guests on Enterprise plans.                                                                     |
| Webhooks                       | Create, list, update, and delete ClickUp workspace webhooks. These are webhooks ClickUp sends, managed through the API - Serval does not automatically register a receiver for them.                                      |
| Docs, Chat, and audit logs     | Work with ClickUp Docs (docs and pages), Chat (channels, direct messages, messages, replies, reactions, members, followers), workspace audit logs, and object access permissions.                                         |
| Identity check                 | Look up which ClickUp user the stored token belongs to - a quick way to verify the connection.                                                                                                                            |

Anything defined in the [ClickUp API](https://developer.clickup.com/) can be accessed through Serval.

## Get your credentials

Serval needs a ClickUp Personal API Token. The token is generated by a specific ClickUp user account and carries exactly that user's access to workspaces, spaces, folders, lists, and tasks - so choose the account deliberately. See the [ClickUp API documentation](https://developer.clickup.com/) for background.

<Warning>
  The token authenticates as the user who generated it and never expires. Prefer a dedicated service account that is a member of every workspace your workflows need, rather than a personal employee account, and plan deliberate rotation.
</Warning>

<Steps>
  <Step title="Log in to ClickUp">
    Sign in as the account that should own the connection.
  </Step>

  <Step title="Open Settings">
    Click your avatar in the upper-right corner and select **Settings**.
  </Step>

  <Step title="Go to Apps">
    In the sidebar, click **Apps** (direct link: [app.clickup.com/settings/apps](https://app.clickup.com/settings/apps)).
  </Step>

  <Step title="Generate the token">
    Under **API Token**, click **Generate** (or **Regenerate** to rotate an existing token).
  </Step>

  <Step title="Copy the token">
    Click **Copy** and keep the token handy - it typically starts with "pk\_". You will paste it into Serval next.
  </Step>
</Steps>

## Connect in Serval

<Steps>
  <Step title="Enter an Instance Name">
    **Instance Name** is the display label for this connection (for example, "ClickUp - IT Workspace"). The form doesn't force you to fill it in when you first connect, but give the connection a name anyway - later edits to the connection are rejected if the name is blank - and make it distinct from any other ClickUp connection on the same team.
  </Step>

  <Step title="Paste your Personal API Token">
    Paste the token from ClickUp into the **Personal API Token** field. It is a password-style field, so the value is hidden as you type.
  </Step>

  <Step title="Save the connection">
    Save to store the credentials. Serval keeps the token encrypted and uses it for every ClickUp request your workflows make. If installation fails, the form shows "Failed to install integration" along with the underlying error.
  </Step>
</Steps>

<Tip>
  When you edit an existing connection, the saved token appears masked - bullets plus its last 4 characters - and can't be typed into directly. On the connection's settings page, click the pencil icon next to the masked value (the reconnect dialog has a **Replace** button instead) to get an empty "Enter new value" box, then paste the new token. Leaving the masked value untouched - or saving while the replacement box is still empty - keeps your existing stored token.
</Tip>

## Verifying the connection

ClickUp connections don't currently include built-in health checks, so you won't see a health-check panel on this connection the way you do for some other integrations. The quickest way to confirm everything works is to run a workflow step that performs the identity check from the capability table above - asking ClickUp which user the stored token belongs to. If it returns the expected user's record, the token is valid and correctly attached. If it fails, the token is invalid, revoked, or was mistyped - regenerate it in ClickUp and update the connection.

<Tip>
  A successful identity check only proves the token works - it does not prove the token's owner can see the data your workflows need. If the check passes but a workflow gets "not found" errors or empty results, the token's ClickUp account is probably not a member of the workspace, space, folder, or list involved.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="ClickUp returns 401 (unauthorized)">
    Serval sends your Personal API Token to ClickUp exactly as ClickUp expects for personal tokens, so a 401 is almost always a token problem: it was revoked, regenerated in ClickUp without updating Serval, or pasted with a typo or stray whitespace. Generate a fresh token in ClickUp and replace it in the connection.
  </Accordion>

  <Accordion title="Workflows see missing or empty data">
    Access is exactly the token owner's access. Workspaces, spaces, folders, lists, and tasks that user cannot see return "not found" or empty results in workflows. Use a service account that is a member of every workspace your workflows touch. Also remember ClickUp personal tokens never expire, so set your own rotation schedule.
  </Accordion>

  <Accordion title="Editing the connection: keeping vs. replacing the token">
    You can safely edit the connection without re-entering the token: leaving the masked **Personal API Token** value untouched - or saving while the "Enter new value" box is still empty - preserves the stored token, and pasting a new token (via the pencil icon on the settings page or **Replace** on the reconnect dialog) rotates it. Just make sure **Instance Name** stays filled in: if you clear it and save, the update fails and Serval shows "Failed to update configuration" or "Failed to update integration", depending on which form you used.
  </Accordion>

  <Accordion title="Only the ClickUp API host is reachable">
    The integration can only call ClickUp's official API host (api.clickup.com). Requests to any other host are not permitted, so workflows cannot use this connection to reach other ClickUp URLs or third-party services.
  </Accordion>

  <Accordion title="Long lists come back one page at a time">
    ClickUp returns list and search results in numbered pages controlled by a page number, not a cursor. Some endpoints indicate when you have reached the last page, but the most reliable pattern is for workflows that need everything to request page after page and stop when a page comes back with zero items (for example, an empty list of tasks).
  </Accordion>

  <Accordion title="Connecting does not install anything">
    Connecting ClickUp does not add pre-built workflows, background ingestion, or scheduled syncs. The integration is an on-demand connection for workflows you author, covering ClickUp's current API surface including the newer Docs, Chat, audit log, and access-permission areas.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your ClickUp integration.