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).

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, call Update 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     Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)
Available in API 3.16 (Tableau Cloud June 2022 / Server 2022.3) and later.

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 as 3.24. For more information, see REST 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 the publish-value is not specified in the request, or the publishSamples parameter is missing, no samples will be published. To publish the sample workbooks, set publishSamples parameter to true. This option is equivalent to the tabcmd command-line utility option, publishsamples. For more information, see tabcmd(Link opens in a new window).

Request Body

Copy 
<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"/>
  </project>
</tsRequest>

Copy 
{
  "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 the parentProjectId attribute.

For information about how permissions are evaluated in project hierarchies, see Project Permissions States and Defaults.
project contentPermissions

(Optional) This value controls user permissions in a project, however, if the project is nested within a project with more restrictive policies, it will inherit those permissions and these settings will have no effect. The functional permissions of a project, including those it inherits, are available in value of contentPermission in the response body from a request to create, update, or query a project.

  • LockedToProject to lock permissions so that users cannot overwrite the default permissions set for the project
  • ManagedByOwner to allow users to manage permissions for content that they own
  • LockedToProjectWithoutNested to lock the permissions of a parent project, but not those of its child projects.

The default is ManagedByOwner. For more information, see Lock 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

Copy 
<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"/>
  </project>
</tsResponse>

Copy 
{
  "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 to LockedToProjectWithoutNested 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 not POST.
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, see Handling 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 the External Assets Default Project, and can also be found in External Assets. In Tableau Cloud October 2022 / Server 2022.3 and earlier, external assets are not moved to any other project, but can be found in External 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 as 3.24. For more information, see REST 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).

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:projects:delete

Response Code

204

Response Body

None

Version

Version 1.0 and later. For more information, see REST 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 not DELETE.

For more information, see Handling Errors.

Example

curl "http://MY-SERVER/api/3.24/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 a query 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 as 3.24. For more information, see REST 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, see Paginating Results.
page-number (Optional) The offset for paging. The default is 1. For more information, see Paginating Results.
filter-expression (Optional) An expression that lets you specify a subset of data sources to return. You can filter on predefined fields such as name, ownerName, and parentProjectId. You can include multiple filter expressions. For more information, see Filtering 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 the information that's returned is undefined. For more information, see Filtering and Sorting.

Request Body

None

Permissions

Users who are not server administrators or site administrators can call this method only if they have Read (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).

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:content:read

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"
          id="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>
    <project id="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, 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.
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 not GET.

For more information, see Handling Errors.

Example: Filter query by project ID

curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/projects?filter=parentProjectId:eq:711d4c5d-60b7-4f77-a9a6-bbf05021b6ec" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
	<pagination pageNumber="1" pageSize="100" totalAvailable="1"/>
    <projects>
        <project id="fae56e51-fbee-4eab-a9af-d8283cc0ed77" name="TestNestProject" description="" createdAt="2018-11-15T17:14:45Z" updatedAt="2018-11-15T17:14:45Z" contentPermissions="LockedToProject" parentProjectId="711d4c5d-60b7-4f77-a9a6-bbf05021b6ec">
            <owner id="4d8308f7-ec47-4eb1-a383-429374a8d9cb"/>
        </project>
    </projects>
</tsResponse>

Example: Show all fields in the first ten query results

curl "https://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/projects?pageSize=10&fields=_all_" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"

Example response:

<tsResponse version-and-namespace-settings>
    <pagination pageNumber="1" pageSize="100" totalAvailable="1"/>
    <projects>
        <project id="fae56e51-fbee-4eab-a9af-d8283cc0ed77"
            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 id="4d8308f7-ec47-4eb1-a383-429374a8d9cb" 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     Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)
Available in API 3.16 (Tableau Cloud June 2022 / Server 2022.3) and later.

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 as 3.24. For more information, see REST 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 the publish-value is not specified in the request, or the publishSamples parameter is missing, no samples will be published. To publish the sample workbooks, set publishSamples parameter to true. This option is equivalent to the tabcmd command-line utility option, publishsamples. For more information, see tabcmd(Link opens in a new window).

Request Body

Copy 
<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"/>
  </project>
</tsRequest>

Copy 
{
  "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 Defaults Windows(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 the parentProjectId attribute. To move a project to the top of the project hierarchy, provide an empty string ("") for the parentProjectId attribute.

For information about how permissions are evaluated in project hierarchies, see Project Permissions States and Defaults.
project contentPermissions

(Optional) This value controls user permissions in a project, however, if the project is nested within a project with more restrictive policies, it will inherit those permissions and these settings will have no effect. The functional permissions of a project, including those it inherits, are available in value of contentPermission in the response body from a request to create, update, or query a project.

  • LockedToProject to lock permissions so that users cannot overwrite the default permissions set for the project
  • ManagedByOwner to allow users to manage permissions for content that they own
  • LockedToProjectWithoutNested to lock the permissions of a parent project, but not those of its child projects.

The default is ManagedByOwner. For more information, see Lock 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 the parentProjectId attribute. To move a project to the top of the project hierarchy, provide an empty string ("") for the parentProjectId attribute.

For information about how permissions are evaluated in project hierarchies, see Project 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

Copy 
<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"/>
  </project>
</tsResponse>

Copy 
{
  "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 to LockedToProjectWithoutNested 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 not PUT.
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, see Handling Errors.


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