How to Integrate Bolt.new with Monday.com

Monday.com authenticates API requests using a personal API token tied to your account. To get it, click your avatar (profile picture) in the bottom-left corner of Monday.com, then select 'Developers' from the menu. On the Developers page, click 'My Access Tokens' in the left sidebar. You will see your personal token — click 'Show' to reveal it and copy the full value. This token grants the same access as your account, so treat it like a password. For team projects, consider creating a dedicated service account in Monday.com and using its token instead of a personal account token, so API access does not break if the personal account is deactivated. Next, find the board ID you want to work with. Open the board in Monday.com and look at the URL — it looks like https://your-company.monday.com/boards/1234567890. The number after /boards/ is your board ID. Note this down — you will use it in GraphQL queries to scope requests to the correct board. If you need to discover board IDs programmatically, you can also query all accessible boards using { boards { id name } } in the Monday.com API playground at developer.monday.com. In your Bolt.new project, open the .env file in the project root and add both values. For Next.js API routes, use MONDAY_API_TOKEN without any prefix — this keeps the token server-side only and never exposes it in client bundles. Never prefix the token with NEXT_PUBLIC_, which would embed it in your JavaScript bundle and make it visible to anyone inspecting your deployed site. When deploying to Netlify or Vercel, add the same variables in the hosting dashboard's environment variable settings.

1# .env — add to project root, never commit to source control
2# Next.js: server-side only — do NOT use NEXT_PUBLIC_ prefix for the API token
3MONDAY_API_TOKEN=your_monday_api_token_here
4MONDAY_BOARD_ID=1234567890
5
6# If you need the board ID client-side (e.g. for display), you can expose it:
7NEXT_PUBLIC_MONDAY_BOARD_ID=1234567890

Monday.com uses GraphQL exclusively — every API call is a POST request to https://api.monday.com/v2 with a JSON body containing a query field (the GraphQL operation) and a variables field (any parameters). Bolt.new can generate a properly structured API route that handles this pattern and exposes a clean interface to your React components. In the Bolt chat, describe the data you need. Bolt will create a Next.js API route at app/api/monday/route.ts that reads MONDAY_API_TOKEN from environment variables, constructs the request to Monday.com's endpoint, and returns the response data to your React components. The Authorization header format for Monday.com is a plain Bearer token — include 'Authorization': `Bearer ${process.env.MONDAY_API_TOKEN}` in the request headers. Also add 'API-Version': '2024-01' to ensure consistent API behavior as Monday.com evolves its schema. One important difference from REST APIs: Monday.com always returns HTTP 200, even for errors. Error details are in the response body's errors array, not the HTTP status code. Your API route should check for this errors array and return a 400 status code if it is present, so your React components can handle API failures consistently. The route acts as a secure proxy — all GraphQL queries from the frontend pass through it, keeping your API token server-side and out of browser memory. Review the generated route code to confirm it passes the query and variables from the request body through to Monday.com without modification. This generic proxy pattern means you only need one API route to handle all Monday.com operations, rather than creating separate routes for boards, items, and mutations.

1// app/api/monday/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3
4const MONDAY_API_URL = 'https://api.monday.com/v2';
5
6interface MondayError {
7  message: string;
8}
9
10interface MondayApiResponse {
11  data?: Record<string, unknown>;
12  errors?: MondayError[];
13  error_message?: string;
14}
15
16export async function POST(request: NextRequest) {
17  const apiToken = process.env.MONDAY_API_TOKEN;
18
19  if (!apiToken) {
20    return NextResponse.json(
21      { error: 'MONDAY_API_TOKEN is not configured' },
22      { status: 500 }
23    );
24  }
25
26  const { query, variables } = await request.json();
27
28  const response = await fetch(MONDAY_API_URL, {
29    method: 'POST',
30    headers: {
31      'Content-Type': 'application/json',
32      'Authorization': `Bearer ${apiToken}`,
33      'API-Version': '2024-01',
34    },
35    body: JSON.stringify({ query, variables: variables ?? {} }),
36  });
37
38  const result: MondayApiResponse = await response.json();
39
40  // Monday.com returns HTTP 200 even for errors — check the errors array
41  if (result.errors && result.errors.length > 0) {
42    return NextResponse.json(
43      { error: result.errors[0].message, details: result.errors },
44      { status: 400 }
45    );
46  }
47
48  if (result.error_message) {
49    return NextResponse.json({ error: result.error_message }, { status: 400 });
50  }
51
52  return NextResponse.json(result.data ?? {});
53}

Monday.com's GraphQL schema centers around boards, items, columns, and column_values. The most common query pattern fetches items from a board including each item's name and the values for specific columns. Understanding the query structure is essential — Monday.com columns are identified by their column ID (a string like status, person, date, or a custom ID like text_1), not by display name. To find column IDs, open Board Settings in Monday.com and look for the Column IDs section, or run a discovery query that returns all columns for the board. The GraphQL response nests column values inside each item — each column value object has an id matching the column ID and a text property containing the human-readable value. For status columns, the text field returns the label like 'Done' or 'Working on it'. For people columns, the text field returns the assignee's name. For date columns, text returns the formatted date string. The raw value field is a JSON string with more detail, but text is sufficient for most display use cases. For creating or updating items, Monday.com uses GraphQL mutations. The create_item mutation takes a board ID, an optional group ID, an item name, and a column_values argument. The column_values argument must be a JSON-stringified string — it is not a nested object but a string containing JSON. Each column type expects a specific value format: status columns use { label: 'Done' }, text columns use the plain string value, date columns use { date: '2026-12-31' }, and people columns use { personsAndTeams: [{ id: userId, kind: 'person' }] }. Bolt generates these patterns correctly when you describe the operation and mention the column names and types. Note that Monday.com's API version 2023-10 and later replaced the items field with items_page for pagination support. If you see empty results, check that your query uses items_page(limit: 100) { items { ... } } rather than items { ... } directly.

1// lib/monday-queries.ts
2// Reusable GraphQL queries and mutations for Monday.com
3
4export const GET_BOARD_ITEMS = `
5  query GetBoardItems($boardId: ID!) {
6    boards(ids: [$boardId]) {
7      id
8      name
9      items_page(limit: 100) {
10        items {
11          id
12          name
13          state
14          column_values {
15            id
16            title
17            text
18            type
19            value
20          }
21          created_at
22          updated_at
23        }
24      }
25    }
26  }
27`;
28
29export const CREATE_ITEM = `
30  mutation CreateItem($boardId: ID!, $groupId: String, $itemName: String!, $columnValues: JSON) {
31    create_item(
32      board_id: $boardId
33      group_id: $groupId
34      item_name: $itemName
35      column_values: $columnValues
36    ) {
37      id
38      name
39      column_values {
40        id
41        text
42      }
43    }
44  }
45`;
46
47export const UPDATE_ITEM_COLUMN = `
48  mutation UpdateColumn($boardId: ID!, $itemId: ID!, $columnId: String!, $value: JSON!) {
49    change_column_value(
50      board_id: $boardId
51      item_id: $itemId
52      column_id: $columnId
53      value: $value
54    ) {
55      id
56      name
57    }
58  }
59`;
60
61// Helper to call the Monday.com API route
62export async function callMondayAPI(
63  query: string,
64  variables?: Record<string, unknown>
65): Promise<Record<string, unknown>> {
66  const response = await fetch('/api/monday', {
67    method: 'POST',
68    headers: { 'Content-Type': 'application/json' },
69    body: JSON.stringify({ query, variables }),
70  });
71
72  if (!response.ok) {
73    const error = await response.json().catch(() => ({ error: 'Unknown error' }));
74    throw new Error(error.error ?? `API error: ${response.status}`);
75  }
76
77  return response.json();
78}

Monday.com webhooks let your app receive real-time notifications when board events occur — an item is created, a status column changes, a due date is updated, or a new update comment is posted. During development in Bolt's WebContainer, these webhooks cannot be received because the preview runs inside a browser sandbox with no public URL for Monday.com to POST requests to. The WebContainer can make outbound calls but cannot receive incoming HTTP connections. Deploy your app to Netlify or Vercel first to get a stable public domain. Once deployed, create a webhook receiver route at app/api/monday/webhook/route.ts. Monday.com's webhook registration includes a required challenge verification step: when you register a webhook URL, Monday.com immediately sends a POST request containing a challenge field as a string. Your endpoint must respond with { challenge: 'the_same_value' } within a few seconds, or registration fails. After this handshake completes, Monday.com begins sending real event payloads to the same URL. Monday.com webhook event payloads include the event type, the board ID, the item ID, the item name, the column that changed, and the old and new values. The payload structure is { event: { type, boardId, itemId, itemName, columnId, columnTitle, value, previousValue } }. Use the event.type field to distinguish between different triggers like change_column_value, create_item, or item_deleted. To register a webhook, go to your Monday.com board → Integrations (puzzle icon in the top bar) → Webhooks → Create Webhook. Enter your deployed endpoint URL (e.g. https://your-app.netlify.app/api/monday/webhook), select the event trigger, and click Create. Optionally add a secret query parameter to your URL for validation: ?secret=your_secret, then check this parameter in your handler before processing the event. Add MONDAY_WEBHOOK_SECRET to your Netlify environment variables.

1// app/api/monday/webhook/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3
4interface MondayWebhookEvent {
5  type: string;
6  boardId: number;
7  itemId: number;
8  itemName: string;
9  columnId?: string;
10  columnTitle?: string;
11  value?: {
12    label?: { text: string };
13    previousLabel?: { text: string };
14  };
15  userId?: number;
16  triggerTime?: string;
17}
18
19interface MondayWebhookPayload {
20  challenge?: string;
21  event?: MondayWebhookEvent;
22}
23
24export async function POST(request: NextRequest) {
25  // Optional: validate secret query parameter
26  const secret = request.nextUrl.searchParams.get('secret');
27  if (process.env.MONDAY_WEBHOOK_SECRET && secret !== process.env.MONDAY_WEBHOOK_SECRET) {
28    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
29  }
30
31  const body: MondayWebhookPayload = await request.json();
32
33  // Step 1: respond to Monday.com's challenge verification immediately
34  if (body.challenge) {
35    return NextResponse.json({ challenge: body.challenge });
36  }
37
38  // Step 2: process the real event
39  const event = body.event;
40  if (!event) {
41    return NextResponse.json({ received: true });
42  }
43
44  console.log('Monday.com webhook event:', {
45    type: event.type,
46    item: event.itemName,
47    boardId: event.boardId,
48    column: event.columnTitle,
49    newValue: event.value?.label?.text,
50    previousValue: event.value?.previousLabel?.text,
51  });
52
53  if (
54    event.type === 'change_column_value' &&
55    event.value?.label?.text === 'Done'
56  ) {
57    // Trigger downstream action: notification, DB update, billing, etc.
58    console.log(`Item "${event.itemName}" marked as Done on board ${event.boardId}`);
59  }
60
61  return NextResponse.json({ received: true });
62}