{"id":12046,"library":"smartsheet","title":"Smartsheet JavaScript SDK","description":"The Smartsheet JavaScript SDK, currently at version 4.7.2, provides an official client library for interacting with the Smartsheet API from Node.js applications. It ships with comprehensive TypeScript types, facilitating development in type-safe environments. The SDK maintains an active and consistent release cadence, frequently introducing minor versions with new features, API endpoint support, and critical bug fixes, as evidenced by recent updates adding new sharing, workspace, and folder endpoints, alongside improvements to retry mechanisms and pagination. It differentiates itself as the directly supported client, offering extensive coverage of the Smartsheet API's functionalities. Developers can initialize the client using an access token obtained from the Smartsheet UI and leverage promise-based methods for operations such as listing and loading sheets, managing users, and handling attachments. The SDK requires actively supported Node.js versions 14.x or later for optimal compatibility and robust operation.","status":"active","version":"4.7.2","language":"javascript","source_language":"en","source_url":"https://github.com/smartsheet/smartsheet-javascript-sdk","tags":["javascript","Smartsheet","productivity","collaboration","typescript"],"install":[{"cmd":"npm install smartsheet","lang":"bash","label":"npm"},{"cmd":"yarn add smartsheet","lang":"bash","label":"yarn"},{"cmd":"pnpm add smartsheet","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"For modern ESM usage, `createClient` is a named export. The SDK's README still shows a CommonJS `require` pattern for the full module object.","wrong":"import smartsheet from 'smartsheet'; const client = smartsheet.createClient(...);","symbol":"createClient","correct":"import { createClient } from 'smartsheet';"},{"note":"While the README uses the older `const client = require('smartsheet'); const smartsheet = client.createClient(...)` pattern, destructuring is generally preferred in CommonJS for clarity.","wrong":"const smartsheet = require('smartsheet'); const client = smartsheet.createClient(...);","symbol":"createClient (CommonJS)","correct":"const { createClient } = require('smartsheet');"},{"note":"When importing types in TypeScript, it's best practice to use `import type` to ensure they are stripped during compilation.","wrong":"import { SmartsheetClient } from 'smartsheet';","symbol":"SmartsheetClient (Type)","correct":"import type { SmartsheetClient } from 'smartsheet';"}],"quickstart":{"code":"import { createClient } from 'smartsheet';\n\nconst accessToken = process.env.SMARTSHEET_ACCESS_TOKEN ?? ''; // Load from environment variable for security\n\nif (!accessToken) {\n  console.error('Error: SMARTSHEET_ACCESS_TOKEN environment variable is not set.');\n  process.exit(1);\n}\n\n// Initialize the client\nconst smartsheet = createClient({\n  accessToken: accessToken,\n  logLevel: 'info' // Can be 'info', 'warn', 'error', 'debug'\n});\n\n// Set queryParameters for `include` and pagination\nconst options = {\n  queryParameters: {\n    include: 'attachments',\n    includeAll: true\n  }\n};\n\nasync function listAndLoadSheets() {\n  try {\n    // List all sheets\n    const result = await smartsheet.sheets.listSheets(options);\n    if (result.data && result.data.length > 0) {\n      const sheetId = result.data[0].id; // Choose the first sheet\n\n      // Load one sheet\n      const sheetInfo = await smartsheet.sheets.getSheet({ sheetId: sheetId });\n      console.log('Successfully loaded sheet:', sheetInfo.name, 'with ID:', sheetInfo.id);\n      // console.log(JSON.stringify(sheetInfo, null, 2)); // Uncomment to see full sheet data\n    } else {\n      console.log('No sheets found in your Smartsheet account.');\n    }\n  } catch (error) {\n    console.error('An error occurred:', error);\n  }\n}\n\nlistAndLoadSheets();","lang":"typescript","description":"This quickstart demonstrates how to initialize the Smartsheet client, list all available sheets, and then load the details of the first sheet found using asynchronous `await` syntax."},"warnings":[{"fix":"Migrate your code to use the newly introduced sharing endpoints. Refer to the Smartsheet API documentation for the updated methods.","message":"Older sharing endpoints were deprecated in favor of new ones. Existing code using the deprecated endpoints may eventually break or behave unexpectedly.","severity":"breaking","affected_versions":">=4.7.0"},{"fix":"Replace calls to `getWorkspace()` with `smartsheet.workspaces.getWorkspaceMetadata(id)` and `smartsheet.workspaces.getWorkspaceChildren(id)`. Apply similar changes for folder methods.","message":"The `getWorkspace()` and `getFolder()` methods were deprecated. Developers must now use `getWorkspaceMetadata()` paired with `getWorkspaceChildren()` (and similarly for folders) to retrieve equivalent data.","severity":"breaking","affected_versions":">=4.4.0"},{"fix":"Upgrade to version 4.2.3 or later to ensure correct retry behavior for all HTTP methods.","message":"Versions prior to 4.2.3 had a bug where the request body was not correctly resent during retries for POST/PUT methods, potentially leading to data loss or incorrect state on intermittent network failures.","severity":"gotcha","affected_versions":"<4.2.3"},{"fix":"Ensure your Node.js environment is actively supported (v14.x or later). Update Node.js to a compatible version.","message":"The Smartsheet SDK requires Node.js version 14.x or later. Using older, unsupported Node.js versions may lead to unexpected errors, security vulnerabilities, or installation failures.","severity":"gotcha","affected_versions":"<any"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Provide a valid Smartsheet API access token, ideally through an environment variable like `SMARTSHEET_ACCESS_TOKEN`, or directly in the `createClient` call (not recommended for production).","cause":"The Smartsheet client was initialized without an access token, or the token was invalid.","error":"Error: SMARTSHEET_ACCESS_TOKEN environment variable is not set."},{"fix":"Update your code to use the new methods introduced in v4.4.0: `getWorkspaceMetadata()` and `getWorkspaceChildren()` for workspaces, and `getFolderMetadata()` and `getFolderChildren()` for folders.","cause":"Attempting to call a deprecated method (`getWorkspace` or `getFolder`) that has been removed or replaced in newer SDK versions.","error":"TypeError: smartsheet.sheets.getWorkspace is not a function"},{"fix":"Ensure `npm install smartsheet` has been run. For ESM, use `import { createClient } from 'smartsheet';`. For CommonJS, use `const { createClient } = require('smartsheet');`. Check your `package.json` `type` field if encountering issues in mixed environments.","cause":"Incorrect module import path or attempting a CommonJS `require` in an ESM module without proper configuration (or vice versa).","error":"ERR_MODULE_NOT_FOUND: Cannot find module 'smartsheet'"}],"ecosystem":"npm"}