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
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"
curl -s "https://api.clickup.com/api/v2/space/${SPACE_ID}/list" \
-H "Authorization: $CLICKUP_API_TOKEN" | jq '.lists[] | {id, name}'
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}'
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,
status: 'to do',
assignees: [123456],
due_date: Date.now() + 86400000,
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"
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 |
Resources
Next Steps
Proceed to clickup-core-workflow-a for workspace/space/task management patterns.
