How to Integrate Bolt.new with ClickUp

ClickUp provides a personal API token that gives access to all your workspaces. To find it, log into ClickUp and go to Settings (bottom-left corner, click your avatar) → Apps → scroll down to the API Token section. Click Generate if you haven't yet, then copy the token. Store it immediately in a safe place — ClickUp only shows it once per generation, though you can regenerate it at any time. Next, find your workspace and list IDs. The easiest way is to look at the URL while browsing ClickUp. When you open a Space or List, the URL pattern is: app.clickup.com/{teamId}/v/li/{listId}. The teamId is your workspace ID (also called team ID in the ClickUp API). You can also fetch these programmatically: the ClickUp API endpoint GET /team returns all teams your token has access to, and from there you can traverse the hierarchy down to spaces and lists. Create a .env.local file in your Bolt project root with the values below. The VITE_* prefix is for client-side access in Vite projects — but for security, never expose your ClickUp API token client-side. Use process.env (no VITE_ prefix) only in server-side API routes. The CLICKUP_TEAM_ID and CLICKUP_LIST_ID values are safe to expose as they are just identifiers, not credentials.

1// .env.local
2CLICKUP_API_TOKEN=pk_your_personal_api_token_here
3CLICKUP_TEAM_ID=your_workspace_id
4CLICKUP_LIST_ID=your_default_list_id

The ClickUp API hierarchy is: Team (Workspace) → Spaces → Folders → Lists. Tasks live inside lists. To build any task view, you first need to know which lists exist. The API provides endpoints for each level: GET /team returns all workspaces, GET /team/{teamId}/space returns spaces in a workspace, GET /space/{spaceId}/folder returns folders, and GET /space/{spaceId}/list returns folderless lists. For most use cases, you need the list IDs up front to query tasks. Rather than traversing the full hierarchy on every page load, fetch the hierarchy once during app setup and store the list IDs in your app state or database. For a personal tool, you can even hardcode the list IDs you care about after finding them through a one-time API call. The API route below fetches all spaces and their lists in one operation by chaining the calls. It returns a simplified structure that is easy to render in a React dropdown or sidebar navigation. All ClickUp API calls use the same Authorization header format: the raw token string — not 'Bearer {token}', just the token itself. This is different from most other APIs.

1// app/api/clickup/spaces/route.ts
2import { NextResponse } from 'next/server';
3
4const CLICKUP_API = 'https://api.clickup.com/api/v2';
5const API_TOKEN = process.env.CLICKUP_API_TOKEN;
6const TEAM_ID = process.env.CLICKUP_TEAM_ID;
7
8type ClickUpList = { id: string; name: string; task_count: number };
9type ClickUpFolder = { id: string; name: string; lists: ClickUpList[] };
10type ClickUpSpace = { id: string; name: string; folders: ClickUpFolder[]; lists: ClickUpList[] };
11
12async function clickupFetch(path: string) {
13  const response = await fetch(`${CLICKUP_API}${path}`, {
14    headers: { Authorization: API_TOKEN! },
15  });
16  if (!response.ok) throw new Error(`ClickUp API error: ${response.status}`);
17  return response.json();
18}
19
20export async function GET() {
21  try {
22    const { spaces } = await clickupFetch(`/team/${TEAM_ID}/space?archived=false`);
23
24    const spacesWithLists: ClickUpSpace[] = await Promise.all(
25      spaces.map(async (space: { id: string; name: string }) => {
26        const [{ folders }, { lists: folderlessLists }] = await Promise.all([
27          clickupFetch(`/space/${space.id}/folder?archived=false`),
28          clickupFetch(`/space/${space.id}/list?archived=false`),
29        ]);
30        return { id: space.id, name: space.name, folders, lists: folderlessLists };
31      })
32    );
33
34    return NextResponse.json({ spaces: spacesWithLists });
35  } catch (error) {
36    return NextResponse.json(
37      { error: error instanceof Error ? error.message : 'Unknown error' },
38      { status: 500 }
39    );
40  }
41}

With list IDs available, you can fetch tasks from any list using GET /list/{listId}/task. The ClickUp task endpoint supports extensive query parameters for filtering: assignees (comma-separated user IDs), statuses (comma-separated status names), due_date_gt and due_date_lt (Unix timestamps in milliseconds for date range filtering), order_by (created, updated, or due_date), and reverse (true/false for sort direction). The task response includes all task fields: id, name, description, status, priority, due_date, assignees, tags, custom fields, and parent (for subtasks). Priority is returned as an object with priority (integer 1-4) and color fields. Status is an object with status (the name string) and type fields. Map these to your UI components accordingly. Pagination is handled through the page query parameter (0-indexed) with 100 tasks per page. Always check if the response indicates more pages are available (last_page field in the response) and implement a Load More button or automatic pagination for lists with more than 100 tasks. Because ClickUp API calls work fine as outbound requests from Bolt's WebContainer, you can build and test this entire task board in the Bolt preview without deploying. Incoming webhooks from ClickUp (for real-time task updates) require a deployed URL, but polling-based task fetching works in development.

1// app/api/clickup/tasks/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3
4const CLICKUP_API = 'https://api.clickup.com/api/v2';
5const API_TOKEN = process.env.CLICKUP_API_TOKEN;
6
7export async function GET(request: NextRequest) {
8  const { searchParams } = new URL(request.url);
9  const listId = searchParams.get('listId') ?? process.env.CLICKUP_LIST_ID;
10  const page = searchParams.get('page') ?? '0';
11  const orderBy = searchParams.get('order_by') ?? 'due_date';
12
13  const params = new URLSearchParams({
14    page,
15    order_by: orderBy,
16    subtasks: 'true',
17    include_closed: 'false',
18  });
19
20  const response = await fetch(
21    `${CLICKUP_API}/list/${listId}/task?${params.toString()}`,
22    { headers: { Authorization: API_TOKEN! } }
23  );
24
25  if (!response.ok) {
26    return NextResponse.json(
27      { error: `ClickUp returned ${response.status}` },
28      { status: response.status }
29    );
30  }
31
32  const data = await response.json();
33  return NextResponse.json({
34    tasks: data.tasks,
35    lastPage: data.last_page,
36  });
37}

Creating a task requires a POST to /list/{listId}/task with at minimum a name field. Optional fields include description (plain text or Markdown), status (must match an existing status name in the list), priority (1=urgent, 2=high, 3=normal, 4=low), assignees (array of user IDs), due_date (Unix timestamp in milliseconds), and tags (array of tag names). The task creation response includes the full task object with the newly assigned task ID. Updating an existing task uses PUT /task/{taskId} with the same field structure. Only include the fields you want to change — omitted fields are left unchanged. To update an assignee, use the special add or rem arrays inside the assignees object: { assignees: { add: [userId], rem: [] } }. Time tracking in ClickUp uses the Time Tracking API. To log time, POST to /task/{taskId}/time with a start (Unix ms), duration (in milliseconds), and optional description. To start a timer (live tracking), POST to /team/{teamId}/time_entries/start. Fetch time entries for a task with GET /task/{taskId}/time. These mutation endpoints all work from Bolt's WebContainer since they are outbound HTTP requests. No deployment is needed to test task creation and updates — only ClickUp webhook receipt (for real-time change notifications pushed FROM ClickUp) requires a deployed URL.

1// app/api/clickup/tasks/create/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3
4const CLICKUP_API = 'https://api.clickup.com/api/v2';
5const API_TOKEN = process.env.CLICKUP_API_TOKEN;
6const DEFAULT_LIST_ID = process.env.CLICKUP_LIST_ID;
7
8export async function POST(request: NextRequest) {
9  const { listId, name, description, priority, dueDate, assignees } = await request.json();
10
11  const taskBody: Record<string, unknown> = {
12    name,
13    description: description ?? '',
14    priority: priority ?? 3, // 1=urgent, 2=high, 3=normal, 4=low
15    assignees: assignees ?? [],
16  };
17
18  if (dueDate) {
19    taskBody.due_date = new Date(dueDate).getTime(); // Convert to Unix ms
20    taskBody.due_date_time = true;
21  }
22
23  const response = await fetch(
24    `${CLICKUP_API}/list/${listId ?? DEFAULT_LIST_ID}/task`,
25    {
26      method: 'POST',
27      headers: {
28        Authorization: API_TOKEN!,
29        'Content-Type': 'application/json',
30      },
31      body: JSON.stringify(taskBody),
32    }
33  );
34
35  if (!response.ok) {
36    const error = await response.json();
37    return NextResponse.json({ error }, { status: response.status });
38  }
39
40  const task = await response.json();
41  return NextResponse.json({ id: task.id, name: task.name, url: task.url });
42}
43
44// app/api/clickup/time/log/route.ts — log a time entry
45export async function logTime(taskId: string, durationHours: number, description: string) {
46  const durationMs = Math.round(durationHours * 3600 * 1000);
47  const start = Date.now() - durationMs;
48
49  return fetch(`${CLICKUP_API}/task/${taskId}/time`, {
50    method: 'POST',
51    headers: {
52      Authorization: API_TOKEN!,
53      'Content-Type': 'application/json',
54    },
55    body: JSON.stringify({ start, duration: durationMs, description }),
56  });
57}