Tableau REST API Help
Projects Methods
Projects(Link opens in a new window) are sets of workbooks, data sources, and flows whose members inherit the project's permissions.
Using the projects methods of the Tableau Server REST API you can:
- Get a filtered, sorted list of projects on a server
- Create, update, and delete projects on a server
This functionality relates to the UI elements and concepts described at:Use Projects to Manage Content Access(Link opens in a new window).
Use Postman
Postman is a free, comprehensive API platform that simplifies the entire API lifecycle, providing a collaborative environment for designing, testing, and managing APIs. Postman allows you to construct, send, and examine HTTP requests to the Tableau Server or Tableau Cloud API without writing initial code.
Postman: Projects(Link opens in a new window)
Create Project
Creates a project on the specified site. You can also create project hierarchies by creating a project under the specified parent project on the site.To make changes to an existing project, callUpdate Project.
Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.
Version:Available in API 1.0 and later.Version Overview(Link opens in a new window)
License:No additional license required.
Permissions:Only Tableau Administrators can update a project. Permissions Overview(Link opens in a new window)
JWT Access Scope:tableau:projects:create
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
URI
POST /api/api-version/sites/site-id/projects
POST /api/api-version/sites/site-id/projects?publishSamples=publish-value
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-id | The ID of the site to create the project in. |
| publish-value | (Optional) A Boolean value that specifies whether to publish the sample workbooks provided by Tableau to the project. When thepublish-value is not specified in the request, or thepublishSamples parameter is missing, no samples will be published. To publish the sample workbooks, setpublishSamples parameter totrue. This option is equivalent to thetabcmd command-line utility option,publishsamples. For more information, seetabcmd(Link opens in a new window). |
Request Body
<tsRequest>
<project
parentProjectId="afe6f0b8-cb10-11e7-9fd4-db8b61369aa5"
name="Update-Project-Name"
description="This is the new description after the project update"
contentPermissions="ManagedByOwner">
<owner/>
</project>
</tsRequest>{
"project": {
"parentProjectId": "afe6f0b8-cb10-11e7-9fd4-db8b61369aa5",
"name": "Update-Project-Name",
"description": "This is the new description after the project update",
"contentPermissions": "ManagedByOwner",
"owner": {
"id": "abc12e4e-5d6d-7c8c-9b0b-1a2a3f4f5e90"
}
}
}Attribute Values
project name | (Required) The new name for the project. |
project description | (Optional) The new description for the project. |
project parentProjectId | (Optional) The new identifier of the parent project. Use this option to create or change project hierarchies. To create a project as a stand alone or at the top of a project hierarchy, omit theparentProjectId attribute. For information about how permissions are evaluated in project hierarchies, seeProject Permissions States and Defaults. |
project contentPermissions | (Optional) This value controls user permissions in a project, however, if the project is nested within a projectwith more restrictive policies, it will inherit those permissions and these settingswill have no effect. The functional permissions of a project, including those it inherits, are available in value ofcontentPermission in the response body from a request to create, update, or query a project.
The default isManagedByOwner. For more information, seeLock Content Permissions(Link opens in a new window). |
owner id | The LUID of the user that owns the project. |
cURL Example
curl --request PUT "https://myServer/api/3.21/sites/1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e/projects/xz2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e3w" --header "Content-Type: application/xml" --header "X-Tableau-Auth;" --data "<tsRequest> <project parentProjectId='ab2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5ee0' name='new-name' description='new-description' contentPermissions='ManagedByOwner' /> </tsRequest>"
Response Code
201
Response Body
<tsResponse>
<project
parentProjectId="afe6f0b8-cb10-11e7-9fd4-db8b61369aa5"
name="Update-Project-Name"
description="This is the new description after the project update"
contentPermissions="ManagedByOwner"
controllingPermissionsProjectId="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" >
<owner/>
</project>
</tsResponse>{
"project": {
"id": "1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e",
"parentProjectId": "afe6f0b8-cb10-11e7-9fd4-db8b61369aa5",
"name": "Update-Project-Name",
"description": "This is the new description after the project update",
"contentPermissions": "ManagedByOwner",
"controllingPermissionsProjectId": "1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e",
"owner": {
"id": "abc12e4e-5d6d-7c8c-9b0b-1a2a3f4f5e90"
}
}
}Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
| 400 | 400008 | Bad request | The request cannot set content permissions toLockedToProjectWithoutNested for a REST API version lower than 3.8. |
| 403 | 403008 | Insufficient storage on site | The samples could not be published because there is not enough storage space remaining on the server to accommodate the samples. |
| 404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
| 405 | 405000 | Invalid request method | Request type was notPOST. |
| 409 | 409006 | Project name conflict | The project name in the request already belongs to the specified site. For the purpose of uniqueness checks, project names are case-insensitive. |
For more information, seeHandling Errors.
Delete Project
Deletes the specified project on a specific site. When a project is deleted, all Tableau assets inside of it are also deleted, including assets like associated workbooks, data sources, project view options, and rights.
External assets, such as databases and tables, are not deleted. Starting in Tableau Cloud December 2022 / Server 2023.1, external assets from deleted projects are moved to theExternal Assets Default Project, and can also be found inExternal Assets. In Tableau Cloud October 2022 / Server 2022.3 and earlier, external assets are not moved to any other project, but can be found inExternal Assets.
Use this method with caution.
URI
DELETE /api/api-version/sites/site-luid/projects/project-luid
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-luid | The LUID of the site that contains the project. |
| project-luid | The LUID of the project to delete. |
Request Body
None
Permissions
Only server administrators and site administrators can call this method.
Required scope for JWT authorization
Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).
tableau:projects:deleteFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
204
Response Body
None
Version
Version 1.0 and later. For more information, seeREST API and Resource Versions.
Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 403 | 403003 | Deletion forbidden | You attempted to delete a default project that cannot be deleted. |
| 404 | 404000 | Site not found | The site LUID or URL namespace in the URI doesn't correspond to an existing site. |
| 404 | 404005 | Project not found | The project LUID in the URI doesn't correspond to an existing project or the project is not found on this site. |
| 405 | 405000 | Invalid request method | Request type was notDELETE. |
For more information, seeHandling Errors.
Example
curl "http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/projects/1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" -X DELETE -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
The response contains no body (data) for a successful delete operation. The HTTP response code is 204 if the delete operation succeeded.
Query Projects
Returns a list of projects on the specified site, with optional parameters for specifying the paging of large results.
Note: After you create a resource, the server updates its search index. If you make aquery immediately to see a new resource, the query results might not be up to date.
URI
GET /api/api-version/sites/site-id/projects
GET /api/api-version/sites/site-id/projects?pageSize=page-size&pageNumber=page-number
GET /api/api-version/sites/site-id/projects?filter=filter-expression
GET /api/api-version/sites/site-id/projects?sort=sort-expression
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-id | The ID of the site that contains the projects. |
| 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, seePaginating Results. |
| page-number | (Optional) The offset for paging. The default is 1. For more information, seePaginating Results. |
| filter-expression | (Optional) An expression that lets you specify a subset of data sources to return. You can filter on predefined fields such asname,ownerName, andparentProjectId. You caninclude multiple filter expressions. For more information, seeFiltering and Sorting. |
| sort-expression | (Optional) An expression that lets you specify the order in which user information is returned. If you do not specify a sort expression, the sort order of theinformation that's returned is undefined. For more information, seeFiltering and Sorting. |
Request Body
None
Permissions
Users who are not server administrators or site administrators can call this method only if they haveRead (view) permission for the project (either implicitly or explicitly).
Required scope for JWT authorization
Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).
tableau:content:readFor more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
Response Code
200
Response Body
<tsResponse> <pagination pageNumber="pageNumber" pageSize="page-size" totalAvailable="total-available" /> <projects> <project id="project-id" name="project-name" description="project-description" topLevelProject="top-level-project-flag" writeable="writeable-flag" controllingPermissionsProjectId="controlling-permissions-project-id" createdAt="created-date-and-time" updatedAt="updated-date-and-time" contentPermissions="content-permissions" parentProjectId="parent-project-id"> <owner email="owner-email" fullName="owner-full-name" api-placeholder">owner-id" lastLogin="owner-last-login-date" name="owner-username" siteRole="owner-site-role"/> <contentCounts projectCount="number-of-projects" workbookCount="number-of-workbooks" viewCount="number-of-views" datasourceCount="number-of-data-sources"/> </project> <projectapi-placeholder">project-id" name="project-name" description="project-description" contentPermissions="content-permissions" controllingPermissionsProjectId="controlling-permissions-project-id" />... additional attributes and projects ... </projects></tsResponse>Version
Version 2.0 and later. For more information, seeREST 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. |
| 404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
| 405 | 405000 | Invalid request method | Request type was notGET. |
For more information, seeHandling Errors.
Example: Filter query by project ID
curl "http://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/projects?filter=parentProjectId:eq:711d4c5d-60b7-4f77-a9a6-bbf05021b6ec" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponseversion-and-namespace-settings><pagination pageNumber="1" pageSize="100" totalAvailable="1"/> <projects> <project name="TestNestProject" description="" createdAt="2018-11-15T17:14:45Z" updatedAt="2018-11-15T17:14:45Z" contentPermissions="LockedToProject" parentProjectId="711d4c5d-60b7-4f77-a9a6-bbf05021b6ec"> <owner/> </project> </projects></tsResponse>Example: Show all fields in the first ten query results
curl "https://MY-SERVER/api/3.27/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/projects?pageSize=10&fields=_all_" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Example response:
<tsResponseversion-and-namespace-settings> <pagination pageNumber="1" pageSize="100" totalAvailable="1"/> <projects> <project name="TestNestProject" description="A project." topLevelProject="false" writeable="true" createdAt="2018-11-15T17:14:45Z" updatedAt="2018-13-15T17:12:30Z" contentPermissions="ManagedByOwner" parentProjectId="711d4c5d-60b7-4f77-a9a6-bbf05021b6ec" controllingPermissionsProjectId="57646e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" /> <owner email="rkawal@tableau.com" fullName="Reena Kawal" lastLogin="2020-06-02T16:23:49Z" name="rkawal" siteRole="SiteAdministratorCreator"/> <contentCounts projectCount="2" workbookCount="3" viewCount="10" datasourceCount="2" /> </project> </projects></tsResponse>Update Project
Updates the name, description, or project hierarchy of the specified project. You can create or update project hierarchies by specifying a parent project for the project that you are updating using this method.
Version:Available in API 1.0 and later.Version Overview(Link opens in a new window)
License:No additional license required.
Permissions:Only Tableau Administrators can update a project. Permissions Overview(Link opens in a new window)
JWT Access Scope:tableau:projects:update
For more information, seeAccess scopes for UATs(Link opens in a new window) (Cloud)and access scopes for connected apps:Cloud(Link opens in a new window),Server-Windows(Link opens in a new window),orServer-Linux(Link opens in a new window).
URI
PUT /api/api-version/sites/site-id/projects/project-id
PUT /api/api-version/sites/site-id/projects/project-id?publishSamples=publish-value
Parameter Values
| api-version | The version of the API to use, such as3.27. For more information, seeREST API and Resource Versions. |
| site-id | The ID of the site that contains the project. |
| project-id | The ID of the project to update. |
| publish-value | (Optional) A Boolean value that specifies whether to publish the sample workbooks provided by Tableau to the project when you update the project. When thepublish-value is not specified in the request, or thepublishSamples parameter is missing, no samples will be published. To publish the sample workbooks, setpublishSamples parameter totrue. This option is equivalent to thetabcmd command-line utility option,publishsamples. For more information, seetabcmd(Link opens in a new window). |
Request Body
<tsRequest>
<project
parentProjectId="afe6f0b8-cb10-11e7-9fd4-db8b61369aa5"
name="Update-Project-Name"
description="This is the new description after the project update"
contentPermissions="ManagedByOwner"
controllingPermissionsProjectId="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" >
<owner/>
</project>
</tsRequest>{
"project": {
"id": "1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e",
"parentProjectId": "afe6f0b8-cb10-11e7-9fd4-db8b61369aa5",
"name": "Update-Project-Name",
"description": "This is the new description after the project update",
"contentPermissions": "ManagedByOwner",
"controllingPermissionsProjectId": "1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e",
"owner": {
"id": "abc12e4e-5d6d-7c8c-9b0b-1a2a3f4f5e90"
}
}
}Attribute Values
project id | (Required) The LUID of the project being updated. For information about how permissions are evaluated in project hierarchies, see Project Permissions States and DefaultsWindows(Link opens in a new window) |Linux(Link opens in a new window). |
project name | (Optional) The new name for the project. |
project description | (Optional) The new description for the project. |
project parentProjectId | (Optional) The new identifier of the parent project. Use this option to create or change project hierarchies. To update a project without changing its placement in the project hierarchy, omit theparentProjectId attribute.To move a project to the top of the project hierarchy, provide an empty string ("") fortheparentProjectId attribute. For information about how permissions are evaluated in project hierarchies, seeProject Permissions States and Defaults. |
project contentPermissions | (Optional) This value controls user permissions in a project, however, if the project is nested within a projectwith more restrictive policies, it will inherit those permissions and these settingswill have no effect. The functional permissions of a project, including those it inherits, are available in value ofcontentPermission in the response body from a request to create, update, or query a project.
The default isManagedByOwner. For more information, seeLock Content Permissions(Link opens in a new window). |
project parentProjectId | (Optional) The new identifier of the parent project. Use this option to create or change project hierarchies. To update a project without changing its placement in the project hierarchy, omit theparentProjectId attribute.To move a project to the top of the project hierarchy, provide an empty string ("") fortheparentProjectId attribute. For information about how permissions are evaluated in project hierarchies, seeProject Permissions States and Defaults. |
owner id | The LUID of the user that owns the project. |
cURL Example
curl --request PUT "https://myServer/api/3.21/sites/1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e/projects/ds2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e70" --header "Content-Type: application/xml" --header "X-Tableau-Auth;" --data "<tsRequest> <project parentProjectId='ab2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5ee0' name='new-name' description='new-description' contentPermissions='ManagedByOwner' /> </tsRequest>"
Response Code
200
Response Body
<tsResponse>
<project
parentProjectId="afe6f0b8-cb10-11e7-9fd4-db8b61369aa5"
name="Update-Project-Name"
description="This is the new description after the project update"
contentPermissions="ManagedByOwner"
controllingPermissionsProjectId="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" >
<owner/>
</project>
</tsResponse>{
"project": {
"id": "1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e",
"parentProjectId": "afe6f0b8-cb10-11e7-9fd4-db8b61369aa5",
"name": "Update-Project-Name",
"description": "This is the new description after the project update",
"contentPermissions": "ManagedByOwner",
"controllingPermissionsProjectId": "1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e",
"owner": {
"id": "abc12e4e-5d6d-7c8c-9b0b-1a2a3f4f5e90"
}
}
}Errors
| HTTP status | error Code | Condition | Details |
|---|---|---|---|
| 400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
| 400 | 400008 | Bad request | The request cannot set content permissions toLockedToProjectWithoutNested for a REST API version lower than 3.8. |
| 403 | 403005 | Update forbidden | Attempt to rename the default project, which cannot be renamed. |
| 403 | 403008 | Insufficient storage on site | The samples could not be published because there is not enough storage space remaining on the server to accommodate the samples. |
| 403 | 403004 | Update forbidden | A non-administrative user tried to update the project, but does not have permissions to update the project. |
| 404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
| 404 | 404009 | Project ID mismatch | The request body contains a project ID (which is optional) and it doesn't match the ID in the URI. |
| 404 | 404005 | Project not found | The project ID in the URI doesn't correspond to an existing project. |
| 405 | 405000 | Invalid request method | Request type was notPUT. |
| 409 | 409006 | Project name conflict | The project name in the request already belongs to the specified site. For the purpose of uniqueness checks, project names are case-insensitive. |
For more information, seeHandling Errors.