Revisions Methods


Using the revisions methods of the Tableau Server REST API you can:

  • Get a list of all revisions of a workbook or data source
  • Download or delete a specific workbook or data source revision with or without its extract

This functionality relates to the UI elements and concepts described at: Allow Users to Save Revision History(Link opens in a new window).

Download Data Source Revision

Downloads a specific version of a data source prior to the current one in .tdsx format. To down load the current version of a data source use the Download Data Source method.

Note: This method is available only if version history is enabled for the specified site. For more information, see Maintain a History of Revisions(Link opens in a new window) in the Tableau Server Help.

URI

GET /api/api-version/sites/site-id/datasources/datasource-id/revisions/revision-number/content

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the data source.
datasource-id The ID of the data source to download.
revision-number The revision number of the data source to download. To determine what versions are available, call Get Data Source Revisions.

Request Body

None

Permissions

Tableau Server users who are site administrators can download data source revisions on the site that they are administrators for. Users who are not server administrators or site administrators can get data source revisions if they have all of the following:

  • A site role of ExplorerCanPublish.
  • Read (view), Write (save), and Download (save as) permissions for the specified data source.
  • Save (write) permissions for the project that contains the data source.

Response Code

200

Response Body

The data source content in .tdsx format (Content-Type: application/octet-stream).

The response will have the following content disposition header:

Content-Disposition: name="tableau_datasource"; filename="datasource-filename"

Version

Version 2.3 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
403 403028 Read forbidden A non-administrator user attempted to download a data source, but the caller doesn't have required permissions.
403 403053 Version history not enabled version history is not enabled for the specified site.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404004 Data source not found The data source ID in the URI doesn't correspond to an existing data source.
404 404024 Data source revision not found The revision number in the URI doesn't correspond to an existing data source revision.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Download Workbook Revision

Downloads a specific version of a workbook in .twb or .twbx format.

Note: This method is available only if version history is enabled for the specified site. For more information, see

Security note: Content in .twb or .twbx files downloaded using this method is stored in plain text. All data, including filter values that may give semantic clues to the data, will be readable by anyone who opens the files.

Maintain a History of Revisions(Link opens in a new window) in the Tableau Server Help.

URI

GET /api/api-version/sites/site-id/workbooks/workbook-id/revisions/revision-number/content

GET /api/api-version/sites/site-id/workbooks/workbook-id/revisions/revision-number/content?includeExtract=extract-value

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the workbook.
workbook-id The ID of the workbook to download.
revision-number The revision number of the workbook to download. To determine what versions are available, call Get Workbook Revisions. Note that the current revision of a workbook cannot be accessed by this call; use Download Workbook instead.
extract-value (Optional) The extract-value is a Boolean value (False or True). When the workbook specified for download has an extract, if you add the parameter ?includeExtract=False, the extract is not included when you download the workbook. You can use this option to improve performance if you are downloading workbooks or data sources that have large extracts.

Request Body

None

Permissions

Users who are site administrators can download workbook revisions on the site that they are administrators for. Users who are not server administrators or site administrators can download workbook revisions if they have all of the following:

  • A site role of ExplorerCanPublish.
  • Read (view), Write (save), and Download (save as) permissions for the specified workbook.
  • Save (write) permissions for the project that contains the workbook.

Required scope for JWT authorization

Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).

Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.

tableau:workbooks:download

Response Code

200

Response Body

One of the following, depending on the format of the workbook:

  • The workbook's content in .twb format (Content-Type: application/xml)
  • The workbook's content in .twbx format (Content-Type: application/octet-stream)

In both cases, the response will have the following content disposition header:

Content-Disposition: name="tableau_workbook"; filename="workbook-filename"

Version

Version 2.3 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
403 403053 Version history not enabled version history is not enabled for the specified site.
403 403019 Read forbidden A non-administrator user attempted to download a workbook, but the caller doesn't have required permissions.
404 404024 Workbook revision not found The revision number in the URI doesn't correspond to an existing data source revision.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404006 Workbook not found The workbook ID in the URI doesn't correspond to an existing workbook.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Get Data Source Revisions

Returns a list of revision information (history) for the specified data source.

Note: This method is available only if version history is enabled for the specified site. For more information, see Maintain a History of Revisions(Link opens in a new window) in the Tableau Server Help.

To get a specific version of the data source from revision history, use the Download Data Source Revision method.

URI

GET /api/api-version/sites/site-id/datasources/datasource-id/revisions

GET /api/api-version/sites/site-id/datasources/datasource-id/revisions?pageSize=page-size&pageNumber=page-number

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the data source to get revisions for.
datasource-id The ID of the data source to get revisions for.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.

Request Body

None

Permissions

Tableau Server users who are site administrators can get data source revisions on the site that they are administrators for. Users who are not server administrators or site administrators can get data source revisions if they have all of the following:

  • A site role of ExplorerCanPublish.
  • Read (view), Write (save), and Download (save as) permissions for the specified data source.
  • Save (write) permissions for the project that contains the data source.

Response Code

200

Response Body

<tsResponse>
  <pagination pageNumber="pageNumber" pageSize="page-size"
       totalAvailable="total-available" />
  <revisions>
    <revision createdAt="date" revisionNumber="1" isDeleted="false">
      <user id="user-id" name="user-name"/>
    </revision>
    <revision createdAt="date" revisionNumber="2" isDeleted="false">
    </revision>
    <revision createdAt="date" revisionNumber="3" isCurrent="true">
        <user id="user-id" name="user-name"/>
    </revision>
  </revisions>
</tsResponse>

If the revision element includes the attribute isDeleted="true", the data source has been deleted and cannot be downloaded using the Download Data Source Revision method.

If a user has been deleted from the site, no <user> element is included in the <revision> element.

Version

Version 2.3 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400006 Invalid page number The page number parameter is not an integer, is less than one, or is greater than the final page number for data sources at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
403 403014 Page size limit exceeded The specified page size is larger than the maximum page size.
403 403053 Version history not enabled version history is not enabled for the specified site.
403 403054 A non-administrator user attempted to get data source revision information, but the caller doesn't have sufficient permissions.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 Data source not found The data source ID in the URI doesn't correspond to an existing data source.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Get Workbook Revisions

Returns a list of revision information (history) for the specified workbook.

Note: This method is available only if version history is enabled for the specified site.

To get a specific version of the workbook from revision history, use the Download Workbook Revision method. For more information, see Maintain a History of Revisions(Link opens in a new window) in the Tableau Server Help.

URI

GET /api/api-version/sites/site-id/workbooks/workbook-id/revisions

GET /api/api-version/sites/site-id/workbooks/workbook-id/revisions?pageSize=page-size&pageNumber=page-number

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the workbook to get revisions for.
workbook-id The ID of the workbook to get revisions for.
page-size (Optional) The number of items to return in one response. The minimum is 1. The maximum is 1000. The default is 100. For more information, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.

Request Body

None

Permissions

Tableau Server users who are site administrators can get workbook revisions on the site that they are administrators for. Users who are not server administrators or site administrators can get workbook revisions if they have all of the following:

  • A site role of ExplorerCanPublish.
  • Read (view), Write (save), and Download (save as) permissions for the specified workbook.
  • Save (write) permissions for the project that contains the workbook.

Response Code

200

Response Body

<tsResponse>
  <pagination pageNumber="pageNumber" pageSize="page-size"
       totalAvailable="total-available" />
  <revisions>
    <revision createdAt="date" revisionNumber="1" isDeleted="false">
      <user id="user-id" name="user-name"/>
    </revision>
    <revision createdAt="date" revisionNumber="2" isDeleted="false">
    </revision>
    <revision createdAt="date" revisionNumber="3" isCurrent="true">
        <user id="user-id" name="user-name"/>
    </revision>
  </revisions>
</tsResponse>

If the revision element includes the attribute isDeleted="true", the workbook has been deleted and cannot be downloaded using the Download Workbook Revision method.

If a user has been deleted from the site, no <user> element is included in the <revision> element.

Version

Version 2.3 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
400 400006 Invalid page number The page number parameter is not an integer, is less than one, or is greater than the final page number for data sources at the requested page size.
400 400007 Invalid page size The page size parameter is not an integer, or is less than one.
403 403014 Page size limit exceeded The specified page size is larger than the maximum page size.
403 403053 Version history not enabled version history is not enabled for the specified site.
403 403056 A non-administrator user attempted to get workbook revision information, but the caller doesn't have sufficient permissions.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404006 Workbook not found The workbook ID in the URI doesn't correspond to an existing workbook.
405 405000 Invalid request method Request type was not GET.

For more information, see Handling Errors.

Remove Data Source Revision

Removes a specific version of a data source from the specified site.

The content is removed, and the specified revision can no longer be downloaded using Download Data Source Revision. If you call Get Data Source Revisions, the revision that's been removed is listed with the attribute IsDeleted="true".

Note: Calling this method permanently removes the specified data source revision.

URI

DELETE /api/api-version/sites/site-id/datasources/datasource-id/revisions/revision-number

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the group.
datasource-id The ID of the data source to remove the revision for.
revision-number The revision number of the data source to remove. To determine what versions are available, call Get Data Source Revisions.

Request Body

None

Permissions

Tableau Server users who are site administrators can remove data source revisions on the site that they are administrators for. Users who are not server administrators or site administrators can remove data source revisions if they have all of the following:

  • A site role of ExplorerCanPublish.
  • Read (view), Write (save), and Download (save as) permissions for the specified data source.
  • Save (write) permissions for the project that contains the data source.

Response Code

204

Response Body

None

Version

Version 2.3 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
403 403004 Deletion forbidden A non-administrator user attempted to remove a data source revision, but the caller doesn't have required permissions.
403 403053 Version history not enabled version history is not enabled for the specified site.
403 403055 Cannot delete head revision The head (first) version cannot be deleted. To remove the data source, call Delete Data Source.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404006 Data source not found The data source ID in the URI doesn't correspond to an existing data source.
404 404024 Data source revision not found The revision number in the URI doesn't correspond to an existing data source revision.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.

Remove Workbook Revision

Removes a specific version of a workbook from the specified site.

The content is removed, and the specified revision can no longer be downloaded using Download Workbook Revision. If you call Get Workbook Revisions, the revision that's been removed is listed with the attribute IsDeleted="true".

Note: Calling this method permanently removes the specified workbook revision.

URI

DELETE /api/api-version/sites/site-id/workbooks/workbook-id/revisions/revision-number

Parameter Values

api-version The version of the API to use, such as 3.22. For more information, see REST API and Resource Versions.
site-id The ID of the site that contains the group.
workbook-id The ID of the workbook to remove the revision for.
revision-number The revision number of the workbook to remove. To determine what versions are available, call Get Workbook Revisions.

Request Body

None

Permissions

Tableau Server users who are site administrators can remove workbook revisions on the site that they are administrators for. Users who are not server administrators or site administrators can remove workbook revisions if they have all of the following:

  • A site role of ExplorerCanPublish.
  • Read (view), Write (save), and Download (save as) permissions for the specified workbook.
  • Save (write) permissions for the project that contains the workbook.

Response Code

204

Response Body

None

Version

Version 2.0 and later. For more information, see REST API and Resource Versions.

Errors

HTTP status error Code Condition Details
403 403004 Deletion forbidden A non-administrator user attempted to remove a data source revision, but the caller doesn't have required permissions.
403 403053 Version history not enabled version history is not enabled for the specified site.
403 403055 Cannot delete head revision The head (first) version cannot be deleted. To remove the workbook, call Delete Workbook.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404006 Workbook not found The workbook ID in the URI doesn't correspond to an existing workbook.
404 404024 Workbook revision not found The revision number in the URI doesn't correspond to an existing workbook revision.
405 405000 Invalid request method Request type was not DELETE.

For more information, see Handling Errors.


Back to top
Thanks for your feedback!Your feedback has been successfully submitted. Thank you!