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.24 . 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.24 . 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.24 . 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 revisionNumber="1" publishedAt="date" deleted="false">
<publisher id="publisher-id" name="publisher-name"/>
</revision>
<revision revisionNumber="2" publishedAt="date" deleted="false">
</revision>
<revision revisionNumber="3" publishedAt="date" deleted="false" current="true" sizeInBytes="size>
<publisher id="publisher-id" name="publisher-name"/>
</revision>
</revisions>
</tsResponse>
If the revision element includes the attribute deleted="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 <publisher>
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.24 . 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.24 . 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.24 . 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.