ClickUp Hello World

Overview

Walk through the ClickUp hierarchy and make your first API calls. ClickUp's data model: Workspace (called "team" in API v2) > Space > Folder (optional) > List > Task.

Prerequisites

• Completed clickup-install-auth setup
• Valid CLICKUP_API_TOKEN in environment

ClickUp Hierarchy

Workspace (team_id)        GET /api/v2/team
  └── Space (space_id)     GET /api/v2/team/{team_id}/space
       ├── List            GET /api/v2/space/{space_id}/list  (folderless lists)
       └── Folder          GET /api/v2/space/{space_id}/folder
            └── List       GET /api/v2/folder/{folder_id}/list
                 └── Task  GET /api/v2/list/{list_id}/task

Step 1: Discover Your Workspace

# Get authorized workspaces (returns team_id needed for all subsequent calls)
curl -s https://api.clickup.com/api/v2/team \
  -H "Authorization: $CLICKUP_API_TOKEN" | jq '.teams[] | {id, name}'

Response shape:

{
  "teams": [{
    "id": "1234567",
    "name": "My Workspace",
    "color": "#536cfe",
    "members": [{ "user": { "id": 123, "username": "john", "email": "[email protected]" } }]
  }]
}

Step 2: List Spaces

TEAM_ID="1234567"
curl -s "https://api.clickup.com/api/v2/team/${TEAM_ID}/space?archived=false" \
  -H "Authorization: $CLICKUP_API_TOKEN" | jq '.spaces[] | {id, name}'

Step 3: Get Lists in a Space

SPACE_ID="12345678"
# Folderless lists (directly in Space)
curl -s "https://api.clickup.com/api/v2/space/${SPACE_ID}/list" \
  -H "Authorization: $CLICKUP_API_TOKEN" | jq '.lists[] | {id, name}'

# Or lists inside folders
curl -s "https://api.clickup.com/api/v2/space/${SPACE_ID}/folder" \
  -H "Authorization: $CLICKUP_API_TOKEN" | jq '.folders[] | {id, name, lists: [.lists[] | {id, name}]}'