A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Smartsheet API is how an app or AI agent works with a Smartsheet account: reading and updating sheets, adding and changing rows, building reports and dashboards, and organizing work into workspaces. Access is granted through an access token, where an OAuth token carries named scopes that set what a call can do and a raw API token inherits the access of the user who created it, limiting an agent to the sheets that token reaches. Smartsheet can also push a sheet's changes to a registered callback when something on it changes.
How an app or AI agent connects to Smartsheet determines what it can reach. There is a route for making calls, a route for receiving events, and a hosted server that exposes Smartsheet tools to agents, and each is governed by the token behind it and the permissions that token carries.
The REST API answers at https://api.smartsheet.com/2.0, returns JSON, and authenticates each call with a Bearer access token. Regional instances use their own hosts for the Gov, Europe, and Australia editions.
A webhook delivers a sheet's change events as callbacks to a registered HTTPS URL. Enabling one starts a verification handshake, where Smartsheet sends a Smartsheet-Hook-Challenge header that the receiver must echo back, and it re-verifies every 100 callbacks.
Smartsheet's hosted MCP server lets an AI agent call Smartsheet through the Model Context Protocol. It is generally available at https://mcp.smartsheet.com, with regional hosts at mcp.smartsheet.eu and mcp.smartsheet.au, and authenticates with an API access token sent as a Bearer header or with OAuth from supported AI clients. Its tools cover sheets, rows, columns, discussions, comments, and workspaces.
A raw API access token is generated in Smartsheet account settings and sent as 'Authorization: Bearer
OAuth 2.0 uses the authorization-code flow: a user is sent to Smartsheet to consent to a set of scopes, the app exchanges the returned code for an access token, and the token represents that user limited to the granted scopes. The access token lasts about seven days, and a refresh token obtains a new pair.
The Smartsheet API is split into areas an agent can act on, like sheets, rows, columns, reports, dashboards, and workspaces. Each area has its own methods and its own permissions, and a write in some areas changes shared work that a whole team relies on.
List, read, create, update, and delete sheets, the grids that hold a team's rows and columns.
Add, update, and delete rows on a sheet.
List and add columns, and read the change history of a single cell.
List reports and read a single report, the saved views that roll up rows across sheets.
List dashboards, called Sights in the API, and read a single dashboard.
List and read workspaces, create a workspace, and create a folder to organize sheets and reports.
List, create, update, and delete webhooks that deliver sheet change events to a callback URL.
Read the current user, list users in the organization, and add a user to a plan.
List the attachments on a sheet and attach a file to a sheet.
List the discussions on a sheet and start a new discussion.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
SheetsList, read, create, update, and delete sheets, the grids that hold a team's rows and columns.5 | ||||||
| GET | /sheets | List the sheets the access token can see. | read | READ_SHEETS | Current | |
Returns sheets accessible to the token; a raw API access token returns the sheets the owning user can see. Acts onsheet Permission (capability) READ_SHEETSVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /sheets/{sheetId} | Get a single sheet, including its rows, columns, and cell data. | read | READ_SHEETS | Current | |
READ_SHEETS also covers the sheet's attachments, discussions, and cell data. Acts onsheet Permission (capability) READ_SHEETSVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /sheets | Create a sheet, from columns, from a template, or by copying an existing sheet. | write | CREATE_SHEETS | Current | |
Creating a sheet needs CREATE_SHEETS, separate from WRITE_SHEETS which edits existing sheet data. Acts onsheet Permission (capability) CREATE_SHEETSVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /sheets/{sheetId} | Update a sheet's settings, such as its name or user settings. | write | WRITE_SHEETS | Current | |
Changing a sheet's column structure or publish state needs ADMIN_SHEETS instead. Acts onsheet Permission (capability) WRITE_SHEETSVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /sheets/{sheetId} | Delete a sheet, moving it to the deleted items of the owner. | write | DELETE_SHEETS | Current | |
Deleting a sheet needs DELETE_SHEETS, a scope distinct from editing sheet data. Acts onsheet Permission (capability) DELETE_SHEETSVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
RowsAdd, update, and delete rows on a sheet.3 | ||||||
| POST | /sheets/{sheetId}/rows | Add one or more rows to a sheet. | write | WRITE_SHEETS | Current | |
Multiple rows are added in a single call rather than one request per row. Acts onrow Permission (capability) WRITE_SHEETSVersionAvailable since the API’s base version Webhook event sheet-eventRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /sheets/{sheetId}/rows | Update one or more rows, including their cell values. | write | WRITE_SHEETS | Current | |
Updating cell values is part of WRITE_SHEETS. Serial updates to one sheet avoid save collisions. Acts onrow Permission (capability) WRITE_SHEETSVersionAvailable since the API’s base version Webhook event sheet-eventRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /sheets/{sheetId}/rows | Delete one or more rows from a sheet, named by row id. | write | WRITE_SHEETS | Current | |
Row ids are passed in the ids query parameter; child rows can be removed with the parent. Acts onrow Permission (capability) WRITE_SHEETSVersionAvailable since the API’s base version Webhook event sheet-eventRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Columns & cellsList and add columns, and read the change history of a single cell.3 | ||||||
| GET | /sheets/{sheetId}/columns | List the columns of a sheet. | read | READ_SHEETS | Current | |
Read-only; returns each column's id, type, and options. Acts oncolumn Permission (capability) READ_SHEETSVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /sheets/{sheetId}/columns | Add one or more columns to a sheet. | write | ADMIN_SHEETS | Current | |
Changing a sheet's column structure needs ADMIN_SHEETS, not just WRITE_SHEETS. Acts oncolumn Permission (capability) ADMIN_SHEETSVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /sheets/{sheetId}/rows/{rowId}/columns/{columnId}/history | Get the change history of a single cell. | read | READ_SHEETS | Current | |
Each cell history request counts as 10 requests toward the rate limit, capping it at about 30 per minute. Acts oncell Permission (capability) READ_SHEETSVersionAvailable since the API’s base version Webhook eventNone Rate limitCounts as 10 requests SourceOfficial documentation ↗ | ||||||
ReportsList reports and read a single report, the saved views that roll up rows across sheets.2 | ||||||
| GET | /reports | List the reports the access token can see. | read | READ_SHEETS | Current | |
Reports are covered by the same READ_SHEETS scope as sheet data. Acts onreport Permission (capability) READ_SHEETSVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /reports/{reportId} | Get a single report, including its rows rolled up across sheets. | read | READ_SHEETS | Current | |
Read-only; a large report is paged through page and pageSize. Acts onreport Permission (capability) READ_SHEETSVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Dashboards (Sights)List dashboards, called Sights in the API, and read a single dashboard.2 | ||||||
| GET | /sights | List the dashboards, called Sights, the access token can see. | read | READ_SIGHTS | Current | |
Dashboards use the separate READ_SIGHTS scope, not READ_SHEETS. Acts onsight Permission (capability) READ_SIGHTSVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /sights/{sightId} | Get a single dashboard, including its widgets. | read | READ_SIGHTS | Current | |
Read-only; changing a dashboard's structure needs ADMIN_SIGHTS. Acts onsight Permission (capability) READ_SIGHTSVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Workspaces & foldersList and read workspaces, create a workspace, and create a folder to organize sheets and reports.3 | ||||||
| GET | /workspaces | List the workspaces the access token can see. | read | READ_SHEETS | Current | |
Listing workspaces is a read covered by READ_SHEETS. Acts onworkspace Permission (capability) READ_SHEETSVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /workspaces | Create a workspace, a container that shares its access with everything inside it. | write | ADMIN_WORKSPACES | Current | |
Creating and managing workspaces and their shares needs ADMIN_WORKSPACES. Acts onworkspace Permission (capability) ADMIN_WORKSPACESVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /folders/{folderId}/folders | Create a folder inside another folder to organize sheets and reports. | write | ADMIN_WORKSPACES | Current | |
Folders sit inside workspaces or home, and creating them needs ADMIN_WORKSPACES. Acts onfolder Permission (capability) ADMIN_WORKSPACESVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WebhooksList, create, update, and delete webhooks that deliver sheet change events to a callback URL.4 | ||||||
| GET | /webhooks | List the webhooks owned by the access token. | read | ADMIN_WEBHOOKS | Current | |
All webhook operations, including listing, use the ADMIN_WEBHOOKS scope. Acts onwebhook Permission (capability) ADMIN_WEBHOOKSVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /webhooks | Create a webhook that delivers a sheet's change events to a callback URL. | write | ADMIN_WEBHOOKS | Current | |
The events array must be '*.*', meaning all object and event types on the scoped sheet. Acts onwebhook Permission (capability) ADMIN_WEBHOOKSVersionAvailable since the API’s base version Webhook event sheet-eventRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /webhooks/{webhookId} | Update a webhook, such as enabling it or changing its callback URL. | write | ADMIN_WEBHOOKS | Current | |
Enabling a webhook here triggers Smartsheet's callback verification handshake. Acts onwebhook Permission (capability) ADMIN_WEBHOOKSVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /webhooks/{webhookId} | Delete a webhook, stopping its callbacks. | write | ADMIN_WEBHOOKS | Current | |
Deleting a webhook needs ADMIN_WEBHOOKS, the same scope as creating one. Acts onwebhook Permission (capability) ADMIN_WEBHOOKSVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
UsersRead the current user, list users in the organization, and add a user to a plan.3 | ||||||
| GET | /users/me | Get the current user behind the access token. | read | — | Current | |
Returns the user the token authenticates as; no special scope is required. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /users | List the users of the organization account. | read | READ_USERS | Current | |
Listing the organization's users and groups needs READ_USERS. Acts onuser Permission (capability) READ_USERSVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /users | Add a user to the organization account. | write | ADMIN_USERS | Current | |
Adding or removing users and managing seats needs ADMIN_USERS, a system-admin scope. Acts onuser Permission (capability) ADMIN_USERSVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
AttachmentsList the attachments on a sheet and attach a file to a sheet.2 | ||||||
| GET | /sheets/{sheetId}/attachments | List the attachments on a sheet. | read | READ_SHEETS | Current | |
Attachments are covered by READ_SHEETS. Acts onattachment Permission (capability) READ_SHEETSVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /sheets/{sheetId}/attachments | Attach a file to a sheet. | write | WRITE_SHEETS | Current | |
Attaching a file counts as 10 requests toward the rate limit, capping it at about 30 per minute. Acts onattachment Permission (capability) WRITE_SHEETSVersionAvailable since the API’s base version Webhook event sheet-eventRate limitCounts as 10 requests SourceOfficial documentation ↗ | ||||||
DiscussionsList the discussions on a sheet and start a new discussion.2 | ||||||
| GET | /sheets/{sheetId}/discussions | List the discussions on a sheet. | read | READ_SHEETS | Current | |
Discussions and their comments are covered by READ_SHEETS. Acts ondiscussion Permission (capability) READ_SHEETSVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /sheets/{sheetId}/discussions | Start a new discussion on a sheet. | write | WRITE_SHEETS | Current | |
A comment posted here is visible to everyone shared on the sheet. Acts ondiscussion Permission (capability) WRITE_SHEETSVersionAvailable since the API’s base version Webhook event sheet-eventRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Smartsheet can notify an app or AI agent when something changes on a sheet, like a row being added or a cell value being updated, instead of the app repeatedly asking. Smartsheet posts a callback to a URL that has been registered for the chosen sheet.
| Event | What it signals | Triggered by |
|---|---|---|
sheet (*.*) | Fires when an object on the scoped sheet changes, covering a row, cell, column, attachment, comment, or discussion being added, updated, or deleted. A webhook subscribes to all of these at once, since the events array must be '*.*'. | /sheets/{sheetId}/rows/sheets/{sheetId}/rows/sheets/{sheetId}/rows/webhooks/sheets/{sheetId}/attachments/sheets/{sheetId}/discussions |
Smartsheet limits how fast an app or AI agent can call, through a per-token request rate measured per minute, where a few heavier operations count for more than one request each.
Smartsheet sets a default rate limit of 300 requests per minute per access token, and exceeding it returns HTTP 429 with error code 4003 and the message 'Rate limit exceeded.' A few resource-intensive operations count for more than one request: attaching a file and reading a cell's history each count as 10, which effectively caps those to about 30 per minute. The recommended response to a 429 is to sleep at least 60 seconds, or to use exponential backoff, which the official SDKs apply by default; batching many changes into a single bulk call and serializing writes to one sheet keep request volume down.
List endpoints page with offset-based parameters: page is the 1-based page number and pageSize sets how many items per page, defaulting to 100. The response wraps the items in an IndexResult with pageNumber, pageSize, totalPages, and totalCount alongside the data array. The older includeAll parameter, which returned every result at once, is being retired: as of 15 June 2026 several object types, including workspaces, folders, dashboards, and webhooks, moved to token-based paging with maxItems and a lastKey token that marks the position for the next page.
A page size should stay at or below 10,000 items. There is no single documented payload size limit across the whole API, though individual operations such as file attachments set their own ceilings, and bulk row operations have practical per-call limits.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | 1001 / 1002 / 1003 | Authentication failed: an access token is required (1001), the token is invalid (1002), or the token has expired (1003). | Send a valid, unexpired access token in the Authorization header, refreshing an OAuth token where needed. |
| 403 | 1004 | The token is authenticated but not authorized for this action, often because the user lacks share access to the object or the OAuth scope does not cover the call. | Grant the user access to the object, or request the scope the call needs, such as WRITE_SHEETS or ADMIN_USERS. |
| 404 | 1006 | Not found: the requested object does not exist or is not visible to this token. | Confirm the id is correct and the token's user has been shared on the object. |
| 400 | 1008 | The request could not be parsed, usually a malformed body or an invalid value for a field. | Read the message, which names the parsing problem, then correct the request body and resend. |
| 429 | 4003 | The rate limit was exceeded. The default is 300 requests per minute per token, and heavier operations like attaching a file or reading cell history count as 10 each. | Back off and retry, sleeping at least 60 seconds or using exponential backoff, and batch changes into bulk calls. |
| 500 | 4002 / 4004 | A server-side error: the request timed out (4002) or an unexpected error occurred, which can include a concurrent update conflict on the same sheet (4004). | Retry the request, and serialize writes to a single sheet to avoid save collisions. |
| 503 | 4001 | Smartsheet is temporarily offline for system maintenance. | Wait and retry later, honoring any Retry-After header. |
Smartsheet serves a single numbered version of its API at one base path, and ships dated, backward-compatible changes through its release notes rather than minting a new version for each one.
The Smartsheet API is served at version 2.0 on the base path /2.0, a single numbered version rather than dated versions. Smartsheet ships changes through dated, mostly backward-compatible release notes and gives advance notice before deprecations, so an integration tracks the changelog rather than migrating between version strings. The dated entries below are recent notable changes from that changelog.
Several object types dropped the includeAll parameter and offset-based paging in favor of token-based paging, and the pageSize maximum was set to 10,000.
Added new events and properties to the event log.
Webhooks now work on sheets of any size, with callbacks delivered for all events regardless of sheet scale.
Full create, read, update, and delete support arrived for reports, alongside a seat-type change.
An integration can rely on a stable base path and track changes through the changelog.
Smartsheet API changelog ↗Bollard AI sits between a team's AI agents and Smartsheet. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.