Changelog

Here is the log of changes to the API.

NOTE: To learn the deprecation process, see Deprecation process.

2025-08-04

DEPRECATION:

We’re changing several of our resource retrieval endpoints (ones that list references to resource objects and that fetch individual objects) to improve performance, reduce network latency, and conserve resources. For most of these endpoints, we’re replacing offset-based pagination with token-based pagination. At the very least, we’re removing the ability of these endpoints to return unbounded results.

Consequently, we deprecated several functionality components, and in most cases, we’ve provided improved components to replace them.

SUNSET DATE: The deprecated functionality will be discontinued as early as Feb-09-2026.

IMPORTANT: During this deprecation period, the deprecated functionality remains in place, and applicable replacement functionality is also available. Now is the best time to migrate from the deprecated functionality.

NOTE: See Deprecation process for deprecation and sunset term definitions, and for details on the deprecation process.

The following sections describe the deprecations (and applicable replacements), in order by simplest migrations first.

Webhook pagination

We deprecated the following List webhooks (GET /webhooks) endpoint functionality to reduce latency, mitigate performance issues, and add stability, especially for users with many webhooks.

• Deprecated the includeAll query parameter and will remove it.
• Deprecated the pageSize query parameter's unlimited value range and will set the maximum value to 10,000.
• Deprecated the totalCount response attribute and will set it to -1.
• Deprecated the totalPages response attribute and will set it to -1.
• Deprecated sorting the returned webhooks by name and will sort them by creation date (most recent first).

If you're currently using the includeAll parameter, update your code to page through the results using offset-based pagination via the pageSize and page parameters.

Otherwise, if you're not currently using the includeAll parameter but are using a pageSize greater than 10000, reduce your page size to 10000 or lower.

Dashboard pagination (deprecation preview)

NOTE: Token-based pagination for this endpoint is delayed, but is expected within the next few weeks. Please stay tuned for a follow-up changelog entry announcing token-based pagination availability for this endpoint.

We will be deprecating the List dashboards (GET /sights) operation's offset-based pagination and its ability to return an unbounded number of dashboards in a single request. Token-based pagination is replacing the offset-based pagination. These planned changes reduce latency, mitigate performance issues, and add stability, especially for users with many dashboards.

The following query parameters and response properties will be deprecated.

• Query parameters:

  • includeAll
  • modifiedSince
  • page
  • pageSize

• Response properties:

  • pageNumber
  • pageSize
  • totalCount
  • totalPages

List Workspaces pagination

We deprecated the List workspaces (GET /workspaces) operation's offset-based pagination and the operation's ability to return an unbounded list of results in a single request. Token-based pagination is replacing the offset-based pagination. These changes will reduce latency, mitigate performance issues, and improve stability, especially for users with many workspaces.

During the deprecation, the operation will continue to support offset-based pagination and will support the new token-based pagination. That will be the optimal time to migrate to token-based pagination using the paginationType=token request parameter setting to get your first results page and the lastKey request parameter to get each subsequent results page.

The following query parameters and response properties are deprecated.

Deprecated query parameters:

• includeAll
• page
• pageSize

Deprecated response properties:

• pageNumber
• pageSize
• totalCount
• totalPages

Template listing endpoints

We deprecated the List user-created templates (GET /templates) endpoint and List public templates (GET /templates/public) endpoint.

Folder and workspace pagination and fetching

We deprecated the following folder and workspace endpoints and are replacing them with new endpoints.

Deprecated endpoints:

• List folders (GET /folders/{folderId}/folders)
• List workspace folders (GET /workspaces/{workspaceId}/folders)
• Get folder (GET /folders/{folderId})
• Get workspace (GET /workspaces/{workspaceId})

New replacement endpoints:

• Get folder metadata (GET /folders/{folderId}/metadata) - Returns the folder's metadata.
• Get folder children (GET /folders/{folderId}/children)- Returns the folder's child items.
• Get workspace metadata (GET /workspaces/{workspaceId}/metadata) - Returns the workspace's metadata.
• Get workspace children (GET /workspaces/{workspaceId}/children) - Returns the workspace's child items.

NOTE: The *children endpoints return pages of results via token-based pagination.

Replacement Mapping:

Unsupported Query Params:

The replacement endpoints above don't support the following previously-deprecated include query parameter values:

• distributionLink
• sheetVersion - Alternatively, call Get sheet version (GET /sheets/{sheetId}/version) to get a sheet's version.

Sharing sheets, reports, dashboards, and workspaces

We have deprecated the asset-specific sharing endpoints and will be replacing it with new sharing endpoints to improve scalability and performance of our API.

Deprecated endpoints:

• List sheet shares (GET /sheets/{sheetId}/shares)
• List report shares (GET /reports/{reportId}/shares)
• List dashboard shares (GET /sights/{sightId}/shares)
• List workspace shares (GET /workspaces/{workspaceId}/shares)
• Get sheet share (GET /sheets/{sheetId}/shares/{shareId})
• Get report share (GET /reports/{reportId}/shares/{shareId})
• Get dashboard share (GET /sights/{sightId}/shares/{shareId})
• Get workspace share (GET /workspaces/{workspaceId}/shares/{shareId})
• Share sheet (POST /sheets/{sheetId}/shares)
• Share report (POST /reports/{reportId}/shares)
• Share dashboard (POST /sights/{sightId}/shares)
• Share workspac (POST /workspaces/{workspaceId}/shares)
• Update sheet share (PUT /sheets/{sheetId}/shares/{shareId})
• Update report share (PUT /reports/{reportId}/shares/{shareId})
• Update dashboard share (PUT /sights/{sightId}/shares/{shareId})
• Update workspace share (PUT /workspaces/{workspaceId}/shares/{shareId})
• Delete sheet share (DELETE /sheets/{sheetId}/shares/{shareId})
• Delete report share (DELETE /reports/{reportId}/shares/{shareId})
• Delete dashboard share (DELETE /sights/{sightId}/shares/{shareId})
• Delete workspace share (DELETE /workspaces/{workspaceId}/shares/{shareId})

New replacement endpoints:

• List asset shares (GET /shares) - Retrieves a list of all users and groups to whom the specified asset is shared, and their access level.
• Get asset share (GET /shares/{shareId}) - Retrieves a specific share for the specified asset.
• Share asset (POST /shares)- Shares an asset with the specified users and/or groups.
• Update asset share (PATCH /shares/{shareId})- Updates the share for a specified asset.
• Delete asset share (DELETE /shares/{shareId}) - Deletes the share for a specified asset.

Replacement Mapping:

Migrating from deprecated sharing endpoints

We designed all the new endpoints listed above to scale with new asset types that we introduce at Smartsheet. This means that you can use the same endpoint for various asset types, such as sheets, reports, workspaces, and sights (dashboards). For example, the new endpoints support collections and files.

Use the following query parameters to specify the asset type and instance you're working with:

• assetType - The type of asset you are working with. One of:
  • sheet
  • report
  • workspace
  • sight
  • collection
  • file
• assetId - The ID of the asset you are working with.

Example request: GET https://api.smartsheet.com/2.0/shares?assetType=sheet&assetId=1234567890

We're changing the endpoint contracts; specifically the contracts for endpoints that get shares. As early as the sunset date, we will no longer support offset-based pagination (page, pageSize, etc) in the Sharing endpoints. We will have moved exclusively to token-based pagination. The new endpoints return a lastKey response property if there are more shares on the asset; you can use the lastkey as a request query parameter to retrieve the next set of results.

Example request: GET https://api.smartsheet.com/2.0/shares?assetType=sheet&assetId=1234567890&lastKey=abcDefGhIjKlMnOpQrStUvWxYz

Request and response schema updates

The Sharing category lists the new endpoints and object schemas. The endpoint documentation specifies the query parameters and the returned response.

Here are the new object schemas:

• ShareResponse
• CreateShareRequest
• UpdateShareRequest

As early as the sunset date, we will no longer support the createdAt and updatedAt properties and the Share object.

Furthermore, many of the new endpoint response property values are Strings. By using the String type, we can accommodate numeric or alphanumeric values and provide a consistent and predictable API experience. Make sure to update your code to handle these values as Strings.

2025-07-31

ADDITION:

We added a header named smartsheet-integration-source to track the following service request information:

• Integration type
• Smartsheet organization name
• Client integrator name

Example values:

AI,SampleOrg,My-AI-Connector-v2

SCRIPT,SampleOrg2,Accounting-updater-script

APPLICATION,SampleOrg3,SheetUpdater

We added this header to help us distinguish between human-initiated API requests and those coming from third-party services like AI Connectors or ITSM. As AI adoption grows, AI-based connectors are increasingly frequent sources of public API requests. The header enables us to break down requests by their source, which is crucial for the following reasons:

• Enforce API protective measures: We can better safeguard our systems by understanding the origin of requests.
• Enhance services: We'll gain actionable insights to improve our offerings.
• Innovate new customer capabilities: This data will help us build new features using data-driven approaches and sound AI-connector integration analytics.

For more details, see smartsheet-integration-source in the HTTP headers table.

2025-07-07

FIX:

We removed the modifiedSince parameter from the documentation for the List users (GET /users) operation because the operation doesn't support a modifiedSince parameter.

2025-06-25

IMPROVEMENT:

We migrated the Event Reporting event type definitions to this site and integrated them into the OpenAPI document.

Our new Event types article describes all the event types and links to their schemas and object examples.

2025-06-09

DEPRECATION:

We deprecated webhook traffic through specific known Smartsheet IP addresses. We’re consolidating all Smartsheet API webhook traffic behind a single DNS: webhooks.smartsheet.com. This simplifies firewall management and enhances security. As a result, the origin IP addresses for the webhook verification callbacks sent when enabling a webhook via the Update Webhook (PUT /webhooks/{webhookId}) endpoint have changed.

If you have previously allow-listed Smartsheet IP addresses in your firewall for webhook verification or callbacks, you should allow-list traffic from the following domain:

webhooks.smartsheet.com

Allow-listing the domain ensures successful verification and activation of new webhooks using the Update Webhook endpoint.

IMPORTANT: Until the sunset date mentioned below, if you previously allow-listed the Smartsheet IP addresses in your firewall, you will continue to to receive existing webhook callbacks.

NOTE: This change does not affect the process of registering webhooks via the Create Webhook (POST /webhooks) endpoint or receiving callbacks for webhooks that were enabled prior to this change. Existing Workflow Rules callbacks continue to originate from their current IP addresses until a future migration step. Allow-listing the domain webhooks.smartsheet.com is the recommended approach for future compatibility.

Sunset date: As early as Sep-01-2025, we will discontinue webhook traffic through the above-mentioned Smartsheet IP addresses.

2025-05-15

SUNSET:

To improve the performance of the GET /users/* endpoint operations, we discontinued the sheetCount response attribute behavior for the following endpoint operations:

• GET /users
• GET /users/me
• GET /users/{userId}

The sheetCount attribute previously indicated the total number of sheets owned by the calling user. Now sheetCount consistently returns a value of -1 and is included only if the calling user is active (the user object's status is ACTIVE).

Alternatively, you can call GET /sheets to list all the sheets you (or a user you're impersonating) can access. Each sheet object listed in the response data array shows the user's access level to the sheet. You can filter on sheets with access levels you're interested in for the user. For details on access levels to sheets and other assets, see Resource access levels.

NOTE: If you're a System Admin, you can impersonate another user to list sheets accessible to that user. For impersonation details, see User impersonation.

2025-05-01

FIX:

Corrected the documentation for the Make Alternate Email Primary endpoint POST /users/{userId}/alternateemails/{alternatEmailId}/makeprimary to state that it is only for Enterprise plans with the feature activated by Support.

2025-04-30

ADDITION:

We added the ability to remove users from User Subscription Model (USM) plans via the DELETE /users/{userId} endpoint.

2025-04-24

ADDITION:

For Event Reporting, we now include the email address of the user responsible for the event. The emailAddress property is in each event's additionalDetails property.

For example,

{
    "eventId": "2.1.saN0P9Eg7CAwauk5yRTz1jS5J6q7Fj9OzJJkJJvgtUI",
    "objectType": "SHEET",
    "action": "LOAD",
    "objectId": 2242242917230468,
    "eventTimestamp": "2025-02-04T22:07:39Z",
    "userId": 4159154089682820,
    "requestUserId": 4159154089682820,
    "source": "API_INTEGRATED_APP",
    "additionalDetails": {
        "emailAddress": "john.doe@company.com"
    }
}

NOTE: For event types that already have an additionalDetails.emailAddress property, we preserved their existing email address behavior.

Please see the Events section for event endpoints and the Event types reference article.

2025-04-22

DEPRECATION:

To improve the performance of the GET /users/* endpoints, we deprecated the sheetCount response attribute for the following endpoint operations:

• GET /users
• GET /users/me
• GET /users/{userId}

Sunset date: May-12-2025

As early as the above sunset date, the current sheetCount behavior will be discontinued, and sheetCount will instead hold the value -1 and be included only if the user's status is ACTIVE.

2025-04-21

FIX:

We fixed the transferTo query parameter type of DELETE /users/{userId} from number to integer, with format: int64.

2025-04-16

FIX:

We fixed the DELETE /users/{userId} specification to reflect that the endpoint takes the following parameters as query parameters--not body parameters:

• removeFromSharing
• transferSheets
• transferTo

2025-04-07

FIX:

We removed the Search result item schema's proofUrl property and mention a proof URL as a possible contextData property item. The Search endpoint responses never included a proofUrl property--a proof URL was always a possible string value in the context data.

2025-04-01

IMPROVEMENT:

With the User Subscription Model (USM), you can now deactivate and reactivate users with non-ISP domain primary email addresses belonging to your plan.

Regarding user reactivation, you can now reactivate a user to your plan if the user has been deactivated less than 30 days. The previous threshold was 7 days.

2025-03-31

SUNSET:

We removed the following properties from GET /sights/{sightId} response.

• favorite has been deprecated since July 2024.
• workspace.accessLevel has never been included in the response.
• workspace.permalink has never been included in the response.

2025-03-25

DEPRECATION:

We deprecated the "Sheets" folder and are replacing it with Workspaces for a more streamlined experience.

Sunset date: Jun-01-2025

We're providing access to the following API endpoints associated with the "Sheets" folder until the above sunset date.

• GET /home
• GET /home/folders
• GET /folders/personal
• POST /sheets
• POST /sheets/import
• POST /home/folders

As part of this deprecation, we deprecated the home destinationType enum in folder and sheets endpoints.

Learn how to update your code to these changes at Migrate from using the Sheets folder.

2025-03-14

FIX:

We updated the Event schema documentation to provide more accurate examples and comprehensive information:

• Updated the eventId example to match the actual format used in production
• Expanded the objectType enum to include all possible resource types
• Fixed the property name from eventTimeStamp to eventTimestamp
• Updated the source field description and added the complete list of possible values

2025-03-11

FIX:

We fixed the Criteria schema's operator property to include the enum value IS_ONE_OF. The value has been part of the schema implementation and is listed in the example but missing from the property documentation.

2025-03-07

FIX:

We fixed the Assume-User header description. The header allows System Administrators (admins) to impersonate or act on behalf of any user (including other admins) in their plan to make API calls. For details, see User Impersonation.

2025-03-04

ADDITION:

We added the POST filteredEvents endpoint. This endpoint allows non-admin users to retrieve events for sheets and workspaces that they have access to.

2025-03-03

DEPRECATION REVERT:

We reverted deprecation notices for the following endpoint methods:

• GET /folders/{folderId}
• GET /workspaces
• GET /workspaces/{workspaceId}

See 2025-02-01 for the original change.

ADDITION REVERT:

We removed the 'lastKey' query parameter from the GET /workspaces endpoint method.

See 2025-02-18 for the original change.

2025-02-18

ADDITION:

We added the lastKey query parameter and response property for the GET /workspaces endpoint method. This is the new and recommended way to get paginated workspace results. The pageSize query parameter is used in conjunction with lastKey--the page and includeAll query parameters remain deprecated and will be removed.

2025-02-12

SUNSET:

We removed the permalink option from the include query parameter for the following endpoint methods because the option has never been supported:

• GET /folders/{folderId}
• GET /folders/personal

2025-02-10

FIX:

We corrected response schemas for the following endpoint methods:

• GET /folders/{folderId}
• GET /workspaces/{workspaceId}

2025-02-03

DEPRECATION:

We deprecated the distributionLink and sheetVersion options for the include query parameter on the following endpoint methods:

• GET /folders/{folderId}
• GET /workspaces/{workspaceId}

The corresponding response properties will soon stop providing meaningful values.

DEPRECATION:

We deprecated the loadAll query parameter on the GET /folders/{folderId} endpoint method, and we will eventually remove it. To replace the loadAll query parameter, use calls to GET /folders/{folderId} to build out workspace structures.

FIX:

Regarding the ownerInfo option for the include query parameter, we clarified which user is returned when no user is an Owner of the asset.

2025-02-01

DEPRECATION:

We deprecated the includeAll and page params for the following endpoint methods:

• GET /folders/{folderId}/folders
• GET /workspaces
• GET /workspaces/{workspaceId}/folders

We deprecated the following response properties because they are irrelevant to the new pagination system.

• pageNumber
• totalCount
• totalPages

2025-01-22

IMPROVEMENT:

We now automatically deactivate Webhooks on sheets exceeding any scale limits.

Scale limits:

• 20,000 rows
• 400 columns
• 500,000 cells

Related resources:

• Webhook Status has a new related status
• Webhook Error Codes has new related error codes

To keep webhooks enabled on a sheet, stay below the limits mentioned above.

As a sheet Owner, you can re-enable webhooks on a sheet by following these steps:

1. Reduce the sheet size to within the limits mentioned above.
2. Execute the PUT /webhooks/{webhookId} method with the enabled body attribute set to true.

Related resources:

• Webhook Status has a new related status.
• Webhook Error Codes has new related error codes.

2024-10-14

IMPROVEMENT:

For Smartsheet US and Smartsheet Regions Europe, we introduced a one-minute debounce to optimize event trigger handling in the Webhooks event callback API. It reduces traffic and prevents workflows from acting on incomplete or transitional data.

2024-10-09

FIX:

We updated the WebContentWidgetContent.type enum, from WEBCONTENT to WidgetWebContent. The former enum WEBCONTENT was incorrect.