Smartsheet
The Smartsheet toolkit connects a Smartsheet account to agents and workflows using an API access token and lets you search and browse workspaces, read filtered sheet rows by column title, add and update rows, manage attachments and discussions, inspect reports and dashboards, and handle sharing and favorites. The toolkit requires a Smartsheet Business, Enterprise, or Advanced Work Management plan.
Prerequisites
- A Smartsheet Business, Enterprise, or Advanced Work Management plan. API access is not available on other plans.
- A licensed Smartsheet user with access only to the sheets, workspaces, and reports the agent or workflow should use.
- A Smartsheet API access token — go to Account → Personal Settings → API Access in Smartsheet, generate a new access token, and copy it immediately.
- The Smartsheet region that matches the token (US, EU, Australia, or Gov). Regional tokens are not interchangeable.
- Prefer a dedicated licensed service account rather than a personal day-to-day login.
warning
Smartsheet API tokens are unscoped — they inherit every permission of the user who generated them. Use a dedicated service account with access limited to only the sheets and workspaces the agent should use. Never expose tokens in prompts, workflow inputs, chat, tickets, screenshots, or documentation. Enable write and delete actions only for trusted agents.
Setup
- Generate a Smartsheet API access token
In Smartsheet, go to Account → Personal Settings → API Access. Generate a new access token, give it a recognizable name, and copy it immediately.
- Open an agent or workflow
Open an agent and add the Smartsheet toolkit under Toolkits, or add a Smartsheet step to a workflow.
- Create a saved connection
In the Smartsheet step, choose + New under Select saved connection. Enter a Connection Name, the API Access Token, and the correct Region (US, EU, Australia, or Gov). Save the connection.
- Enable only the tools you need
New agents default to a read-focused subset. Start with List Workspaces, Get Sheet Summary, and Get Columns. Enable write and delete actions only after testing on a non-production sheet.
- Test with a safe read action
Run List Workspaces to confirm the connection. Then use Get Columns on a test sheet to get exact column titles before running Get Sheet Summary.
Available tools
Discovery
| Tool | Description |
|---|---|
| Search | Searches assets the token owner can access by name or content. Returns up to 100 results. |
| List Workspaces | Lists accessible workspaces. Safe first check after connecting. |
| Browse Workspace | Lists sheets, reports, dashboards, and folders in a workspace. |
| Browse Folder | Lists contents of a folder. |
| Get Sheet Path | Returns the workspace and folder path, permalink, and metadata for a sheet. |
| Create Workspace | Creates a new workspace. |
| Create Folder | Creates a folder in a workspace or under a parent folder. |
Sheets
| Tool | Description |
|---|---|
| Get Sheet Summary | Reads filtered sheet rows using column titles, with optional filters, sorting, and column selection. There is no full-sheet dump — this is the intended way to read sheet data. |
| Get Sheet Version | Returns the monotonic sheet version number. Use as a cheap change-detection check before re-reading a sheet. |
| Find In Sheet | Searches text inside a sheet and returns matching cells with row and column IDs. |
| Create Sheet | Creates a sheet with defined columns, optionally inside a workspace or folder. |
Columns
| Tool | Description |
|---|---|
| Get Columns | Lists columns including type, options, locked, and formula flags. Run this before reading or writing rows — column titles are case-sensitive. |
| Add Columns | Adds one or more columns to a sheet. |
| Update Column | Updates a column's title, position, or picklist options. |
| Delete Column | Deletes a column and its cell data. Destructive — confirm before running. |
Rows
| Tool | Description |
|---|---|
| Add Rows | Adds one or more rows using column titles. Column titles are case-sensitive; locked and formula columns cannot be written. |
| Update Rows | Updates existing rows by row ID using column titles. |
| Delete Rows | Deletes one or more rows permanently. Destructive — confirm before running. |
| Get Cell History | Returns edit history for one cell. Counts as 10 API requests — avoid tight loops. |
Attachments
| Tool | Description |
|---|---|
| List Attachments | Lists attachments on a sheet, row, or discussion. |
| Get Attachment | Returns attachment metadata and a download URL. |
| Attach URL | Attaches a public URL to a sheet or row. |
| Delete Attachment | Deletes an attachment. Destructive — confirm before running. |
Discussions
| Tool | Description |
|---|---|
| List Discussions | Lists discussions on a sheet or a specific row. |
| Get Discussion | Returns one discussion including its comments. |
| Create Discussion | Starts a new discussion thread on a sheet or row. |
| Add Comment | Adds a comment to an existing discussion. |
| Update Comment | Updates a comment (typically limited to comments created by the token owner). |
| Delete Discussion | Deletes a discussion. Destructive — confirm before running. |
| Delete Comment | Deletes a comment. Destructive — confirm before running. |
Reports and Dashboards
| Tool | Description |
|---|---|
| List Reports | Lists accessible reports. |
| Get Report | Returns a report including a page of rows. |
| Create Report | Creates a report with named columns and a source scope in a workspace or folder. Name, columns, scope, and destination are all required. |
| List Dashboards | Lists accessible dashboards. |
| Get Dashboard | Returns a dashboard including its widgets. |
| Create Dashboard | Creates an empty dashboard in a workspace or folder. |
Sharing and Favorites
| Tool | Description |
|---|---|
| List Shares | Lists users and groups a sheet is shared with. |
| List Favorites | Lists the token owner's favorited assets. |
| Is Favorite | Checks whether a sheet, report, or dashboard is in the token owner's favorites. |
| Add Favorites | Adds an asset to the token owner's favorites. |
| Delete Favorites | Removes an asset from the token owner's favorites. Does not delete the underlying asset. |
Plan
| Tool | Description |
|---|---|
| Get Plan ID | Returns plan identifiers for the current user. |
| Get Seat Usage | Returns seat and user counts. May require an organization-admin role. |
| Get License Inventory | Returns licensed-user inventory for the organization. May require an organization-admin role. |
Use cases
- Look up overdue or blocked rows in a project sheet using filters and return a summary to the agent.
- Add a new row to a tracking sheet after an approval step in a workflow.
- Update a row's status column after a later workflow step confirms completion.
- Browse a workspace to find the right sheet before reading filtered rows.
- List discussions on a row and add a follow-up comment summarizing the latest update.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Smartsheet not visible in the toolkit picker | The toolkit is not enabled for the environment or project. | Ask a Super Admin to enable the toolkit and refresh the picker. |
| Invalid access token | The token was not copied in full, has been revoked, or the wrong region was selected. | Confirm the region matches the account that generated the token, then generate a new token and update the connection. |
| Plan does not allow API access | The Smartsheet account is not on a Business, Enterprise, or Advanced Work Management plan. | Upgrade the plan or use a licensed user on an eligible plan. |
403 Forbidden or not-found errors | The token owner does not have sharing access to the sheet, workspace, report, or dashboard. | Ensure the Smartsheet user has access to the asset. Use numeric IDs from Search or List Workspaces — not display names. |
| Unknown column error | The column title is incorrect or does not match the sheet's exact capitalization. | Run Get Columns and copy the column title exactly — titles are case-sensitive. |
| Create Report fails | Name, columns, scope, or destination is missing, or no column is marked as primary. | Provide all required fields. One column must be marked as the primary column. |
| Truncated sheet summary | The response exceeded the character limit. | Narrow filters, reduce the column list, or reduce the page size. |
| Rate limit or busy response | The request rate exceeded Smartsheet's 300-per-minute token budget. | The toolkit retries automatically. Avoid tight loops, especially with Get Cell History (counts as 10 requests). |