How to Integrate ClickUp with V0

ClickUp uses a personal API token for authentication. You need this token plus the ID of the list (or space) you want to query before writing any code. To get your personal API token, go to ClickUp and click your profile avatar in the bottom-left corner. Select 'My Settings' from the menu. Scroll down to the 'Apps' section and click 'Generate' next to 'API Token'. If you have already generated a token before, it will be displayed there. Copy this token — it looks like a long alphanumeric string starting with 'pk_'. Keep it confidential: anyone with this token can access your entire ClickUp workspace. To find your List ID, navigate to the ClickUp list that contains the tasks you want to display. Click the three-dot menu (ellipsis) icon next to the list name in the sidebar. Select 'Copy link'. The link will look like https://app.clickup.com/XXXXXXXX/v/li/YYYYYYYYY — the numbers after '/li/' are your List ID. Alternatively, open your ClickUp list and look at the URL in the browser — the list ID appears in the URL path. If you want to fetch tasks across an entire space rather than a single list, you can find the Space ID similarly. Right-click on a space name in the sidebar, select 'Copy link', and extract the ID from the URL. Note: ClickUp also supports OAuth2 for multi-user applications where each user connects their own ClickUp account. For single-workspace dashboards where you control the data, a personal API token is simpler and perfectly appropriate.

Store your ClickUp API token and list configuration in Vercel's environment variables so your Next.js API route can access them securely without exposing them in your code. Go to your Vercel Dashboard, open your project, click the 'Settings' tab, and select 'Environment Variables' from the left sidebar. Add the following variables: CLICKUP_API_TOKEN: Set this to your personal API token (starts with 'pk_'). This is a secret — add it for Production, Preview, and Development environments. Never add a NEXT_PUBLIC_ prefix to this variable, which would expose it in the browser JavaScript bundle. CLICKUP_LIST_ID: Set this to your ClickUp List ID (the numeric string from your list URL). This identifies which list's tasks to fetch. If you need multiple lists, you can add CLICKUP_LIST_ID_2 etc., or make the list ID a query parameter from the frontend. Click Save for each variable. After saving, trigger a redeployment to make the variables available in your deployed serverless functions. For local development, create a .env.local file in your project root containing the same variables. The V0-generated .gitignore already excludes .env.local from Git, so your credentials stay safe. You can use 'vercel env pull .env.local' from the Vercel CLI to automatically sync development-scoped variables from your Vercel project.

1# .env.local — local development only, excluded from Git
2CLICKUP_API_TOKEN=pk_XXXXXXXXXXXXXXXXXXXXXXXXXXX
3CLICKUP_LIST_ID=900XXXXXXXXX

Create the Next.js API route that fetches tasks from ClickUp. This file runs server-side on Vercel, can safely access your environment variables, and returns cleaned task data to your React components. Create the file app/api/clickup/tasks/route.ts. The ClickUp REST API endpoint for fetching tasks in a list is: https://api.clickup.com/api/v2/list/{listId}/task. Authentication uses the Authorization header with your API token directly as the value (no 'Bearer' prefix — this is specific to ClickUp's API design). The ClickUp tasks API supports several query parameters that are useful for dashboards: subtasks (include subtasks in results), include_closed (whether to include tasks in closed status), due_date_gt and due_date_lt for date filtering (ClickUp uses Unix timestamp in milliseconds), assignees[] to filter by specific user IDs, statuses[] to filter by status names, and page for pagination (0-indexed). ClickUp returns tasks with rich metadata including id, name, description, status (with color and type), priority (with id, priority, color, orderindex), assignees (array of user objects), due_date (Unix timestamp in milliseconds), time_estimate, tags, and custom_fields. The route should transform this into a flatter structure that is easier for React components to render. Pagination in ClickUp works via a page parameter (default page size is 100). Check the last_page boolean in the response to know if there are more pages. For most dashboard use cases, the first 100 tasks are sufficient.

1import { NextRequest, NextResponse } from 'next/server';
2
3interface ClickUpStatus {
4  status: string;
5  color: string;
6  type: string;
7}
8
9interface ClickUpPriority {
10  id: string;
11  priority: string;
12  color: string;
13  orderindex: string;
14}
15
16interface ClickUpAssignee {
17  id: number;
18  username: string;
19  email: string;
20  profilePicture: string | null;
21}
22
23interface ClickUpTask {
24  id: string;
25  name: string;
26  description: string;
27  status: ClickUpStatus;
28  priority: ClickUpPriority | null;
29  assignees: ClickUpAssignee[];
30  due_date: string | null;
31  tags: { name: string; tag_fg: string; tag_bg: string }[];
32  url: string;
33}
34
35interface ClickUpResponse {
36  tasks: ClickUpTask[];
37  last_page: boolean;
38}
39
40export async function GET(request: NextRequest) {
41  const apiToken = process.env.CLICKUP_API_TOKEN;
42  const listId = process.env.CLICKUP_LIST_ID;
43
44  if (!apiToken || !listId) {
45    return NextResponse.json(
46      { error: 'ClickUp configuration missing' },
47      { status: 500 }
48    );
49  }
50
51  const { searchParams } = new URL(request.url);
52  const statusFilter = searchParams.get('status');
53  const includeClosed = searchParams.get('include_closed') === 'true';
54
55  const clickupUrl = new URL(
56    `https://api.clickup.com/api/v2/list/${listId}/task`
57  );
58  clickupUrl.searchParams.set('include_closed', String(includeClosed));
59  clickupUrl.searchParams.set('subtasks', 'true');
60  if (statusFilter) {
61    clickupUrl.searchParams.set('statuses[]', statusFilter);
62  }
63
64  try {
65    const response = await fetch(clickupUrl.toString(), {
66      headers: {
67        Authorization: apiToken,
68        'Content-Type': 'application/json',
69      },
70      next: { revalidate: 60 },
71    });
72
73    if (!response.ok) {
74      const error = await response.text();
75      console.error('ClickUp API error:', error);
76      return NextResponse.json(
77        { error: `ClickUp returned ${response.status}` },
78        { status: response.status }
79      );
80    }
81
82    const data: ClickUpResponse = await response.json();
83
84    const tasks = data.tasks.map((task) => ({
85      id: task.id,
86      name: task.name,
87      description: task.description || '',
88      status: {
89        name: task.status.status,
90        color: task.status.color,
91        type: task.status.type,
92      },
93      priority: task.priority
94        ? {
95            label: task.priority.priority,
96            color: task.priority.color,
97          }
98        : null,
99      assignees: task.assignees.map((a) => ({
100        id: a.id,
101        username: a.username,
102        email: a.email,
103        avatar: a.profilePicture,
104      })),
105      dueDate: task.due_date
106        ? new Date(parseInt(task.due_date)).toISOString()
107        : null,
108      tags: task.tags.map((t) => t.name),
109      url: task.url,
110    }));
111
112    return NextResponse.json({ tasks, total: tasks.length });
113  } catch (error) {
114    console.error('Failed to fetch ClickUp tasks:', error);
115    return NextResponse.json(
116      { error: 'Failed to fetch tasks' },
117      { status: 500 }
118    );
119  }
120}

With the API route in place, prompt V0 to generate the React components that display your ClickUp data. The most effective V0 prompts for project management interfaces specify the exact data fields available and the visual layout you want. Before prompting V0, test your API route by navigating to /api/clickup/tasks in your browser after deploying, or by running the project locally. Note the exact shape of the data returned — especially the status names and priority labels your ClickUp workspace uses. These will vary by workspace (e.g., your statuses might be 'Backlog', 'In Review', 'Complete' rather than generic names). Describe the UI layout explicitly in your V0 prompt. For a kanban board, specify the column names (matching your ClickUp status names) and how cards should look. For a list view, specify the columns and any sorting or filtering controls. For a dashboard, describe the summary metrics you want at the top (total tasks, overdue count, completion percentage) and the detailed task list below. Ask V0 to handle the async data fetching pattern — a loading skeleton state while the fetch is pending, an error state with a retry button, and an empty state for when the tasks array is empty. These three states are essential for a polished component. If you want tasks to automatically refresh without a page reload, ask V0 to add polling using setInterval inside a useEffect hook. A 30-second refresh interval is reasonable for most dashboards.

A read-only dashboard is useful, but many teams also want to create tasks directly from their custom app without switching to ClickUp. Add a POST handler to create new ClickUp tasks from a V0 form component. Create app/api/clickup/tasks/route.ts (or add a POST handler to the existing file). The ClickUp API endpoint for creating a task in a list is POST https://api.clickup.com/api/v2/list/{listId}/task with a JSON body. Required fields are name (task name) and optionally description, priority (1=urgent, 2=high, 3=normal, 4=low as integers), due_date (Unix timestamp in milliseconds), assignees (array of user IDs), and tags (array of tag name strings). V0 can generate a task creation modal or drawer that the user opens by clicking an 'Add Task' button. The form collects the task name (required), description (optional text area), priority (dropdown with Urgent/High/Normal/Low), due date (date picker), and optionally assignee. On form submission, the component POSTs to your /api/clickup/tasks endpoint, which creates the task in ClickUp and returns the created task object. After creating a task, the component should refetch the task list to show the new task immediately. Ask V0 to invalidate the task list cache after a successful creation so the UI stays in sync with ClickUp. For teams that use ClickUp heavily and want deep two-way sync with custom approval workflows or automated status transitions, RapidDev's team can help design a more sophisticated integration using ClickUp webhooks to push real-time updates to your Vercel app.

1// Add POST handler to app/api/clickup/tasks/route.ts
2export async function POST(request: NextRequest) {
3  const apiToken = process.env.CLICKUP_API_TOKEN;
4  const listId = process.env.CLICKUP_LIST_ID;
5
6  if (!apiToken || !listId) {
7    return NextResponse.json(
8      { error: 'ClickUp configuration missing' },
9      { status: 500 }
10    );
11  }
12
13  let body: {
14    name: string;
15    description?: string;
16    priority?: number;
17    dueDate?: string;
18  };
19
20  try {
21    body = await request.json();
22  } catch {
23    return NextResponse.json({ error: 'Invalid request body' }, { status: 400 });
24  }
25
26  if (!body.name || body.name.trim().length === 0) {
27    return NextResponse.json({ error: 'Task name is required' }, { status: 400 });
28  }
29
30  const clickupPayload: Record<string, unknown> = {
31    name: body.name.trim(),
32  };
33
34  if (body.description) clickupPayload.description = body.description;
35  if (body.priority) clickupPayload.priority = body.priority;
36  if (body.dueDate) {
37    clickupPayload.due_date = new Date(body.dueDate).getTime();
38  }
39
40  try {
41    const response = await fetch(
42      `https://api.clickup.com/api/v2/list/${listId}/task`,
43      {
44        method: 'POST',
45        headers: {
46          Authorization: apiToken,
47          'Content-Type': 'application/json',
48        },
49        body: JSON.stringify(clickupPayload),
50      }
51    );
52
53    if (!response.ok) {
54      const error = await response.text();
55      console.error('ClickUp create error:', error);
56      return NextResponse.json(
57        { error: 'Failed to create task' },
58        { status: response.status }
59      );
60    }
61
62    const task = await response.json();
63    return NextResponse.json({ success: true, taskId: task.id });
64  } catch (error) {
65    console.error('ClickUp task creation failed:', error);
66    return NextResponse.json(
67      { error: 'Failed to create task' },
68      { status: 500 }
69    );
70  }
71}