Smartsheet logo

Methods

Get Folder

Gets a Folder object.

Authorizations:
APITokenOAuth2 (READ_SHEETS)
path Parameters
folderId
required
number

Folder Id where you can create sheets, sights, reports, templates, and other folders.

query Parameters
include
string

A comma-separated list of optional elements to include in the response:

  • source - adds the Source object indicating which object the folder was created from, if any
  • distributionLink
  • ownerInfo Returns the user with owner permissions, or the user with admin permissions if there is no owner assigned. If no owner or admins are assigned, the Plan Asset Admin is returned. If no Plan Asset Admin is assigned, the System Admin is returned.
  • sheetVersion
Enum: "source" "distributionLink" "ownerInfo" "sheetVersion"
header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789

Responses

Request samples 

curl https://api.smartsheet.com/2.0/folders/{folderId} \
-H " Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789"

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "favorite": true,
  • "permalink": "string",
  • "folders": [
    ],
  • "reports": [
    ],
  • "sheets": [
    ],
  • "sights": [
    ],
  • "templates": [
    ]
}

Delete Folder

Deletes a folder.

Authorizations:
APITokenOAuth2 (ADMIN_WORKSPACES)
path Parameters
folderId
required
number

Folder Id where you can create sheets, sights, reports, templates, and other folders.

header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789

Responses

Request samples 

curl https://api.smartsheet.com/2.0/folders/{folderId} \
-H " Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789" \
-X DELETE

Response samples

Content type
application/json
{
  • "message": "SUCCESS",
  • "resultCode": 0
}

Update Folder

Updates a folder.

Authorizations:
APITokenOAuth2 (ADMIN_WORKSPACES)
path Parameters
folderId
required
number

Folder Id where you can create sheets, sights, reports, templates, and other folders.

header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789
Request Body schema: application/json
any

Responses

Request samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "favorite": true,
  • "permalink": "string",
  • "folders": [
    ],
  • "reports": [
    ],
  • "sheets": [
    ],
  • "sights": [
    ],
  • "templates": [
    ]
}

Response samples

Content type
application/json
{
  • "version": 0,
  • "failedItems": [
    ],
  • "message": "SUCCESS",
  • "resultCode": 0,
  • "result": {
    }
}

Copy Folder

Copies a folder.

Authorizations:
APITokenOAuth2 (ADMIN_WORKSPACES)
path Parameters
folderId
required
number

Folder Id where you can create sheets, sights, reports, templates, and other folders.

query Parameters
include
string

A comma-separated list of elements to copy:

  • attachments
  • cellLinks - includes cross-sheet references
  • data - includes formatting
  • discussions - includes comments
  • filters
  • forms
  • ruleRecipients -- includes notification recipients, must also include rules when using this attribute
  • rules -- includes notifications and workflow rules
  • shares | NOTE: Cell history is not copied, regardless of which include parameter values are specified.
Enum: "attachments" "cellLinks" "data" "discussions" "filters" "forms" "ruleRecipients" "rules" "shares"
exclude
string

When specified with a value of sheetHyperlinks, excludes this category from the response

Value: "sheetHyperlinks"
skipRemap
string

A comma-separated list of references to NOT re-map for the newly created folder.

Enum: "cellLinks" "reports" "sheetHyperlinks" "sights"
header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789
Content-Type
string
Default: application/json

Required for POST and PUT requests. Defines the structure for the request body.

Request Body schema: application/json

New folder name.

One of
destinationId
number

The Id of the destination container (when copying or moving a sheet or a folder). Required if destinationType is "folder" or "workspace". If destinationType is "home", this value must be null.

destinationType
string Nullable

Type of the destination container.

Enum: "folder" "home" "workspace"
newName
string

Name of the newly created object (when creating a copy of a dashboard, folder, sheet, or workspace). This attribute is not supported for "move" operations.

Responses

Request samples

Content type
application/json
{
  • "destinationId": 0,
  • "destinationType": "folder",
  • "newName": "string"
}

Response samples

Content type
application/json
{
  • "destinationId": 0,
  • "destinationType": "folder",
  • "newName": "string"
}

List Folders

Gets a list of folders in a given folder. The list contains an abbreviated Folder object for each folder.

Authorizations:
APITokenOAuth2 (READ_SHEETS)
path Parameters
folderId
required
number

Folder Id where you can create sheets, sights, reports, templates, and other folders.

query Parameters
includeAll
boolean
Default: false

(Deprecated as of February 1, 2025, and will be removed. A replacement is coming soon.) If true, include all results, that is, do not paginate. Mutually exclusive with page and pageSize (they are ignored if includeAll=true is specified).

page
number
Default: 1

(Deprecated as of February 1, 2025, and will be removed. A replacement is coming soon.) Which page to return. Defaults to 1 if not specified. If you specify a value greater than the total number of pages, the last page of results is returned.

pageSize
number
Default: 100

The maximum number of items to return per page. Unless otherwise stated for a specific endpoint, defaults to 100. If only page is specified, defaults to a page size of 100. For reports, the default is 100 rows. If you need larger sets of data from your report, returns a maximum of 10,000 rows per request.

header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789

Responses

Request samples 

curl https://api.smartsheet.com/2.0/folders/{folderId}/folders \ 
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789" \ 
-H "Content-Type: application/json"

Response samples

Content type
application/json
{
  • "pageNumber": 1,
  • "pageSize": 50,
  • "totalPages": 25,
  • "totalCount": 136,
  • "result": [
    ]
}

Create Folder

Creates a new folder.

Authorizations:
APITokenOAuth2 (ADMIN_WORKSPACES)
path Parameters
folderId
required
number

Folder Id where you can create sheets, sights, reports, templates, and other folders.

query Parameters
include
string

A comma-separated list of elements to copy:

  • attachments
  • cellLinks - includes cross-sheet references
  • data - includes formatting
  • discussions - includes comments
  • filters
  • forms
  • ruleRecipients -- includes notification recipients, must also include rules when using this attribute
  • rules -- includes notifications and workflow rules
  • shares | NOTE: Cell history is not copied, regardless of which include parameter values are specified.
Enum: "attachments" "cellLinks" "data" "discussions" "filters" "forms" "ruleRecipients" "rules" "shares"
exclude
string

When specified with a value of sheetHyperlinks, excludes this category from the response

Value: "sheetHyperlinks"
skipRemap
string

A comma-separated list of references to NOT re-map for the newly created folder.

Enum: "cellLinks" "reports" "sheetHyperlinks" "sights"
header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789
Content-Type
string
Default: application/json

Required for POST and PUT requests. Defines the structure for the request body.

Request Body schema: application/json

Folder to create.

One of
id
number

Folder Id.

name
string

Folder name.

favorite
boolean

(Deprecated) Returned only if the user has marked the folder as a favorite in their "Home" tab (value = true).

permalink
string

URL that represents a direct link to the folder in Smartsheet.

Array of objects

Folders contained in folder.

Array of objects

Reports contained in folder.

Array of objects

Sheets contained in folder.

Array of objects

Dashboards contained in folder.

Array of objects

Templates contained in folder.

Responses

Request samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "favorite": true,
  • "permalink": "string",
  • "folders": [
    ],
  • "reports": [
    ],
  • "sheets": [
    ],
  • "sights": [
    ],
  • "templates": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "SUCCESS",
  • "resultCode": 0,
  • "result": {
    }
}

Move Folder

Moves a folder.

Authorizations:
APITokenOAuth2 (ADMIN_WORKSPACES)
path Parameters
folderId
required
number

Folder Id where you can create sheets, sights, reports, templates, and other folders.

header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789
Content-Type
string
Default: application/json

Required for POST and PUT requests. Defines the structure for the request body.

Request Body schema: application/json

New folder destination.

One of
destinationId
number

The Id of the destination container (when copying or moving a sheet or a folder). Required if destinationType is "folder" or "workspace". If destinationType is "home", this value must be null.

destinationType
string Nullable

Type of the destination container.

Enum: "folder" "home" "workspace"
newName
string

Name of the newly created object (when creating a copy of a dashboard, folder, sheet, or workspace). This attribute is not supported for "move" operations.

Responses

Request samples

Content type
application/json
{
  • "destinationId": 0,
  • "destinationType": "folder",
  • "newName": "string"
}

Response samples

Content type
application/json
{
  • "destinationId": 0,
  • "destinationType": "folder",
  • "newName": "string"
}
➔ Next to Groups Basics