How to Integrate Bolt.new with Smartsheet

Smartsheet personal access tokens provide API access on behalf of your account. To generate one, click your account avatar in the top-right of Smartsheet, go to Personal Settings → API Access → Generate new access token. Give it a descriptive name, copy the token immediately (Smartsheet shows it only once), and store it in a secure location. Before you can write data to a Smartsheet, you must know the column IDs for your sheet. Smartsheet columns have internal numeric IDs that you use when creating or updating cells — the column name in the Smartsheet UI is not used in API calls. To discover your column IDs, call GET https://api.smartsheet.com/2.0/sheets/{sheetId} with your token. The response includes a 'columns' array with each column's id, title, type, and options (for PICKLIST columns). Your sheet ID is the number in the Smartsheet URL: app.smartsheet.com/sheets/1234567890123456. Store it as SMARTSHEET_SHEET_ID in your .env.local file. After fetching the columns, copy the column IDs for the fields you will read and write — store them as comments in your API route for reference. Smartsheet column types you will commonly encounter: TEXT_NUMBER (plain text or numbers), DATE (stores ISO date strings), CONTACT_LIST (stores email addresses linked to Smartsheet contacts), PICKLIST (dropdown with predefined options), CHECKBOX (boolean true/false), and AUTO_NUMBER (system-generated row numbers). Values are formatted differently depending on type — plain text for TEXT_NUMBER, ISO date strings for DATE, and email strings for CONTACT_LIST.

1// .env.local
2SMARTSHEET_ACCESS_TOKEN=your_personal_access_token
3SMARTSHEET_SHEET_ID=your_sheet_id_from_url

To fetch the full sheet including all rows and cells, call GET /sheets/{sheetId}. The response includes the sheet metadata, columns array, and rows array. Each row contains a 'cells' array where each cell has a columnId, value (the stored value), displayValue (the formatted string for display), and type. For PICKLIST cells, the value is the option string. For DATE cells, the value is an ISO date string. For CONTACT_LIST cells, the value is an email address. For large sheets with hundreds of rows, use pagination: append ?pageSize=100&page=1 to fetch 100 rows at a time. The response includes totalCount and totalPages in the pagination object. Increase the page number to fetch subsequent batches. To fetch only specific rows, use the rowIds query parameter: /sheets/{sheetId}/rows/{rowId} fetches a single row. The search endpoint GET /search/sheets/{sheetId}?query={searchTerm} finds rows containing specific text — useful for looking up rows by a unique identifier column. For constructing a useful table display, build a mapping from column ID to column title using the columns array, then iterate through rows and cells to create objects keyed by column title. This gives you a readable data structure like { 'Client Name': 'Acme Corp', 'Status': 'Active' } rather than { '1234567': 'Acme Corp' }. All GET operations work from Bolt's WebContainer — you will see your real Smartsheet data rendered in the Bolt preview without deploying.

1// app/api/smartsheet/sheet-data/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3
4const SMARTSHEET_API = 'https://api.smartsheet.com/2.0';
5const ACCESS_TOKEN = process.env.SMARTSHEET_ACCESS_TOKEN;
6const SHEET_ID = process.env.SMARTSHEET_SHEET_ID;
7
8type SmartsheetColumn = { id: number; title: string; type: string };
9type SmartsheetCell = { columnId: number; value: unknown; displayValue?: string };
10type SmartsheetRow = { id: number; rowNumber: number; cells: SmartsheetCell[] };
11
12export async function GET(request: NextRequest) {
13  const { searchParams } = new URL(request.url);
14  const page = searchParams.get('page') ?? '1';
15  const pageSize = searchParams.get('pageSize') ?? '100';
16
17  const response = await fetch(
18    `${SMARTSHEET_API}/sheets/${SHEET_ID}?pageSize=${pageSize}&page=${page}`,
19    { headers: { Authorization: `Bearer ${ACCESS_TOKEN}`, Accept: 'application/json' } }
20  );
21
22  if (!response.ok) {
23    return NextResponse.json(
24      { error: `Smartsheet API ${response.status}` },
25      { status: response.status }
26    );
27  }
28
29  const sheet = await response.json();
30
31  // Build column ID → title map
32  const colMap: Record<number, string> = {};
33  for (const col of sheet.columns as SmartsheetColumn[]) {
34    colMap[col.id] = col.title;
35  }
36
37  // Transform rows to human-readable objects
38  const rows = (sheet.rows as SmartsheetRow[]).map((row) => {
39    const record: Record<string, unknown> = { _id: row.id, _rowNumber: row.rowNumber };
40    for (const cell of row.cells) {
41      const colTitle = colMap[cell.columnId];
42      if (colTitle) {
43        record[colTitle] = cell.displayValue ?? cell.value ?? null;
44      }
45    }
46    return record;
47  });
48
49  return NextResponse.json({
50    rows,
51    columns: sheet.columns.map((c: SmartsheetColumn) => ({ id: c.id, title: c.title, type: c.type })),
52    totalRows: sheet.totalRowCount,
53  });
54}

Adding rows to a Smartsheet requires a POST to /sheets/{sheetId}/rows with a 'cells' array where each cell specifies a columnId and value. The columnId is the numeric ID from your sheet's column list. The value format depends on the column type: strings for TEXT_NUMBER, ISO date strings (YYYY-MM-DD) for DATE, email strings for CONTACT_LIST, and boolean values for CHECKBOX. You can add multiple rows in a single request by sending an array of row objects. Each row object must have a 'cells' array. Optionally include 'toBottom: true' to insert at the bottom of the sheet, or 'toTop: true' for the top. Without either, rows insert at the top by default. Updating existing rows uses PUT /sheets/{sheetId}/rows with an array of row objects that include both the row 'id' and the 'cells' you want to change. Only include cells you want to update — omitted columns retain their existing values. Deleting rows uses DELETE /sheets/{sheetId}/rows?rowIds={comma-separated row IDs}. This permanently removes rows and cannot be undone — consider updating a 'Status' or 'Archived' column to 'Deleted' instead for safer soft-deletion. For PICKLIST columns (dropdowns), the cell value must exactly match one of the predefined options for that column. Fetch valid options from the columns endpoint: each PICKLIST column includes an 'options' array. Sending an invalid picklist value results in a 400 error. These mutation operations are outbound HTTP calls that work perfectly in Bolt's WebContainer — you can test form submissions that create real Smartsheet rows during development without deploying first.

1// app/api/smartsheet/rows/add/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3
4const SMARTSHEET_API = 'https://api.smartsheet.com/2.0';
5const ACCESS_TOKEN = process.env.SMARTSHEET_ACCESS_TOKEN;
6const SHEET_ID = process.env.SMARTSHEET_SHEET_ID;
7
8// Cache column map to avoid fetching on every request
9let columnMapCache: Record<string, number> | null = null;
10
11async function getColumnMap(): Promise<Record<string, number>> {
12  if (columnMapCache) return columnMapCache;
13
14  const res = await fetch(
15    `${SMARTSHEET_API}/sheets/${SHEET_ID}?include=columnType`,
16    { headers: { Authorization: `Bearer ${ACCESS_TOKEN}` } }
17  );
18  const sheet = await res.json();
19  columnMapCache = {};
20  for (const col of sheet.columns) {
21    columnMapCache[col.title] = col.id;
22  }
23  return columnMapCache;
24}
25
26export async function POST(request: NextRequest) {
27  const { rowData } = await request.json();
28
29  if (!rowData || typeof rowData !== 'object') {
30    return NextResponse.json({ error: 'rowData object is required' }, { status: 400 });
31  }
32
33  const colMap = await getColumnMap();
34
35  const cells = Object.entries(rowData)
36    .filter(([title]) => colMap[title] !== undefined)
37    .map(([title, value]) => ({
38      columnId: colMap[title],
39      value,
40    }));
41
42  if (cells.length === 0) {
43    return NextResponse.json({ error: 'No matching columns found in rowData' }, { status: 400 });
44  }
45
46  const response = await fetch(`${SMARTSHEET_API}/sheets/${SHEET_ID}/rows`, {
47    method: 'POST',
48    headers: {
49      Authorization: `Bearer ${ACCESS_TOKEN}`,
50      'Content-Type': 'application/json',
51    },
52    body: JSON.stringify([{ toBottom: true, cells }]),
53  });
54
55  if (!response.ok) {
56    const error = await response.json();
57    return NextResponse.json({ error: error.message }, { status: response.status });
58  }
59
60  const result = await response.json();
61  const newRow = result.result[0];
62  return NextResponse.json({ id: newRow.id, rowNumber: newRow.rowNumber });
63}

Smartsheet webhooks allow your app to receive real-time notifications when rows are added, updated, or deleted — without polling. This is valuable for keeping a Bolt dashboard synchronized with a Smartsheet that operations teams update continuously throughout the day. To deploy, click the Publish button in Bolt to deploy to Netlify, or use Bolt's GitHub integration to push to a repository connected to Vercel. After deployment, add SMARTSHEET_ACCESS_TOKEN and SMARTSHEET_SHEET_ID as environment variables in your hosting platform's dashboard. Smartsheet webhooks use a verification handshake similar to Asana: when you create a webhook, Smartsheet sends a challenge request with a X-Smartsheet-Hook-Challenge header, and your handler must echo it back in the response body as JSON: { smartsheetHookResponse: challengeValue }. Create a webhook via POST https://api.smartsheet.com/2.0/webhooks with your token, specifying: callbackUrl (your deployed endpoint), name, scope ('sheet'), scopeObjectId (your sheet ID), and events (array of event types like ['*.*'] for all events or ['rows.created', 'rows.updated', 'rows.deleted'] for specific types). After creation, enable the webhook with PUT /webhooks/{webhookId} with { enabled: true }. Webhook payloads contain a 'events' array with objects describing each change: eventType, objectType, id (row ID for row events), and timestamp. For row changes, fetch the updated row data using GET /sheets/{sheetId}/rows/{rowId} to get the current cell values. Note that in Bolt's WebContainer development environment, your app runs inside the browser and has no public URL — Smartsheet cannot send webhook events to a browser-based runtime. Deploy first, then register and test webhooks against your production URL.

1// app/api/smartsheet/webhook/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3
4export async function POST(request: NextRequest) {
5  // Smartsheet handshake: echo back the challenge header in the response body
6  const challenge = request.headers.get('x-smartsheet-hook-challenge');
7  if (challenge) {
8    return NextResponse.json({ smartsheetHookResponse: challenge });
9  }
10
11  // Regular webhook events
12  const payload = await request.json();
13  const events = payload.events ?? [];
14
15  for (const event of events) {
16    console.log(`Smartsheet event: ${event.eventType} on ${event.objectType}`, {
17      id: event.id,
18      timestamp: event.timestamp,
19    });
20  }
21
22  return NextResponse.json({ received: events.length });
23}