Smartsheet Sheets & Rows
For teams that run projects in Smartsheet: find a sheet, read its rows and columns, add or update rows by column id, and leave a comment on a row for the owner. Also searches across workspaces and reads a sheet's summary fields such as status or budget.
Connect this API to an AI agent Browse all specs
What you can do with Smartsheet Sheets & Rows via MCP
Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.
| Method | Path | Operation | Description |
|---|---|---|---|
| GET | /users/me |
getCurrentUser | Get the Smartsheet user the token belongs to |
| GET | /search |
searchEverything | Search sheets, rows, discussions and attachments by text |
| GET | /search/sheets/{sheetId} |
searchSheet | Search for text inside one sheet |
| GET | /sheets |
listSheets | List the sheets you can open |
| GET | /sheets/{sheetId} |
getSheet | Read a sheet with its columns and rows |
| GET | /sheets/{sheetId}/columns |
listColumns | List a sheet's columns with ids and types |
| GET | /sheets/{sheetId}/rows/{rowId} |
getRow | Read one row |
| POST | /sheets/{sheetId}/rows |
addRows | Add one or more rows to a sheet |
| PUT | /sheets/{sheetId}/rows |
updateRows | Change cell values or move existing rows |
| GET | /workspaces |
listWorkspaces | List the workspaces you can access |
| GET | /workspaces/{workspaceId}/children |
listWorkspaceChildren | List the sheets, reports and folders in a workspace |
| GET | /sheets/{sheetId}/discussions |
listDiscussions | List comment threads on a sheet and its rows |
| POST | /sheets/{sheetId}/rows/{rowId}/discussions |
createRowDiscussion | Start a comment thread on a row |
| GET | /sheets/{sheetId}/summary |
getSheetSummary | Read a sheet's summary fields (status, owner, budget...) |
Authentication
smartsheetToken
Bearer token — sent as Authorization: Bearer <token>
How to get a credential
- Sign in to Smartsheet (API access needs a Business or Enterprise plan).
- From your account menu open API Access (Smartsheet help article Generate an API key: help.smartsheet.com/articles/2482389-generate-API-key).
- Generate a new access token, name it and copy it (it is shown once).
- The token acts as you: it can see and edit whatever your Smartsheet user can.
Permissions used
| Access (OAuth scope equivalent) | Operations |
|---|---|
| Your profile | getCurrentUser |
| READ_SHEETS | searchEverything, searchSheet, listSheets, getSheet, listColumns, getRow, listWorkspaces, listWorkspaceChildren, listDiscussions, getSheetSummary |
| WRITE_SHEETS | addRows, updateRows, createRowDiscussion |
Common errors
- 401 Unauthorized (error code 1002 or 1003): token invalid or expired; generate a new one.
- 403 Forbidden (error code 1004): you are not allowed to do this, e.g. you are a viewer on that sheet and editor access is needed for writes.
- 400 Bad Request: a cell's
columnIddoes not exist or a value fails column validation (useoverrideValidationonly if the user agrees). - 429 Too Many Requests (error code 4003): about 300 requests per minute per token; wait and retry.
Store the token as a VX Agents bearer token credential. EU and AU accounts use https://api.smartsheet.eu/2.0 or https://api.smartsheet.au/2.0.
Usage guide
Setup
- Credential: a Smartsheet API access token (bearer). It acts as your user, so it can see and change only what you can.
- Worth pinning:
sheetIdof the tracker you use most (Smartsheet → File → Properties, or fromlistSheets). EU and AU accounts must change the base URL toapi.smartsheet.euorapi.smartsheet.au.
Update a project tracker
- Find the sheet:
searchEverythingwithquery, orlistSheets/listWorkspaces→listWorkspaceChildren. listColumnsto map column titles tocolumnId(writes use ids, not titles) and to see each column's type and picklist options.- Read rows:
getSheetwithpageSize(andpage), or narrow withrowIds,columnIdsorrowsModifiedSince.searchSheetfinds rows containing a text;getRowreads one row. - Add:
addRowswith an array like[{"toBottom": true, "cells": [{"columnId": 123, "value": "Design review"}, {"columnId": 456, "value": "2026-10-24"}]}]. - Change:
updateRowswith[{"id": <rowId>, "cells": [{"columnId": 789, "value": "Done"}]}]. Only the cells you send change. - Tell the owner:
createRowDiscussionwith{"comment": {"text": "..."}}on that row.listDiscussions(include=comments) reads existing threads. getSheetSummaryfor sheet-level fields such as overall status, owner or budget.
Show new rows, changed cells and comment text to the user and get a yes before addRows, updateRows or createRowDiscussion: collaborators see the changes and automations may send alerts.
Good to know
- Ids are large integers; send them as numbers.
- Dates are
YYYY-MM-DD; contact cells take an email address asvalue; checkbox cells taketrueorfalse. strict: falseon a cell lets Smartsheet parse loose values (e.g. "10/24/26" as a date).- Cells with formulas cannot take a
value; sendformulainstead. - About 300 requests per minute per token (error code 4003 when exceeded). Batch rows in one
addRowsorupdateRowscall. getSheeton a big sheet is heavy: usepageSizeandcolumnIds.
Source: Smartsheet API reference (https://developers.smartsheet.com/api/smartsheet/openapi), checked 2026-10-19.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “Smartsheet Sheets & Rows” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.