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

# ClickUp

> Teams, spaces, folders, lists, tasks, comments, tags, time tracking, and checklists.

ClickUp is included in Archal's environment catalog. Use it in a sandbox for teams, spaces, folders, lists, tasks, comments, tags, time tracking, and checklists.

| | |
| - | - |
| Environment ID | `clickup` |
| Transport | REST and MCP |
| State | JSON |
| Contract | `archal.environment-state.clickup` version `1` |
| Channel | Public |
| Curated samples | 5 |

Public means the environment is released and startable. It still describes a bounded provider surface, not a promise that every upstream operation exists.

## Compatibility boundary

**Local catalog validation:** All five published samples passed. Checks cover the state contract, relationships, artifact hash, secret scan, and size limit.

> [!NOTE]
>
> Local catalog validation is not hosted proof. Archal checks current certification, reset, and isolation evidence before admitting new sandboxes. Use the authenticated environment catalog for live availability.

* Custom-field and hierarchy behavior is limited to the documented provider surface.

## Curated starting states

List the five samples with `archal sample list clickup`. Each sample is a versioned starting state with a representative read, mutation, expected diff, reset expectation, and verified artifact hash.

> [accordion] ClickUp task list baseline
>
> Expose one workspace, space, list, and open task as the smallest task-creation baseline.
>
> **Sample ID:** `clickup.task-list-baseline.v1`
>
> **Category:** `minimal`
>
> **Starting state:** 4 records across `lists`: 1, `spaces`: 1, `tasks`: 1, `teams`: 1
>
> **Supported surface:** Stateful workspace, list, task, comment, tag, and checklist records.
>
> **Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.tasks`
>
> **First read:** `GET /api/v2/team`. Expected result: HTTP 200.
>
> **Representative mutation:** `POST /api/v2/list/901417041097/task`. Expected result: HTTP 200, 201, 204.
>
> **Mutation input**
>
> ```json theme={null}
> {
>   "description": "Reproduce the retry path and attach the delivery trace before triage.",
>   "name": "Investigate duplicate webhook deliveries"
> }
> ```
>
> **Expected diff:** changes include `tasks`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.
>
> **Expected reset:** restores loaded sample.
>
> **Known limits**
>
> * Custom-field and hierarchy behavior is limited to the documented provider surface.
>
> **Start this sample**
>
> ```bash theme={null}
> archal sample show clickup.task-list-baseline.v1 --raw > archal-clickup-task-list-baseline.json
> archal state validate clickup archal-clickup-task-list-baseline.json
> archal session create clickup \
>   --state clickup=archal-clickup-task-list-baseline.json
> ```
>
> **Inspect the raw state**
>
> ```bash theme={null}
> archal sample show clickup.task-list-baseline.v1 --raw
> ```
>
> The packaged JSON artifact is `samples/states/clickup/task-list-baseline/state.json` and is 7,798 bytes. The CLI verifies SHA-256 `96e0b03b072a80fbd72e588b4325097b04b9f8dac6618a0ff9304768b45679d8` before printing it.
>
> Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

> [accordion] ClickUp product squad
>
> Model a product squad with one workspace, two lists, assignees, tags, comments, and checklists.
>
> **Sample ID:** `clickup.product-squad.v1`
>
> **Category:** `small-team`
>
> **Starting state:** 13 records across `checklists`: 2, `comments`: 2, `lists`: 2, `spaces`: 1, `tags`: 2, `tasks`: 3, `teams`: 1
>
> **Supported surface:** Stateful workspace, list, task, comment, tag, and checklist records.
>
> **Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.tasks`
>
> **First read:** `GET /api/v2/team`. Expected result: HTTP 200.
>
> **Representative mutation:** `POST /api/v2/list/901417041097/task`. Expected result: HTTP 200, 201, 204.
>
> **Mutation input**
>
> ```json theme={null}
> {
>   "description": "Reproduce the retry path and attach the delivery trace before triage.",
>   "name": "Investigate duplicate webhook deliveries"
> }
> ```
>
> **Expected diff:** changes include `tasks`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.
>
> **Expected reset:** restores loaded sample.
>
> **Known limits**
>
> * Custom-field and hierarchy behavior is limited to the documented provider surface.
>
> **Start this sample**
>
> ```bash theme={null}
> archal sample show clickup.product-squad.v1 --raw > archal-clickup-product-squad.json
> archal state validate clickup archal-clickup-product-squad.json
> archal session create clickup \
>   --state clickup=archal-clickup-product-squad.json
> ```
>
> **Inspect the raw state**
>
> ```bash theme={null}
> archal sample show clickup.product-squad.v1 --raw
> ```
>
> The packaged JSON artifact is `samples/states/clickup/product-squad/state.json` and is 17,229 bytes. The CLI verifies SHA-256 `e32deb5412514c7edf697624efe38a189f6ceb019a5641965c5e7bfd22054a05` before printing it.
>
> Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

> [accordion] ClickUp populated workspace portfolio
>
> Use the full reviewed workspace seed for spaces, folders, lists, tasks, comments, time entries, goals, and checklists.
>
> **Sample ID:** `clickup.workspace-portfolio.v1`
>
> **Category:** `populated`
>
> **Starting state:** 31 records across `checklists`: 4, `comments`: 2, `folders`: 2, `goalGroups`: 1, `goals`: 1, `keyResults`: 1, `lists`: 6, `spaces`: 2, `tasks`: 5, `teams`: 1, `timeEntries`: 6
>
> **Supported surface:** Stateful workspace, list, task, comment, tag, and checklist records.
>
> **Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.tasks`
>
> **First read:** `GET /api/v2/team`. Expected result: HTTP 200.
>
> **Representative mutation:** `POST /api/v2/list/901417041097/task`. Expected result: HTTP 200, 201, 204.
>
> **Mutation input**
>
> ```json theme={null}
> {
>   "description": "Reproduce the retry path and attach the delivery trace before triage.",
>   "name": "Investigate duplicate webhook deliveries"
> }
> ```
>
> **Expected diff:** changes include `tasks`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.
>
> **Expected reset:** restores loaded sample.
>
> **Known limits**
>
> * Custom-field and hierarchy behavior is limited to the documented provider surface.
>
> **Start this sample**
>
> ```bash theme={null}
> archal sample show clickup.workspace-portfolio.v1 --raw > archal-clickup-workspace-portfolio.json
> archal state validate clickup archal-clickup-workspace-portfolio.json
> archal session create clickup \
>   --state clickup=archal-clickup-workspace-portfolio.json
> ```
>
> **Inspect the raw state**
>
> ```bash theme={null}
> archal sample show clickup.workspace-portfolio.v1 --raw
> ```
>
> The packaged JSON artifact is `samples/states/clickup/workspace-portfolio/state.json` and is 29,867 bytes. The CLI verifies SHA-256 `74a8b73658ed2cddbb595b46f9fe06be1900e01c57216be7a54e5808ef6f1138` before printing it.
>
> Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

> [accordion] ClickUp overdue checklist
>
> Read an overdue release task with an incomplete sign-off checklist, then add a provider-visible blocker comment.
>
> **Sample ID:** `clickup.overdue-checklist.v1`
>
> **Category:** `edge-case`
>
> **Starting state:** 5 records across `checklists`: 1, `lists`: 1, `spaces`: 1, `tasks`: 1, `teams`: 1
>
> **Supported surface:** Stateful workspace, list, task, comment, tag, and checklist records.
>
> **Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.tasks`
>
> **First read:** `GET /api/v2/task/sample-overdue-task`. Expected result: HTTP 200.
>
> **Representative mutation:** `POST /api/v2/task/sample-overdue-task/comment`. Expected result: HTTP 200.
>
> **Mutation input**
>
> ```json theme={null}
> {
>   "comment_text": "Release remains blocked: provider retry verification is complete, but the required sign-off checklist is still unresolved."
> }
> ```
>
> **Expected diff:** changes include `comments`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.
>
> **Expected reset:** restores loaded sample.
>
> **Known limits**
>
> * Custom-field and hierarchy behavior is limited to the documented provider surface.
>
> **Start this sample**
>
> ```bash theme={null}
> archal sample show clickup.overdue-checklist.v1 --raw > archal-clickup-overdue-checklist.json
> archal state validate clickup archal-clickup-overdue-checklist.json
> archal session create clickup \
>   --state clickup=archal-clickup-overdue-checklist.json
> ```
>
> **Inspect the raw state**
>
> ```bash theme={null}
> archal sample show clickup.overdue-checklist.v1 --raw
> ```
>
> The packaged JSON artifact is `samples/states/clickup/overdue-checklist/state.json` and is 9,431 bytes. The CLI verifies SHA-256 `8cecfeaf34bf570f4fe063d2ae1fbb0ab66730e502f0c4de0af248c0fc721cbb` before printing it.
>
> Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

> [accordion] ClickUp task and comment workflow
>
> Inspect an active connector rollout task with its checklist and history, append a release-gate comment, and verify reset.
>
> **Sample ID:** `clickup.task-comment-workflow.v1`
>
> **Category:** `workflow`
>
> **Starting state:** 9 records across `checklists`: 2, `comments`: 2, `lists`: 1, `spaces`: 1, `tasks`: 2, `teams`: 1
>
> **Supported surface:** Stateful workspace, list, task, comment, tag, and checklist records.
>
> **Required capabilities:** `state.read`, `state.load`, `state.reset`, `rest.tasks`
>
> **First read:** `GET /api/v2/task/86baa4tbc`. Expected result: HTTP 200.
>
> **Representative mutation:** `POST /api/v2/task/86baa4tbc/comment`. Expected result: HTTP 200.
>
> **Mutation input**
>
> ```json theme={null}
> {
>   "comment_text": "Release gate update: duplicate-delivery and Retry-After checks passed; awaiting final provider-auth verification."
> }
> ```
>
> **Expected diff:** changes include `comments`. Exact match required: no. Hosted promotion must observe every listed path after the provider-native mutation; dynamic provider ids and timestamps are excluded from exact matching.
>
> **Expected reset:** restores loaded sample.
>
> **Known limits**
>
> * Custom-field and hierarchy behavior is limited to the documented provider surface.
>
> **Start this sample**
>
> ```bash theme={null}
> archal sample show clickup.task-comment-workflow.v1 --raw > archal-clickup-task-comment-workflow.json
> archal state validate clickup archal-clickup-task-comment-workflow.json
> archal session create clickup \
>   --state clickup=archal-clickup-task-comment-workflow.json
> ```
>
> **Inspect the raw state**
>
> ```bash theme={null}
> archal sample show clickup.task-comment-workflow.v1 --raw
> ```
>
> The packaged JSON artifact is `samples/states/clickup/task-comment-workflow/state.json` and is 12,397 bytes. The CLI verifies SHA-256 `85d14fac6bb5975e59c9ada00b28c669b978f0ee6d759e83043a6767b4814d10` before printing it.
>
> Catalog validation: **Passed**. Hosted availability is determined by Archal's live certification and admission system, not this static page.

## Use custom state

Start from a sample when possible. For custom state, inspect the contract with `archal environment describe clickup`, then validate the file before creating a sandbox:

```bash theme={null}
archal state validate clickup state.json
```

Loading state replaces the current collections and establishes a new reset baseline. See [Starting state](https://docs.archal.ai/sandboxes/starting-state.md) before replacing state in an existing sandbox.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.