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.

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

<tsRequest>
  <project parentProjectId="parent-project-id"
    name="project-name"
    description="project-description"
    contentPermissions="content-permissions"/>
</tsRequest>
        

Attribute Values

parent-project-id (Optional) The identifier of the parent project. Use this option to create project hierarchies. 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 The name to assign to the project.
project-description (Optional) A description for the project.
new-content-permissions

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

Permissions

This method can only be called by server administrators and site administrators.

Response Code

201

Response Body

<tsResponse>
  <project id="new-project-id"
    parentProjectId="parent-project-id"
    name="project-name"
    description="project-description"
	contentPermissions="content-permissions"
	controllingPermissionsProjectId="controlling-permissions-project-id" />
</tsResponse>
        

Response Headers

Location: /api/3.12/sites/site-id/projects/new-project-id

Version

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

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.

Example 1

curl "http://MY-SERVER/api/3.12/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/projects" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @create-project.xml

Content of create-project.xml:

<tsRequest>
  <project name="New-Project"
   description="This is a new project"
   contentPermissions="LockedToProject" />
</tsRequest>

Example response:

<tsResponse version-and-namespace-settings>
  <project id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" name="New-Project"
    description="This is a new project"
	contentPermissions="LockedToProject"
	controllingPermissionsProjectId="57646e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" />
</tsResponse>

Example 2

curl "http://MY-SERVER/api/3.12/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/projects" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @create-nested-project.xml

Content of create-nested-project.xml:

<tsRequest>
  <project name="New-Nested-Project"
    parentProjectId="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e"
    description="This is a new nested project"
    contentPermissions="LockedToProject" />
</tsRequest>
        

Example response:

<tsResponse version-and-namespace-settings>
  <project id="08a7b6b5-b4ba-be3a-4d2d-1e9e59a8a7b6"
    parentProjectId="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e"
    name="New-Nested-Project"
    description="This is a new nested project"
    contentPermissions="LockedToProject"
    controllingPermissionsProjectId="57464e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" />
</tsResponse>
        

Delete Project

Deletes the specified project on a specific site. When a project is deleted, all of its assets are also deleted: associated workbooks, data sources, project view options, and rights. Use this method with caution.

URI

DELETE /api/api-version/sites/site-id/projects/project-id

Parameter Values

api-version The version of the API to use, such as 3.12. 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 delete.

Request Body

None

Permissions

This method can only be called by server administrators and site administrators.

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 Attempt to delete the default project, which cannot be deleted.
404 404000 Site not found The site ID or URL namespace in the URI doesn't correspond to an existing site.
404 404005 Project not found The project ID 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.12/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.12. 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

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

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.12/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.12/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.

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

<tsRequest>
  <project parentProjectId="new-parent-project-id"
    name="new-name"
    description="new-description"
    contentPermissions="new-content-permissions" />
</tsRequest>
        

Attribute Values

new-parent-project-id

(Optional) The identifier of the parent project. Use this option to create 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 Windows(Link opens in a new window) | Linux(Link opens in a new window).

new-name (Optional) The new name for the project.
new-description (Optional) The new description for the project.
new-parent-project-id (Optional) The new identifier of the parent project. Use this option to create or change project hierarchies. For information about how permissions are evaluated in project hierarchies, see Project Permissions States and Defaults.
new-content-permissions

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

Permissions

This method can only be called by server administrators or site administrators.

Response Code

200

Response Body

<tsResponse>
 <project id="project-"
    parentProjectId="parent-project-id"
    name="name"
    description="description"
    contentPermissions="content-permissions"
    controllingPermissionsProjectId="controlling-permissions-project-id" />
</tsResponse>
        

Version

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

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.

Example

curl "http://MY-SERVER/api/3.12/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/projects/1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @update-project.xml

Content of update-project.xml:

<tsRequest>
  <project parentProjectId="afe6f0b8-cb10-11e7-9fd4-db8b61369aa5"
      name="Update-Project-Name"
      description="This is the new description after the project update" />
</tsRequest>

Example response:

<tsResponse version-and-namespace-settings>
  <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="LockedToProject"
	 controllingPermissionsProjectId="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" />
</tsResponse>


Thanks for your feedback!