Metadata Methods

Metadata methods have been released incrementally beginning with Tableau version 2019.3.

Using the metadata methods of the Tableau REST API, you can do the following tasks with Tableau metadata. Some methods require Data Management and are noted where this applies.

Database, which includes files (external asset type)

  • Query a database or multiple databases
  • Update (e.g., certify), move, or remove a database
  • Add, query, or delete database permissions
  • Add, query, or delete default database permissions

Table (external asset type)

  • Query a table or multiple tables
  • Update (e.g., certify), move, or remove a table
  • Add, query, or delete table permissions

Column (external asset type)

  • Query a column or multiple columns that belong to a specific table
  • Update the column description or remove a column that belongs to a specific table

Data quality warning (DQW) (communicates data quality information for databases, tables, published data sources, and flows)

  • Add, update (e.g., severity), or delete a data quality warning
  • Query data quality warnings
  • Batch add, update, or delete data quality warnings to and from Tableau content and external assets

Data quality certification (communicates data quality certification information for databases, tables, and data sources)

  • Add, update (e.g., severity), or delete a data quality certification
  • Query data quality certification

Label (a different interface for manipulating data quality warnings and data quality certifications)

  • Add, update, or delete labels
  • Query labels on one or more assets

Quality warning trigger (enables monitoring of content and displays alerts when extract refresh and flow run failures occur)

  • Add, update, delete quality warning trigger
  • Query quality warning trigger

Tag (keywords that helps users find, filter, and categorize external assets and Tableau content)

  • Add tags to a database, table, or column
  • Delete a tag from a database, table, or column
  • Batch add and delete tags on Tableau content and external assets

The above functionality relates to metadata concepts and Data Catalog UI elements described at: About Tableau Catalog(Link opens in a new window).

For deeper and more comprehensive API functionality for querying metadata and schema information for Tableau content, see Tableau Metadata API(Link opens in a new window) Help.

Add Database Permissions

Add permissions to a database asset. To add permissions, the database asset must be associated with a published data source.

Version: Available in API 3.5 (Tableau Cloud and Tableau Server) and later.  Version Overview

License: Available with Tableau Data Management(Link opens in a new window).

Permissions: Users that are granted ChangePermissions capabilities for the asset metadata and all administrators can add database permissions.  Permissions Overview

JWT Access Scope: Not available.      

URI

PUT api/api-version/sites/site-luid/databases/database-luid/permissions

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-luid The LUID of the site asset.
database-luid The LUID of the database asset.

Request Body

<tsRequest>
  <permissions>
    <database id="8d4aa9f-3d1a-4b49-8d6d-27f113cbd25e" />
    <granteeCapabilities>
      <user id="user-luid" />
      <capabilities>
        <capability name="ChangePermissions" mode="allow" />
        <!-- ...  additional capabilities ... -->
      </capabilities>
    </granteeCapabilities>
    <granteeCapabilities>
      <group id="group-luid" />
 	  <capabilities>
	    <capability name="Read" mode="Allow" />
	    <!-- ...  additional capabilities ... -->
	  </capabilities>
	</granteeCapabilities>
    <!-- ... additional grantee capability sets ...  -->
  </permissions>
</tsRequest>

Attribute Values

{
  "permissions": {
    "database": {
      "id": "1d4aa9f-3d1a-4b49-8d6d-27f113cbd25e"
    },
    "granteeCapabilities": [
      {
        "user": {
          "@id": "2d4aa9f-3d1a-4b49-8d6d-27f113cbd25e"
        },
        "capabilities": {
          "capability": {
            "name": "ChangePermissions",
            "mode": "allow"
          }
        }
      },
      {
        "group": {
          "id": "3d4aa9f-3d1a-4b49-8d6d-27f113cbd25e"
        },
        "capabilities": {
          "capability": {
            "name": "Read",
            "mode": "Allow"
          }
        }
      }
    ]
  }
}

Request Attributes

database The LUID of the database asset you want to add permissions to.
user id The LUID of the user to add permissions for.
capability name

The capability to assign. If any capability has been granted or denied for a specified user or group, that capability is ignored. Valid capabilities for a database are:

  • Read (view)
  • Write (edit)
  • ChangePermissions (set permissions)
  • ChangeHierarchy (move)

These values are case sensitive.

capability mode

Use one of the following capabilities:

  • Allow
  • Deny

These values are case sensitive.

group id The LUID of the group to add permissions for.

Response Code

200

Response Body

<tsResponse>
  <permissions>
	<database id="e8d4aa9f-3d1a-4b49-8d6d-27f113cbd25e" name="oracle.test.tsi.lan:1521"/>
	<granteeCapabilities>
	  <user id="6265b714-7533-465d-b6db-6d0be92bfd07"/>
	  <capabilities>
		<capability name="Read" mode="Allow"/>
	  </capabilities>
	</granteeCapabilities>
  </permissions>
</tsResponse>
      
{
  "permissions": {
    "database": {
      "id": "e8d4aa9f-3d1a-4b49-8d6d-27f113cbd25e",
      "name": "oracle.test.tsi.lan:1521"
    },
    "granteeCapabilities": {
      "user": {
        " id": "6265b714-7533-465d-b6db-6d0be92bfd07"
      },
      "capabilities": {
        "capability": {
          "name": "Read",
          "mode": "Allow"
        }
      }
    }
  }
}

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 400120 Bad request Permissions could not be added because support for explicit permissions is available for database assets associated with published data sources only.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site LUID in the URI doesn't correspond to an existing site.
404 404031 Database not found The requested database could not be found.
405 405000 Invalid request method Request type was not PUT.
409 409045 Database error An unknown database asset error occurred.
409 409050 Database update error An unknown error occurred and the database asset could not be updated.
409 409051 Database update forbidden A user without "write" permissions to the database asset attempted an update.

Add Default Database Permissions

Adds default permission capabilities to a user or group for table resources in that database. These default permissions function as a permissions template for the database's table assets.

Note: If a database is in a project, default database permissions are not evaluated to determine table permissions. Use the Add Default Permissions method to control default permission capabilities on tables through projects instead.

How default permissions are enforced depends on whether the database is locked or unlocked.

  • Locked to the database: If the permissions on a database are locked or Locked to the database, existing child table assets and new child table assets that get indexed by Catalog will inherit the default permissions applied to the parent database asset. Note: If the database is locked, explicit permissions cannot be made for individual tables.

  • Managed by the owner: If the permissions on a database are unlocked or Managed by the owner, only new child table assets that get indexed by Catalog will inherit the default permissions applied to the parent database asset. Note: If the database is unlocked, explicit permissions for the table can be made in a separate request.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

PUT /api/api-version/sites/site-luid/databases/database-luid/default-permissions/tables

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-luid The LUID of the site asset.
database-luid The LUID of the database asset to set default permissions for.

Request Body

<tsRequest>
  <permissions>
    <granteeCapabilities>
      <user id="user-luid" />
      <capabilities>
        <capability name="capability-name" mode="capability-mode" />
        <!-- ... additional capabilities ... -->
      </capabilities>
    </granteeCapabilities>
    <granteeCapabilities>
      <group id="group-luid" />
      <capabilities>
        <capability name="capability-name" mode="capability-mode" />
        <!-- ...  additional capabilities ... -->
      </capabilities>
    </granteeCapabilities>
    <!-- ... additional grantee capability sets ... -->
  </permissions>
</tsRequest>

Attribute Values

user-luid The LUID of the user to add default permissions for.
group-luid The LUID of the group to add permissions for.
capability-name

The capability to assign. If any capability has been granted or denied for a specified user or group, that capability is ignored. Valid capabilities for a databases are the following:

  • Read (view)
  • Write (edit)
  • ChangePermissions (set permissions)
  • ChangeHierarchy (move)

These values are case sensitive.

capability-mode

Use one of the following capabilities:

  • Allow
  • Deny

These values are case sensitive.

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following authorized users set default permissions for the database asset:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have been granted explicit permission to set or "ChangePermissions" to the asset metadata

Response Code

200

Response Body

<tsResponse>
  <permissions>
	<database id="e8d4aa9f-3d1a-4b49-8d6d-27f113cbd25e" name="oracle.test.tsi.lan:1521"/>
	<granteeCapabilities>
	  <user id="6265b714-7533-465d-b6db-6d0be92bfd07"/>
	  <capabilities>
		<capability name="Read" mode="Allow"/>
	  </capabilities>
	</granteeCapabilities>
  </permissions>
</tsResponse>
      

Version

Version 3.5 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.
403 403004 Permissions setting forbidden A non-administrator user called this method but doesn't have permission to add permissions on the project.
403 403114 Permissions setting forbidden Default permissions cannot be added because the database asset is locked.
404 404000 Site not found The site LUID in the URI doesn't correspond to an existing site.
404 404003 Resource not found The database LUID in the URI doesn't correspond to a database asset on the site.
404 404002 User not found A user LUID in the request body as the grantee doesn't correspond to an existing user.
404 404012 Group not found A group LUID in the request body doesn't correspond to an existing group.
404 404013 Capability not found The capability in the request body doesn't correspond to a defined capability. This can apply to either an invalid capability name or to a capability other than Allow or Deny for any mode value.
405 405000 Invalid request method Request type was not PUT.

Add Data Quality Warning

Create and apply a data quality warning to a database, table, column, published data source, flow, virtual connection, or virtual connection table.

Only one data quality warning can be applied to the asset. (An automatically-generated monitoring warning does not count towards this limit.) Adding a data quality warning to the asset that already has one causes an error.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

POST api/api-version/sites/site-id/dataQualityWarnings/content-type/content-luid

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
content-type The type of asset that the data quality warning is being attached to. To specify the type, use:
  • database
  • table
  • column - Available in API 3.16 and later (Tableau Cloud October 2022, Server 2022.3)
  • datasource
  • flow
  • virtual connection
  • virtual connection table

These values are not case sensitive.

content-luid The unique ID of the asset (database, table, column, published data source, flow, virtual connection, or virtual connection table). This is the same as the content ID.

Request Body

<tsRequest>
  <dataQualityWarning type="type" isActive="state" message="message" isSevere="severity"/>
</tsRequest>

Attribute Values

Any combination of attributes inside the <dataQualityWarning> element is valid, but the data quality warning type is required. If the data quality warning type is not included, an error is thrown.

type

Type of data quality warning to apply to the asset. To specify the type, use one of the following values:

  • DEPRECATED
  • WARNING
  • STALE
  • SENSITIVE_DATA
  • MAINTENANCE

These values are case sensitive.

state

(Optional) Controls whether the data quality warning displays. Value can be "true" or "false". If the state is not specified, the data quality warning is set to "true" and is visible by default. For more information about data quality warnings, see "Set a Data Quality Warning" in the Server Help or Online Help.

message A required custom message to accompany the data quality warning.
severity (Optional) Enables high visibility for the data quality warning when set to "true". Value can be "true" or "false". For more information, see "Set high visibility for data quality warning" in the Server Help or Online Help.

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to add the data quality warning:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

201

Response Body

Example response:

<tsResponse>
   <dataQualityWarning id="1c8ebdfc-270a-4414-812c-3306a1c95e07" userDisplayName="Steve Nguyen"
	contentId="0d7465f2-4989-417e-b88d-f787359edc63" contentType="DATABASE" message="Delayed"
	type="WARNING" isActive="true" createdAt="2020-10-08T00:00:35Z" isSevere="false">
	<site id="a946d998-2ead-4894-bb50-1054a91dcab3"/>
	<owner id="cdfe8548-84c8-418e-9b33-2c0728b1234a"/>
   </dataQualityWarning>
</tsResponse>     

Version

Version 3.5 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 400108 Generic add data quality warning error The data quality warning could not be added for some other reason than those specified in this table.
400 400109 Bad request The request body is missing the data quality warning type.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
403 403004 Unauthorized operation Insufficient permissions to perform the operation.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
404 404029 Content not found The requested asset could not be found.
409 409004 Invalid parameter One or more values in the request body are invalid.

Batch Add or Update Data Quality Warnings

Add or update multiple data quality warnings (DQWs) for different content and asset items.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

POST api/api-version/sites/site-id/dataQualityWarnings/createOrUpdate

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.

Request Body

<tsRequest>
  <contentList>
	<content contentType="content" id="database-id" />
	<content contentType="content" id="table-id" />
	<content contentType="content" id="column-id" />
	<content contentType="content" id="datasource-id" />
	<content contentType="content" id="flow-id" />
	<content contentType="content" id="virtualconnection-id" />
	<content contentType="content" id="virtualconnectiontable-id" />
  </contentList>
  <dataQualityWarning type="type" message="message" isActive="state" isSevere="severity" />
</tsRequest>
      

Attribute Values

content

The type of content or asset the data quality warning is attached to. To specify type, use one of the following values:

  • database
  • table
  • column - Available in API 3.16 and later (Tableau Cloud October 2022, Server 2022.3)
  • datasource
  • flow
  • virtualconnection
  • virtualconnectiontable
database-id The unique ID of the database asset.
table-id The unique ID of the table asset.
column-id The unique ID of the column asset.
datasource-id The unique ID of the data source content.
flow-id The unique ID of the flow content.
virtualconnection-id The unique ID of the virtual connection.
virtualconnectiontable-id The unique ID of the virtual connection table.
type

The type of data quality warning to apply to the content or asset. To specify type, use one of the following values:

  • DEPRECATED
  • WARNING
  • STALE
  • SENSITIVE_DATA
  • MAINTENANCE
message (Optional) A custom message to accompany the data quality warning.
state (Optional) Controls whether the data quality warning displays. Value can be "true" or "false". If the state is not specified, the data quality warning is set to "true" and is visible by default. For more information about data quality warnings, see "Set a Data Quality Warning" in the Server Help or Online Help.
severity (Optional) Enables high visibility for when the data quality warning is set to "true". Value can be "true" or "false". For more information, see "Set high visibility for data quality warning" in the Server Help or Online Help.

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to batch add or update data quality warnings:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

200

Response Body

Example response

<tsRequest>
  <dataQualityWarningList>
	<dataQualityWarning id="8f58aa47-7313-4504-8537-52d869552e18" userDisplayName="Mark Nguyen" contentId="7cfd2ac8-a934-4aa8-bf24-96bff08a019c" contentType="DATABASE" message="Contact admin with questions" type="WARNING" isActive="true" createdAt="2021-06-26T21:34:46Z" updatedAt="2021-06-26T21:34:46Z" isSevere="true">
	  <site id="1e4b3aa0-b48a-4b8e-9bdf-74b7596b9f0a" />
	  <owner id="adcc51d7-8558-4099-9f87-dc1a1615d297" />
	</dataQualityWarning>
	<dataQualityWarning id="c8f0b332-a1c1-48f1-b650-86f342ab937f" userDisplayName="Mark Nguyen" contentId="f6dcfd24-7c65-40f4-a3f3-c29f91b7731e" contentType="DATASOURCE" message="Contact admin with questions" type="WARNING" isActive="true" createdAt="2021-06-26T21:34:46Z" updatedAt="2021-06-26T21:34:46Z" isSevere="true">
	  <site id="1e4b3aa0-b48a-4b8e-9bdf-74b7596b9f0a" />
	  <owner id="adcc51d7-8558-4099-9f87-dc1a1615d297" />
	<dataQualityWarning>
  </dataQualityWarningList>
</tsRequest>     

Version

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

Errors

HTTP status error Code Condition Details
400 400109 Bad request The content of the request body (content type, content id, or dataQualityWarning attributes) is missing, incomplete, or contains malformed XML.
400 400108 Generic add data quality warning error The data quality warning could not be added for some other reason than those specified in this table.
403 403004 Unauthorized operation Insufficient permissions to perform the operation.
404 404029 Content not found The content does not exist.
409 409004 Invalid parameter One or more values in the request body are invalid.

Batch Add or Update Data Quality Certifications

Create or update one or more data quality certifications for different content and asset items.

A content or asset item can only have up to one data quality certification applied to it. Adding a data quality certification to an item that already has one will update the data quality certification with the latest specified values.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

POST api/api-version/sites/site-id/dataQualityCertifications

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.

Request Body

<tsRequest>
  <contentList>
	<content contentType="content" id="database-id" />
	<content contentType="content" id="table-id" />
	<content contentType="content" id="datasource-id" />
	<content contentType="content" id="virtualconnection-id" />
	<content contentType="content" id="virtualconnectiontable-id" />
  </contentList>
  <dataQualityIndicator type="type" message="message"
	active="state" elevated="severity" />
</tsRequest> 

Attribute Values

Any combination of attributes inside the <dataQualityIndicator> element is valid, however type and message attributes are required.

content

The type of content or asset the data quality warning is attached to. To specify type, use one of the following values:

  • database
  • table
  • datasource
  • virtualconnection
  • virtualconnectiontable
database-id The unique ID of the database asset.
table-id The unique ID of the table asset.
datasource-id The unique ID of the data source content.
virtualconnection-id The unique ID of the virtual connection asset.
virtualconnectiontable-id The unique ID of the virtual connection table asset.
type

Use the following value to apply a data quality certification: CERTIFIED.

message A custom message to accompany the data quality certification.
state (Optional) Controls whether the data quality certification displays. Value can be "true" or "false". If the state is not specified, the data quality certification is set to "true" and is visible by default.
severity (Optional) Enables high visibility for when the data quality certification is set to "true". Value can be "true" or "false". If the severity is not specified, the data quality certification is set to "false." This setting is available only through the REST API.

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to add or update data quality certifications:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

201

Response Body

Example response

<tsRequest>
  <dataQualityIndicatorList>
	<dataQualityIndicator id="8f58aa47-7313-4504-8537-52d869552e18"
	    userDisplayName="Mark Nguyen" contentId="7cfd2ac8-a934-4aa8-bf24-96bff08a019c" contentType="DATABASE" message="Marketing approved" type="CERTIFIED" active="true" createdAt="2021-09-26T21:34:46Z" updatedAt="2021-09-26T21:34:46Z" elevated="true">
	  <site id="1e4b3aa0-b48a-4b8e-9bdf-74b7596b9f0a" />
	  <owner id="adcc51d7-8558-4099-9f87-dc1a1615d297" />
	</dataQualityIndicator>
	<dataQualityIndicator id="c8f0b332-a1c1-48f1-b650-86f342ab937f"
	    userDisplayName="Mark Nguyen" contentId="f6dcfd24-7c65-40f4-a3f3-c29f91b7731e" contentType="DATASOURCE" message="Marketing approved" type="CERTIFIED" active="true" createdAt="2021-09-26T21:34:46Z" updatedAt="2021-09-26T21:34:46Z" elevated="true">
	  <site id="1e4b3aa0-b48a-4b8e-9bdf-74b7596b9f0a" />
	  <owner id="adcc51d7-8558-4099-9f87-dc1a1615d297" />
	<dataQualityIndicator>
  </dataQualityIndicatorList>
</tsRequest>    

Version

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

Errors

HTTP status error Code Condition Details
400 400108 Generic data quality certification error The data quality certification could not be added for some reason other than those specified in this table.
403 403004 Unauthorized operation Insufficient permissions to perform the operation.
404 404029 Content not found The content does not exist.
409 409004 Invalid parameter One or more values in the request body are invalid.

Add (or Update) Quality Warning Trigger

Create or update one or more quality warning triggers to monitor and display alerts for the following events: refresh failures on extract data sources and flow run failures on flows.

An asset can only have one trigger. Adding a trigger to an asset that already has one will update the trigger with the latest specified values.

Note: An asset can have one trigger and one DQW applied to it at the same time.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

Add or update a quality warning trigger

POST api/api-version/sites/site-id/dataQualityTriggers/content-type/contentIds?filter=contentId:in:[content-luid]

Add or update a quality warning trigger for multiple assets

POST api/api-version/sites/site-id/dataQualityTriggers/content-type/contentIds?filter=contentId:in:[content-luid1,content-luid2,content-luid3,...]

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
content-type

The type of content the quality warning trigger is being applied to. Use one of the following values:

  • datasource
  • flow

These values are not case sensitive.

content-luid The unique ID of the asset. This is the same as the content ID.

Request Body

<tsRequest>
  <dataQualityTrigger type="content" active="status" message="message" severe="severity"/>
</tsRequest>
      

Attribute Values

Any combination of attributes inside the <dataQualityTrigger> element is valid, however type is required.

content

Type of content item to apply the trigger. To specify the type, use one of the following values:

  • EXTRACT_REFRESH
  • FLOW_RUN

These values are not case sensitive.

status

(Optional) Status of the trigger. Values can be "true" or "false". If set to "true", either the extract data source is monitored for refresh failures or the flow is monitored for flow run failures. If a failure occurs, an alert is applied (or replaces an existing one) to either the extract data source or flow. The alert remains there until the next successful refresh or flow run. For more information about quality warning triggers, see "Set a Data Quality Warning" in the Server Help or Online Help.

message (Optional) A custom message to accompany the trigger.
severity (Optional) Enables high visibility for the trigger. Values can be "true" or "false". For more information, see "Set high visibility for data quality warning" in the Server Help or Online Help.

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to add quality warning triggers:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

200

Response Body

Example response

<tsResponse>
  <dataQualityTriggerList>
	<dataQualityTrigger id="{trigger-luid}" siteId="{site-luid}"
		userId="{user-luid}" userDisplayName="Joe Nguyen" contentId="{content-luid}"
		contentType="DATASOURCE" message=" This message is specified by the user."
		type="EXTRACT_REFRESH" active="true" createdAt="Wed Sep 22 05:49:52 UTC 2020"
		updatedAt="Wed Sep 22 05:49:52 UTC 2020" severe="false"/>
  </dataQualityTriggerList>
</tsResponse>
      

Version

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

Errors

HTTP status error Code Condition Details
400 400136 Generic quality warning trigger error The quality warning trigger could not be added or updated for some other reason than those specified below.
403 403004 Unauthorized operation Insufficient permissions to perform the operation.
409 409004 Invalid parameter One or more values in the request body are invalid.

Add Table Permissions

Add permissions to a table asset.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

PUT api/api-version/sites/site-luid/tables/table-luid/permissions

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-luid The LUID of the site asset.
table-luid The LUID of the table asset.

Request Body

<tsRequest>
  <permissions>
    <table id="table-luid" />
    <granteeCapabilities>
      <user id="user-luid" />
      <capabilities>
        <capability name="capability-name" mode="capability-mode" />
        <!-- ... additional capabilities ... -->
      </capabilities>
    </granteeCapabilities>
    <granteeCapabilities>
      <group id="group-luid" />
      <capabilities>
        <capability name="capability-name" mode="capability-mode" />
        <!-- ... additional capabilities ... -->
      </capabilities>
    </granteeCapabilities>
    <!-- ... additional grantee capability sets ... -->
  </permissions>
</tsRequest>
    

Attribute Values

table-luid The LUID for the table asset you want to add permissions to.
user-luid The LUID of the user to add permissions for.
capability-name

The capability to assign. If any capability has been granted or denied for a specified user or group, that capability is ignored. Valid capabilities for a database are:

  • Read (view)
  • Write (edit)
  • ChangePermissions (set permissions)
  • ChangeHierarchy (move)

These values are case sensitive.

capability-mode

Use one of the following capabilities:

  • Allow
  • Deny

These values are case sensitive.

group-id The LUID of the group to add permissions for.

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to add table asset permissions:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have been granted explicit permission to set or "ChangePermissions" to the asset metadata

Response Code

200

Response Body

Example response:

<tsResponse>
  <permissions>
	<table id="d0fe66ae-1407-4338-8520-9489d7ce959c" name="_WarehouseConfig"/>
	<granteeCapabilities>
	  <user id="6265b714-7533-465d-b6db-6d0be92bfd07"/>
	  <capabilities>
		<capability name="Read" mode="Allow"/>
	  </capabilities>
	</granteeCapabilities>
  </permissions>
</tsResponse>
      

Version

Version 3.5 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 400120 Bad request Permissions could not be added because support for explicit permissions is available for table assets associated with published data sources only.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
403 403117 Database locked Permissions for the table asset cannot be deleted because the database asset is locked.
404 404000 Resource not found The site LUID in the URI doesn't correspond to an existing site.
404 404032 Table not found The requested table asset could not be found.
409 409052 Table error An unknown table asset error occurred.
409 409057 Table update error An unknown error occurred and the table asset could not be updated.
409 409058 Table update forbidden A user without "write" permissions to the table asset attempted an update.

Add Tags to Column

Add one or more tags to a column.

For more information about tags, see Tag Items(Link opens in a new window) in the Tableau User Help.

URI

PUT api/api-version/sites/site-id/columns/column-id/tags

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
column-id The unique ID of the column asset.

Request Body

<tsRequest>
  <tags>
	<tag label="tag-value1" />
	<tag label="tag-value2" />
  </tags>
</tsRequest>
      

Attribute Values

tag-value1

Keyword text you want to add to the asset.

tag-value2

Keyword text you want to add to the asset.

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to add tags:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

200

Response Body

Example response

<tsResponse>
  <tags>
	<tag label="Noteworthy" />
	<tag label="PII" />
  </tags>
</tsResponse>
      

Version

Version 3.9 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.
403 403004 Unauthorized operation Insufficient permissions to perform the operation.
409 409062 Generic column tag error The tag or tags could not be added (or deleted) for some other reason than those specified above.
409 409066 Column not found The column asset does not exist.

Add Tags to Database

Add one or more tags to a database.

For more information about tags, see Tag Items(Link opens in a new window) in the Tableau User Help.

URI

PUT api/api-version/sites/site-id/databases/database-id/tags

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
database-id The unique ID of the database asset.

Request Body

<tsRequest>
  <tags>
	<tag label="tag-value1" />
	<tag label="tag-value2" />
  </tags>
</tsRequest>
      

Attribute Values

tag-value1

Keyword text you want to add to the asset.

tag-value2 Keyword text you want to add to the asset.

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to add tags:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

200

Response Body

Example response

<tsResponse>
  <tags>
	<tag label="Noteworthy" />
	<tag label="PII" />
  </tags>
</tsResponse>
      

Version

Version 3.9 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.
403 403004 Unauthorized operation Insufficient permissions to perform the operation.
404 404031 Database not found The database asset does not exist.
409 409048 Generic database tag error The tag or tags could not be added (or deleted) for some other reason than those specified above.

Add Tags to Table

Add one or more tags to a table.

For more information about tags, see Tag Items(Link opens in a new window) in the Tableau User Help.

URI

PUT api/api-version/sites/site-id/tables/table-id/tags

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
table-id The unique ID of the column asset.

Request Body

<tsRequest>
  <tags>
	<tag label="tag-value1" />
	<tag label="tag-value2" />
  </tags>
</tsRequest>
      

Attribute Values

tag-value1

Keyword text you want to add to the asset.

tag-value2

Keyword text you want to add to the asset.

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to add tags:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

200

Response Body

Example response

<tsResponse>
  <tags>
	<tag label="Noteworthy" />
	<tag label="PII" />
  </tags>
</tsResponse>
      

Version

Version 3.9 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.
403 403004 Unauthorized operation Insufficient permissions to perform the operation.
404 404032 Table not found The table asset does not exist.
409 409055 Generic table tag error The tag or tags could not be added (or deleted) for some other reason than those specified above.

Batch Add Tags

Add multiple tags to items that are different content and asset types.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

For more information about tags, see Tag Items(Link opens in a new window) in the Tableau User Help.

URI

PUT api/api-version/sites/site-id/tags:batchCreate

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.

Request Body

<tsRequest>
  <tagBatch>
	<tags>
	   <tag label="tag-value1"></tag>
	   <tag label="tag-value2"></tag>
	</tags>
	<contents>
	   <content id="database-id"></content>
	   <content id="table-id"></content>
	   <content id="column-id"></content>
	   <content id="datasource-id"></content>
	   <content id="workbook-id"></content>
	   <content id="flow-id"></content>
	</contents>
  </tagBatch>
</tsRequest>
      

Attribute Values

tag-value1

Keyword text you want to add to item.

tag-value2

Keyword text you want to add to item.

database-id The unique ID of the database asset.
table-id The unique ID of the table asset.
column-id The unique ID of the column asset.
datasource-id The unique ID of the data source content.
workbook-id The unique ID of the workbook content.
flow-id The unique ID of the flow content.

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to add tags:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

200

Response Body

Example response

<tsRequest>
  <tagBatch>
	<tags>
	   <tag label="PII"></tag>
	   <tag label="Noteworthy"></tag>
	</tags>
	<contents>
	   <content id="21cade8c-d4eb-4fef-bd4a-bdb9d8b09b7d" contentType="Database"></content>
	   <content id="a0314be1-afd4-4a4f-ab85-d75dac661c41" contentType="Table"></content>
	   <content id="8fec4046-e054-476d-a6d0-e808b0d5448b" contentType="Column"></content>
	   <content id="c8c3a0be-3ac8-4de7-8bd6-f912900a1ccd" contentType="Datasource"></content>
	   <content id="ec2b7845-d627-430e-b99c-8543ed50b25c" contentType="Workbook"></content>
	   <content id="c4a560eb-c8a6-48c6-86f4-c9d5e518d027" contentType="Flow"></content>
	</contents>
  </tagBatch>
</tsRequest>
      

Version

Version 3.9 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.
403 403004 Unauthorized operation Insufficient permissions to perform the operation.
404 404029 Content not found The content does not exist.
404 404031 Database not found The database asset does not exist.
404 404032 Table not found The table asset does not exist.
409 409004 Invalid parameter One or more values in the request body are invalid.
409 409066 Column not found The column asset does not exist.

Delete Database Permissions

Permanently remove the permissions applied to a database asset.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

DELETE api/api-version/sites/site-luid/databases/database-luid/permissions/users/user-luid/capability-name/capability-mode

DELETE api/api-version/sites/site-luid/databases/database-luid/permissions/groups/group-luid/capability-name/capability-mode

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-luid The LUID of the site.
database-luid The LUID of the database asset.
user-luid The LUID of the user to remove the permissions for.
group-luid The LUID of the group to remove the permissions for.
capability-name The explicit permissions capability to remove. Capabilities that can be removed are Read, Write, ChangePermissions, or ChangeHierarchy.
capability-mode The permissions mode to remove. Modes that can be removed are Allow or Deny.

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following authorized users have permissions to delete the permissions on the database asset:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have been granted explicit permission to set or "ChangePermissions" to the asset metadata

Response Code

200

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
400 400120 Bad request Permissions could not be deleted because support for explicit permissions is available for database assets associated with published data sources only.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
403 403117 Database locked Permissions for the database asset cannot be deleted because the database asset is locked.
404 404000 Resource not found The site LUID in the URI doesn't correspond to an existing site.
404 404031 Database not found The requested database could not be found.
409 409045 Database error An unknown database asset error occurred.
409 409051 Database update forbidden A user without "write" permissions to the database asset attempted an update.

Delete Default Database Permissions

Permanently remove the default permissions on a database asset.

Removing the default permissions from the database asset means that any new child table assets that are indexed by Catalog won't have any default permissions set.

Note: If a database is in a project, default database permissions are not evaluated to determine table permissions. Use the Delete Default Permissions method to control default permission capabilities on tables through projects instead.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

DELETE api/api-version/sites/site-luid/databases/database-luid/default-permissions/tables/users/user-luid/capability-name/capability-mode

DELETE api/api-version/sites/site-luid/databases/database-luid/default-permissions/tables/groups/group-luid/capability-name/capability-mode

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-luid The LUID of the site asset.
database-luid The LUID of the database asset.
user-luid The LUID of the user to remove the default permission for.
group-id The LUID of the group to remove the default permission for.
capability-name

The capability to remove the permissions for.

Valid capabilities for databases are the following:

  • Read (view)
  • Write (edit)
  • ChangePermissions (set permissions)
  • ChangeHierarchy (move)

For more information, see Permissions.

capability-mode Allow to remove the allow permission, or Deny to remove the deny permission.

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following authorized users have permissions to delete the permissions on the database asset:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

200

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
400 400120 Bad request Permissions could not be deleted because support for explicit permissions is available for database assets associated with published data sources only.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
403 403117 Database locked Default permissions cannot be deleted because the database asset is locked.
404 404000 Resource not found The site LUID in the URI doesn't correspond to an existing site.
404 404031 Database not found The requested database could not be found.
409 409045 Database error An unknown database asset error occurred.
409 409051 Database update forbidden A user without "write" permissions to the database asset attempted an update.

Delete Data Quality Warning by ID

Permanently remove a data quality warning.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

DELETE api/api-version/sites/site-id/dataQualityWarnings/dataqualitywarning-id

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
dataqualitywarning-id The unique ID of the data quality warning.

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to delete the data quality warning:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

204

Response Body

None

Version

Version 3.5 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 400105 Data quality warning delete error An unknown error occurred and the data quality warning could not be deleted.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
404 404029 Content not found The requested asset could not be found.
404 404030 Data quality warning not found The data quality warning for the requested asset could not be found.

Delete Data Quality Warning by Content

Permanently remove the data quality warning from the database, table, column, published data source, flow, virtual connection, or virtual connection table.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

DELETE api/api-version/sites/site-id/dataQualityWarnings/content-type/content-luid

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
content-type

The type of asset that the data quality warning is being attached to. To specify the type, use:

  • database
  • table
  • column - Available in API 3.16 and later (Tableau Cloud October 2022, Server 2022.3)
  • datasource
  • flow
  • virtualconnection
  • virtualconnectiontable

Types are not case sensitive.

content-luid The LUID of the content (database, table, column, published data source, flow, virtual connection, or virtual connection table).

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to delete the data quality warning:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

204

Response Body

None

Version

Version 3.5 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.
409 400106 Data quality warning delete error An unknown error occurred and the data quality warning could not be deleted.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
404 404029 Content not found The requested asset could not be found.
404 404030 Data quality warning not found The data quality warning for the requested asset could not be found.

Batch Delete Data Quality Warnings

Permanently remove multiple data quality warning (DQW) items from different content and asset types.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

DELETE api/api-version/sites/site-id/dataQualityWarnings/batchDelete

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.

Request Body

<tsRequest>
  <contentList>
	<content contentType="content" id="database-id" />
	<content contentType="content" id="table-id" />
	<content contentType="content" id="column-id" />
	<content contentType="content" id="datasource-id" />
	<content contentType="content" id="flow-id" />
	<content contentType="content" id="virtualconnection-id" />
	<content contentType="content" id="virtualconnectiontable-id" />
  </contentList>
</tsRequest>
      

Attribute Values

content

The type of content or asset the data quality warning is attached to. To specify type, use one of the following values:

  • database
  • table
  • column - Available in API 3.16 and later (Tableau Cloud October 2022, Server 2022.3)
  • datasource
  • flow
  • virtualconnection
  • virtualconnectiontable
database-id The unique ID of the database asset.
table-id The unique ID of the table asset.
column-id The unique ID of the column asset.
datasource-id The unique ID of the data source content.
flow-id The unique ID of the flow content.
virtualconnection-id The unique ID of the virtual connection.
virtualconnectiontable-id The unique ID of the virtual connection table.

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to delete data quality warnings:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

204

Response Body

None

Version

Version 3.12 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.
403 403004 Unauthorized operation Insufficient permissions to perform the operation.
404 404029 Content not found The content does not exist.
404 404031 Database not found The database asset does not exist.
404 404032 Table not found The table asset does not exist.
409 409004 Invalid parameter One or more values in the request body are invalid.

Delete Data Quality Certification by ID

Permanently remove a data quality certification from a content or asset item using the data quality certification ID.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

DELETE api/api-version/sites/site-id/dataQualityCertifications/certification-luid

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
certification-luid The unique ID of the data quality certification.

Request body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to delete a data quality certification:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

204

Version

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

Errors

HTTP status error Code Condition Details
400 400105 Generic data quality certification error The data quality certification could not be deleted for some reason other than those specified in this table.
403 403004 Unauthorized operation Insufficient permissions to perform the operation.
409 409004 Invalid parameter One or more values in the request body are invalid.

Delete Data Quality Certifications by Content

Permanently remove all data quality certifications from multiple content or asset items.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

DELETE api/api-version/sites/site-id/dataQualityCertifications

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
indicator-id The unique ID of the data quality certification.

Request body

<tsRequest>
  <contentList>
	<content contentType="content" id="database-id" />
	<content contentType="content" id="table-id" />
	<content contentType="content" id="datasource-id" />
	<content contentType="content" id="virtualconnection-id" />
	<content contentType="content" id="virtualconnectiontable-id" />
  </contentList>
</tsRequest>

Attribute Values

content

The type of content or asset the data quality warning is attached to. To specify type, use one of the following values:

  • database
  • table
  • datasource
  • virtualconnection
  • virtualconnectiontable
database-id The unique ID of the database asset.
table-id The unique ID of the table asset.
datasource-id The unique ID of the data source content.
virtualconnection-id The unique ID of the virtual connection.
virtualconnectiontable-id The unique ID of the virtual connection table.

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to delete data quality certifications:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

204

Version

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

Errors

HTTP status error Code Condition Details
400 400106 Generic data quality certification error The data quality certifications could not be deleted for some reason other than those specified in this table.
404 404029 Content not found The content does not exist.
403 403004 Unauthorized operation Insufficient permissions to perform the operation.
409 409004 Invalid parameter One or more values in the request body are invalid.

Delete Quality Warning Trigger by ID

Permanently remove a quality warning trigger using the quality warning trigger ID.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

DELETE api/api-version/sites/site-id/dataQualityTriggers/trigger-id

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
trigger-id

The unique ID of the quality warning trigger.

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to delete a quality warning trigger:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

200

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
400 400138 Generic quality warning trigger error The quality warning trigger could not be deleted for some other reason than those specified below.
403 403004 Unauthorized operation Insufficient permissions to perform the operation.
404 404037 Quality warning not found The requested quality warning trigger was not found.
409 409004 Invalid parameter One or more values in the request body are invalid.

Delete Quality Warning Triggers by Content

Permanently remove all quality warning triggers for one or more data sources or flows, or both.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

Delete one quality warning trigger

DELETE api/api-version/sites/site-id/dataQualityTriggers/content-type/contentIds?filter=contentId:in:[content-luid]

Delete multiple quality warning triggers

DELETE api/api-version/sites/site-id/dataQualityTriggers/content-type/contentIds?filter=contentId:in:[content-luid1,content-luid2,content-luid3,...]

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
content-type

The type of content the quality warning trigger has been applied to. In this case, use one of the following values:

  • datasource
  • flow

These values are not case sensitive.

content-luid The unique ID of the asset. This is the same as the content ID.

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to delete quality warning triggers:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

200

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
400 400138 Generic quality warning trigger error The quality warning trigger could not be deleted for some other reason than those specified below.
403 403004 Unauthorized operation Insufficient permissions to perform the operation.
404 404037 Quality warning not found The requested quality warning trigger was not found.
409 409004 Invalid parameter One or more values in the request body are invalid.

Delete Label

Deletes a data label by its LUID.

You can't delete extract refresh or flow run monitoring warnings (the extract_refresh_failure and flow_run_failure label values) using this method because those warnings are set and cleared automatically, depending on their triggers. See also "How to set a monitoring quality warning" in the Tableau Server(Link opens in a new window) and Tableau Cloud(Link opens in a new window) Help and the quality warning trigger methods in Metadata Methods.

All label operations except those related to the certification of data sources require Catalog to be enabled. Catalog requires a Data Management license.

URI

DELETE api/api-version/sites/site-luid/labels/label-luid

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-luid The unique LUID of the site asset.
label-luid The unique LUID of the label asset.

Request Body

None

Permissions

  • To delete a warning label, you must have Write permission on the associated asset.
  • To delete a certification label for an asset in a project, you must be a Tableau Server site or server admin, a Tableau Cloud site admin, a project leader for the project the asset is in, or the project owner for the project the asset is in.
  • To delete a certification label for an asset not in a project, you must have the ChangePermissions permission on the associated asset.

Response Code

204

Version

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

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.
401 400105 Generic delete label error An unknown error occurred. Confirm that the LUID in the URI is correct.
403 403004 Operation on resource unauthorized Insufficient permissions to perform the operation.
409 409004 Invalid parameter The URI does not contain a properly-formatted LUID.

Delete Labels on Assets

Deletes the data labels on one or more assets.

You can optionally limit the data labels to delete by category using a query string.

You can't delete extract refresh or flow run monitoring warnings (the extract_refresh_failure and flow_run_failure label values) using this method because those warnings are set and cleared automatically, depending on their triggers. See also "How to set a monitoring quality warning" in the Tableau Server(Link opens in a new window) and Tableau Cloud(Link opens in a new window) Help and the quality warning trigger methods in Metadata Methods.

All label operations except those related to the certification of data sources require Catalog to be enabled. Catalog requires a Data Management license.

URI

DELETE api/api-version/sites/site-luid/labels

DELETE api/api-version/sites/site-luid/labels?categories=category-list

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-luid The unique LUID of the site.
category-list (Optional) A comma-separated list of categories used to limit the label deletions to only the listed categories. Valid categories are warning and certification.

Request Body

<tsRequest>
  <contentList>
    <content contentType="asset-type"
      id="asset-luid" />
    <!-- ... additional content elements ... -->
  </contentList>
</tsRequest>      

Attribute Values

asset-type

The type of asset. Valid asset types are:

  • database
  • table
  • column - Available in API 3.16 and later (Tableau Cloud October 2022, Server 2022.3)
  • datasource
  • flow
  • virtualconnection
  • virtualconnectiontable
asset-luid The asset LUID.

Permissions

  • To delete a warning label, you must have Write permission on the associated asset.
  • To delete a certification label for an asset in a project, you must be a Tableau Server site or server admin, a Tableau Cloud site admin, a project leader for the project the asset is in, or the project owner for the project the asset is in.
  • To delete a certification label for an asset not in a project, you must have the ChangePermissions permission on the associated asset.

Response Code

204

Version

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

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.
401 400106 Generic delete labels error An unknown error occurred.
403 403004 Operation on resource unauthorized Insufficient permissions to perform the operation.
404 404029 Resource not found The contentType and contentID attribute combination does not correspond to an asset on the server. This can be caused by an incorrect contentType, an incorrect contentID, or both.
409 409004 Invalid parameter One or more values in the request body are invalid.

Delete Table Permissions

Permanently remove the permissions applied to a table asset.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

DELETE api/api-version/sites/site-luid/tables/table-luid/permissions/users/user-luid/capability-name/capability-mode

DELETE api/api-version/sites/site-luid/tables/table-luid/permissions/groups/group-luid/capability-name/capability-mode

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-luid The LUID of the site asset.
table-luid The LUID of the table asset.
user-luid The LUID of the user to remove the permissions for.
group-luid The LUID of the group to remove the permissions for.
capability-name The explicit permissions capability to remove. Capabilities that can be removed are Read, Write, ChangePermissions, or ChangeHierarchy.
capability-mode The permissions mode to remove. Modes that can be removed are Allow or Deny.

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to delete the permissions on a table asset:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have been granted explicit permission to set or "ChangePermissions" to the asset metadata

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
400 400120 Bad request Permissions could not be deleted because support for explicit permissions is available for table assets associated with published data sources only.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
403 403117 Database locked Permissions for the table asset cannot be deleted because the database asset is locked.
404 404000 Resource not found The site LUID in the URI doesn't correspond to an existing site.
409 409051 Database update forbidden A user without "write" permissions to the database asset attempted an update.

Delete Tag from Column

Delete a tag from a column.

For more information about tags, see Tag Items(Link opens in a new window) in the Tableau User Help.

URI

DELETE api/api-version/sites/site-id/columns/column-id/tags/tag-name

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
column-id The unique ID of the column asset.
tag-name The keyword text of the tag.

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to delete tags:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Unauthorized operation Insufficient permissions to perform the operation.
404 404007 Tag not found The tag does not exist.
409 409062 Generic database tag error The tag or tags could not be deleted (or added) for some other reason than those specified in this table.
409 409066 Column not found The column asset does not exist.

Delete Tag from Database

Delete a tag from a database.

For more information about tags, see Tag Items(Link opens in a new window) in the Tableau User Help.

URI

DELETE api/api-version/sites/site-id/databases/database-id/tags/tag-name

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
database-id The unique ID of the database asset.
tag-name The keyword text of the tag.

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to delete tags:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Unauthorized operation Insufficient permissions to perform the operation.
404 404007 Tag not found The tag does not exist.
404 404031 Database not found The database asset does not exist.
409 409048 Generic database tag error The tag or tags could not be deleted (or added) for some other reason than those specified above.

Delete Tag from Table

Delete a tag from a table.

For more information about tags, see Tag Items(Link opens in a new window) in the Tableau User Help.

URI

DELETE api/api-version/sites/site-id/tables/table-id/tags/tag-name

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
table-id The unique ID of the table asset.
tag-name The keyword text of the tag.

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to delete tags:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

204

Response Body

None

Version

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

Errors

HTTP status error Code Condition Details
403 403004 Unauthorized operation Insufficient permissions to perform the operation.
404 404007 Tag not found The tag does not exist.
404 404032 Table not found The table asset does not exist.
409 409055 Generic database tag error The tag or tags could not be deleted (or added) for some other reason than those specified above.

Batch Delete Tags

Delete multiple tags from items that are different content and asset types.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

For more information about tags, see Tag Items(Link opens in a new window) in the Tableau User Help.

URI

DELETE api/api-version/sites/site-id/tags:BatchDelete

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.

Request Body

<tsRequest>
  <tagBatch>
	<tags>
	   <tag label="tag-value1"></tag>
	   <tag label="tag-value2"></tag>
	</tags>
	<contents>
	   <content id="database-id"></content>
	   <content id="table-id"></content>
	   <content id="column-id"></content>
	   <content id="datasource-id"></content>
	   <content id="workbook-id"></content>
	   <content id="flow-id"></content>
	</contents>
  </tagBatch>
</tsRequest>
      

Attribute Values

tag-value1

Keyword text you want to add to item.

tag-value2

Keyword text you want to add to item.

database-id The unique ID of the database asset.
table-id The unique ID of the table asset.
column-id The unique ID of the column asset.
datasource-id The unique ID of the data source content.
workbook-id The unique ID of the workbook content.
flow-id The unique ID of the flow content.

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to delete tags:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

204

Response Body

Example response

<tsRequest>
  <tagBatch>
	<tags>
	   <tag label="PII"></tag>
	   <tag label="Noteworthy"></tag>
	</tags>
	<contents>
	   <content id="database-id"></content>
	   <content id="table-id"></content>
	   <content id="column-id"></content>
	   <content id="datasource-id"></content>
	   <content id="workbook-id"></content>
	   <content id="flow-id"></content>
	</contents>
  </tagBatch>
</tsRequest>
      

Version

Version 3.9 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.
403 403004 Unauthorized operation Insufficient permissions to perform the operation.
404 404029 Content not found The content does not exist.
404 404031 Database not found The database asset does not exist.
404 404032 Table not found The table asset does not exist.
409 409004 Invalid parameter One or more values in the request body are invalid.
409 409066 Column not found The column asset does not exist.

Get Label

Gets a data label by its LUID.

All label operations except those related to the certification of data sources require Catalog to be enabled. Catalog requires a Data Management license.

URI

GET api/api-version/sites/site-luid/labels/label-luid

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-luid The unique LUID of the site asset.
label-luid The unique LUID of the label asset.

Request Body

None

Permissions

You must have Read permissions on the associated asset.

Response Code

200

Response Body

<tsResponse>
  <label id="label-luid"
      userDisplayName="user-display-name"
      contentId="asset-luid"
      contentType="asset-type"
      message="label-message"
      value="label-value"
      category="label-category"
      active="true-or-false"
      elevated="true-or-false"
      createdAt="datetime"
      updatedAt="datetime" >
    <site id="site-luid"/>
    <owner id="user-luid"/>
  </label>
</tsResponse>

Version

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

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.
401 400103 Generic query label error An unknown error occurred.
403 403004 Operation on resource unauthorized Insufficient permissions to perform the operation.
404 404030 Label not found The label LUID doesn't correspond to an existing project.
409 409004 Invalid parameter One or more values in the request body are invalid.

Get Labels on Assets

Displays information about the data labels on one or more assets.

You can optionally limit the data labels to show by category using a query string.

All label operations except those related to the certification of data sources require Catalog to be enabled. Catalog requires a Data Management license.

URI

POST api/api-version/sites/site-luid/labels

POST api/api-version/sites/site-luid/labels?categories=category-list

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-luid The unique LUID of the site asset.
category-list (Optional) A comma-separated list of categories used to limit the labels shown to only the listed categories. Valid categories are warning and certification.

Request Body

<tsRequest>
  <contentList>
    <content contentType="asset-type"
      id="asset-luid" />
    <!-- ... additional content elements ... -->
  </contentList>
</tsRequest>      

Attribute Values

asset-type

The type of asset. Valid asset types are:

  • database
  • table
  • column - Available in API 3.16 and later (Tableau Cloud October 2022, Server 2022.3)
  • datasource
  • flow
  • virtualconnection
  • virtualconnectiontable
asset-luid The asset LUID.

Permissions

You must have Read permissions on the associated asset.

Response Code

200

Response Body

<tsResponse>
  <labelList>
    <label id="label-luid"
        userDisplayName="user-display-name"
        contentId="asset-luid"
        contentType="asset-type"
        message="label-message"
        value="label-value"
        category="label-category"
        active="true-or-false"
        elevated="true-or-false"
        createdAt="datetime"
        updatedAt="datetime">
      <site id="site-luid"/>
      <owner id="user-luid"/>
    </label>
    <!-- ... additional label elements ... –->
  </labelList>
</tsResponse>

Version

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

Errors

When more than one asset appears in the request (the contentList element contains more than one content element), this method will fail if an error is encountered operating on any of them. For example, if you are getting labels for a database and a table, but you provide the wrong table LUID, the method will return an error even if the database LUID was correct.

HTTP status error Code Condition Details
400 400000 Bad request The content of the request body is missing or incomplete, or contains malformed XML.
401 400104 Generic delete label error An unknown error occurred.
403 403004 Operation on resource unauthorized Insufficient permissions to perform the operation.
404 404029 Resource not found The contentType and contentID attribute combination does not correspond to an asset on the server. This can be caused by an incorrect contentType, an incorrect contentID, or both.
409 409004 Invalid parameter One or more values in the request body are invalid.

Get Databases and Tables from Connection

Query databases and tables from the connection information in the data source (.tds or .tdsx) or workbook (.tws or .twbx) file's XML.

Note: This method can't be used to query databases and tables when the database is an embedded asset. For more information about embedded assets see one of the following: 

URI

POST api/api-version/sites/site-id/databaseAndTables/lookup

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.

Request Body

<tsRequest>
  <databaseAnchor isArchived="embedded"
    datasourceName="datasource_name" datasourceFormattedName="datasource_format">
	<connectionParams>
	   <base64xml>encoded_xml</base64xml>
  	</connectionParams>
  </databaseAnchor>
</tsRequest> 

Attribute Values

embedded

(Optional) Indicates whether the database is embedded or not. Use "false" if the database is not embedded and "true" if the database is embedded. For more information about embedded databases (and tables), see one of the following topics: 

datasource-name (Optional) The data source name that can be found in the XML of the data source (.tds or .tdsx) or workbook (.tws or .twbx) file.
datasource-format (Optional) The format of the data source that can be found in the XML of the data source (.tds or .tdsx) or workbook (.tws or .twbx) file.
encoded_xml

This is the encoded version of the connection element (<connection>...</connection>) in the XML of the data source (.tds or .tdsx) or workbook (.tws or .twbx) file.

  • Before you begin, make a copy of the data source or workbook file to ensure you have a backup.
  • To encode the connection element, you can use a free online base64 encoding tool or write a simple script. Note: Make sure there are no extra spaces between the connection element's start and end tags. For example, after encoding the connection element, the generated encoding should look like <base64xml>...</base64xml>. If the generated encoding looks like <base64xml> ... </base64xml>, you might see an invalid parameter (409097) error.

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to query databases and tables from the connection:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have "derived permissions" (if enabled) or have been granted explicit "Read" (view) permissions to the asset

Otherwise, authorized users who have "derived permissions" (if enabled), and Tableau Server admins or Tableau Cloud site admins.

Response Code

200

Response Body

Example response

<tsResponse>
  <databaseAnchors>
	<databaseAnchor connectionName="mysql.myco" id="71081fcd-d142-4d19-98b5-c87192d837f5">
	  <tableAnchors>
		<tableAnchor id="85e7b082-20c0-433d-9bfe-70506a93452b" name="Marketing" fullName="[Marketing]"/>
	  </tableAnchors>
	</databaseAnchor>
	<databaseAnchor connectionName="sqlserver.myco" id="1ef8c5cc-7d82-4062-aff7-2d9305cab8a1">
	  <tableAnchors>
		<tableAnchor id="8b8c639a-864e-4f29-b1d8-23057d2d59f3" name="Advertising" fullName="[dbo].[Advertising]"/>
	  </tableAnchors>
	</databaseAnchor>
  </databaseAnchors>
</tsResponse>

Note: Both databaseAnchor and tableAnchor IDs returned from this request correspond to database and table IDs that you can use to retrieve additional information about databases and tables endpoints using other REST endpoints, including Query Database and Query Table.

Version

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

Errors

HTTP status error Code Condition Details
409 409095 Generic asset retrieval error The database and table information could not be queried for some reason other than those specified in this table.
409 409096 Unauthorized operation Insufficient permissions to perform the operation.
409 409097 Invalid parameter One or more values in the request body are invalid.

Move Database

Move one or more databases to a project. You can move the database and its tables, or move only the database. To move a table independently of its database, use the Move Table method.

Note: Starting in Tableau Cloud June 2022 and Tableau Server 2022.3, projects can contain databases and tables, and database and table permissions can be managed at the project level through inheritance. In Tableau Cloud March 2022 and Tableau Server 2022.1 and earlier, projects couldn't contain databases or tables.

The Move Database method can either:

  • Move a database from one project to another project.
  • Move a database not in a project to a project.

This method can't remove a database from all projects. (The only way to remove a database from all projects is to delete the project that the database is in.)

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

POST api/api-version/sites/site-luid/databases

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-luid The LUID of the site that contains the database.

Request Body

<tsRequest>
  <contentLocationRequest>
    <location id="project-luid" type="location-type" />
    <contentAction action="action-type" />
    <resourceList>
      <resource id="database-luid" contentType="asset-type"/>
      <!-- ... more database resources ... -->
    </resourceList>
  </contentLocationRequest>
</tsRequest>

The contentAction element is optional.

  • If the contentAction element is not included, moving the database will also move its tables.
  • If the contentAction element is included and the action attribute is set to MoveDatabaseOnly, moving the database will not move its tables.

The resourceList element can contain a minimum of 1 and a maximum of 1000 resource elements.

Attribute Values

project-luid The LUID of the destination project.
location-type

The destination type. Currently, this value must be "PROJECT".

action-type To move a database without moving its tables, this value must be "MoveDatabaseOnly".
database-luid The LUID of the database.
asset-type The type of asset being moved. Currently, this value must be "DATABASE".

Permissions

If you are moving a database without its tables, you must have read and changeHierarchy permissions for the database, and write permission for the target project.

If you are moving both a database and its tables, you must have read and changeHierarchy permissions for both the database and its tables, and write permission for the target project.

Note: Currently, you can only set the ChangeHierarchy permission for databases and tables using the REST API. See Add Database Permissions and Add Table Permissions for information on adding this permission.

Setting the required database and table permissions depends on whether the database is in a project or not.

Response Code

200

Response Body

Example response when all elements were moved successfully:

<tsResponse />

Example response when not all elements were moved successfully.:

When some database resource elements of a request with multiple database resource elements can’t be moved, the HTTP status 400 is returned, and the response contains additional information about failures. Resource elements from the request body that are not referenced in the response body were successfully moved. A response indicating partial success looks like:

<tsResponse>
  <error code="400000">
    <summary>Bad Request</summary>
    <detail>There was a problem completing one or more requests.</detail>
  </error>
  <warnings>
    <warning message="Database '12ab34cd-56ef-78ab-90cd-12ef34ab56cd' could not be found."
        id="12ab34cd-56ef-78ab-90cd-12ef34ab56cd"
        errorCode="404031"/>
  </warnings>
</tsResponse>     

Version

Introduced Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17). 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 409100 Invalid location type The location element's type attribute must be "PROJECT".
400 409103 Invalid content type The resource element's contentType attribute must be "DATABASE".
403 403004 Operation on resource unauthorized Insufficient permissions or operation not allowed. Make sure Tableau Catalog is enabled.
403 403030 Permissions denied The user does not have permission to move the database.
403 403112 Invalid Operation The database may be embedded, and therefore cannot be moved.
403 403156 External assets can not be moved The user does not have appropriate permissions.
404 404005 Project not found The project LUID doesn't correspond to an existing project.
404 404031 Database not found The database LUID doesn't correspond to an existing database. In a case where multiple databases were specified in the request, other database moves could have succeeded.

For more information, see Handling Errors.

Example

curl --location --request POST 'http://MY-SERVER/api/3.16/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/databases' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: 12ab34cd56ef78ab90cd12ef34ab56cd' -d @move-database.xml

Content of move-database.xml:

<tsRequest>
  <contentLocationRequest>
  <location id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" type="PROJECT" />
    <resourceList>
      <resource id="dd9eb9de-50b3-4f90-a224-e6170e044766" contentType="DATABASE"/>
    </resourceList>
  </contentLocationRequest>
</tsRequest>

Example response:

<tsresponse />

Move Table

Moves one or more tables to a project.

Note: Starting in Tableau Cloud June 2022 and Tableau Server 2022.3, projects can contain databases and tables, and database and table permissions can be managed at the project level through inheritance. In Tableau Cloud March 2022 and Tableau Server 2022.1 and earlier, projects couldn’t contain databases or tables.

The Move Table method can either:

  • Move a table from one project to another project.
  • Move a table not in a project to a project.

This method can’t remove a table from all projects. (The only way to remove a table from all projects is to delete the project that the table is in.)

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

POST api/api-version/sites/site-luid/tables

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-luid The LUID of the site that contains the table.

Request Body

<tsRequest>
  <contentLocationRequest>
    <location id="project-luid" type="location-type" />
      <resourceList>
        <resource id="table-luid" contentType="asset-type"/>
        <!-- ...more resources... -->
      </resourceList>
  </contentLocationRequest>
</tsRequest>

The resourceList element can contain a minimum of 1 and a maximum of 1000 resource elements.

Attribute Values

project-luid The LUID of the destination project.
location-type

The destination type. Currently, this value must be "PROJECT".

table-luid The LUID of the table.
asset-type The type of asset being moved. Currently, this value must be "TABLE".

Permissions

You must have read and changeHierarchy permissions for the table, and write permission for the target project.

If you are moving both a database and its tables, you must have read and changeHierarchy permissions for both the database and its tables, and write permission for the target project.

Note: Currently, you can only set the ChangeHierarchy permission for databases and tables using the REST API. See Add Database Permissions and Add Table Permissions for information on adding this permission.

Setting the required table permissions depends on whether the parent database is in a project or not.

Response Code

200

Response Body

Example response when all elements were moved successfully:

<tsResponse />

Example response when not all elements were moved successfully.:

When some table resource elements of a request with multiple table resource elements can’t be moved, the HTTP status 400 is returned, and the response contains additional information about failures. Resource elements from the request body that are not referenced in the response body were successfully moved. A response indicating partial success looks like:

<tsResponse>
  <error code="400000">
    <summary>Bad Request</summary>
    <detail>There was a problem completing one or more requests.</detail>
  </error>
  <warnings>
    <warning message="Table '12ab34cd-56ef-78ab-90cd-12ef34ab56cd' could not be found."
      id="12ab34cd-56ef-78ab-90cd-12ef34ab56cd"
      errorCode="404032"/>
    </warnings>
</tsResponse>    

Version

Introduced Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17). 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 409100 Invalid location type The location element's type attribute must be "PROJECT".
400 409103 Invalid content type The resource element's contentType attribute must be "TABLE".
403 403004 Operation on resource unauthorized Insufficient permissions or operation not allowed. Make sure Tableau Catalog is enabled.
403 403030 Permissions denied The user does not have permission to move the table.
403 403112 Invalid Operation The table may belong to an embedded database, and therefore cannot be moved.
403 403156 External assets can not be moved The user does not have appropriate permissions.
404 404005 Project not found The project LUID doesn't correspond to an existing project.
404 404032 Table not found The table LUID doesn't correspond to an existing table. In a case where multiple tables were specified in the request, other table moves could have succeeded.

For more information, see Handling Errors.

Example

curl --location --request POST 'http://MY-SERVER/api/3.16/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/tables' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: 12ab34cd56ef78ab90cd12ef34ab56cd' -d @move-table.xml

Content of move-table.xml:

<tsRequest>
  <contentLocationRequest>
  <location id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" type="PROJECT" />
    <resourceList>
      <resource id="ac353e22-3e78-43a7-914f-73e9bd05ec97" contentType="TABLE"/>
    </resourceList>
  </contentLocationRequest>
</tsRequest>

Example response:

<tsresponse />

Query Column in a Table

Get information about a column in a table asset.

URI

GET api/api-version/sites/site-id/tables/table-id/columns/column-id

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
table-id The unique ID of the table asset.
column-id The unique ID of the column asset.

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to query a column asset in a table:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have "derived permissions" (if enabled) or have been granted explicit "Read" (view) permissions to the asset

Otherwise, authorized users who have "derived permissions" (if enabled), and Tableau Server admins or Tableau Cloud site admins.

Response Code

200

Response Body

Example response:

<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-3.5.xsd">
	<column id="0b589fc9-1523-4aae-b711-62d48672ac6a" name="StateProvinceID" remoteType="I4" parentTableId="75029ee7-935a-4f57-8717-58c2339dd219">
	  <site id="5286d663-8668-4ac2-8c8d-91af7d585f6b"/>
	</column>
</tsResponse>
      

Version

Version 3.5 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.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
409 409059 Unknown column error An unknown column asset error occurred.
409 409060 Unknown column query error An unknown error occurred and the column query could not complete.
409 409066 Column not found The requested column asset could not be found.

Query Columns in a Table

Get information about the columns in a table asset.

URI

GET api/api-version/sites/site-id/tables/table-id/columns

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
table-id The unique ID of the table asset.

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to query column assets in a table:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have "derived permissions" (if enabled) or have been granted explicit "Read" (view) permissions to the asset

Otherwise, authorized users who have "derived permissions" (if enabled), and Tableau Server admins or Tableau Cloud site admins.

Response Code

200

Response Body

Example response:

<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-3.5.xsd">
  <columns>
	<column id="38cb9944-4b81-4107-8946-5adf9e047d23" name="AddressID" remoteType="I4" parentTableId="75029ee7-935a-4f57-8717-58c2339dd219">
		<site id="5286d663-8668-4ac2-8c8d-91af7d585f6b"/>
	</column>
	<column id="c6dcdb0e-9b2a-4224-bf3b-58662fe72b09" name="AddressLine1" remoteType="WSTR" parentTableId="75029ee7-935a-4f57-8717-58c2339dd219">
		<site id="5286d663-8668-4ac2-8c8d-91af7d585f6b"/>
	</column>
  </columns>
</tsResponse>
      

Version

Version 3.5 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.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
409 409059 Unknown column error An unknown column asset error occurred.
409 409060 Unknown column query error An unknown error occurred and the column query could not complete.
409 409066 Column not found The requested column assets could not be found.

Query Database

Get information about a database asset.

URI

GET api/api-version/sites/site-luid/databases/database-luid

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-luid The LUID of the site asset.
database-luid The LUID of the database asset.

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to query a database asset:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have "derived permissions" (if enabled) or have been granted explicit "Read" (view) permissions to the asset

Otherwise, authorized users who have "derived permissions" (if enabled), and Tableau Server admins or Tableau Cloud site admins.

Response Code

200

Response Body

Example response:

<tsResponse>
  <database id="c495c67b-2a17-4706-991c-b3b14f881e20" name="dataengine_42020_789079537040lea.hyper" connectionType="hyper" isEmbedded="true" isCertified="true" certificationNote="Verified" type="File" filePath="dataengine_42020_789079537040lea.hyper" contentPermissions="ManagedByOwner">
    <site id="5286d663-8668-4ac2-8c8d-91af7d585f6b"/>
    <contact id="95656dcf-c669-46c0-81fb-8f278e4806b2" name="fsuzuki"/>
    <certifier id="2c5ea058-6408-46a6-9aa2-09f795a31237" name="snguyen"/>
    <location id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" type="PROJECT"/>
    <tags/>
  </database>
</tsResponse>
      

Note: This method returns connection information, including connection type. In some cases, the name of the connection type might not map directly to a name of a connection type that you're familiar with. In those cases, see Mapping ConnectionType Names for more information.

Version

Version 3.5 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.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site LUID in the URI doesn't correspond to an existing site.
404 404031 Database not found The requested database could not be found.
409 409045 Database error An unknown database asset error occurred.
409 409046 Unknown database query error An unknown error occurred and the database query could not complete.

Query Databases

Get information about all database assets for a site.

URI

GET api/api-version/sites/site-luid/databases

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-luid The LUID of the site asset.

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to query database assets:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have "derived permissions" (if enabled) or have been granted explicit "Read" (view) permissions to the asset

Otherwise, authorized users who have "derived permissions" (if enabled), and Tableau Server admins or Tableau Cloud site admins.

Response Code

200

Response Body

Example response:

<tsResponse>
  <databases>
	<pagination pageNumber="1" pageSize="100" totalAvailable="496">
	<database id="b749a80e-43eb-4805-9e6d-44c615ee10e2" name="airlines" connectionType="sqlserver" isEmbedded="false" description="This is about airlines and other stuff but mainly airlines"
		isCertified="true" certificationNote="THIS IS ALSO FROM THE REST API"
        type="DatabaseServer" hostName="mssql.test.example.com" contentPermissions="ManagedByOwner">
		<site id="5286d663-8668-4ac2-8c8d-91af7d585f6b"/>
		<contact id="95656dcf-c669-46c0-81fb-8f278e4806b2" name="jsmith"/>
        <certifier id="2c5ea058-6408-46a6-9aa2-09f795a31237" name="snguyen"/>
        <location id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" type="PROJECT"/>
        <tags/>
	</database>
	<database id="522f8295-5a07-4ba7-89be-cbbd9617928d" name="small.csv" connectionType="textscan" isEmbedded="true"
        isCertified="false"
         type="File" filePath="small.csv" contentPermissions="ManagedByOwner">
		<site id="5286d663-8668-4ac2-8c8d-91af7d585f6b"/>
		<contact id="95656dcf-c669-46c0-81fb-8f278e4806b2" name="fsuzuki"/>
        <tags/>
	</database>
	<database id="fcd0f91e-8c8d-45c4-848a-0aa3b42990c6" name="ows.json" connectionType="semistructpassivestore-direct" isEmbedded="true"
        isCertified="false"
        type="File" filePath="ows.json" contentPermissions="ManagedByOwner">
		<site id="5286d663-8668-4ac2-8c8d-91af7d585f6b"/>
        <tags/>
	</database>
	<database id="24010777-0e17-43ed-8624-577a85e8043b" name="/Users/awang/Dropbox (Tableau Software)/911_calls_short.csv" connectionType="textscan" isEmbedded="false"
        isCertified="false"
        type="File" filePath="/Users/jsmith/Dropbox (Tableau Software)/911_calls_short.csv" contentPermissions="ManagedByOwner">
		<site id="5286d663-8668-4ac2-8c8d-91af7d585f6b"/>
        <location id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" type="PROJECT"/>
        <tags/>
	</database>
	<database id="1d1879b2-789d-46c2-950f-f82a4d77e150" name="911_calls_short.csv" connectionType="textscan" isEmbedded="true"
        isCertified="false"
        type="File" filePath="911_calls_short.csv" contentPermissions="ManagedByOwner">
		<site id="5286d663-8668-4ac2-8c8d-91af7d585f6b"/>
        <tags/>
	</database>
	<database id="bc872610-aa3e-4071-8a39-2c1a847cf39c" name="Prince.xlsx" connectionType="excel-direct" isEmbedded="true"
        isCertified="false"
        type="File" filePath="Prince.xlsx" contentPermissions="ManagedByOwner">
		<site id="5286d663-8668-4ac2-8c8d-91af7d585f6b"/>
        <tags/>
	</database>
  </databases>
</tsResponse>
      

Note: This method returns connection information, including connection type. In some cases, the name of the connection type might not map directly to a name of a connection type that you're familiar with. In those cases, see Mapping ConnectionType Names for more information.

Version

Version 3.5 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.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site LUID in the URI doesn't correspond to an existing site.
404 404031 Database not found The requested databases could not be found.
409 409045 Database error An unknown database asset error occurred.
409 409046 Unknown database query error An unknown error occurred and the database query could not complete.

Query Database Permissions

Get information about the permissions on a database asset.

URI

GET api/api-version/sites/site-luid/databases/database-luid/permissions

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-luid The LUID of the site asset.
database-luid The LUID of the database asset.

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following authorized users have permissions to query the permissions on the database asset:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have been granted explicit permission to set or "ChangePermissions" to the asset metadata

Response Code

200

Response Body

Example response with explicit permissions set on a database asset:

<tsResponse>
  <permissions>
	<database id="e8d4aa9f-3d1a-4b49-8d6d-27f113cbd25e" name="oracle.test.example.com:1521"/>
	<granteeCapabilities>
	  <user id="6265b714-7533-465d-b6db-6d0be92bfd07"/>
	  <capabilities>
		<capability name="Read" mode="Allow"/>
	  </capabilities>
	</granteeCapabilities>
  </permissions>
</tsResponse>
      

Example response without explicit permissions set on a database asset:

<tsResponse>
  <permissions>
	<database id="0f206b0e-da69-4746-bb95-87695f522b4d" name="stage"/>
  </permissions>
</tsResponse>
    

Version

Version 3.5 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 400120 Bad request Permissions could not be returned because support for explicit permissions is available for database assets associated with published data sources only.
401 401000 Unauthorized access No authorization credentials were provided.
400 400120 Bad request Support for explicit permissions is available for database assets associated with published data sources only.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site LUID in the URI doesn't correspond to an existing site.
404 404031 Database not found The requested database could not be found.
409 409045 Database error An unknown database asset error occurred.

Query Default Database Permissions

Get the default permissions applied to the database asset and its children tables.

Note: If a database is in a project, default database permissions are not evaluated to determine table permissions. Use Query Default Permissions to see default permissions for projects instead.

URI

GET /api/api-version/sites/site-luid/databases/database-luid/default-permissions/tables

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-luid The LUID of the site asset.
database-luid The LUID of the database asset to set default permissions for.

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following authorized users set default permissions for the database asset:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

200

Response Body

Example response

<tsResponse>
  <permissions>
	<database id="e8d4aa9f-3d1a-4b49-8d6d-27f113cbd25e" name="oracle.test.example.com:1521"/>
	<granteeCapabilities>
	  <user id="6265b714-7533-465d-b6db-6d0be92bfd07"/>
	  <capabilities>
		<capability name="Read" mode="Allow"/>
	  </capabilities>
	</granteeCapabilities>
  </permissions>
</tsResponse>
		
      

Version

Version 3.5 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 400120 Bad request Permissions could not be returned because support for explicit permissions is available for database assets associated with published data sources only.
404 404000 Site not found The site LUID in the URI doesn't correspond to an existing site.
404 404003 Resource not found The database LUID in the URI doesn't correspond to a database asset on the site.

Query Data Quality Warning by ID

Get information about a specific data quality warning.

URI

GET api/api-version/sites/site-id/dataQualityWarnings/dataqualitywarning-id

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
dataqualitywarning-id The unique ID of the data quality warning.

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to query the data quality warning:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have "derived permissions" (if enabled) or have been granted explicit "Read" (view) permissions to the asset

Otherwise, authorized users who have "derived permissions" (if enabled), and Tableau Server admins or Tableau Cloud site admins.

Response Code

200

Response Body

Example response:

<tsResponse>
   <dataQualityWarning id="1c8ebdfc-270a-4414-812c-3306a1c95e07" userDisplayName="Steve Nguyen" contentId="0d7465f2-4989-417e-b88d-f787359edc63" contentType="DATABASE" message="Delayed" type="WARNING" isActive="true" createdAt="2020-10-08T00:00:35Z" updatedAt="2020-10-08T00:00:35Z" isSevere="false">
	<site id="a946d998-2ead-4894-bb50-1054a91dcab3"/>
	<owner id="cdfe8548-84c8-418e-9b33-2c0728b1234a"/>
   </dataQualityWarning>
</tsResponse>
      

Version

Version 3.5 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 400103 Unknown data quality warning query error An unknown error occurred and the data quality warning query could not complete.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
404 404030 Data quality warning not found The data quality warning for the requested asset could not be found.

Query Data Quality Warning by Content

Get information about the data quality warning for the database, table, column, published data source, flow, virtual connection, or virtual connection table.

URI

GET api/api-version/sites/site-id/dataQualityWarnings/content-type/content-luid

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
content-type The type of asset that the data quality warning is being attached to. To specify the type, use one of the following values:
  • database
  • table
  • column - Available in API 3.16 and later (Tableau Cloud October 2022, Server 2022.3)
  • datasource
  • flow
  • virtualconnection
  • virtualconnectiontable

These values are not case sensitive.

content-luid The LUID of the content (database, table, column, published data source, flow, virtual connection, or virtual connection table).

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to query the data quality warning:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have "derived permissions" (if enabled) or have been granted explicit "Read" (view) permissions to the asset

Otherwise, authorized users who have "derived permissions" (if enabled), and Tableau Server admins or Tableau Cloud site admins.

Response Code

200

Response Body

Example response:

<tsResponse>
   <dataQualityWarningList>
	<dataQualityWarning id="3b9fa2df-0915-4cda-9e29-bccb64a2eb7b" userDisplayName="Steve Nguyen" contentId="924ae707-a915-498d-b909-a86cd5135b8d" contentType="DATABASE" message="Talk to admin" type="WARNING" isActive="true" createdAt="2021-01-12T01:04:55Z" updatedAt="2021-01-12T01:04:55Z" isSevere="false">
	   <site id="3d512018-64c4-4b66-a1fa-1c83710e323c"/>
	   <owner id="2bfe6c21-17e0-449a-8e5c-382e740eca85"/>
	</dataQualityWarning>
   </dataQualityWarningList>
</tsResponse>
      

Version

Version 3.5 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 400104 Unknown data quality warning query error An unknown error occurred and the data quality warning query could not complete.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
404 404029 Content not found The requested asset could not be found.
404 404030 Data quality warning not found The data quality warning for the requested asset could not be found.

Query Data Quality Certification by ID

Get information about a data quality certification.

URI

GET api/api-version/sites/site-id/dataQualityCertification/certification-luid

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
certification-luid The unique ID of the data quality certification.

Request body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to query a data quality certification:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have "derived permissions" (if enabled) or have been granted explicit "Read" (view) permissions to the asset

Otherwise, authorized users who have "derived permissions" (if enabled), and Tableau Server admins or Tableau Cloud site admins.

Response Code

200

Response Body

Example response

<tsResponse>
   <dataQualityIndicator>
	id="d5a4006c-0276-4c5a-bb98-712815c91ce7"
	userDisplayName="Mark Nguyen"
	contentId="a34884d0-1d80-4505-bf21-c6b7ce10814a" contentType="DATASOURCE"
	message="Marketing approved"
	type="CERTIFIED" active="true"
	createdAt="2021-06-08T17:22:20Z"
	updatedAt="2021-09-08T17:27:57Z" severe="false"/>
	siteID="284e2a17-65c8-47bf-b88f-ff96d69c2303"
	ownerID="f95180e7-0c64-4a58-86da-b9f4d3db2583"
   </dataQualityIndicator>
</tsResponse>

Version

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

Errors

HTTP status error Code Condition Details
400 400103 Generic data quality certification error The data quality certification could not be queried for some reason other than those specified in this table.
403 403004 Unauthorized operation Insufficient permissions to perform the operation.
404 404030 Data quality indicator not found The requested data quality certification was not found.
409 409004 Invalid parameter One or more values in the request body are invalid.

Query Data Quality Certifications by Content

Get all data quality certifications for content or asset items.

URI

GET api/api-version/sites/site-id/dataQualityCertifications/content-type/content-luid

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
content-type

The type of content the data quality certification has been applied to. To specify the type, use one of the following values:

  • database
  • table
  • datasource
  • virtualconnection
  • virtualconnectiontable

These values are not case sensitive.

content-luid The LUID of the content (database, table, published data source, flow, virtual connection, or virtual connection table).

Request body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to query data quality certifications:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have "derived permissions" (if enabled) or have been granted explicit "Read" (view) permissions to the asset

Otherwise, authorized users who have "derived permissions" (if enabled), and Tableau Server admins or Tableau Cloud site admins.

Response Code

200

Response Body

Example response

<tsResponse>
   <dataQualityIndicator>
	id="d5a4006c-0276-4c5a-bb98-712815c91ce7"
	userDisplayName="Mark Nguyen" contentId="a34884d0-1d80-4505-bf21-c6b7ce10814a"
	contentType="DATASOURCE"
	message="Marketing approved"
	type="CERTIFIED" active="true"
	createdAt="2021-06-08T17:22:20Z"
	updatedAt="2021-09-08T17:27:57Z"
	severe="false"/>
	siteID="284e2a17-65c8-47bf-b88f-ff96d69c2303"
	ownerID="f95180e7-0c64-4a58-86da-b9f4d3db2583"
   </dataQualityIndicator>
</tsResponse>

Version

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

Errors

HTTP status error Code Condition Details
400 400104 Generic data quality certification error The data quality certification could not be queried for some reason other than those specified in this table.
403 403004 Unauthorized operation Insufficient permissions to perform the operation.
404 404029 Data quality indicator not found The requested data quality certification was not found.
409 409004 Invalid parameter One or more values in the request body are invalid.

Query Quality Warning Trigger

Get information about a quality warning trigger.

URI

GET api/api-version/sites/site-id/dataQualityTriggers/trigger-id

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
content-type

The type of content the quality warning trigger has been applied to. To specify the type, use on of the following values:

  • datasource
  • flow

These values are not case sensitive.

trigger-id The unique ID of the quality warning trigger.

Request body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to query a quality warning trigger:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have "derived permissions" (if enabled) or have been granted explicit "Read" (view) permissions to the asset

Otherwise, authorized users who have "derived permissions" (if enabled), and Tableau Server admins or Tableau Cloud site admins.

Response Code

200

Response Body

Example response

<tsResponse>
  <dataQualityTriggerList>
	<dataQualityTrigger id="{trigger-luid}" siteId="{site-luid}"
		userId="1c8ebdfc-270a-4414-812c-3306a1c95e07" userDisplayName="Joe Nguyen" contentId="{content-luid}"
		contentType="DATASOURCE" message=" This message is specified by the user."
		type="EXTRACT_REFRESH" active="true" createdAt="Wed Sep 22 05:49:52 UTC 2020"
		updatedAt="Wed Sep 22 05:49:52 UTC 2020" severe="false"/>
  </dataQualityTriggerList>
</tsResponse>     

Version

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

Errors

HTTP status error Code Condition Details
400 400134 Generic quality warning trigger error The quality warning trigger could not be queried for some reason other than those specified below.
403 403004 Unauthorized operation Insufficient permissions to perform the operation.
404 404037 Quality warning not found The requested quality warning trigger was not found.
409 409004 Invalid parameter One or more values in the request body are invalid.

Query All Quality Warning Triggers by Content

Get information about all quality warning triggers for a content item.

URI

GET api/api-version/sites/site-id/dataQualityTriggers/content-type/content-luid

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
content-type

The type of content that the quality warning trigger has been applied to. To specify the type, use one of the following values:

  • datasource
  • flow

These values are not case sensitive.

content-luid The unique ID of the asset. This is the same as the content ID.

Request body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to query quality warning triggers:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have "derived permissions" (if enabled) or have been granted explicit "Read" (view) permissions to the asset

Otherwise, authorized users who have "derived permissions" (if enabled), and Tableau Server admins or Tableau Cloud site admins.

Response Code

200

Response Body

Example response

<tsResponse>
  <dataQualityTriggerList>
	<dataQualityTrigger id="{trigger-luid}" siteId="{site-luid}"
		userId="f95180e7-0c64-4a58-86da-b9f4d3db2583" userDisplayName="Mark Nguyen" contentId="a34884d0-1d80-4505-bf21-c6b7ce10814a"
		contentType="DATASOURCE" message=" This message is specified by the user."
		type="EXTRACT_REFRESH" active="true" createdAt="Wed Sep 22 05:49:52 UTC 2020"
		updatedAt="Wed Sep 22 05:49:52 UTC 2020" severe="false"/>
  </dataQualityTriggerList>
</tsResponse>    

Version

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

Errors

HTTP status error Code Condition Details
400 400134 Generic quality warning trigger error The quality warning triggers could not be queried for some other reason than those specified below.
403 403004 Unauthorized operation Insufficient permissions to perform the operation.
404 404037 Quality warning not found The requested quality warning trigger was not found.
409 409004 Invalid parameter One or more values in the request body are invalid.

Query Table

Get information about a table asset.

URI

GET api/api-version/sites/site-id/tables/table-id

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
table-id The unique ID of the table asset.

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to query the table asset:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have "derived permissions" (if enabled) or have been granted explicit "Read" (view) permissions to the asset

Otherwise, authorized users who have "derived permissions" (if enabled), and Tableau Server admins or Tableau Cloud site admins.

Response Code

200

Response Body

Example response:

<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-3.5.xsd">
  <table id="917b1438-7000-4a9e-a949-13b90a0237dd" name="[Orders$]" isEmbedded="true" isCertified="false">
	<site id="3dd2f0ef-4a9b-44a7-bec5-a50598f41792"/>
  </tsResponse>
      

Version

Version 3.5 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.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
404 404032 Table not found The requested table could not be found.
409 409052 Unknown table error An unknown table asset error occurred.
409 409053 Unknown table query error An unknown error occurred and the table query could not complete.

Query Tables

Get information about all table assets for a site.

URI

GET api/api-version/sites/site-id/tables

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to query table assets:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have "derived permissions" (if enabled) or have been granted explicit "Read" (view) permissions to the asset

Otherwise, authorized users who have "derived permissions" (if enabled), and Tableau Server admins or Tableau Cloud site admins.

Response Code

200

Response Body

Example response:

<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-3.5.xsd">
  <tables>
	<table id="6a9b6058-671d-44bc-ad6d-c58b225f5d4c" name="Culture" isEmbedded="false" isCertified="false">
	  <site id="3dd2f0ef-4a9b-44a7-bec5-a50598f41792"/>
 	</table>
	<table id="917b1438-7000-4a9e-a949-13b90a0237dd" name="[Orders$]" isEmbedded="true" isCertified="false">
	  <site id="3dd2f0ef-4a9b-44a7-bec5-a50598f41792"/>
	</table>
	<table id="58d94f3f-1339-4721-8674-e53dc9dfe02e" name="Batters" isEmbedded="false" isCertified="false">
	  <site id="3dd2f0ef-4a9b-44a7-bec5-a50598f41792"/>
	</table>
	<table id="5e8ca1e3-9752-430c-abae-11104084b469" name="[911_calls_short#csv]" isEmbedded="false" isCertified="false">
	  <site id="3dd2f0ef-4a9b-44a7-bec5-a50598f41792"/>
	</table>
  </tables>
</tsResponse>
      

Version

Version 3.5 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.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
404 404032 Table not found The requested tables could not be found.
409 409052 Unknown table error An unknown table asset error occurred.
409 409053 Unknown table query error An unknown error occurred and the table query could not complete.

Query Table Permissions

Get information about the permissions on a table asset.

URI

GET api/api-version/sites/site-id/tables/table-id/permissions

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
table-id The unique ID of the table asset.

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following authorized users have permissions to query the permissions on the table asset:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have been granted explicit permission to set or "ChangePermissions" to the asset metadata

Response Code

200

Response Body

Example response with explicit permissions set:

<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-3.5.xsd">
  <permissions>
	<table id="d0fe66ae-1407-4338-8520-9489d7ce959c" name="_WarehouseConfig"/>
	<granteeCapabilities>
	  <user id="6265b714-7533-465d-b6db-6d0be92bfd07"/>
	  <capabilities>
		<capability name="Read" mode="Allow"/>
	  </capabilities>
	</granteeCapabilities>
  </permissions>
</tsResponse>
      

Example response without explicit permissions set:

<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-3.5.xsd">
  <permissions>
	<parent id="95ac9b30-5b2c-48ed-af56-cab9b0d4b064" type="Database"/>
	  <table id="4ef842be-5c90-4878-a048-99a896b59996" name="BigMachines"/>
  </permissions>
</tsResponse>
      

Version

Version 3.5 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 400120 Bad request Permissions could not be returned because support for explicit permissions is available for table assets associated with published data sources (not embedded data sources) only.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
404 404032 Table not found The requested table asset could not be found.
409 409052 Table error An unknown table asset error occurred.
409 409053 Unknown table query error An unknown error occurred and the table query could not complete.

Remove Column

Permanently remove the column from a table asset.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

DELETE api/api-version/sites/site-id/tables/table-id/columns/column-id

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
table-id The unique ID of the table asset.
column-id The unique ID of the column asset.

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to remove the column:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

204

Response Body

None

Version

Version 3.5 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.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
404 404032 Table not found The requested table asset could not be found.
409 409059 Column error An unknown column asset error occurred.
409 409061 Unknown column delete error An unknown error occurred and the column could not be deleted.
409 409066 Column not found The requested column asset could not be found.

Remove Database

Permanently remove the database asset.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

DELETE api/api-version/sites/site-id/databases/database-id

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
database-id The unique ID of the database asset.

Request Body

None

Permissions

Server or site administrators only.

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to remove the database asset:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

204

Response Body

None

Version

Version 3.5 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.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
404 404031 Database not found The requested database could not be found.
409 409045 Database error An unknown database asset error occurred.
409 409047 Database delete error An unknown error occurred and the database asset could not be deleted.

Remove Table

Permanently remove the table asset.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

DELETE api/api-version/sites/site-id/tables/table-id

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
table-id The unique ID of the table asset.

Request Body

None

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to remove the table asset:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

204

Response Body

None

Version

Version 3.5 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.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
404 404032 Table not found The requested table asset could not be found.
409 409052 Table error An unknown table asset error occurred.
409 409054 Unknown table delete error An unknown error occurred and the table could not be deleted.

Update Column

Update the description of the column.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

PUT api/api-version/sites/site-id/tables/table-id/columns/column-id

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
table-id The unique ID of the table asset.
column-id The unique ID of the column asset.

Request Body

<tsRequest>
  <column description="new-description-value">
  </column>
</tsRequest>
      

Attribute Values

Any combination of attributes inside the <column> element is valid. Only the attributes and child elements that are included result in updates to the table. If no attributes or nested elements are included, no update is made.

new-description-value (Optional) Custom text to describe the column.

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to update the column:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

200

Response Body

Example response:

<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-3.5.xsd">
  <column id="0b589fc9-1523-4aae-b711-62d48672ac6a" name="StateProvinceID" description="Validated against maps" remoteType="I4" parentTableId="75029ee7-935a-4f57-8717-58c2339dd219">
	<site id="5286d663-8668-4ac2-8c8d-91af7d585f6b"/>
  </column>
</tsResponse>
      

Version

Version 3.5 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.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
404 404032 Table not found The requested table asset could not be found.
409 409052 Column error An unknown table asset error occurred.
409 409057 Column update error An unknown error occurred and the table asset could not be updated.
409 409058 Column update forbidden A user without "write" permissions to the table asset attempted an update.
409 409066 Column not found The requested column asset could not be found.

Update Database

Update the database description, certify a database, set content permissions, or assign a contact (must be a Tableau Server or Tableau Cloud user) to the database asset.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

PUT api/api-version/sites/site-luid/databases/database-luid

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-luid The LUID of the site asset.
database-luid The LUID of the database asset.

Request Body

<tsRequest>
  <database isCertified="certification-status"
      certificationNote="certification-note"
      description="new-description-value"
      contentPermissions="new-content-permissions">
    <contact id="new-contact-luid" />
  </database>
</tsRequest>
      

Attribute Values

Any combination of attributes inside the <database> element is valid. Only the attributes and child elements that are included result in updates to the database asset. If no attributes or nested elements are included, no update is made.

certification-status

(Optional) Certify or remove certification by using the following:

  • True
  • False
certification-note (Optional) Custom text to accompany the certification status.
new-description-value (Optional) Custom text to describe the database asset.
new-content-permissions

(Optional) The new permissions setting for the database. You can specify one of the following:

  • LockedToDatabase to lock permissions so that users cannot overwrite the default permissions set for the database asset.
  • ManagedByOwner to allow users to manage permissions for the database asset used by the content that they own.

The default permissions setting is ManagedByOwner. These values are case sensitive.

new-contact-luid (Optional) The LUID of the Tableau Server or Tableau Cloud user to associate with the database asset.

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to update the database asset:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

200

Response Body

Example response:

<tsResponse>
  <database id="31d6ab16-3821-489b-8197-39453ce94a49" name="coffee" connectionType="sqlserver" isEmbedded="false" description="Contact Susan Nguyen (database admin) for changes." isCertified="true" certificationNote="Removed certification via REST" type="DatabaseServer" hostName="mssql.test.tsi.lan" contentPermissions="LockedToDatabase">
	<site id="5286d663-8668-4ac2-8c8d-91af7d585f6b"/>
	<contact id="2a80c15e-87c8-4b07-a5f4-e49f95e9fb0b" name="fsuzuki"/>
	<certifier id="26183d16-82f7-4fcf-b163-0e607bf292bc" name="admin"/>
  </database>
</tsResponse>
      

Version

Version 3.5 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.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site LUID in the URI doesn't correspond to an existing site.
404 404031 Database not found The requested database could not be found.
409 409045 Database error An unknown database asset error occurred.
409 409050 Database update error An unknown error occurred and the database asset could not be updated.
409 409051 Database update forbidden A user without "write" permissions to the database asset attempted an update.

Update Data Quality Warning

Update the warning type, status, and message of a data quality warning.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

PUT api/api-version/sites/site-id/dataQualityWarnings/dataqualitywarning-id

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
dataqualitywarning-id The unique ID of the data quality warning.

Request Body

<tsRequest>
  <dataQualityWarning type="type" isActive="status" message="message" isSevere="severity"/>
</tsRequest>    

Attribute Values

Any combination of attributes inside the <dataQualityWarning> element is valid, but the data quality warning type is required. If the data quality warning type is not included, an error is thrown.

type

Type of data quality warning to apply to the asset. To specify the type, use one of the following values:

  • DEPRECATED
  • WARNING
  • STALE
  • SENSITIVE_DATA
  • MAINTENANCE

These values are not case sensitive.

status

(Optional) Controls whether the data quality warning displays. Value can be "true" or "false". If the state is not specified, the data quality warning is set to "true" and is visible by default.

message A required custom message to accompany the data quality warning.
severity (Optional) Enables high visibility for the data quality warning when set to "true". Values can be "true" or "false". For more information, see "Set high visibility for data quality warning" in the Server Help or Online Help.

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to update the data quality warning:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

200

Response Body

Example response:

<tsResponse>
   <dataQualityWarning id="3b9fa2df-0915-4cda-9e29-bccb64a2eb7b" userDisplayName="Steve Nguyen"
	contentId="924ae707-a915-498d-b909-a86cd5135b8d" contentType="DATABASE" message="OUT OF DATE - DO NOT USE"
	type="WARNING" isActive="true" createdAt="2021-01-12T01:04:55Z" updatedAt="2021-01-12T01:23:04Z"
	isSevere="true">
	<site id="3d512018-64c4-4b66-a1fa-1c83710e323c" />
	<owner id="2bfe6c21-17e0-449a-8e5c-123e740eca45" />
   </dataQualityWarning>
</tsResponse>     

Version

Version 3.5 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 400109 Bad request The request body can't be empty.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
404 404029 Content not found The requested asset could not be found.
404 404030 Data quality warning not found The data quality warning for the requested asset could not be found.

Update Quality Warning Trigger

Update a quality warning trigger.

URI

PUT api/api-version/sites/site-id/dataQualityTriggers/trigger-id

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
trigger-id The unique ID of the quality warning trigger.

Request Body

<tsRequest>
  <dataQualityTrigger type="extract_refresh" active="status" message="message" severe="severity"/>
</tsRequest>

Attribute Values

Any combination of attributes inside the <dataQualityTrigger> element is valid, however type is required.

type

Type of content to apply the data quality warning trigger. To specify the type, use one of the following values:

  • EXTRACT_REFRESH
  • FLOW_RUNS

These values are case sensitive.

status

(Optional) Status of the trigger. Values can be "true" or "false". If set to "true", the extract data source is monitored for refresh failures. If a refresh failure occurs, an alert is applied to the extract data source. The alert remains there until the next successful refresh.

message (Optional) A custom message to accompany the trigger.
severity (Optional) Enables high visibility for the trigger. Values can be "true" or "false". For more information, see "Set high visibility for data quality warning" in the Server Help or Online Help.

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to update a quality warning trigger:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

200

Response Body

Example response

<tsResponse>
  <dataQualityTriggerList>
	<dataQualityTrigger id="{trigger-luid}" siteId="{site-luid}"
		userId="{user-luid}" userDisplayName="Joe Nguyen" contentId="{content-luid}"
		contentType="DATASOURCE" message=" This message is specified by the user."
		type="EXTRACT_REFRESH" active="true" createdAt="Wed Sep 22 05:49:52 UTC 2020"
		updatedAt="Wed Sep 22 05:49:52 UTC 2020" severe="false"/>
  </dataQualityTriggerList>
</tsResponse>

Version

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

Errors

HTTP status error Code Condition Details
400 400137 Generic quality warning trigger error The quality warning trigger could not be updated for some other reason than those specified below.
403 403004 Unauthorized operation. Insufficient permissions to perform the operation.
409 409004 Invalid parameter One or more values in the request body are invalid.

Update Label

Updates a label by its LUID. This method can update the label value, message, active flag, and elevated flag.

You can't update the label category. If you set the label value to one that's in a different category, you get an error. See Data Labels for information on label categories and values.

You can't update extract refresh or flow run monitoring warnings (the extract_refresh_failure and flow_run_failure label values) using this method because those warnings are set and cleared automatically, depending on their triggers. See also "How to set a monitoring quality warning" in the Tableau Server(Link opens in a new window) and Tableau Cloud(Link opens in a new window) Help and the quality warning trigger methods in Metadata Methods.

All label operations except those related to the certification of data sources require Catalog to be enabled. Catalog requires a Data Management license.

URI

PUT api/api-version/sites/site-luid/labels/label-luid

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-luid The unique LUID of the site asset.
label-luid The unique LUID of the label asset.

Request Body

<tsRequest>
  <label
    value="label-value"
    message="label-message"
    active="active-flag"
    elevated="elevated-flag" />
</tsRequest>

Attribute Values

label-value

(Optional) For labels with a category of certification, the only valid value is certified.

For labels with a category of warning, valid values are warning, deprecated, stale, maintenance, and sensitive_data.

Choosing a monitoring quality warning value (extract_refresh_failure or flow_run_failure) causes an error.

label-message (Optional) The message text for the label. In the web interface, this is reflected as a certification note or a data quality warning message.
active-flag (Optional) Boolean. If set to true, the label becomes active. If set to false, the label becomes inactive.  If omitted, the default is true.
elevated-flag (Optional) Boolean. If set to true, the label becomes elevated. If set to false, the label becomes not elevated.  If omitted, the default is false.

Permissions

  • To create or update a warning label, you must have Write permission on the associated asset.
  • To create or update a certification label for an asset in a project, you must be a Tableau Server site or server admin, a Tableau Cloud site admin, a project leader for the project the asset is in, or the project owner for the project the asset is in.
  • To create or update a certification label for an asset not in a project, you must have the ChangePermissions permission on the associated asset.

Response Code

200

Response Body

<tsResponse>
  <label id="label-luid"
      userDisplayName="user-display-name"
      contentId="asset-luid"
      contentType="asset-type"
      message="label-message"
      value="label-value"
      category="label-category"
      active="true-or-false"
      elevated="true-or-false"
      createdAt="datetime"
      updatedAt="datetime" >
    <site id="site-luid"/>
    <owner id="user-luid"/>
  </label>
</tsResponse>

Version

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

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 400103 Generic query label error An unknown error occurred.
400 400109 Missing payload The request body is missing a label element.
403 403004 Invalid parameter Operation on resource unauthorized
404 404030 Label not found The label LUID doesn't correspond to an existing project.
409 409004 Invalid parameter One or more values in the request body are invalid, or you are trying to change the label value to one from a different category. This error can also occur if you try to create or change a monitoring quality warning (label values extract_refresh_failure and flow_run_failure).

Update Labels on Assets

Creates or updates labels on one or more assets. (An asset can be Tableau content or an external asset.) Each asset listed in the request body is updated to have a label with the specified value, message, active flag, and elevated flag. Assets without an existing label of the corresponding category will have a new label created. Assets that already have a label of the same category will have the label updated.

Note that the label category is not an attribute in the request body, because you do not set it explicitly. Instead you implicitly set the category by using the label value. For example, choosing a label value of stale means that the label category will be warning. Also, you can't update the label category on an existing label. If you set the label value to one that's in a different category, you get an error. See Data Labels for information on label categories and values.

You can't update extract refresh or flow run monitoring warnings (the extract_refresh_failure and flow_run_failure label values) using this method because those warnings are set and cleared automatically, depending on their triggers. See also "How to set a monitoring quality warning" in the Tableau Server(Link opens in a new window) and Tableau Cloud(Link opens in a new window) Help and the quality warning trigger methods in Metadata Methods.

All label operations except those related to the certification of data sources require Catalog to be enabled. Catalog requires a Data Management license.

URI

PUT api/api-version/sites/site-luid/labels

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-luid The unique LUID of the site asset.

Request Body

<tsRequest>
  <contentList>
    <content contentType="asset-type" id="asset-luid" />
    <!-- ... additional content elements ... -->
  </contentList>
  <label
      value="label-value"
      message="label-message"
      active="active-flag"
      elevated="elevated-flag" />
</tsRequest>

Attribute Values

asset-type

The type of asset. Valid asset types are:

  • database
  • table
  • column - Available in API 3.16 and later (Tableau Cloud October 2022, Server 2022.3)
  • datasource
  • flow
  • virtualconnection
  • virtualconnectiontable
asset-luid The asset LUID.
label-value

For labels with a category of certification, the only valid value is certified.

For labels with a category of warning, valid values are warning, deprecated, stale, maintenance, and sensitive_data.

Choosing a monitoring quality warning value (extract_refresh_failure or flow_run_failure) causes an error.

label-message The message text for the label. In the web interface, this is reflected as a certification note or a data quality warning message.
active-flag (Optional) Boolean. If set to true, the label becomes active. If set to false, the label becomes inactive.  If omitted, the default is true.
elevated-flag (Optional) Boolean. If set to true, the label becomes elevated. If set to false, the label becomes not elevated.  If omitted, the default is false.

Permissions

  • To create or update a warning label, you must have Write permission on the associated asset.
  • To create or update a certification label for an asset in a project, you must be a Tableau Server site or server admin, a Tableau Cloud site admin, a project leader for the project the asset is in, or the project owner for the project the asset is in.
  • To create or update a certification label for an asset not in a project, you must have the ChangePermissions permission on the associated asset.

Response Code

200

Version

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

Response Body

<tsResponse>
  <labelList>
    <label id="label-luid"
        userDisplayName="user-display-name"
        contentId="asset-luid"
        contentType="asset-type"
        message="label-message"
        value="label-value"
        category="label-category"
        active="true-or-false"
        elevated="true-or-false"
        createdAt="datetime"
        updatedAt="datetime" >
      <site id="site-luid"/>
      <owner id="user-luid"/>
    </label>
    <!-- ... additional label elements ... –->
  </labelList>
</tsResponse>

Errors

When more than one asset appears in the request (the contentList element contains more than one content element), this method will fail if an error is encountered operating on any of them. For example, if you are updating labels for a database and a table, but you provide the wrong table LUID, the method will return an error even if the database LUID was correct.

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 400108 Missing payload The request body is missing all content and/or all label elements.
400 400109 Generic add labels to content error An unknown error occurred.
403 403004 Operation on resource unauthorized Insufficient permissions to perform the operation.
404 404029 Resource not found The contentType and contentID attribute combination does not correspond to an asset on the server. This can be caused by an incorrect contentType, an incorrect contentID, or both.
409 409004 Invalid parameter One or more values in the request body are invalid, or one of the required attributes (active or elevated) is missing. This error can also occur if you try to create or change a monitoring quality warning (label values extract_refresh_failure and flow_run_failure).

Update Table

Update the table description, certify a table, or a assign a user contact to the table asset.

This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.

URI

PUT api/api-version/sites/site-id/tables/table-id

Parameter Values

api-version The version of the API to use, such as 3.19. For more information, see REST API and Resource Versions.
site-id The unique ID of the site asset.
table-id The unique ID of the table asset.

Request Body

<tsRequest>
  <table isCertified="certification-status"
      certificationNote="certification-note"
      description="new-descrption-value">
    <contact id="new-contact-id" />
  </table>
</tsRequest>

Attribute Values

Any combination of attributes inside the <table> element is valid. Only the attributes and child elements that are included result in updates to the table. If no attributes or nested elements are included, no update is made.

certification-status

(Optional) Use one of the following values:

  • true
  • false

These values are case sensitive.

certification-note (Optional) Custom text to accompany the certification status.
new-description-value (Optional) Custom text to describe the table asset.
new-contact-id (Optional) The ID (not name) of the certification owner.

Permissions

If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to update the table asset:

  • Tableau Server admins or Tableau Cloud site admins
  • Authorized users who have been granted explicit permission to edit or "Write" to the asset metadata

Response Code

200

Response Body

Example response:

<tsResponse xmlns="http://tableau.com/api" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tableau.com/api http://tableau.com/api/ts-api-3.5.xsd">
  <table id="b86632d7-b82e-4d4c-88e5-11957cdadd95" name="Zoning.shp" description="Contact Susan Nguyen (database admin) for changes." isEmbedded="true" isCertified="false">
	<site id="5286d663-8668-4ac2-8c8d-91af7d585f6b"/>
  </table>
</tsResponse>

Version

Version 3.5 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.
401 401000 Unauthorized access No authorization credentials were provided.
401 401002 Unauthorized access Invalid authorization credentials were provided.
404 404000 Resource not found The site ID in the URI doesn't correspond to an existing site.
404 404032 Table not found The requested table asset could not be found.
409 409052 Table error An unknown table asset error occurred.
409 409057 Table update error An unknown error occurred and the table asset could not be updated.
409 409058 Table update forbidden A user without "write" permissions to the table asset attempted an update.

Thanks for your feedback!