How to Integrate Bolt.new with Trello

Trello uses a two-part authentication system: an API key that identifies your developer application, and a token that grants access to your specific account data. Both are needed for every API call. To get your API key, navigate to trello.com/app-key while logged into Trello. You will see your personal API key on this page — it is a 32-character alphanumeric string. This key is tied to your Trello account and persists until you regenerate it. To generate a token, click the 'Generate a Token' link on the same trello.com/app-key page. Trello will ask you to authorize the application and choose an expiration time. For personal automation tools, select '30 days' or 'Never expires'. After clicking Allow, you will see a 64-character token string — copy it immediately as this is the only time it is shown. Unlike most modern APIs that use OAuth 2.0 Bearer tokens, Trello passes both the key and token as URL query parameters on every request. This means every API URL looks like: https://api.trello.com/1/boards/{id}?key={apiKey}&token={token}. This is convenient but requires extra care: never construct Trello API URLs in client-side React components, since the key and token would be visible in browser network tabs. Always call Trello through your server-side Next.js API routes. Because the board ID is just a public identifier (not a credential), you can safely store it as a NEXT_PUBLIC_ variable if needed, but for consistency keep all Trello-related configuration in server-side .env variables.

1// .env.local
2TRELLO_API_KEY=your_32_char_api_key
3TRELLO_TOKEN=your_64_char_token
4TRELLO_BOARD_ID=your_board_id_from_url

Trello's API is organized around three main resources: boards, lists, and cards. To build a board view, you need data from all three levels. The most efficient approach is to fetch all lists and their cards in a single API call using Trello's nested resource pattern — append /lists?cards=open to any board endpoint to get all lists with their cards embedded in the response. The board endpoint GET /1/boards/{boardId} accepts a fields parameter to limit which board properties are returned. For lists and cards, GET /1/boards/{boardId}/lists?cards=open returns all lists with each list containing a cards array. Card objects include: id, name, desc (description), due, dueComplete (boolean), labels (array of label objects with name and color), members (array of member IDs), idList (the list this card belongs to), url (link to card in Trello), pos (position within the list), and closed (archived status). Trello label colors are standard names: green, yellow, orange, red, purple, blue, sky, lime, pink, black. Labels also have a name property that you set in the Trello board settings. Use these to build color-coded UI elements in your React components. For member avatars, you need a separate call to GET /1/boards/{boardId}/members to get member details including avatarHash. The avatar URL pattern is: https://trello-members.s3.amazonaws.com/{memberId}/{avatarHash}/50.png. Since avatars require a separate API call and count against rate limits, cache them after the first fetch. All these API calls are outbound HTTP requests that work perfectly in Bolt's WebContainer preview. You can see your Trello boards rendered in your Bolt app without deploying.

1// app/api/trello/board-data/route.ts
2import { NextResponse } from 'next/server';
3
4const TRELLO_API = 'https://api.trello.com/1';
5const KEY = process.env.TRELLO_API_KEY;
6const TOKEN = process.env.TRELLO_TOKEN;
7const BOARD_ID = process.env.TRELLO_BOARD_ID;
8
9function trelloParams(extra: Record<string, string> = {}) {
10  return new URLSearchParams({ key: KEY!, token: TOKEN!, ...extra }).toString();
11}
12
13export async function GET() {
14  try {
15    const [boardRes, listsRes, membersRes] = await Promise.all([
16      fetch(`${TRELLO_API}/boards/${BOARD_ID}?${trelloParams({ fields: 'name,id,url' })}` ),
17      fetch(`${TRELLO_API}/boards/${BOARD_ID}/lists?${trelloParams({ cards: 'open', card_fields: 'name,desc,due,dueComplete,labels,idMembers,pos,url' })}` ),
18      fetch(`${TRELLO_API}/boards/${BOARD_ID}/members?${trelloParams({ fields: 'fullName,avatarHash,id' })}` ),
19    ]);
20
21    if (!boardRes.ok || !listsRes.ok || !membersRes.ok) {
22      throw new Error('Trello API error');
23    }
24
25    const [board, lists, members] = await Promise.all([
26      boardRes.json(),
27      listsRes.json(),
28      membersRes.json(),
29    ]);
30
31    // Sort lists by position
32    lists.sort((a: { pos: number }, b: { pos: number }) => a.pos - b.pos);
33
34    return NextResponse.json({ board, lists, members });
35  } catch (error) {
36    return NextResponse.json(
37      { error: error instanceof Error ? error.message : 'Unknown error' },
38      { status: 500 }
39    );
40  }
41}

Creating a Trello card requires a POST to /1/cards with at minimum the idList field (the list to create the card in). Optional fields: name (card title), desc (description text, supports Markdown), due (ISO 8601 datetime string for due dates), idLabels (array of label IDs from the board), idMembers (array of member IDs to assign), pos (position: 'top', 'bottom', or a positive float for specific positioning). To get label IDs for your board (needed when creating cards with specific labels), call GET /1/boards/{boardId}/labels. Each label has an id, name, and color. Store these IDs — they are stable and you can hardcode them after fetching once. Moving a card between lists uses PUT /1/cards/{cardId} with the idList field set to the destination list ID. You can also update card name, description, due date, and completion status in the same PUT call by including those fields. Archiving (not permanently deleting) a card uses PUT /1/cards/{cardId} with closed: true. This is the Trello equivalent of soft-delete — the card still exists and can be unarchived. Permanent deletion uses DELETE /1/cards/{cardId} and cannot be undone. For adding comments to cards, POST to /1/cards/{cardId}/actions/comments with a text field. Comments are visible in the card's activity feed in Trello. All these mutation operations work from Bolt's WebContainer since they are outbound HTTP requests. Only Trello webhooks — where Trello pushes card change events to your server URL — require a deployed application. For apps that only need to read and write data to Trello (not receive real-time push notifications), no deployment is required for a fully functional integration.

1// app/api/trello/cards/create/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3
4const TRELLO_API = 'https://api.trello.com/1';
5const KEY = process.env.TRELLO_API_KEY;
6const TOKEN = process.env.TRELLO_TOKEN;
7
8export async function POST(request: NextRequest) {
9  const { idList, name, desc, due, idLabels, idMembers } = await request.json();
10
11  if (!idList || !name) {
12    return NextResponse.json(
13      { error: 'idList and name are required' },
14      { status: 400 }
15    );
16  }
17
18  const params = new URLSearchParams({
19    key: KEY!,
20    token: TOKEN!,
21    idList,
22    name,
23    pos: 'bottom',
24  });
25
26  if (desc) params.set('desc', desc);
27  if (due) params.set('due', new Date(due).toISOString());
28  if (idLabels?.length) params.set('idLabels', idLabels.join(','));
29  if (idMembers?.length) params.set('idMembers', idMembers.join(','));
30
31  const response = await fetch(`${TRELLO_API}/cards`, {
32    method: 'POST',
33    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
34    body: params.toString(),
35  });
36
37  if (!response.ok) {
38    const error = await response.json();
39    return NextResponse.json({ error }, { status: response.status });
40  }
41
42  const card = await response.json();
43  return NextResponse.json({ id: card.id, name: card.name, url: card.url, shortUrl: card.shortUrl });
44}

While polling every 30-60 seconds is adequate for most Trello dashboard use cases, webhooks give you real-time updates when cards move, get created, or are modified — essential for apps where multiple people are working on the same board simultaneously. Trello webhooks work differently from most services: instead of registering a webhook URL through a web interface, you create webhooks via the Trello API itself. Send a POST to https://api.trello.com/1/webhooks/ with your API key and token as query parameters, and a JSON body containing callbackURL (your webhook endpoint URL), idModel (the board, list, or card ID to watch), and description. Deploy your Bolt app first using the Publish button or Bolt's Netlify integration. After deployment, your app has a stable public URL. Create the Trello webhook by calling your own webhook registration API route, which internally calls the Trello API with your deployed callback URL. The webhook payload Trello sends contains an action object describing what changed: action.type (like updateCard, createCard, moveCardToList), action.data (the full change data including old and new values), action.memberCreator (who made the change), and the board, list, and card objects involved. Trello expects a 200 response within 30 seconds — acknowledge immediately and process asynchronously if needed. Trello also sends a HEAD request to your webhook URL to verify it exists before activating the webhook. Your handler must respond to HEAD requests with 200 as well — Next.js does this automatically if you only define a POST export in the route file, since unhandled methods return 405, not 200. Add an explicit HEAD handler that returns 200 to ensure webhook registration succeeds. Note that Bolt's WebContainer development environment cannot receive inbound webhook requests since it runs inside the browser and has no public URL. Test webhooks after deploying to Netlify or Vercel.

1// app/api/trello/webhook/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3
4// HEAD request: required for Trello webhook verification
5export async function HEAD() {
6  return new NextResponse(null, { status: 200 });
7}
8
9export async function POST(request: NextRequest) {
10  const payload = await request.json();
11  const { action } = payload;
12
13  if (!action) {
14    return NextResponse.json({ received: true });
15  }
16
17  const { type, data } = action;
18
19  switch (type) {
20    case 'createCard':
21      console.log(`New card created: "${data.card.name}" in list "${data.list.name}"`);
22      break;
23    case 'updateCard':
24      if (data.listAfter) {
25        console.log(`Card "${data.card.name}" moved from "${data.listBefore.name}" to "${data.listAfter.name}"`);
26      }
27      break;
28    case 'commentCard':
29      console.log(`Comment added to "${data.card.name}": ${data.text}`);
30      break;
31    default:
32      break;
33  }
34
35  return NextResponse.json({ received: true });
36}