ClickUp ExecModule

Overview

ClickUpModule connects ValkyrAI workflows to ClickUp API v2 through the native map I/O ExecModule ABI. Workflow Studio discovers it as ClickUpModule; personal and OAuth access tokens are resolved only from an encrypted IntegrationAccount.

The first production operation set covers hierarchy discovery, task work, and comments:

• list_workspaces, list_spaces, list_folders, list_lists
• list_tasks, get_task, create_task, update_task, delete_task
• list_comments, add_comment

Task lists use ClickUp's zero-based, 100-task pagination. Provider responses and errors are bounded and redacted. Only reads can retry automatically; creates, updates, comments, and deletion run once so an ambiguous timeout cannot repeat a mutation.

Usage

1. Create a dedicated ClickUp automation identity or OAuth application.
2. Authorize only the Workspaces that the workflow needs.
3. Store the personal token or OAuth access token in the encrypted apiKey field of an IntegrationAccount.
4. Bind the account through ExecModuleConfig.authConfig.integrationAccount.
5. Add ClickUpModule to a workflow, discover the hierarchy, then use returned IDs in task operations.

Workflow input may provide resource IDs, bounded task fields, filters, pagination controls, and destructive confirmation. It cannot provide credentials or redirect requests away from the trusted ClickUp API endpoint.

Inputs

Name	Type	Requirement	Default	Description	Constraints
operation	string	Required	None	Operation to execute.	One of the eleven operations above.
workspaceId	string	list_spaces	None	ClickUp Workspace ID.	1–128 letters, digits, _, or -.
spaceId	string	list_folders	None	ClickUp Space ID.	Same bounded ID rule.
folderId	string	list_lists	None	ClickUp Folder ID.	Same bounded ID rule.
listId	string	Task list/create	None	ClickUp List ID.	Same bounded ID rule.
taskId	string	Task/comment operations	None	ClickUp task ID.	Same bounded ID rule.
name	string	Required for create	None	Task name.	1–2,000 characters for creation.
description	string	Optional	None	Plain-text task description.	Maximum 64,000 characters; mutually exclusive with markdownContent.
markdownContent	string	Optional	None	Markdown task description.	Maximum 64,000 characters; maps to markdown_content.
task	object or JSON string	Optional	None	Additional ClickUp task fields.	256 KiB cap; allowlisted fields only.
commentText	string	add_comment	None	Plain-text task comment.	1–15,000 characters.
archived	boolean	Optional list filter	false	Include archived objects.	Applied only to relevant reads.
includeClosed	boolean	Optional task filter	false	Include closed tasks.	Maps to include_closed.
includeSubtasks	boolean	Optional task filter	false	Include subtasks.	Maps to subtasks.
page	integer	Optional	0	First zero-based task page.	0–100,000.
limit	integer	Optional	100	Maximum returned items.	1–10,000.
returnAll	boolean	Optional	false	Continue through task pages.	Safety-capped at 10,000 items.
notifyAll	boolean	Optional	false	Notify supported watchers.	Applied to task creation/comments when supplied.
requestId	string	Optional	None	Caller correlation value.	Maximum 128 characters; sent as X-Request-Id.
confirmDelete	boolean	delete_task	false	Permanent-delete acknowledgement.	Must be true before a request is sent.

The task object accepts only name, description, markdown_content, assignees, group_assignees, tags, status, priority, due_date, due_date_time, time_estimate, start_date, start_date_time, points, notify_all, parent, links_to, custom_fields, custom_item_id, check_required_custom_fields, archived, and watchers. Typed inputs override matching fields.

Outputs

Name	Type	When present	Description
status	string	Always	success or error.
operation	string	Always	Normalized operation name.
attempts	integer	Always	Total provider HTTP attempts.
httpStatus	integer	Provider responded	Last HTTP status.
data	object	Single-resource/mutation success	Provider resource or empty response object.
id / url	string	Provider returned them	Convenience resource fields.
items / count	array / integer	List success	Bounded resources and count.
hasMore / nextPage	boolean / integer	Task list success	Continuation state and next page.
requestId	string	Provider supplies one	Safe request trace reference.
error	object	Failure	Safe {code, message, httpStatus?, retryable} details.

Tokens and authorization headers never enter outputs. Provider messages pass through the shared workflow sensitive-data policy.

IntegrationAccount Requirements

Setting	Requirement
Provider	ClickUp personal token or ClickUp OAuth 2.0
Authentication	Authorization: <personal-or-OAuth-access-token>
accountName	Human-readable automation identity
apiKey	Preferred encrypted SecureField containing the access token
password	Legacy token fallback only; prefer apiKey
status	ready or unset legacy status; closed and error fail closed

Personal tokens inherit their user's accessible Workspaces. OAuth applications should request access only to the Workspaces needed by the workflow. ClickUp API v2 does not expose fine-grained OAuth scopes; Workspace selection and ClickUp permissions form the effective authorization boundary.

Configuration

{
  "version": "1.0.0",
  "authConfig": {
    "authStrategy": 1,
    "integrationAccount": "integration-account:clickup-release-ops"
  },
  "retryPolicy": {
    "maxAttempts": 3,
    "backoffStrategy": "EXPONENTIAL",
    "initialDelayMs": 1000,
    "maxDelayMs": 60000,
    "jitter": false
  },
  "executionConfig": {"timeoutMs": 30000},
  "payloadConfig": {
    "parameters": "{\"operation\":\"list_tasks\",\"listId\":\"901234567890\",\"limit\":100}"
  }
}

The integration-account value is symbolic. Persisted workflows use the generated relationship and never a plaintext token.

Operations

Operation	ClickUp behavior	Side effect
list_workspaces	Reads Workspaces authorized for the token.	Read-only; safe retries.
list_spaces	Lists Spaces in one Workspace.	Read-only; safe retries.
list_folders	Lists Folders in one Space.	Read-only; safe retries.
list_lists	Lists Lists in one Folder.	Read-only; safe retries.
list_tasks	Lists home-List tasks in 100-item pages.	Read-only; safe retries.
get_task	Reads one accessible task.	Read-only; safe retries.
create_task	Creates one bounded task in a List.	New task; single attempt.
update_task	Updates explicitly supplied task fields.	Mutation; single attempt.
delete_task	Permanently deletes a task.	Irreversible; confirmation required.
list_comments	Reads task comments.	Read-only; safe retries.
add_comment	Adds one plain-text task comment.	New comment; single attempt.

Errors and Failure Modes

Code	Typical cause	Retryable	Resolution
VALIDATION_ERROR	Missing/invalid ID, missing task name, unsupported field, conflicting descriptions, empty update, invalid JSON, or absent confirmation.	No	Correct input; no unsafe request was sent.
UNSUPPORTED_OPERATION	Unknown operation.	No	Select a documented operation.
INTEGRATION_ACCOUNT_REQUIRED	No bound account.	No	Bind a ClickUp IntegrationAccount.
INTEGRATION_ACCOUNT_NOT_READY	Account status is closed/error.	No	Repair or reconnect the account.
CLICKUP_HTTP_400	Provider validation failed.	No	Correct the bounded request.
CLICKUP_HTTP_401 / 403	Invalid token or inaccessible object.	No	Rotate credentials or grant minimum ClickUp access.
CLICKUP_HTTP_404	ID is wrong or hidden from the token.	No	Re-run hierarchy discovery with the same account.
CLICKUP_HTTP_429 / 5xx	Rate limit or transient provider failure.	Yes for reads	Honor provider reset headers; reconcile writes first.
NETWORK_ERROR	Timeout, DNS, TLS, or connectivity failure.	Yes for reads	Verify connectivity and inspect write state before retry.
RESPONSE_TOO_LARGE	Response exceeded 5 MiB.	No	Narrow scope or lower the limit.
INVALID_PROVIDER_RESPONSE	Expected array field was absent.	No	Use requestId and verify API compatibility.

Example

{
  "operation": "create_task",
  "listId": "901234567890",
  "name": "Verify public ClickUp ExecModule launch",
  "markdownContent": "Confirm documentation, article, image, and public READ grants.",
  "task": {
    "priority": 2,
    "tags": ["execmodule", "release"],
    "due_date": 1786665600000
  },
  "requestId": "clickup-launch-verification-20260808"
}

Expected result:

{
  "status": "success",
  "operation": "create_task",
  "attempts": 1,
  "httpStatus": 200,
  "id": "86abc123",
  "url": "https://app.clickup.com/t/86abc123",
  "data": {"id": "86abc123", "name": "Verify public ClickUp ExecModule launch"}
}

Notes

• Pagination: ClickUp returns at most 100 tasks per page. The module increments page until provider exhaustion, the requested limit, or 10,000 tasks. Reuse nextPage only with identical filters.
• Rate limits: ClickUp limits each token according to Workspace plan. Reads retry HTTP 408, 429, 500, 502, 503, and 504, honoring Retry-After or X-RateLimit-Reset. Writes never retry automatically.
• API limits: task payloads are allowlisted and capped at 256 KiB; provider responses are capped at 5 MiB.
• Idempotency: writes are single-attempt. Supply a durable requestId and reconcile task state before repeating an ambiguous write.
• Task lists: Get Tasks returns tasks whose home List matches listId; tasks added to multiple Lists may require future include_timl support.
• Custom fields: create accepts applicable custom_fields; updating an existing custom-field value requires ClickUp's separate Set Custom Field endpoint and is deferred.
• Destructive behavior: delete_task is permanent and requires confirmDelete=true. Prefer a status or archival update when available.
• Authentication: tokens stay in IntegrationAccount SecureFields and are redacted from errors and outputs.
• External verification: request construction, hierarchy discovery, task pagination, validation, redaction, retry safety, and metadata discovery are tested locally. Live ClickUp permissions require provider credentials and are deferred.
• Deferred operations: folder/list/goal/checklist mutations, dependencies, tags, time entries, task custom-field updates, attachments, triggers/webhooks, OAuth refresh, and arbitrary raw requests.
• Functional reference: n8n's ClickUp integration demonstrates task, hierarchy, checklist, comment, dependency, goal, and time-entry automation. This module implements its highest-value agentic semantics through ValkyrAI's native ABI against ClickUp API v2.