clickup

# ClickUp Access the ClickUp API with managed OAuth authentication. Manage tasks, lists, folders, spaces, workspaces, users, and webhooks for work management. ## Quick Start ```bash # List workspaces (teams) python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/clickup/api/v2/team') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ## Base URL ``` https://gateway.maton.ai/clickup/{native-api-path} ``` Replace `{native-api-path}` with the actual ClickUp API endpoint path. The gateway proxies requests to `api.clickup.com` and automatically injects your OAuth token. ## Authentication All requests require the Maton API key in the Authorization header: ``` Authorization: Bearer $MATON_API_KEY ``` **Environment Variable:** Set your API key as `MATON_API_KEY`: ```bash export MATON_API_KEY="YOUR_API_KEY" ``` ### Getting Your API Key 1. Sign in or create an account at [maton.ai](https://maton.ai) 2. Go to [maton.ai/settings](https://maton.ai/settings) 3. Copy your API key ## Connection Management Manage your ClickUp OAuth connections at `https://ctrl.maton.ai`. ### List Connections ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=clickup&status=ACTIVE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Create Connection ```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'clickup'}).encode() req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Get Connection ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` **Response:** ```json { "connection": { "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80", "status": "ACTIVE", "creation_time": "2025-12-08T07:20:53.488460Z", "last_updated_time": "2026-01-31T20:03:32.593153Z", "url": "https://connect.maton.ai/?session_token=...", "app": "clickup", "metadata": {} } } ``` Open the returned `url` in a browser to complete OAuth authorization. ### Delete Connection ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Specifying Connection If you have multiple ClickUp connections, specify which one to use with the `Maton-Connection` header: ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/clickup/api/v2/team') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` If omitted, the gateway uses the default (oldest) active connection. ## ClickUp Hierarchy ClickUp organizes data in a hierarchy: - **Workspace** (team) → **Space** → **Folder** → **List** → **Task** Note: In the API, Workspaces are referred to as "teams". ## API Reference ### Workspaces (Teams) #### Get Authorized Workspaces ```bash GET /clickup/api/v2/team ``` **Example:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/clickup/api/v2/team') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` **Response:** ```json { "teams": [ { "id": "1234567", "name": "Acme Corp", "color": "#7B68EE", "avatar": null, "members": [ { "user": { "id": 123, "username": "Alice Johnson", "email": "alice@acme.com" } } ] } ] } ``` ### Spaces #### Get Spaces ```bash GET /clickup/api/v2/team/{team_id}/space ``` Query parameters: - `archived` - Include archived spaces (true/false) **Example:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/clickup/api/v2/team/1234567/space') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` **Response:** ```json { "spaces": [ { "id": "90120001", "name": "Engineering", "private": false, "statuses": [ {"status": "to do", "type": "open"}, {"status": "in progress", "type": "custom"}, {"status": "done", "type": "closed"} ] } ] } ``` #### Get a Space ```bash GET /clickup/api/v2/space/{space_id} ``` #### Create a Space ```bash POST /clickup/api/v2/team/{team_id}/space ``` **Example:** ```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'name': 'New Space', 'multiple_assignees': True, 'features': {'due_dates': {'enabled': True}, 'time_tracking': {'enabled': True}}}).encode() req = urllib.request.Request('https://gateway.maton.ai/clickup/api/v2/team/1234567/space', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` #### Update a Space ```bash PUT /clickup/api/v2/space/{space_id} ``` #### Delete a Space ```bash DELETE /clickup/api/v2/space/{space_id} ``` ### Folders #### Get Folders ```bash GET /clickup/api/v2/space/{space_id}/folder ``` Query parameters: - `archived` - Include archived folders (true/false) **Example:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/clickup/api/v2/space/90120001/folder') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` **Response:** ```json { "folders": [ { "id": "456789", "name": "Sprint 1", "orderindex": 0, "hidden": false, "space": {"id": "90120001", "name": "Engineering"}, "task_count": "12", "lists": [] } ] } ``` #### Get a Folder ```bash GET /clickup/api/v2/folder/{folder_id} ``` #### Create a Folder ```bash POST /clickup/api/v2/space/{space_id}/folder ``` **Example:** ```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'name': 'New Folder'}).encode() req = urllib.request.Request('https://gateway.maton.ai/clickup/api/v2/space/90120001/folder', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` #### Update a Folder ```bash PUT /clickup/api/v2/folder/{folder_id} ``` #### Delete a Folder ```bash DELETE /clickup/api/v2/folder/{folder_id} ``` ### Lists #### Get Lists ```bash GET /clickup/api/v2/folder/{folder_id}/list ``` Query parameters: - `archived` - Include archived lists (true/false) **Example:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/clickup/api/v2/folder/456789/list') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')