Integration Automation API

ClickUp mapping automation

Method	Endpoint	Purpose
GET	/api/v2/clickup/locations	Discover the caller’s connected ClickUp Spaces, Folders and Lists
GET	/api/v2/clickup/mappings	Read mappings within the caller’s permitted projects
PUT	/api/v2/clickup/mappings	Create or replace one versioned mapping

Keys need clickup:mappings:read or clickup:mappings:write. The bound identity also needs active internal membership and Administrator access or explicit ClickUp mapping delegation. A Manager must manage both the previous and new project when replacing a mapping. Scope is an upper bound, not an elevation of the person’s permissions.

Location discovery uses the caller’s own ClickUp grant and selected workspace. With no parameters it lists Spaces with Time Tracking enabled. space_id adds Folders and folderless Lists; folder_id additionally selects that Folder’s Lists and requires space_id. Unknown/repeated parameters are rejected.

Replace a mapping safely

PUT requires an Idempotency-Key and the strict body in OpenAPI. Required fields are locationType (SPACE, FOLDER or LIST), clickUpSpaceId, projectId, taskId, and expectedVersion. Folder/List mappings also identify their location. expectedVersion: 0 creates a mapping; replacing one requires the current version from GET. A stale version returns 409.

The Keito task must be active and belong to or be assigned to the selected project. Provider hierarchy and labels are checked through the caller’s connection. Manual mappings win over automatic mappings, with List → Folder → Space precedence; a disabled/archived override prevents fallback. The mapping operation does not create a project.

Use the identical key and body to recover an uncertain response. Current connection, grant, project and target authority are rechecked before replay. See ClickUp setup for the separate provider connection and workspace settings.