Skills Development ClickUp API v2 Getting Started Guide

ClickUp API v2 Getting Started Guide

v20260423
clickup-hello-world
This guide provides a comprehensive walkthrough for starting with the ClickUp API v2. It details the platform's core data hierarchy (Workspace > Space > Folder > List > Task) and demonstrates the fundamental API calls required for integration setup. Users will learn how to list workspaces, retrieve spaces, and successfully create a new task using both cURL and TypeScript examples. It is ideal for developers beginning a new ClickUp integration or requiring basic API testing.
Get Skill
70 downloads
Overview

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

ErrorCauseSolution
401 UnauthorizedMissing/invalid tokenCheck CLICKUP_API_TOKEN
404 Not FoundInvalid listid/teamidVerify IDs via GET /team
400 Bad RequestMissing name fieldTask name is required
429 Rate LimitedToo many requestsWait for X-RateLimit-Reset

Resources

Next Steps

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

Info
Category Development
Name clickup-hello-world
Version v20260423
Size 4.64KB
Updated At 2026-04-28
Language