Smartsheet logo

Methods

List Workspaces

Gets a list of workspaces that the user has access to. The list contains an abbreviated Workspace object for each workspace.

Authorizations:
APITokenOAuth2 (READ_SHEETS)
query Parameters
accessApiLevel
number
Default: 0

Allows COMMENTER access for inputs and return values. For backwards-compatibility, VIEWER is the default. For example, to see whether a user has COMMENTER access for a sheet, use accessApiLevel=1.

includeAll
boolean
Default: false

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

Which page to return. Defaults to 1 if not specified. If you specify a value greater than the total number of pages, you'll receive an empty data set.

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/workspaces \
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789"

Response samples

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

Create Workspace

Creates a new workspace.

Authorizations:
APITokenOAuth2 (ADMIN_WORKSPACES)
query Parameters
accessApiLevel
number
Default: 0

Allows COMMENTER access for inputs and return values. For backwards-compatibility, VIEWER is the default. For example, to see whether a user has COMMENTER access for a sheet, use accessApiLevel=1.

include
string

A comma-separated list of elements to include:

  • all
  • attachments
  • brand
  • cellLinks - includes cross-sheet references
  • data - includes formatting
  • discussions - includes comments
  • filters
  • forms
  • ruleRecipients
  • rules
  • shares NOTE: Cell history is not copied, regardless of which include parameter values are specified.
Enum: "all" "attachments" "brand" "cellLinks" "data" "discussions" "filters" "forms" "ruleRecipients" "rules" "shares"
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

Workspace to create.

One of
id
number

Workspace Id.

name
string

Workspace name.

accessLevel
string
Enum: "ADMIN" "COMMENTER" "EDITOR" "EDITOR_SHARE" "OWNER" "VIEWER"
permalink
string

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

Responses

Request samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "accessLevel": "ADMIN",
  • "permalink": "string"
}

Response samples

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

Get Workspace

Gets a Workspace object.

Authorizations:
APITokenOAuth2 (READ_SHEETS)
path Parameters
workspaceId
required
string

WorkspaceID of the worksheet being accessed.

query Parameters
accessApiLevel
number
Default: 0

Allows COMMENTER access for inputs and return values. For backwards-compatibility, VIEWER is the default. For example, to see whether a user has COMMENTER access for a sheet, use accessApiLevel=1.

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
  • sheetVersion
  • permalinks
Enum: "source" "distributionLink" "ownerInfo" "sheetVersion" "permalinks"
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/workspaces/{workspaceid} \
 -H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789"

Response samples

Content type
application/json
{
  • "id": 0,
  • "name": "string",
  • "accessLevel": "ADMIN",
  • "permalink": "string"
}

Delete Workspace

Deletes a workspace.

Authorizations:
APITokenOAuth2 (ADMIN_WORKSPACES)
path Parameters
workspaceId
required
string

WorkspaceID of the worksheet being accessed.

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/workspaces/7960873114331012 \ 
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789" \ 
-X DELETE

Response samples

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

Update Workspace

Updates a workspace.

Authorizations:
APITokenOAuth2 (ADMIN_WORKSPACES)
path Parameters
workspaceId
required
string

WorkspaceID of the worksheet being accessed.

query Parameters
accessApiLevel
number
Default: 0

Allows COMMENTER access for inputs and return values. For backwards-compatibility, VIEWER is the default. For example, to see whether a user has COMMENTER access for a sheet, use accessApiLevel=1.

header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789
Request Body schema: application/json
name
string

Workspace name.

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

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

Copy Workspace

Copies a workspace.

Authorizations:
APITokenOAuth2 (ADMIN_WORKSPACES)
path Parameters
workspaceId
required
string

WorkspaceID of the worksheet being accessed.

query Parameters
include
string

A comma-separated list of elements to include:

  • all
  • attachments
  • brand
  • cellLinks - includes cross-sheet references
  • data - includes formatting
  • discussions - includes comments
  • filters
  • forms
  • ruleRecipients
  • rules
  • shares NOTE: Cell history is not copied, regardless of which include parameter values are specified.
Enum: "all" "attachments" "brand" "cellLinks" "data" "discussions" "filters" "forms" "ruleRecipients" "rules" "shares"
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 workspace 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"
}

Get Workspace folders

Gets a workspace's folders.

Authorizations:
APITokenOAuth2 (READ_SHEETS)
path Parameters
workspaceId
required
string

WorkspaceID of the worksheet being accessed.

query Parameters
includeAll
boolean
Default: false

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

Which page to return. Defaults to 1 if not specified. If you specify a value greater than the total number of pages, you'll receive an empty data set.

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/workspaces/{workspaceId}/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 a Folder

Creates a new folder.

Authorizations:
APITokenOAuth2 (ADMIN_WORKSPACES)
path Parameters
workspaceId
required
string

WorkspaceID of the worksheet being accessed.

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.

name
string

Folder name.

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

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

Share Workspace

Shares a Workspace with the specified users and groups. This operation supports both single-object and bulk semantics.

This operation is only available to system administrators.

Authorizations:
APITokenOAuth2 (ADMIN_WORKSPACES)
path Parameters
workspaceId
required
string

WorkspaceID of the worksheet being accessed.

query Parameters
accessApiLevel
number
Default: 0

Allows COMMENTER access for inputs and return values. For backwards-compatibility, VIEWER is the default. For example, to see whether a user has COMMENTER access for a sheet, use accessApiLevel=1.

sendEmail
boolean
Default: false

Either true or false to indicate whether to notify the user by email. Default is false. If true, limit is 1000 emails.

header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789
Request Body schema: application/json
One of
id
string

Share Id.

NOTE: unlike other Smartsheet object Ids, this Id is an alphanumeric string.

groupId
number

Group Id if the share is a group share, else null.

userId
number

User Id if the share is a user share, else null.

type
string

The type of this share. One of the following values: GROUP or USER.

accessLevel
string
Enum: "ADMIN" "COMMENTER" "EDITOR" "EDITOR_SHARE" "OWNER" "VIEWER"
ccMe
boolean

Indicates whether to send a copy of the email to the sharer of the sheet. You can specify this attribute in a request, but it is never present in a response.

email
string

User's primary email address for user shares; null for group shares.

message
string

The message included in the body of the email that is optionally sent to the recipient. You can specify this attribute in a request, but it is never present in a response.

name
string

If a user share and user is also a contact, the user's full name. If a group share, the group's name.

scope
string

The scope of this share. One of the following values:

  • ITEM: an item-level share (that is, the specific object to which the share applies is shared with the user or group).
  • WORKSPACE: a workspace-level share (that is, the workspace that contains the object to which the share applies is shared with the user or group).
subject
string

The subject of the email that is optionally sent to notify the recipient. You can specify this attribute in a request, but it is never present in a response.

Responses

Request samples

Content type
application/json
[ ]

Response samples

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

List Workspace Shares

Gets a list of all users and groups to whom the specified Workspace is shared, and their access level.

Authorizations:
APITokenOAuth2 (READ_SHEETS)
path Parameters
workspaceId
required
string

WorkspaceID of the worksheet being accessed.

query Parameters
accessApiLevel
number
Default: 0

Allows COMMENTER access for inputs and return values. For backwards-compatibility, VIEWER is the default. For example, to see whether a user has COMMENTER access for a sheet, use accessApiLevel=1.

page
number
Default: 1

Which page to return. Defaults to 1 if not specified. If you specify a value greater than the total number of pages, you'll receive an empty data set.

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.

includeAll
boolean
Default: false

If true, include all results, that is, do not paginate. Mutually exclusive with page and pageSize (they are ignored if includeAll=true is specified).

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/workspaces/{workspaceId}/shares \
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789"

Response samples

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

Get Workspace Share

Gets the share specified in the URL.

Authorizations:
APITokenOAuth2 (READ_SHEETS)
path Parameters
workspaceId
required
string

WorkspaceID of the worksheet being accessed.

shareId
required
string

Share Id.

query Parameters
accessApiLevel
number
Default: 0

Allows COMMENTER access for inputs and return values. For backwards-compatibility, VIEWER is the default. For example, to see whether a user has COMMENTER access for a sheet, use accessApiLevel=1.

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/workspaces/{workspaceId}/shares/{shareId} \
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789"

Response samples

Content type
application/json
{
  • "id": "string",
  • "groupId": 0,
  • "userId": 0,
  • "type": "string",
  • "accessLevel": "ADMIN",
  • "ccMe": true,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "email": "string",
  • "message": "string",
  • "modifiedAt": "2019-08-24T14:15:22Z",
  • "name": "string",
  • "scope": "string",
  • "subject": "string"
}

Delete Workspace Share

Deletes the share specified in the URL.

This operation is only available to system administrators.

Authorizations:
APITokenOAuth2 (ADMIN_WORKSPACES)
path Parameters
workspaceId
required
string

WorkspaceID of the worksheet being accessed.

shareId
required
string

Share Id.

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/workspaces/{workspaceId}/shares/{shareId} \
-H "Authorization: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789" \
-X DELETE

Response samples

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

Update Workspace Share

Updates the access level of a user or group for the specified workspace.

This operation is only available to system administrators.

Authorizations:
APITokenOAuth2 (ADMIN_WORKSPACES)
path Parameters
workspaceId
required
string

WorkspaceID of the worksheet being accessed.

shareId
required
string

Share Id.

query Parameters
accessApiLevel
number
Default: 0

Allows COMMENTER access for inputs and return values. For backwards-compatibility, VIEWER is the default. For example, to see whether a user has COMMENTER access for a sheet, use accessApiLevel=1.

header Parameters
Authorization
string

API Access Token used to authenticate requests to Smartsheet APIs.

Example: Bearer JKlMNOpQ12RStUVwxYZAbcde3F5g6hijklM789
Request Body schema: application/json
accessLevel
string
Enum: "ADMIN" "COMMENTER" "EDITOR" "EDITOR_SHARE" "OWNER" "VIEWER"

Responses

Request samples

Content type
application/json
{
  • "accessLevel": "ADMIN"
}

Response samples

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