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": "john@example.com" } }]
  }]
}

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}]}'

Step 4: Create Your First Task

LIST_ID="900100200300"
curl -s -X POST "https://api.clickup.com/api/v2/list/${LIST_ID}/task" \
  -H "Authorization: $CLICKUP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hello from the ClickUp API!",
    "description": "Created via API v2",
    "priority": 3,
    "status": "to do"
  }' | jq '{id, name, url}'

// TypeScript equivalent
async function createFirstTask(listId: string) {
  const task = await clickupRequest(`/list/${listId}/task`, {
    method: 'POST',
    body: JSON.stringify({
      name: 'Hello from the ClickUp API!',
      description: 'Created via API v2',
      priority: 3,         // 1=Urgent, 2=High, 3=Normal, 4=Low
      status: 'to do',
      assignees: [123456], // user IDs (optional)
      due_date: Date.now() + 86400000, // tomorrow (Unix ms)
      due_date_time: true,
    }),
  });

  console.log(`Task created: ${task.name} (${task.id})`);
  console.log(`URL: ${task.url}`);
  return task;
}

Create Task Response Shape

{
  "id": "abc123",
  "custom_id": null,
  "name": "Hello from the ClickUp API!",
  "status": { "status": "to do", "color": "#d3d3d3", "type": "open" },
  "priority": { "id": "3", "priority": "normal", "color": "#6fddff" },
  "date_created": "1695000000000",
  "date_updated": "1695000000000",
  "due_date": "1695086400000",
  "url": "https://app.clickup.com/t/abc123",
  "list": { "id": "900100200300", "name": "My List" },
  "folder": { "id": "456", "name": "My Folder" },
  "space": { "id": "12345678" }
}

Error Handling

Error	Cause	Solution
401 Unauthorized	Missing/invalid token	Check `CLICKUP_API_TOKEN`
404 Not Found	Invalid list_id/team_id	Verify IDs via GET /team
400 Bad Request	Missing `name` field	Task name is required
429 Rate Limited	Too many requests	Wait for `X-RateLimit-Reset`

Instructions

Use a dedicated staging list and scoped token, resolve the target list ID, then create one clearly labeled test task. Re-read the returned task to verify its list and status, and delete or close the test according to the environment policy. Do not use a personal production token or create test tasks in a shared operational list.

Output

Return a redacted operation receipt with the target environment/list, task ID, observed status, token owner reference, and cleanup decision. Do not log the token, full task body, comments, attachments, or unneeded assignee data.

Examples

Create a single task named integration-smoke-test in an isolated staging list, confirm the API response and follow-up GET agree, then delete it. If the ID is unknown or authorization fails, stop and repair scope rather than trying another workspace or privileged credential.

Resources

Next Steps

Proceed to clickup-core-workflow-a for workspace/space/task management patterns.