API Reference—All Methods
Using the Tableau Server REST API, you can manage and change Tableau Server resources programmatically, via HTTP. The API gives you simple access to the functionality behind the data sources, projects, workbooks, site users, and sites on a Tableau server. You can use this access to create your own custom applications or to script interactions with Tableau Server resources.
- On this page, use the API Method Categories list, or find keywords in the API Method Details list with ctrl/cmd-f search.
- To view the API reference for a different version of Tableau, see Previous Schema Versions.
- For more information, see Fundamentals of the Tableau Server REST API and REST API Example Requests.
Note: For help with your code that uses the Tableau REST API, submit questions and ask for help on the Tableau developer community forums(Link opens in a new window). For potential bugs in the Tableau REST API code itself, and for any issue with unmodified sample code we provide, use the feedback widget at the bottom of API reference pages.
API Method Categories
The following table lists the Tableau Server REST API methods by category. The table also indicates which methods can be used with Tableau Cloud.
API Method Details
The following content describes each endpoint in the Tableau REST API surface. Use the alphabetically sorted list of methods on the right, or ctrl/cmd-f to go directly to keywords you have in mind.
Add analytics extension connection to site
Adds an analytics extensions connection for an external service to a site.
Version: Available in API 3.11 (Tableau Cloud March 2021 / Server 2021.1) and later. Version Overview
Permissions: This method can only be called by users with server or site administrator permissions. Permissions Overview
License: No additional license required.
Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux
POST {server}/api/-/settings/site/extensions/analytics/connections
Add Ask Data Lens Permissions - Retired in API 3.22
Retired in API 3.22 (Cloud February 2024 / Server 2024.2)In February 2024, Tableau's Ask Data and Metrics features and their REST API methods will be retired in Tableau Cloud and Tableau Server version 2024.2. With advances in natural language technologies, we're developing an improved interface that will make it easier to ask questions of your data and stay on top of changes. For more information, see Create Metrics with Tableau Pulse(Link opens in a new window) and Explore Metrics with Tableau Pulse(Link opens in a new window).
Adds permissions to the specified ask data lens for a user or group. You can specify multiple sets of permissions using one request.
If a specified permission has already been granted or denied for a given user or group, the system ignores it.
URI
PUT /api/api-version/sites/site-luid/lenses/lens-luid/permissions
Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions. |
| site-luid | The LUID of the site that contains the data source. |
| lens-luid | The LUID of the data source to set permissions for. |
Request Body
<tsRequest>
<permissions>
<lens id="lens-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
| lens-luid | Required. The LUID of the ask data lens permissions are being configured for. |
| user-luid | Optional (at least one user or group must be specified). The LUID of the user to add permissions for. |
| group-luid | Optional. The LUID of the group to add permissions for. |
| capability-name |
The capability to assign. For valid capabilities for a data source project are
ChangePermissions,
Delete,
Move,
Read,
Write.
For more information, see Permissions. |
| capability-mode | Allow to allow the capability, or Deny to deny it. This value is case sensitive. |
Permissions
Users with server or site administrator permissions, and non-administrators that have ChangePermissions permission for the lens (either explicitly or implicitly), can add ask data lens permissions.
Response Code
200
Response Body
<tsResponse>
<permissions>
<lens id="lens-luid" name ="lens-name" />
<granteeCapabilities>
<user id="user-luid" />
<capabilities>
<capability name="capability" mode="Allow-or-Deny" />
<capability name="capability" mode="Allow-or-Deny" />
<!-- ... additional capabilities ... -->
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<group id="group-luid" />
<capabilities>
<capability name="capability" mode="Allow-or-Deny" />
<capability name="capability" mode="Allow-or-Deny" />
<!-- ... additional capabilities ... -->
</capabilities>
</granteeCapabilities>
<!-- ... additional grantee capability sets ... -->
</permissions>
</tsResponse>Version
Introduced Tableau Cloud June 2022 (API 3.16). Not currently available for Tableau Server. 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 | 400009 | Invalid capability | The specified capability is invalid for a data source. Valid capabilities for a data source are ChangePermissions, Delete, Move, Read, and Write. |
| 403 | 403004 | No permissions to set permissions. | A user attempted to add permissions to a data source, but the caller doesn't have permission to set permissions on the data source. |
| 404 | 404000 | Site not found | The specified site doesn't correspond to an existing site. |
| 404 | 404002 | User not found | The user specified in the request body doesn't correspond to an existing user. |
| 404 | 404006 | Lens not found | The specified lens doesn't correspond to an existing data source. |
| 404 | 404012 | Group not found | The group specified in the request body doesn't correspond to an existing group. |
| 404 | 404013 | Capability not found | A capability specified 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. |
For more information, see Handling Errors.
Add Data Quality Warning
Add a data quality warning to a database, table, column, published data source, flow, virtual connection, or virtual connection table.
Note: Data quality warnings and certifications can be more generally managed through the newer Labels methods. Tableau recommends using them to help ensure that you can manage your assets as new features are developed.
Try the Update Labels method instead.
The Add Data Quality Warning method adds a data quality warning to an asset. (An automatically-generated monitoring warning does not count towards this limit.) In Tableau Cloud February 2024 and Tableau Server 2024.2 and earlier, adding a data quality warning to an 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.24. 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:
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:
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 Cloud Help. |
| message |
(Optional. Was required in Tableau Server 2023.3 and earlier.) A 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 the "Visibility" section of the "Set a Data Quality Warning" topic in the Server Help or Cloud 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. |
Add Data Source Permissions
Adds permissions to the specified data source for a user or group. You can specify multiple sets of permissions using one call.
If a specified permission has already been granted or denied for a given user or group, the system ignores it.
If the request body includes a child workbook or <project> element, the request is invalid.
URI
PUT /api/api-version/sites/site-id/datasources/datasource-id/permissions
Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions. |
| site-id | The ID of the site that contains the data source. |
| datasource-id | The ID of the data source to set permissions for. |
Request Body
<tsRequest>
<permissions>
<datasource id="datasource-id" />
<granteeCapabilities>
<user id="user-id" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
... additional capabilities ...
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<group id="group-id" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
... additional capabilities ...
</capabilities>
</granteeCapabilities>
... additional grantee capability sets ...
</permissions>
</tsRequest>
Attribute Values
| datasource-id | The <datasource> element is not required, but can be included for compatibility with earlier versions of the REST API. If the <datasource> element is included, the datasource-id value must match the data source ID in the URI. Any other attributes in the <datasource> element are ignored. |
| user-id | The ID (not name) of the user to add permissions for. |
| group-id | The ID (not name) of the group to add permissions for. |
| capability-name |
The capability to assign. For valid capabilities for a data source project are
ChangePermissions,
Connect,
Delete,
ExportXml,
Read (view),
Write, and
SaveAs.
For more information, see Permissions. |
| capability-mode | Allow to allow the capability, or Deny to deny it. This value is case sensitive. |
Permissions
Users who are not server administrators or site administrators can add permissions only to a data source for which they have ChangePermissions permission (either explicitly or implicitly).
Required scope for JWT authorization
Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).
Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:updateResponse Code
200
Response Body
<tsResponse version-and-namespace-settings>
<permissions>
<datasource id="datasource-id" />
<granteeCapabilities>
<user id="user-id" />
<capabilities>
<capability name="capability" mode="Allow-or-Deny" />
<capability name="capability" mode="Allow-or-Deny" />
... additional capabilities ...
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<group id="group-id" />
<capabilities>
<capability name="capability" mode="Allow-or-Deny" />
<capability name="capability" mode="Allow-or-Deny" />
... additional capabilities ...
</capabilities>
</granteeCapabilities>
... additional grantee capability sets ...
</permissions>
</tsResponse>
Version
Version 2.0 and later. For more information, see REST API and Resource Versions.
Errors
| HTTP status | error Code |
Condition | Details |
|---|---|---|---|
| 400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
| 400 | 400009 | Invalid capability | The specified capability is invalid for a data source. Valid capabilities for a data source are ChangePermissions, Connect, Delete, ExportXml, Read, and Write. |
| 403 | 403004 | No permissions to set permissions. | A user attempted to add permissions to a data source, but the caller doesn't have permission to set permissions on the data source. |
| 404 | 404000 | Site not found | The specified site doesn't correspond to an existing site. |
| 404 | 404002 | User not found | The user specified in the request body doesn't correspond to an existing user. |
| 404 | 404004 | Data source not found | The specified data source doesn't correspond to an existing data source. |
| 404 | 404012 | Group not found | The group specified in the request body doesn't correspond to an existing group. |
| 404 | 404013 | Capability not found | A capability specified 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. |
For more information, see Handling Errors.
Add Data Source to Favorites
Adds the specified data source to the user's favorites.
If the user already has the data source listed as a favorite with the same label, the operation has no effect. If the label differs, the original favorite is overwritten.
URI
PUT /api/api-version/sites/site-id/favorites/user-id
Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions. |
| site-id | The ID of the site that contains the data source. |
| user-id | The ID of the user to add the favorite for. |
Request Body
<tsRequest>
<favorite label="favorite-label">
<datasource id="datasource-id" />
</favorite>
</tsRequest>
Attribute Values
| favorite-label | A label to assign to the favorite. This value is displayed when you search for favorites on the server. |
| datasource-id | The ID of the data source to add as a favorite. |
Permissions
Tableau Server users who are not server administrators or site administrators can call this method only if they have Read (view) permissions on the data source (either explicitly or implicitly).
Response Code
200
Response Body
<tsResponse>
<favorites>
<favorite label="favorite-label">
<datasource id="datasource-id" />
</favorite>
<favorite label="favorite-label">
<datasource id="datasource-id" />
</favorite>
... additional favorites ...
</favorites>
</tsResponse>
Version
Version 2.3 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 | 400005 | Invalid label | The favorite label is empty or consists of only white space characters. |
| 403 | 403004 | Forbidden favorites access | A non-administrator user called this method but doesn't have permission to add a data source to the specified user's favorites. This will always be the case when the user ID in the URI represents a different user than a non-administrator user who is calling the method. |
| 404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
| 404 | 404002 | User not found | The user ID in the URI doesn't correspond to an existing user. |
| 404 | 404011 | Data source not found | The data source ID in the request body doesn't correspond to an existing data source. |
| 405 | 405000 | Invalid request method | Request type was not PUT. |
| 409 | 409007 | Label conflict | There is already a favorite with the same label for a different data source in the specified user's favorites. |
For more information, see Handling Errors.
Add Data Source to Server Schedule
Adds a task to refresh a data source to an existing server schedule on Tableau Server.
For Tableau Cloud, see Create Cloud Extract Refresh Task.
URI
PUT /api/api-version/sites/site-id/schedules/schedule-id/datasources
Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions. |
| site-id | The ID of the site that contains the view. |
| schedule-id | The ID of the schedule that you are associating with the data source. |
Request Body
<tsRequest>
<task>
<extractRefresh>
<datasource id="datasource-id" />
</extractRefresh>
</task>
</tsRequest>
Attribute Values
| datasource-id | The ID of the data source to add to the schedule. |
Permissions
Tableau Server users who are not server administrators or site administrators can only add a data source to a schedule if they own the data source, or are the project leader for the project that contains the data source.
Response Code
200
Response Body
<tsResponse>
<task>
<extractRefresh>
<schedule id="schedule-id" />
<datasource id="datasource-id" />
</extractRefresh>
</task>
</tsResponse>
Version
Version 2.8 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 | 401002 | Unauthorized Access | The authentication token provided in the request header was invalid or has expired. |
| 403 | 403032 | Update Forbidden | A non-administrator user called this method, but the caller doesn't have sufficient permissions. |
| 404 | 404000 | Site not found | The site ID in the URI is unknown. |
| 404 | 404004 | Resource not found | The data source ID in the request body is unknown. |
| 405 | 405000 | Invalid request method | Request type was not PUT. |
| 500 | 500000 | Internal Server Error | The schedule ID in the URI is unknown. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/schedules/9a4ebbab-9ec8-487a-9b48-47fa81d6077a/datasources" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" –d @add-to-schedule.xml
Content of add-to-schedule.xml:
<tsRequest>
<task>
<extractRefresh>
<datasource id="89a82d78-664f-45a1-8256-d4d2961a070b" />
</extractRefresh>
</task>
</tsRequest>
Example response:
<tsResponse>
<task>
<extractRefresh id="9bf8aea0-e3ca-422e-b7ef-d9c4ba6cca45" priority="50" consecutiveFailedCount="0" type="RefreshExtractTask">
<schedule id="9a4ebbab-9ec8-487a-9b48-47fa81d6077a" name="Weekday early mornings" state="Active" />
<datasource id="89a82d78-664f-45a1-8256-d4d2961a070b" />
</extractRefresh>
</task>
</tsResponse>
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.24. 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:
These values are case sensitive. |
capability mode
|
Use one of the following capabilities:
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.
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.24. 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:
These values are case sensitive. |
| capability-mode |
Use one of the following capabilities:
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 Default Permissions
Adds default permission rules for workbook, data source, data role, lens, flow, metric, or virtual connection resources in a project for a user or group. If Tableau Catalog is enabled, also adds default permission rules for database or table resources in a project for a user or group. After adding default permission rules, new resources of the type you specify that are added to the project will have those permission rules. If permissions are locked to the project(Link opens in a new window), then the same is true for all existing child content of the project. For more information, see Permissions(Link opens in a new window).
Content owners can override default permissions for their content, but only if project permissions have not been locked. Project permissions can be locked for a new project when you call Create Project or for an existing project by calling Update Project. For more information, see Lock Content Permissions to the Project(Link opens in a new window).
URI
PUT /api/api-version/sites/site-luid/projects/project-luid/default-permissions/workbooks
PUT /api/api-version/sites/site-luid/projects/project-luid/default-permissions/datasources
PUT /api/api-version/sites/site-luid/projects/project-luid/default-permissions/dataroles
PUT /api/api-version/sites/site-luid/projects/project-luid/default-permissions/lenses
PUT /api/api-version/sites/site-luid/projects/project-luid/default-permissions/flows
PUT /api/api-version/sites/site-luid/projects/project-luid/default-permissions/metrics
PUT /api/api-version/sites/site-luid/projects/project-luid/default-permissions/virtualconnections
PUT /api/api-version/sites/site-luid/projects/project-luid/default-permissions/databases
PUT /api/api-version/sites/site-luid/projects/project-luid/default-permissions/tables
Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions. |
| site-luid | The LUID of the site that contains the project. |
| project-luid | The LUID of the project to 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. Valid capabilities for a workbook are
Valid capabilities for a data source are
Valid capabilities for a flow are
For more information, see Permissions. |
| capability-mode | Allow to allow the capability, or Deny to deny it. This value is case sensitive. |
Permissions
Users who are not server administrators can add permissions defaults for a project only if they have the ProjectLeader permission for that project (either explicitly or implicitly).
Required scope for JWT authorization
Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).
Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:updateResponse Code
200
Response Body
<tsResponse>
<permissions>
<database id="12ab34cd-56ef-78ab-90cd-12ef34ab56cd" name="oracle.test.example.com:1521"/>
<granteeCapabilities>
<user id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"/>
<capabilities>
<capability name="Read" mode="Allow"/>
</capabilities>
</granteeCapabilities>
</permissions>
</tsResponse>
Version
Version 2.1 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 | 400009 | Invalid capability | The capability in the URI is invalid for a data source. Valid capabilities for a workbook are AddComment, ChangeHierarchy, ChangePermissions, CreateRefreshMetrics, Delete, ExportData, ExportImage, ExportXml, Filter, Read (view), RunExplainData, ShareView, ViewComments, ViewUnderlyingData, WebAuthoring, and Write. Valid capabilities for a data source are ChangePermissions, Connect, Delete, ExportXml, Read (view), and Write. |
| 400 | 400042 | Malformed permissions qualifier | The request body includes a <workbook> or <datasource> element. |
| 403 | 403004 | Permissions setting forbidden | A non-administrator user called this method but doesn't have permission to add permissions on the project. |
| 404 | 404000 | Site not found | The site LUID in the URI doesn't correspond to an existing site. |
| 404 | 404002 | User not found | A user LUID in the request body as the grantee doesn't correspond to an existing user. |
| 404 | 404005 | Project not found | The project LUID in the URI doesn't correspond to an existing project. |
| 404 | 404009 | Project ID mismatch | A project LUID specified in the URI does not match the project ID specified in the request body. (You do not have to specify a project ID in the request body.) |
| 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. |
For more information, see Handling Errors.
Add Flow Permissions
Adds permissions to the specified flow for a Tableau Server user or group. You can specify multiple sets of permissions using one call.
URI
PUT /api/api-version/sites/site-id/flows/flow-id/permissions
Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions. |
| site-id | The ID of the site that contains the flow. |
| datasource-id | The ID of the flow. |
Request Body
<tsRequest>
<permissions>
<flow id="flow-id" />
<granteeCapabilities>
<user id="user-id" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
... additional capabilities ...
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<group id="group-id" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
... additional capabilities ...
</capabilities>
</granteeCapabilities>
... additional grantee capability sets ...
</permissions>
</tsRequest>
Attribute Values
| flow-id | The flow-id value for the flow you want to add permissions to. |
| user-id | The ID (not name) of the user to add permissions for. |
| group-id | The ID (not name) of the group to add permissions for. |
| capability-name |
The capability to assign. If any capability has already been granted or denied for a specified user or group, that capability is ignored. Valid capabilities for a flow are:
For more information, see Permissions. |
Permissions
Tableau Server users who are not server administrators or site administrators can call this method only if they have permission to set permissions on the flow (either explicitly or implicitly).
Response Code
200
Response Body
<tsResponse>
<permissions>
<flow id="8359f0c5-4b98-4ca4-a7e5-38e4261e88a2" name="Flow1">
<owner id="8f735728-7484-40d1-89d1-41f09824536b"/>
</flow>
<granteeCapabilities>
<group id="9de5cc1a-5bb8-4c8e-b2cd-b54e736a7b9f"/>
<capabilities>
<capability name="Read" mode="Allow"/>
<capability name="Write" mode="Allow"/>
<capability name="Delete" mode="Deny"/>
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<user id="1f2345678-1234-12d1-12d1-11f234567b"/>
<capabilities>
<capability name="Delete" mode="Allow"/>
</capabilities>
</granteeCapabilities>
</permissions>
</tsResponse>
Version
Version 3.3 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 | 400009 | Invalid capability | The capability in the URI is invalid for a flow. Valid capabilities for a flow are ChangeHierarchy, ChangePermissions, Delete, Execute, ExportXml (Download), Read (view), and Write. |
| 403 | 403004 | Permissions setting forbidden | A non-administrator user called this method but doesn't have permission to set permissions on the flow. |
| 404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
| 404 | 404002 | User not found | A user ID in the request body doesn't correspond to an existing user. |
| 404 | 404027 | Flow not found | The flow ID in the URI doesn't correspond to an existing flow. |
| 404 | 404012 | Group not found | A group ID in the request body doesn't correspond to an existing group. |
| 404 | 404013 | Capability not found | The specified capability doesn't correspond to a defined capability. This can apply to either an invalid capability name or a capability other than Allow or Deny for any mode value. |
For more information, see Handling Errors.
Add Flow Task to Server Schedule
The Add Flow Task to Schedule method is renamed and retired for Tableau Cloud in API 3.22 (Tableau Cloud March 2024). It will remain available for Tableau Server only. For Tableau Cloud in March 2024, this method will be replaced with Create Cloud Flow Task method.
Adds a task to run a flow to an existing schedule.
Note: This method is unavailable if you do not have a Data Management license or Tableau Prep Conductor is disabled for your site.
URI
PUT /api/api-version/sites/site-id/schedules/schedule-id/flows
Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions. |
| site-id | The ID of the site that contains the flow. |
| schedule-id | The ID of the schedule that you are associating with the flow. The schedule that you are adding to must have Flow as the schedule type. |
Request Body
<tsRequest>
<task>
<flowRun>
<flow id="flow-id"/>
<flowRunSpec>
<flowParameterSpecs>
<flowParameterSpec
parameterId="parameter-id"
overrideValue= "overrideValue"/>
<flowParameterSpecs>
<flowRunSpec>
</flowRun>
</task>
</tsRequest>
Attribute Values
| flow-id |
The ID of the flow to add to the schedule. This will include all the output steps in the flow and any output steps created in the future. |
| parameter-id |
The ID of the flow parameter. Use the List Metrics for Site - Retired in API 3.22 method to get the flow parameter ID. A parameter is a global placeholder value such as a number, text value, or boolean value that can replace a constant value in a flow. Note: Parameters are optional and only relevant for flows that contain parameters and the parameter setting is enabled. For more information, see Run flows with parameters. |
| overrideValue |
The run-time value for the flow parameter. You must specify this if the parameter is required. Use the List Metrics for Site - Retired in API 3.22 method to see if the parameter is required and to get a list of allowed values if the parameter is expecting a value from an enumerated list. Note: Parameters are options and only relevant for flows that contains parameters and the parameter setting is enabled. For more information, see Run flows with parameters. |
Permissions
Tableau Server users who are not server administrators or site administrators can only add a flow to a schedule if they own the flow, or are the project leader for the project that contains the workbook.
Response Code
200
Version
Version 3.3 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 | 400148 | Invalid parameter override value | The run-time value provided for the flow parameter is invalid. |
| 400 | 400149 | Missing run-time parameter value. | The run-time value for a required flow parameters was not provided. |
| 401 | 401002 | Unauthorized Access | The authentication token provided in the request header was invalid or has expired. |
| 403 | 403098 | Update Forbidden | A non-administrator user called this method, but the caller doesn't have sufficient permissions. |
| 404 | 404000 | Site not found | The site ID in the URI is unknown. |
| 404 | 404043 | Flow parameter not found | The flow parameter information was not provided. |
| 404 | 404002 | User not found | A user ID in the request body doesn't correspond to an existing user. |
| 404 | 404027 | Flow not found | The flow ID in the URI doesn't correspond to an existing flow. |
| 405 | 405000 | Invalid request method | Request type was not PUT. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/schedules/9a4ebbab-9ec8-487a-9b48-47fa81d6077a/flows" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" –d @add-to-schedule.xml"
Content of add-to-schedule.xml:
The <flowRunSpec> in the request body is optional and only required in the following scenarios:
- The flow has parameters and the parameter is marked as required to run the flow.
- The flow has parameters but not marked as required. However, you want to specify a different value than the configured default.
<tsRequest>
<task>
<flowRun>
<flow id="5ab9cd53-e17f-45gh-804i-4914jk39r29z"/>
<flowRunSpec>
<flowParameterSpecs>
<flowParameterSpec>
parameterId="a2fb691b-90fa-4b6e-850e-f16c5afc1f89"
overrideValue= "2"/>
<flowParameterSpecs>
<flowRunSpec>
</flowRun>
</task>
</tsRequestExample response:
<tsResponse version-and-namespace-settings>
<task>
<flowRun id="8a78c68e-37ad-4b21-80fc-e67e2ab55279" priority="50" consecutiveFailedCount="0" type="RunFlowTask">
<schedule id="99e8841e-8527-4d09-89b8-71d9872634df" name="demo" state="Active" priority="50" createdAt="2021-12-09T19:21:09Z" updatedAt="2022-01-19T23:06:56Z" type="Flow" frequency="Hourly" nextRunAt="2022-01-20T00:00:00Z"/>
<flow id="09942c88-99d5-4669-aa62-07560fc4b201" name="CoffeeChain"/>
<flowParametersRuns>
<parameterRuns parameterId="a2fb691b-90fa-4b6e-850e-f16c5afc1f89" name="param 2 required" description=testparameter2" overrideValue = "2"/>
<flowParametersRuns>
</flowRun>
</task>
</tsResponse>Add Flow to Favorites
Adds the specified flow to the user's favorites.
If the user already has the flow listed as a favorite with the same label, the operation has no effect. If the label differs, the original favorite is overwritten.
URI
PUT /api/api-version/sites/site-id/favorites/user-id
Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions. |
| site-id | The ID of the site that contains the data source. |
| user-id | The ID of the user to add the favorite for. |
Request Body
<tsRequest>
<favorite label="favorite-label">
<flow id="flow-id" />
</favorite>
</tsRequest>
Attribute Values
| favorite-label | A label to assign to the favorite. This value is displayed when you search for favorites on the server. |
| flow-id | The ID of the flow to add as a favorite. |
Permissions
Tableau Server users who are not server administrators or site administrators can call this method only if they have Read (view) permissions on the data source (either explicitly or implicitly).
Response Code
200
Response Body
<tsResponse>
<favorites>
<favorite label="favorite-label">
<flow id="flow-id" />
</favorite>
<favorite label="favorite-label">
<flow id="flow-id" />
</favorite>
... additional favorites ...
</favorites>
</tsResponse>
Version
Version 3.3 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 | 400005 | Invalid label | The favorite label is empty or consists of only white space characters. |
| 403 | 403004 | Forbidden favorites access | A non-administrator user called this method but doesn't have permission to add a data source to the specified user's favorites. This will always be the case when the user ID in the URI represents a different user than a non-administrator user who is calling the method. |
| 404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
| 404 | 404002 | User not found | The user ID in the URI doesn't correspond to an existing user. |
| 404 | 404027 | Flow not found | The flow ID in the URI doesn't correspond to an existing flow. |
| 405 | 405000 | Invalid request method | Request type was not PUT. |
| 409 | 409007 | Label conflict | There is already a favorite with the same label for a different data source in the specified user's favorites. |
For more information, see Handling Errors.
Add Group to Group Set
Adds group to a group set.
Version: Available in API 3.22 (Tableau Cloud February 2024 / Server 2024.2) and later. Version Overview(Link opens in a new window)
License: No additional license required.
Permissions: This method can only be called by Tableau Server administrators or Tableau Cloud site admins. Permissions Overview(Link opens in a new window)
JWT Access Scope: tableau:groupsets:update Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)
URI
PUT api/api-version/sites/site-id/groupsets/group-set-id/groups/group-id
Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions. |
| site-id | The unique ID of the site asset. |
| group-set-id | The unique ID of the group set you want to add the group to. |
| group-id | The unique ID of the group you want to add to the group set. |
Request Body
None
Response Code
200
Response Body
None
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 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
| 404 | 404012 | Group not found | The group ID in the request body doesn't correspond to an existing group. |
| 409 | 409120 | Group set not found | The group set ID in the request body doesn't correspond to an existing group. |
For more information, see Handling Errors.
Add Metric to Favorites - Retired in API 3.22
Retired in API 3.22 (Cloud February 2024 / Server 2024.2)In February 2024, Tableau's Ask Data and Metrics features and their REST API methods will be retired in Tableau Cloud and Tableau Server version 2024.2. With advances in natural language technologies, we're developing an improved interface that will make it easier to ask questions of your data and stay on top of changes. For more information, see Create Metrics with Tableau Pulse(Link opens in a new window) and Explore Metrics with Tableau Pulse(Link opens in a new window).
Adds the specified metric to the user's favorites.
If the user already has the metric listed as a favorite with the same label, the operation has no effect. If the label differs, the original favorite is overwritten.
URI
PUT /api/api-version/sites/site-id/favorites/user-id
Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions. |
| site-id | The ID of the site that contains the metric. |
| user-id | The ID of the user to add the favorite for. |
Request Body
<tsRequest>
<favorite label="favorite-label">
<metric id="metric-id" />
</favorite>
</tsRequest>
Attribute Values
| favorite-label | A label to assign to the favorite. This value is displayed when you search for favorites on the server. |
| metric-id | The ID of the metric to add as a favorite. |
Permissions
Tableau Server users who are not server administrators or site administrators can call this method only if they have Read (view) permissions on the metric (either explicitly or implicitly).
Response Code
200
Response Body
<tsResponse>
<favorites>
<favorite label="favorite-label">
<metric id="metric-id" />
</favorite>
<favorite label="favorite-label">
<metric id="metric-id" />
</favorite>
... additional favorites ...
</favorites>
</tsResponse>
Version
Version 3.15 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 | 400005 | Invalid label | The favorite label is empty or consists of only white space characters. |
| 403 | 403004 | Forbidden favorites access | A non-administrator user called this method but doesn't have permission to add a metric to the specified user's favorites. This will always be the case when the user ID in the URI represents a different user than a non-administrator user who is calling the method. |
| 404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
| 404 | 404002 | User not found | The user ID in the URI doesn't correspond to an existing user. |
| 404 | 404028 | Metric not found | The metric ID in the URI doesn't correspond to an existing metric. |
| 405 | 405000 | Invalid request method | Request type was not PUT. |
| 409 | 409007 | Label conflict | There is already a favorite with the same label for a different metric in the specified user's favorites. |
For more information, see Handling Errors.
Add or Update Monitoring Quality Warning on Content
Create or update one or more monitoring quality warnings.
You can monitor for extract refresh failures on extract data sources or flow run failures on flows. An asset can only have one instance of monitoring. Adding monitoring to an asset that already has it will update it to use the latest specified values.
Note: An asset can have one monitoring warning in addition to other data quality warnings.
This method is available if your Tableau Cloud site or Tableau Server is licensed with Data Management.
URI
Add or update a monitoring quality warning for an asset
POST api/api-version/sites/site-id/dataQualityTriggers/content-type/contentIds?filter=contentId:in:[content-luid]
Add or update a monitoring quality warning for multiple assets
POST api/api-version/sites/site-id/dataQualityTriggers/content-type/contentIds?filter=contentId:in:[content-luid1,content-luid2,content-luid3,...]
Note: The square brackets are required around the single LUID or comma-separated list of LUIDs.
Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions. |
| site-id | The unique ID of the site asset. |
| content-type |
The type of content the monitoring is being applied to. Use one of the following values:
These values are not case sensitive. |
| content-luid |
The LUID of the asset. This is the same as the content ID. The square brackets are required around the single LUID or comma-separated list of LUIDs. |
Request Body
<tsRequest>
<dataQualityTrigger type="type" active="status" message="message" severe="severity"/>
</tsRequest>
Attribute Values
| type |
Type of monitoring quality warning. To specify the type, use one of the following values:
These values are not case sensitive. |
| status |
Monitoring status. Values can be "true" or "false". If set to "true", the data source is monitored for extract refresh failures or the flow is monitored for flow run failures). If an extract refresh or flow run failure occurs, the specified data quality warning is attached to the data source or flow (depending on type). The data quality warning is removed when the extract refresh or flow run is successful. For more information about monitoring quality warnings, see the monitoring quality warning section of the "Set a Data Quality Warning" topic in the Server Help or Cloud Help. |
| message | (Optional) A custom message for the data quality warning. |
| severity | High visibility status of the data quality warning. Values can be "true" or "false". For more information, see the "Visibility" section of the "Set a Data Quality Warning" topic in the Server Help or Cloud Help. |
Permissions
If Tableau Server or Tableau Cloud is licensed through Data Management, the following users have permissions to add a monitoring 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>
<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 monitoring quality warning 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 Project Permissions
Adds permissions to the specified project for a user or group. You can specify multiple sets of permissions using one call.
If the request body includes a child datasource or <project> element, the request is invalid.
URI
PUT /api/api-version/sites/site-id/projects/project-id/permissions
Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions. |
| site-id | The ID of the site that contains the project. |
| project-id | The ID of the project to set permissions for. |
Request Body
<tsRequest>
<permissions>
<granteeCapabilities>
<user id="user-id" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
... additional capabilities ...
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<group id="group-id" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
... additional capabilities ...
</capabilities>
</granteeCapabilities>
... additional grantee capability sets ...
</permissions>
</tsRequest>
Attribute Values
| user-id | The ID (not name) of the user to add permissions for. |
| group-id | The ID (not name) of the group to add permissions for. |
| capability-name |
The capability to assign permissions to. In Tableau Server 10.0, the valid
capabilities for a project are
ProjectLeader,
Read (view), and
Write.
For more information, see Permissions. |
| capability-mode | Allow to allow the capability, or Deny to deny it. This value is case sensitive. |
Permissions
Users who are not server administrators or site administrators can add permissions for a project only if they have ChangePermissions (version 2.0) or
ProjectLeader (version 2.1) permission for that project (either explicitly or implicitly).
Required scope for JWT authorization
Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).
Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:updateResponse Code
200
Response Body
<tsResponse>
<permissions>
<project id="project-id" name="project-name" />
<owner id="project-owner-id" />
</project>
<granteeCapabilities>
<user id="user-id" />
<capabilities>
<capability name="capability" mode="Allow-or-Deny" />
<capability name="capability" mode="Allow-or-Deny" />
... additional capabilities ...
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<group id="group-id" />
<capabilities>
<capability name="capability" mode="Allow-or-Deny" />
<capability name="capability" mode="Allow-or-Deny" />
... additional capabilities ...
</capabilities>
</granteeCapabilities>
... additional grantee capability sets ...
</permissions>
</tsResponse>
Version
Version 2.0 and later. For more information, see REST API and Resource Versions.
Errors
| HTTP status | error Code |
Condition | Details |
|---|---|---|---|
| 400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
| 400 | 400009 | Invalid capability |
The capability specified in the request is not in the list of valid capability names for this method. The mode of the capability for ProjectLeader cannot be set to Deny. |
| 403 | 403004 | Permissions setting forbidden | A non-administrator user called this method but doesn't have permission to add permissions on the project. |
| 404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
| 404 | 404002 | User not found | A user ID in the request body as the grantee doesn't correspond to an existing user. |
| 404 | 404005 | Project not found | The project ID in the URI doesn't correspond to an existing project. |
| 404 | 404009 | Project ID mismatch | A project ID specified in the URI does not match the project ID specified in the request body. (You do not have to specify a project ID in the request body.) |
| 404 | 404012 | Group not found | A group ID 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. |
For more information, see Handling Errors.
Add Project to Favorites
Adds the specified project to a user's favorites.
If the user already has the project listed as a favorite with the same label, the operation has no effect. If the label differs, the original favorite is overwritten.
URI
PUT /api/api-version/sites/site-id/favorites/user-id
Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions. |
| site-id | The ID of the site that contains the project. |
| user-id | The ID of the user to add the favorite for. |
Request Body
<tsRequest>
<favorite label="favorite-label">
<project id="project-id"/>
</favorite>
</tsRequest>
Attribute Values
| favorite-label | A label to assign to the favorite. This value is displayed when you search for favorites on the server. |
| project-id | The ID (not name) of the project to add as a favorite. |
Permissions
Tableau Server users who are not server administrators or site administrators can call this method only if they have permission to add a project to a favorite list (either explicitly or implicitly).
Response Code
200
Response Body
<tsResponse>
<favorites>
<favorite label="favorite1-label">
<project id="project-id" />
</favorite>
<favorite label="favorite2-label">
<project id="project-id" />
</favorite>
</favorites>
</tsResponse>
Version
Version 3.1 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 | 400005 | Invalid label | The favorite label is empty or consists of only white space characters. |
| 403 | 403004 | Access to favorites denied | A non-administrator user called this method but doesn't have permission to add a project to the specified user's favorites. This will always be the case when the user ID in the URI represents a different user than a non-administrator user who is calling the method. |
| 404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
| 404 | 404002 | User not found | The user ID in the URI doesn't correspond to an existing user. |
| 404 | 404005 | Project not found | The project ID in the request body doesn't correspond to an existing project. |
| 405 | 405000 | Invalid request method | Request type was not PUT. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/favorites/2474164d-8d37-4a4c-abc7-c2070fd25fd5" -X PUT -d @add-project-to-favorites.xml -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Content of add-project-to-favorites.xml:
<tsRequest>
<favorite label="Economic Indicators">
<project id="1f1e1d1c-2b2a-2f2e-3d3c-3b3a4f4e4d4c" />
</favorite>
</tsRequest>Example response:
<tsResponse version-and-namespace-settings>
<favorites>
<favorite label="Economic Indicators">
<project id="1f1e1d1c2-b2a2-f2e3-d3c3-b3a4f4e4d4c"/>
</favorite>
</favorites>
</tsResponse>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.24. 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:
These values are case sensitive. |
| capability-mode |
Use one of the following capabilities:
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.24. 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 Data Source
Adds one or more tags to the specified data source.
URI
PUT /api/api-version/sites/site-id/datasources/datasource-id/tags
Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions. |
| site-id | The ID of the site that contains the data source. |
| datasource-id | The ID of the data source to add tags to. |
Request Body
<tsRequest>
<tags>
<tag label="tag" />
... additional tags ...
</tags>
</tsRequest>
Attribute Values
| datasource-id | The data source to add the tag to. If the data source is already tagged with a tag that's included in the request body, those tags are ignored and the data source retains them. If the <tags> element is empty, no new tags are added to the data source. |
| tag | The text of the tag. |
Permissions
Tableau Server users who are not server administrators or site administrators can call this method only if they have Read permissions for the data source (either explicitly or implicitly).
Response Code
200
Response Body
<tsResponse>
<tags>
<tag label="tag"/>
... additional new tags ...
... existing tags ...
</tags>
</tsResponse>Version
Version 1.0 and later. For more information, see REST API and Resource Versions.
Errors
| HTTP status | error Code |
Condition | Details |
|---|---|---|---|
| 400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
| 400 | 400075 | Error adding tags | There was a problem adding tags to the specified data source. |
| 403 | 403004 | Adding tags forbidden |
A non-administrator user called this method but doesn't have permission to add tags. This error is raised even if the <tags> element is empty. |
| 404 | 404000 | Site not found |
The site ID in the URI is not for an existing site. |
| 404 | 404004 | Data source not found | The data source ID in URI doesn't correspond to an existing data source. |
| 404 | 404009 | Data source ID mismatch | The request body contains a data source ID (which is optional) and it doesn't match the ID in the URI. |
| 404 | 405000 | Invalid request method | Request type was not PUT. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/1a2a3b4b-5c6c-7d8d-9e0e-1f2f3a4a5b6b/tags" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @add-tags-to-datasource.xml
Content of add-tags-to-datasource.xml:
<tsRequest>
<tags>
<tag label="GDP" />
<tag label="Health" />
</tags>
</tsRequest>Example response:
<tsResponse version-and-namespace-settings>
<tags>
<tag label="GDP"/>
<tag label="Health"/>
<tag label="Spending"/>
</tags>
</tsResponse>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.24. 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.24. 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. |
Add Tags to View
Adds one or more tags to the specified view.
URI
PUT /api/api-version/sites/site-id/views/view-id/tags
Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions. |
| site-id | The ID of the site that contains the workbook. |
| view-id | The ID of the views to add tags to. |
Request Body
<tsRequest>
<tags>
<tag label="tag" />
... additional tags ...
</tags>
</tsRequest>
Attribute Values
| view-id | The view to add the tag to. If the view is already tagged with a tag that's included in the request body, those tags are ignored and the view retains them. If the <tags> element is empty, no new tags are added to the view. |
| tag | The text of the tag. |
Permissions
Tableau Server users who are not server administrators or site administrators can call this method only if they have Read permissions for the view (either explicitly or implicitly).
Response Code
200
Response Body
<tsResponse>
<tags>
<tag label="tag"/>
... additional new tags ...
... existing tags ...
</tags>
</tsResponse>Version
Version 1.0 and later. For more information, see REST API and Resource Versions.
Errors
| HTTP status | error Code |
Condition | Details |
|---|---|---|---|
| 400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
| 400 | 400076 | Error adding tags | There was a problem adding tags to the specified view. |
| 403 | 403004 | Adding tags forbidden |
A non-administrator user called this method but doesn't have permission to add tags. This error is raised even if the <tags> element is empty. |
| 404 | 404000 | Site not found |
The site ID in the URI is not for an existing site. |
| 404 | 404011 | View not found | The view ID in URI doesn't correspond to an existing view. |
| 404 | 404009 | Workbook ID mismatch | The request body contains a view ID (which is optional) and it doesn't match the ID in the URI. |
| 404 | 405000 | Invalid request method | Request type was not PUT. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/views/1f1e1d1c-2b2a-2f2e-3d3c-3b3a4f4e4d4c/tags" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @add-tags-to-view.xml
Content of add-tags-to-workbook.xml:
<tsRequest>
<tags>
<tag label="GDP" />
<tag label="Health" />
</tags>
</tsRequest>Example response:
<tsResponse version-and-namespace-settings>
<tags>
<tag label="GDP"/>
<tag label="Health"/>
<tag label="Spending"/>
</tags>
</tsResponse>Add Tags to Virtual Connection
Adds tags to a virtual connection.
Version: Available in API 3.23 (Tableau Cloud June 2024 / Tableau Server 2024.2) and later. Version Overview(Link opens in a new window)
License: Requires Tableau Data Management(Link opens in a new window).
Permissions: You must have the View permission for the virtual connection and your site role must be at least Explorer. Permissions Overview(Link opens in a new window)
JWT Access Scope: Not available.
URI
PUT /api/api-version/sites/site-id/virtualconnections/virtualconnection-id/tags
Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
|
| site-luid | The LUID for the site. |
| virtualconnection-luid | The LUID for the virtual connection. |
Request Body
<tsRequest>
<tags>
<tag label="tag" />
<!-- ...additional tag elements... -->
</tags>
</tsRequest>Attribute Values
| tag | The text of the tag. |
cURL Request Example
curl --location --request PUT 'http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections/12ab34cd-56ef-78ab-90cd-12ef34ab56cd/tags' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3' --data @data.xml
Contents of data.xml.
<tsRequest>
<tags>
<tag label="Office" />
<!-- ...additional tag elements... -->
</tags>
</tsRequest>Response Code
200
Response Body
<tsResponse>
<tags>
<tag label="tag"/>
<!-- ...additional tags... -->
</tags>
</tsResponse>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 | 400049 | Error adding tags | There was a problem adding tags to the specified virtual connection. |
| 403 | 403004 | Adding tags forbidden | The user doesn't have permissions to add tags to the virtual connection. |
| 404 | 404000 | Site not found | The site ID in the URI is not for an existing site. |
| 404 | 404006 | Virtual connection not found | The virtual connection ID in URI doesn't correspond to an existing virtual connection. |
| 404 | 405000 | Invalid request method | Request type was not PUT. |
For more information, see Handling Errors.
Add Tags to Workbook
Adds one or more tags to the specified workbook.
URI
PUT /api/api-version/sites/site-id/workbooks/workbook-id/tags
Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions. |
| site-id | The ID of the site that contains the workbook. |
| workbook-id | The ID of the workbook to add tags to. |
Request Body
<tsRequest>
<tags>
<tag label="tag" />
... additional tags ...
</tags>
</tsRequest>
Attribute Values
| workbook-id | The workbook to add the tag to. If the workbook is already tagged with a tag that's included in the request body, those tags are ignored and the workbook retains them. If the <tags> element is empty, no new tags are added to the workbook. |
| tag | The text of the tag. |
Permissions
Tableau Server users who are not server administrators or site administrators can call this method only if they have Read permissions for the workbook (either explicitly or implicitly).
Response Code
200
Response Body
<tsResponse>
<tags>
<tag label="tag"/>
... additional new tags ...
... existing tags ...
</tags>
</tsResponse>Version
Version 1.0 and later. For more information, see REST API and Resource Versions.
Errors
| HTTP status | error Code |
Condition | Details |
|---|---|---|---|
| 400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
| 400 | 400049 | Error adding tags | There was a problem adding tags to the specified workbook. |
| 403 | 403004 | Adding tags forbidden |
A non-administrator user called this method but doesn't have permission to add tags. This error is raised even if the <tags> element is empty. |
| 404 | 404000 | Site not found |
The site ID in the URI is not for an existing site. |
| 404 | 404006 | Workbook not found | The workbook ID in URI doesn't correspond to an existing workbook. |
| 404 | 404009 | Workbook ID mismatch | The request body contains a workbook ID (which is optional) and it doesn't match the ID in the URI. |
| 404 | 405000 | Invalid request method | Request type was not PUT. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/tags" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @add-tags-to-workbook.xml
Content of add-tags-to-workbook.xml:
<tsRequest>
<tags>
<tag label="GDP" />
<tag label="Health" />
</tags>
</tsRequest>Example response:
<tsResponse version-and-namespace-settings>
<tags>
<tag label="GDP"/>
<tag label="Health"/>
<tag label="Spending"/>
</tags>
</tsResponse>Add User to Data-Driven Alert
Adds a specified user to the recipients list for a data-driven alert.
URI
POST /api/api-version/sites/site-id/dataAlerts/data-alert-id/users
Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions. |
| site-id | The ID of the site that contains the specified data-driven alert. |
| data-alert-id | The ID of the data-driven alert. You can obtain this ID by calling Query Data-Driven Alerts. |
Version: Available in API 3.2 (Tableau Cloud / Tableau Server 2018.3) and later. Version Overview(Link opens in a new window)
License: No additional license required.>
Permissions: This method can only be called by server administrators and site administrators, and by users who are owners of the specified alert. Permissions Overview(Link opens in a new window)
JWT Access Scope:
tableau:data_driven_alerts:update
Access Scopes Overview:
Cloud(Link opens in a new window) |
Server-Windows(Link opens in a new window) |
Server-Linux(Link opens in a new window)
Available in API 3.20 (Tableau Cloud June 2023).
Not available for Tableau Server.
Request Body
<tsRequest>
<user id="user-id"/>
</tsRequest>
Response Code
200
Response Body
<tsResponse>
<user id="user-id"
name="user-name"
siteRole="site-role"
externalAuthUserId="external-user-id"/>
</tsResponse>
Errors
| HTTP status | error Code |
Condition | Details |
|---|---|---|---|
| 403 | 403004 | Write forbidden | A user called this method who does not have the required permissions. |
| 403 | 409028 | Adding recipient to data-driven alert forbidden | The user is not authorized to add the recipient to the data-driven alert. |
| 404 | 404000 | Site not found | The site ID or URL namespace in the URI doesn't correspond to an existing site. |
| 404 | 404002 | Resource Not Found | The user ID specified in the request body is invalid. |
| 404 | 409023 | Resource Not Found | The data-driven alert ID specified in the URI is invalid. |
| 405 | 405000 | Invalid request method | Request type was not POST. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/13020592-762f-4de4-a25e-f4beb005836e/dataAlerts/e5a4b73e-5cbb-412d-907e-f31cc31684f7/users" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @add-user-to-alert.xml
Content of add-user-to-alert.xml:
<tsRequest>
<user id="8eda27d9-5ad2-42cd-a39a-61bc01a423af"/>
</tsRequest>Example response:
<tsResponse>
<user id="8eda27d9-5ad2-42cd-a39a-61bc01a423af"
name="admin"
siteRole="ServerAdministrator"
externalAuthUserId=""/>
</tsresponse>Add User to Group
Adds a user to the specified group.
Beginning in API 3.21, you can bulk add users to a group by specifying multiple user IDs.
Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.
URI
POST /api/api-version/sites/site-id/groups/group-id/users
Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions. |
| site-id | The ID of the site that contains the group. |
| group-id | The ID of the group to add the user to. |
Request Body
Add a single user to a group
<tsRequest>
<user id="user-id" />
</tsRequest>Bulk add users to a group (beginning in API 3.21)
<tsRequest>
<users>
<user id="user-id1" />
<user id="user-id2" />
<user id="user-id2" />
</users>
</tsRequest>Attribute Values
| user-id |
The ID (not name) of the user to add. You can get the user ID by calling Get Users on Site. Beginning in API 3.21, you can bulk add users to a group by specifying multiple user IDs. |
Permissions
This method can only be called by server administrators and site administrators.
Required scope for JWT authorization
Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).
Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:groups:updateResponse Code
200
Response Body
Add a single user to a group
<tsResponse>
<user id="user-id" name="user-name" siteRole="site-role" />
</tsResponse>Bulk add users to group (beginning in API 3.21)
<tsResponse>
<users>
<user id="user-id"
name="user-name"
siteRole="site-role" />
<user id="user-id"
name="user-name"
siteRole="site-role" />
</users>
</tsResponse>
The siteRole value is returned as one of the following values: Creator, Explorer, ExplorerCanPublish, ServerAdministrator, SiteAdministratorExplorer, SiteAdministratorCreator, Unlicensed, ReadOnly, or Viewer.
Version
Version 2.0 and later. For more information, see REST API and Resource Versions.
Errors
| HTTP status | error Code |
Condition | Details |
|---|---|---|---|
| 400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
| 404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
| 404 | 404012 | Group not found | The group name in the request body doesn't correspond to an existing group. |
| 405 | 405000 | Invalid request method | Request type was not POST. |
| 409 | 409011 | User conflict | The specified user is already a member of the group. |
For more information, see Handling Errors.
Example
Add a single user to a group
curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups/1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d/users" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @add-user-to-group.xml
Content of add-user-to-group.xml:
<tsRequest>
<users id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" />
</tsRequest>Example response:
<?xml version="1.0" encoding="UTF-8" ?>
<tsResponse version-and-namespace-settings>
<user id="59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba" name="Adam"
siteRole="Explorer" />
</tsResponse>Bulk add users to a group (beginning in API 3.21)
curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups/1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d/users" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @bulk-add-user-to-group.xml
Content of bulk-add-user-to-group.xml:
<tsRequest>
<users>
<user id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" />
<user id="1z4e8n7q-6t8t-8f8e-7d7c-1b1a2f2d2e2d" />
</users>
</tsRequest>Example response:
<?xml version="1.0" encoding="UTF-8" ?>
<tsResponse version-and-namespace-settings>
<users>
<user id="59a8a7b6-be3a-4d2d-1e9e-08a7b6b5b4ba" name="Adam"
siteRole="Explorer" />
<user id="11a1a1b1-be3a-4d2d-1e9e-08a7b6b5b5ba" name="Sadako"
siteRole="Explorer" />
<users>
</tsResponse>Add User to Identity Pool
Add a user to a specified identity pool.
This enables the user to sign in to Tableau Server using the specified identity pool. This method is not available for Tableau Cloud.
For more information about identity pools, see Provision and Authenticate Users Using Identity Pools(Link opens in a new window).
URI
POST /api/api-version/sites/site-id/users/identityPool
Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions. |
| site-id | The ID of the site that is associated with the user you want to add to the identity pool. |
Request Body
<tsRequest>
<user
name="user-name"
siteRole="site-role"
id="user-id"
authSetting="authentication-configuration"
identityPoolUuid="idpool-uuid"
identityUuid="identity-uuid" />
</tsRequest>Attribute Values
| user-name |
The name of the user to add. |
| site-role |
Site role of the user. You can use one of the following values:
|
| user-id | Required. The ID (not name) of the user to add. You can get the user ID by calling Get Users on Site. |
| authentication-configuration | The authentication configuration instance configured for the identity pool you want to add the user to. You can get the authentication configuration instance by calling List Authentication Configurations(Link opens in a new window) endpoint in Tableau REST OpenAPI. |
| idpool-uuid | The ID of the identity pool that you wan to add the user to. You can get the identity pool ID by calling the List Identity Pools(Link opens in a new window) endpoint in the Tableau REST OpenAPI. |
| identity-uuid | The identifier for the user you want to add. Identifiers are only used for identity matching purposes. For more information about identifiers, see Usernames and Identifiers in Tableau(Link opens in a new window) in the Tableau Server Help. |
Permissions
This method can only be called by Tableau Server administrators.
Response Code
200
Response Body
Example response:
<tsResponse>
<user
identityPoolUuid="df47cf24-5ed3-11ed-9b6a-0242ac12000"
id="7ad8f89e-c2a1-44b4-9413-ac8a62286a7a"
name="Michele Kim" />
</tsResponse> Version
Version 3.19 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. |
| 404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
| 405 | 405000 | Invalid request method | Request type was not POST. |
| 429 | 429001 | User conflict | The specified user is already a member of the identity pool. |
| 429 | 429002 | Can't add user | There was a problem and the user couldn't be added to the identity pool. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users/identityPool" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @add-user-to-idpool.xml
MY-SERVERis the name or IP address of your server.9a8b7c6d5-e4f3-a2b1-c0d9-e8f7a6b5c4dis the ID of the site, as returned by a previous call to Sign In.12ab34cd56ef78ab90cd12ef34ab56cdis the credentials token returned by a previous call to Sign In.
Content of add-user-to-idpool.xml:
<tsRequest>
<user id="7ad8f89e-c2a1-44b4-9413-ac8a62286a7a" />
</tsRequest>Example response:
<?xml version="1.0" encoding="UTF-8" ?>
<tsResponse version-and-namespace-settings>
<user identityPoolUuid="7b54b6a8-6095-11ed-9b6a-0242ac120002"
id="7ad8f89e-c2a1-44b4-9413-ac8a62286a7a" name="Michele Kim" />
</tsResponse>Add User to Site
Adds a user to Tableau Server or Tableau and assigns the user to the specified site.
If Tableau Server is configured to use local authentication, the information you specify is used to create a new user in Tableau Server.
Note: After creating the user, you must set a full name, password, and email address for the user with the call to Update User. If you are using SAML with local authentication, the user information that you add is not synchronized with the SAML IdP, as it would be if you were using Active Directory. Even if it is not used by SAML, the user information must be present.
If Tableau Server is configured to use Active Directory for authentication, the user you specify is imported from Active Directory into Tableau Server.
When you add user to Tableau Cloud, the name of the user must be the email address that is used to sign in to Tableau Cloud. After you add a user, Tableau Cloud sends the user an email invitation. The user can click the link in the invitation to sign in and update their full name and password.
If you try to add a user using a specific site role but you have already reached the limit on the number of licenses for your users, the user is added as an unlicensed user. In that case, the response code is 201 (which indicates success), but the siteRole value in the response body is set to Unlicensed.
Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.
URI
POST /api/api-version/sites/site-id/users
Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions. |
| site-id | The ID of the site to add users to. |
Request Body
<tsRequest>
<user name="user-name"
siteRole="site-role"
authSetting="auth-setting"
identityPoolName="identity-pool-name" />
</tsRequest>Attribute Values
| user-name |
The name of the user. If the server uses local authentication, this can be any name. If you are using Active Directory authentication, or if you are using Tableau Cloud, there are specific requirements for the name. For Tableau Server:
Note: Active Directory specifies a user name using two attributes: For Tableau Cloud:
|
| site-role |
The site role to assign to the user. You can assign the following roles: Creator, Explorer, ExplorerCanPublish, SiteAdministratorExplorer, SiteAdministratorCreator, Unlicensed, or Viewer. Note: You cannot use the REST API to set a user to be a server administrator (ServerAdministrator site role). |
| auth-setting |
(Optional) The authentication type for the user. (For Tableau Server: This attribute only applies when adding users to sites with site-specific SAML enabled in settings.) You can assign the following values for this attribute:
|
| identity-pool-name |
(Optional, Tableau Server only) When identity pools are configured, the name of the identity pool. Starting in API 3.19, include the identity pool name when identity pools are configured and you need to add a user to an identity pool that uses the local identity store and OIDC authentication. For more information, see Identity Pools Methods. |
Permissions
This method can only be called by server administrators and site administrators.
Required scope for JWT authorization
Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).
Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:users:createResponse Code
201
Response Body
<tsResponse>
<user id="user-id"
name="user-name"
siteRole="site-role"
authSetting="auth-setting" />
</tsResponse>
Response Headers
Location: /api/3.24/sites/site-id/users/new-user-id
Version
Version 1.0 and later. For more information, see REST API and Resource Versions.
Errors
| HTTP status | error Code |
Condition | Details |
|---|---|---|---|
| 400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
| 400 | 400003 | Bad request | The user authentication setting ServerDefault is not supported for you site. Try again using TableauIDWithMFA instead. |
| 400 | 400013 | Invalid site role |
The value of the siteRole attribute must be Explorer, ExplorerCanPublish, SiteAdministratorCreator, SiteAdministratorExplorer, Unlicensed, or Viewer. |
| 404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
| 404 | 404002 | User not found | The server is configured to use Active Directory for authentication, and the username specified in the request body doesn't match an existing user in Active Directory. |
| 405 | 405000 | Invalid request method | Request type was not POST. |
| 409 | 409000 | User conflict | The specified user already exists on the site. |
| 409 | 409005 | Guest user conflict | The Tableau Server API doesn't allow adding a user with the guest role to a site. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/users/" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @add-user-to-site.xml
MY-SERVERis the name or IP address of your server.9a8b7c6d5-e4f3-a2b1-c0d9-e8f7a6b5c4dis the ID of the site to add the user to, as returned by a previous call to Sign In.12ab34cd56ef78ab90cd12ef34ab56cdis the authentication returned by a previous call to Sign In.
Content of add-user-to-site.xml:
<tsRequest>
<user name="Adam"
siteRole="Explorer" />
</tsRequest>Example response:
<tsResponse version-and-namespace-settings>
<user id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d"
name="Adam"
siteRole="Explorer"
authSetting="ServerDefault" />
</tsResponse>Add View Permissions
Adds permissions to the specified view (also known as a sheet) for a user or group. You can specify multiple sets of permissions using one call.
URI
PUT /api/api-version/sites/site-id/views/view-id/permissions
Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions. |
| site-id | The ID of the site that contains the workbook view. |
| view-id | The ID of the view to set permissions for. You can obtain this ID by calling Query Views for Site. |
Request Body
<tsRequest>
<permissions>
<view id="view-id" />
<granteeCapabilities>
<user id="user-id" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
... additional capabilities ...
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<group id="group-id" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
... additional capabilities ...
</capabilities>
</granteeCapabilities>
... additional grantee capability sets ...
</permissions>
</tsRequest>
Attribute Values
| view-id | The view-id value must match the view ID in the URI. |
| user-id | The ID (not name) of the user to add permissions for. |
| group-id | The ID (not name) of the group to add permissions for. |
| capability-name | The capability to assign. If any capability has already been
granted or denied for a specified user or group, that capability is ignored. For valid capabilities for a view are
AddComment, ChangePermissions, Delete, ExportData, ExportImage, ExportXml, Filter, Read (view), ShareView, ViewComments, ViewUnderlyingData, WebAuthoring, and Write.
For more information, see Permissions. |
| capability-mode | Allow to allow the capability, or Deny to deny it. This value is case sensitive. |
Permissions
This method can only be called by server and site administrators, and user who have permission to set permissions on the workbook (either explicitly or implicitly). To use this method, the parent workbook that contains the specified view must have its showTabs attribute set to Hide. You can configure this setting by using the Update Workbook method.
Required scope for JWT authorization
Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).
Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:updateResponse Code
200
Response Body
<tsResponse>
<permissions>
<view id="view-id" />
<owner id="owner-id"/>
</view>
<granteeCapabilities>
<user id="user-id" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
<capability name="capability-name" mode="capability-mode" />
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<user id="user-id" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
<capability name="capability-name" mode="capability-mode" />
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<group id="group-id" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
</capabilities>
</granteeCapabilities>
</permissions>
</tsResponse>
The createdAt and updatedAt values are dates and times in UTC format (YYYY-MM-DDTHH:MM:SSZ).
Version
Version 3.2 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 | 400009 | Invalid capability | The capability in the URI is invalid for a view. |
| 403 | 403004 | Permissions setting forbidden | A non-administrator user called this method but doesn't have permission to set permissions on the view. |
| 404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
| 404 | 404011 | View not found | The view ID in the URI doesn't correspond to an existing view. |
| 404 | 404012 | Group not found | A group ID in the request body doesn't correspond to an existing group. |
| 404 | 404013 | Capability not found | The specified capability doesn't correspond to a defined capability. This can apply to either an invalid capability name or an invalid capability value (other than Allow or Deny). |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/13020592-762f-4de4-a25e-f4beb005836e/views/e5a4b73e-5cbb-412d-907e-f31cc31684f7" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @add-view-permissions.xml
Example of add-view-permissions.xml:
<tsRequest>
<permissions>
<view id="34acb0d7-fa37-43d7-bdde-d6635eb724b5" />
<granteeCapabilities>
<user id="8eda27d9-5ad2-42cd-a39a-61bc01a423af" />
<capabilities>
<capability name="ExportImage" mode="Allow" />
<capability name="ChangePermissions" mode="Deny" />
</capabilities>
</granteeCapabilities>
</permissions>
</tsRequest>Example response:
<tsResponse>
<permissions>
<view id="34acb0d7-fa37-43d7-bdde-d6635eb724b5" name="What If Forecast">
<owner id="8eda27d9-5ad2-42cd-a39a-61bc01a423af"/>
</view>
<granteeCapabilities>
<group id="2aa47cfa-9f2b-11e8-a260-af4a26124661"/>
<capabilities>
<capability name="ShareView" mode="Allow"/>
<capability name="ViewComments" mode="Allow"/>
<capability name="Filter" mode="Allow"/>
<capability name="ExportData" mode="Allow"/>
<capability name="Read" mode="Allow"/>
<capability name="AddComment" mode="Allow"/>
<capability name="ViewUnderlyingData" mode="Allow"/>
<capability name="ExportImage" mode="Allow"/>
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<user id="8eda27d9-5ad2-42cd-a39a-61bc01a423af"/>
<capabilities>
<capability name="ExportImage" mode="Allow"/>
<capability name="ChangePermissions" mode="Deny"/>
</capabilities>
</granteeCapabilities>
</permissions>
</tsResponse>Add View to Favorites
Adds the specified view to a user's favorites.
If the user already has the view listed as a favorite with the same label, the operation has no effect. If the label differs, the original favorite is overwritten.
URI
PUT /api/api-version/sites/site-id/favorites/user-id
Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions. |
| site-id | The ID of the site that contains the view. |
| user-id | The ID of the user to add the favorite for. |
Request Body
<tsRequest>
<favorite label="favorite-label">
<view id="view-id" />
</favorite>
</tsRequest>
Attribute Values
| favorite-label | A label to assign to the favorite. This value is displayed when you search for favorites on the server. |
| view-id | The ID (not name) of the view to add as a favorite. |
Permissions
Tableau Server users who are not server administrators or site administrators can call this method only if they have permission to add a view to a favorite list (either explicitly or implicitly).
Response Code
200
Response Body
<tsResponse>
<favorites>
<favorite label="favorite-labe1">
<view id="view-id"
name="view-name"
contentUrl="content-url"
createdAt="created-at"
updatedAt="updated-at"
viewUrlName="view-url-name">
<workbook id="workbook-luid"/>
<project id"project-luid"/>
<tags />
</view>
</favorite>
... additional favorites ...
</favorites>
</tsResponse>
The value of view-url-name is the name of the view in its URL.
For example, if a view named View 1 shows the URL https://MY_SERVER/#/site/MY_SITE/views/VIEW_1
in your browser address bar, then the view-url-name would be VIEW_1.
Modifying the name (display name) of a view will not impact the view-url-name
(path element of the view's URL).
Version
Version 1.0 and later. For more information, see REST API and Resource Versions.
Errors
| HTTP status | error Code |
Condition | Details |
|---|---|---|---|
| 400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
| 400 | 400005 | Invalid label | The favorite label is empty or consists of only white space characters. |
| 403 | 403004 | Forbidden Favorites access | A non-administrator user called this method but doesn't have permission to add a view to the specified user's favorites. This will always be the case when the user ID in the URI represents a different user than a non-administrator user who is calling the method. |
| 404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
| 404 | 404002 | User not found | The user ID in the URI doesn't correspond to an existing user. |
| 404 | 404011 | View not found | The view ID in the request body doesn't correspond to an existing view. |
| 405 | 405000 | Invalid request method | Request type was not PUT. |
| 409 | 409007 | Label conflict | There is already a favorite with the same label for a different view of the same workbook in the specified user's favorites. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/favorites/9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" -X PUT -d @add-view-to-favorites.xml -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Content of add-view-to-favorite.xml:
<tsRequest>
<favorite label="Economic Indicators">
<view id="1f1e1d1c-2b2a-2f2e-3d3c-3b3a4f4e4d4c" />
</favorite>
</tsRequest>Example response:
<tsResponse version-and-namespace-settings>
<favorites>
<favorite label="DC Crimespotting">
<view id="08a7b6b5-b4ba-be3a-4d2d-1e9e59a8a7b6" name="Crimes_DC"
contentUrl="content-url"
createdAt="created-at"
updatedAt="updated-at"
viewUrlName="view-url-name">
<workbook id="abb3e4c1-e650-4704-870a-03fb7615136f"/>
<project id"3d6e8174-8cdf-43ec-94dd-0a1fd3662e47"/>
<tags />
</view>
</favorite>
<favorite label="Economic Indicators">
<view id="1f1e1d1c2-b2a2-f2e3-d3c3-b3a4f4e4d4c"/>
</favorite>
</favorites>
</tsResponse>Add Virtual Connection Permissions
Adds permissions to the specified virtual connection for a user or group. You can specify multiple sets of permissions using one call.
If a specified permission has already been granted or denied for a given user or group, the system ignores it.
URI
PUT /api/api-version/sites/site-id/virtualconnections/virtualconnection-id/permissions
Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions. |
| site-id | The ID of the site that contains the virtual connection. |
| virtualconnection‑id | The ID of the virtual connection to set permissions for. |
Request Body
<tsRequest>
<permissions>
<granteeCapabilities>
<user id="user-id" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
<!-- ...additional capabilities... -->
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<group id="group-id" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
<!-- ...additional capabilities... -->
</capabilities>
</granteeCapabilities>
<!-- ...additional granteeCapability sets... -->
</permissions>
</tsRequest>
Attribute Values
| user-id | The LUID of the user to add permissions for. A request does not need to include both a user and a group grantee. |
| group-id | The LUID of the group to add permissions for. A request does not need to include both a user and a group grantee. |
| capability-name |
The capability to assign. Valid capabilities for a virtual connection are Read, Connect, Overwrite, ChangeHierarchy, Delete, and ChangePermissions. For more information, see Permissions. |
| capability-mode | Allow to allow the capability, or Deny to deny it. |
Permissions
You must be an administrator or have the ChangePermissions permission for the virtual connection (either explicitly or implicitly).
Required scope for JWT authorization
Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).
Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:updateResponse Code
200
Response Body
<tsResponse>
<permissions>
<virtualConnection id="virtualconnection-luid"
name="virtual-connection-name">
<owner id="user-luid"/>
</virtualConnection>
<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 granteeCapability sets ... -->
</permissions>
</tsResponse> Version
Version 3.23 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 | 400009 | Invalid capability | The specified capability is invalid for a virtual connection. Valid capabilities for a virtual connection are Read, Connect, Overwrite, ChangeHierarchy, Delete, and ChangePermissions. |
| 403 | 403004 | Permissions setting forbidden | The user tried to change permissions for a virtual connection but doesn't have the permission to change them. |
| 404 | 404000 | Site not found | The specified site doesn't correspond to an existing site. |
| 404 | 404002 | User not found | The user specified in the request body doesn't correspond to an existing user. |
| 404 | 404012 | Group not found | The group specified in the request body doesn't correspond to an existing group. |
| 404 | 404013 | Capability not assigned | The capability in the URI is not assigned to the specified user or group with the specified mode (Allow or Deny). |
| 404 | 404014 | Capability not found | A capability specified 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. |
| 400 | 409004 | Invalid LUID | The virtual connection LUID in the URI was not found. |
For more information, see Handling Errors.
Example
curl --location --request PUT 'http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/virtualconnections/12ab34cd-56ef-78ab-90cd-12ef34ab56cd/permissions' --header 'Content-Type: application/xml' --header 'X-Tableau-Auth: HvZMqFFfQQmOM4L-AZNIQA|5fI6T54OPK1Gn1p4w0RtHv6EkojWRTwq|a946d998-2ead-4894-bb50-1054a91dcab3' --data '<tsRequest>
<permissions>
<granteeCapabilities>
<user id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" />
<capabilities>
<capability name="read" mode="allow" />
</capabilities>
</granteeCapabilities>
</permissions>
</tsRequest>'
Add Workbook Permissions
Adds permissions to the specified workbook for a user or group. You can specify multiple sets of permissions using one call.
URI
PUT /api/api-version/sites/site-id/workbooks/workbook-id/permissions
Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions. |
| site-id | The ID of the site that contains the workbook. |
| workbook-id | The ID of the workbook to set permissions for. |
Request Body
<tsRequest>
<permissions>
<workbook id="workbook-id" />
<granteeCapabilities>
<user id="user-id" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
... additional capabilities ...
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<group id="group-id" />
<capabilities>
<capability name="capability-name" mode="capability-mode" />
... additional capabilities ...
</capabilities>
</granteeCapabilities>
... additional grantee capability sets ...
</permissions>
</tsRequest>
Attribute Values
| workbook-id | The <workbook> element is not required, but can be included for compatibility with earlier versions of the REST API. If the <workbook> element is included, the workbook-id value must match the workbook ID in the URI. Any other attributes in the <workbook> element are ignored. |
| user-id | The ID (not name) of the user to add permissions for. |
| group-id | The ID (not name) of the group to add permissions for. |
| capability-name |
The capability to assign. If any capability has already been granted or denied for a specified user or group, that capability is ignored. Valid capabilities for a workbook are AddComment, ChangeHierarchy, ChangePermissions, CreateRefreshMetrics, Delete, ExportData, ExportImage, ExportXml, Filter, Read (view), RunExplainData, ShareView, ViewComments, ViewUnderlyingData, WebAuthoring, and Write. For more information, see Permissions. |
| capability-mode | Allow to allow the capability, or Deny to deny it. This value is case sensitive. |
Permissions
Users who are not server administrators or site administrators can call this method only if the have permission to set permissions on the workbook (either explicitly or implicitly).
Required scope for JWT authorization
Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).
Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:permissions:updateResponse Code
200
Response Body
<tsResponse>
<permissions>
<workbook id="workbook-id" />
<granteeCapabilities>
<user id="user-id" />
<capabilities>
<capability name="capability" mode="Allow-or-Deny" />
<capability name="capability" mode="Allow-or-Deny" />
... additional capabilities ...
</capabilities>
</granteeCapabilities>
<granteeCapabilities>
<group id="group-id" />
<capabilities>
<capability name="capability" mode="Allow-or-Deny" />
<capability name="capability" mode="Allow-or-Deny" />
... additional capabilities ...
</capabilities>
</granteeCapabilities>
... additional grantee capability sets ...
</permissions>
</tsResponse>
Version
Version 2.0 and later. For more information, see REST API and Resource Versions.
Errors
| HTTP status | error Code |
Condition | Details |
|---|---|---|---|
| 400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
| 400 | 400009 | Invalid capability | The capability in the URI is invalid for a workbook resource. Valid capabilities for a workbook are AddComment, ChangeHierarchy, ChangePermissions, CreateRefreshMetrics, Delete, ExportData, ExportImage, ExportXml, Filter, Read (view), RunExplainData, ShareView, ViewComments, ViewUnderlyingData, WebAuthoring, and Write. |
| 403 | 403004 | Permissions setting forbidden | A non-administrator user called this method but doesn't have permission to set permissions on the workbook. |
| 404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
| 404 | 404002 | User not found | A user ID in the request body doesn't correspond to an existing user. |
| 404 | 404006 | Workbook not found | The workbook ID in the URI doesn't correspond to an existing workbook. |
| 404 | 404012 | Group not found | A group ID in the request body doesn't correspond to an existing group. |
| 404 | 404013 | Capability not found | The specified capability doesn't correspond to a defined capability. This can apply to either an invalid capability name or a capability other than Allow or Deny for any mode value. |
For more information, see Handling Errors.
Add Workbook to Favorites
Adds the specified workbook to a user's favorites.
If the user already has the workbook listed as a favorite with the same label, the operation has no effect. If the label differs, the original favorite is overwritten.
URI
PUT /api/api-version/sites/site-id/favorites/user-id
Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions. |
| site-id | The ID of the site that contains the workbook. |
| user-id | The ID of the user to add the favorite for. |
Request Body
<tsRequest>
<favorite label="favorite-label">
<workbook id="workbook-id" />
</favorite>
</tsRequest>
Attribute Values
| favorite-label | A label to assign to the favorite. This value is displayed when you search for favorites on the server. If the label is already in use for another workbook, an error is returned. |
| workbook-id | The ID (not name) of the workbook to add as a favorite. |
Permissions
Tableau Server users who are not administrators or site administrators can call this method only if they have permission to add a workbook to a favorites list.
Response Code
200
Response Body
<tsResponse>
<favorites>
<favorite label="favorite-label">
<workbook id="workbook-id" />
</favorite>
<favorite label="favorite">
<view id="view-id" />
</favorite>
... additional favorites ...
</favorites>
</tsResponse>
Version
Version 1.0 and later. For more information, see REST API and Resource Versions.
Errors
| HTTP status | error Code |
Condition | Details |
|---|---|---|---|
| 400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
| 400 | 400005 | Invalid label |
The favorite label is empty or consists of only white space characters. |
| 403 | 403004 | Access to Favorites forbidden |
A non-administrator user called this method but doesn't have permission to add a workbook to the specified user's favorites. This will always be the case when the user references in the URI identifies a user other than the user who is calling the method. |
| 404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
| 404 | 404002 | User not found | The user ID in the URI doesn't correspond to an existing user. |
| 404 | 404006 | Workbook not found | The workbook ID in the request body doesn't correspond to an existing workbook. |
| 405 | 405000 | Invalid request method | Request type was not PUT. |
| 409 | 409007 | Label conflict | There is already a favorite with the same label for a different workbook in the specified user's favorites. |
For more information, see Handling Errors.
Add Workbook to Server Schedule
Adds a task to refresh or accelerate a workbook to an existing schedule on Tableau Server.
The task type must match the schedule type. For a list of schedule types, see Create a Schedule.
For Tableau Cloud, see Create Cloud Extract Refresh Task.
This method is not available for Tableau Cloud.
Starting in Tableau version 2022.1 (API v3.16), with the introduction of
View Acceleration(Link opens in a new window),
the data acceleration feature is deprecated. Requests for data acceleration endpoints and attributes will not return an error, but will
also not cause any change on the server or return meaningful information about data acceleration of a workbook. We recommend removing
any dependencies on data acceleration in your requests to REST API endpoints, as the feature may become unsupported in future releases
resulting in error codes being returned.
URI
PUT /api/api-version/sites/site-id/schedules/schedule-id/workbooks
Parameter Values
| api-version | The version of the API to use, such as 3.24.
For more information, see REST API and Resource Versions. |
| site-id | The ID of the site that contains the view. |
| schedule-id | The ID of the schedule that you are associating with the workbook. |
Request Body
<tsRequest>
<task>
<extractRefresh>
<workbook id="workbook-id" />
</extractRefresh>
</task>
<task>
<dataAcceleration>
<workbook id="workbook-id" />
</dataAcceleration>
</task>
</tsRequest>Attribute Values
| workbook-id | The ID of the workbook to add to the schedule. |
Permissions
Only Tableau Server users who are server administrators or site administrators can add a workbook to a data acceleration schedule. Tableau Server users who are not server administrators or site administrators can only add a workbook to other types of schedules if they own the workbook, or are the project leader for the project that contains the workbook.
Response Code
200
Response Body
<tsResponse>
<task>
<extractRefresh id="extractRefresh-id" type="extractRefresh-type">
<schedule id="schedule-id" />
<workbook id="workbook-id" />
</extractRefresh>
</task>
</tsResponse>
Version
Starting in Tableau Server 10.5 (API 2.8) you can add a task to refresh a workbook extract. In Tableau Server 2020.2 (API 3.8)
through 2021.4 (API 3.15), you can add a task to add data acceleration to a workbook.
Starting in Tableau version 2022.1 (API v3.16), with the introduction of
View Acceleration(Link opens in a new window),
the data acceleration feature is deprecated. Requests for data acceleration endpoints and attributes will not return an error, but will
also not cause any change on the server or return meaningful information about data acceleration of a workbook. We recommend removing
any dependencies on data acceleration in your requests to REST API endpoints, as the feature may become unsupported in future releases
resulting in error codes being returned.
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 | 401002 | Unauthorized Access | The authentication token provided in the request header was invalid or has expired. |
| 403 | 403032 | Update Forbidden | A non-administrator user called this method, but the caller doesn't have sufficient permissions. |
| 404 | 404000 | Site not found | The site ID in the URI is unknown. |
| 404 | 404006 | Resource not found | The workbook ID in the request body is unknown. |
| 405 | 405000 | Invalid request method | Request type was not PUT. |
| 500 | 500000 | Internal Server Error | The schedule ID in the URI is unknown. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/
1edc53ac-e247-4870-9fd3-6fad0ce5f84d/schedules/9a4ebbab-9ec8-487a-9b48-47fa81d6077a/workbooks" -X PUT
-H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" –d @add-to-schedule.xml"
Content of add-to-schedule.xml:
<tsRequest>
<task>
<extractRefresh>
<workbook id="5de9cc53-b17d-45af-804d-49144b39f29f" />
</extractRefresh>
</task>
</tsRequest>Example response:
<tsResponse>
<task>
<extractRefresh id="9bf8aea0-e3ca-422e-b7ef-d9c4ba6cca45" priority="50" consecutiveFailedCount="0" type="RefreshExtractTask">
<schedule id="9a4ebbab-9ec8-487a-9b48-47fa81d6077a" name="Weekday early mornings" state="Active" />
<workbook id="5de9cc53-b17d-45af-804d-49144b39f29f" />
</extractRefresh>
</task>
</tsResponse>Allow dashboard extension on site - Retired in API 3.21
Retired in API 3.21 (Cloud October 2023 / Server 2023.3)
In October 2023 Tableau Cloud and Tableau Server version 2023.3 releases, Tableau's REST API methods for dashboard extensions settings are retired. We recommend you replace dashboard extensions methods for enabling, listing, getting details of, and updating dashboard extensions with Tableau extensions settings methods that have similar functionality.
Adds a dashboard extension to the safe list of the site you are signed into.
Version: Available in API 3.11 (Tableau Cloud March 2021 / Server 2021.1) and later. Version Overview
Permissions: This method can only be called by users with server or site administrator permissions. Permissions Overview
License: No additional license required.
Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux
POST {server}/api/-/settings/site/extensions/dashboard/safeListItems
Append to File Upload
Uploads a block of data and appends it to the data that is already uploaded. This method is called after an upload has been initiated using Initiate File Upload.
You call Append to File Upload as many times as needed in order to upload the complete contents of a file. When the final block of data has been uploaded, you call Publish Data Source, Publish Flow, or Publish Workbook to commit the file.
For more information, see Publishing Resources.
URI
PUT /api/api-version/sites/site-id/fileUploads/upload-session-id
Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions. |
| site-id | The ID of the site to upload the file to. |
| upload-session-id | The ID of the upload session. You get this value when you start an upload session using Initiate File Upload. |
Request Body
The content of the file to be uploaded is included in a MIME multipart message. For more information, see Publishing Resources.
Permissions
Users who are not server administrators or site administrators can call this method only if they have publishing rights on the site.
Required scope for JWT authorization
Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).
Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:file_uploads:createResponse Code
200
Response Body
<tsResponse>
<fileUpload uploadSessionId=upload-session-id
fileSize=size-of-file-in-megabytes-after-append />
</tsResponse>
Version
Version 2.0 and later. For more information, see REST API and Resource Versions.
Errors
| HTTP status | error Code |
Condition | Details |
|---|---|---|---|
| 400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
| 400 | 400016 | File size too large | The attached file exceeds the configured maximum attachment size for a single append call. The maximum allowable size will be reported in the error response. |
| 400 | 400019 | Malformed request body | The XML content in the MIME multipart request is not empty. |
| 400 | 400020 | Missing file data | There is no attachment in the request with the file data to be appended to the upload. |
| 403 | 403007 | Not a publisher | A non-administrator user attempted to initiate a file upload, but the caller doesn't have publishing rights on the site. |
| 403 | 403016 | Upload failure | The file could not be uploaded for some other reason than those specified earlier. |
| 404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
| 404 | 404015 | File upload not found | The file upload ID in the URI doesn't correspond to an existing file upload. |
| 405 | 405000 | Invalid request method | Request type was not PUT. |
For more information, see Handling Errors.
Batch Add or Update Data Quality Certifications
Create or update one or more data quality certifications for different content and asset items.
Note: Data quality warnings and certifications can be more generally managed through the newer Labels methods. Tableau recommends using them to help ensure that you can manage your assets as new features are developed.
Try the Update Labels method instead.
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.24. 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-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. For more information about data quality certifications, see "Set a Data Quality Certification" in the Server Help or Cloud Help. |
| 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. |
Batch Add or Update Data Quality Warnings
Add or update multiple data quality warnings on assets.
Note: Data quality warnings and certifications can be more generally managed through the newer Labels methods. Tableau recommends using them to help ensure that you can manage your assets as new features are developed.
Try the Update Labels method instead.
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.24. 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-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:
|
| 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 Cloud 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 the "Visibility" section of the "Set a Data Quality Warning" topic in the Server Help or Cloud 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 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.24. 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. |
Batch create subscriptions
Creates multiple subscriptions to a metric for specified users and/or groups.
Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Versioning Overview Version Overview
Permissions: Any user that has read or connect permission to the data source used in the definition can create subscriptions. Permissions Overview
License: No additional license required.
Access Scope: tableau:metric_subscriptions:create
Access Scopes Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux
POST {server}/api/-/pulse/subscriptions:batchCreate
Batch Delete Data Quality Warnings
Delete multiple data quality warnings from assets.
Note: Data quality warnings and certifications can be more generally managed through the newer Labels methods. Tableau recommends using them to help ensure that you can manage your assets as new features are developed.
Try the Delete Labels method 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-id/dataQualityWarnings/batchDelete
Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions. |
| site-id | The 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-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. |
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.24. 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. |
Batch get subscriber counts
Gets the number of unique users subscribed to a set of metrics specified in a comma separated list of metric LUIDs.
Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Versioning Overview Version Overview
Permissions: Any user that has read or connect permission to the data source used in the definition can create subscriptions. Permissions Overview
License: No additional license required.
Access Scope: tableau:metric_subscriptions:read
Access Scopes Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux
GET {server}/api/-/pulse/subscriptions:batchGetMetricFollowerCounts
Batch get subscriptions
Gets a batch of subscriptions, specified in a comma delimited list of subscriptions LUIDs.
Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Versioning Overview Version Overview
Permissions: Any user that has read or connect permission to the data source used in the definition can get the details of subscriptions. Permissions Overview
License: No additional license required.
Access Scope: tableau:metric_subscriptions:read
Access Scopes Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux
GET {server}/api/-/pulse/subscriptions:batchGet
Batch list metric definitions
Gets a batch of metric definitions and metrics available on a site.
Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Versioning Overview Version Overview
Permissions: Can be called by any user, but only returns definitions and metrics that the user has permissions to view. Permissions Overview
License: No additional license required.
Access Scope: tableau:insight_definitions_metrics:read
Access Scopes Overview: Cloud Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux
GET {server}/api/-/pulse/definitions:batchGet
Batch list metrics
Gets a batch of metrics from a definition, specified in a comma delimited list.
Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Versioning Overview Version Overview
Permissions: Any user can get a batch of metrics as long as the user has read or connect access to the data source used in the definition that contains them. Permissions Overview
License: No additional license required.
Access Scope: tableau:insight_metrics:read
Access Scopes Overview: Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux
GET {server}/api/-/pulse/metrics:batchGet
Block dashboard extension on server - Retired in API 3.21
Retired in API 3.21 (Cloud October 2023 / Server 2023.3)
In October 2023 Tableau Cloud and Tableau Server version 2023.3 releases, Tableau's REST API methods for dashboard extensions settings are retired. We recommend you replace dashboard extensions methods for enabling, listing, getting details of, and updating dashboard extensions with Tableau extensions settings methods that have similar functionality.
Adds a dashboard extension to the block list of a server.
Version: Available in API 3.11 ( Tableau Server 2021.1) and later. Not available for Tableau Cloud. Version Overview
Permissions: This method can only be called by users with server administrator permissions. Permissions Overview
License: No additional license required.
Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux
POST {server}/api/-/settings/server/extensions/dashboard/blockListItems
Cancel Flow Run
Cancels a flow run that is in progress.
URI
PUT /api/api-version/sites/site-id/flows/runs/flow-run-id
Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions. |
| site-id | The ID of the site that contains the flow. |
| flow-run-id | The ID of the flow run. |
Request Body
None
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 |
|---|---|---|---|
| 403 | 403135 | Flow run already complete | The flow run is already complete so it could not be canceled. |
| 403 | 403137 | User does not have permissions to cancel flow run | In addition to server administrators and site administrators, users can cancel a flow run if they initiated the flow run or created the flow run scheduled task and have "Run Flow Now" permissions for the flow. |
| 404 | 404000 | Site not found | The site ID or URL namespace in the URI doesn't correspond to an existing site. |
| 404 | 404036 | Flow run not found | The flow run ID in the URI doesn't correspond to an existing flow run. |
| 405 | 405000 | Invalid request method | Request type was not PUT. |
For more information, see Handling Errors.
Cancel Job
Cancels a job specified by job ID. To get a list of job IDs for jobs that are currently queued or in-progress, use the Query Jobs method.
The following jobs can be canceled using the Cancel Job method:
- Full extract refresh
- Incremental extract refresh
- Subscription
- Flow Run
- Data Acceleration (Data acceleration is not available in Tableau Server 2022.1 (API 3.16) and later. See View Acceleration(Link opens in a new window).)
- Bridge full extract refresh
- Bridge incremental extract refresh
- Queue upgrade Thumbnail (Job that puts the upgrade thumbnail job on the queue)
- Upgrade Thumbnail
URI
PUT /api/api-version/sites/site-id/jobs/job-id
Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions. |
| site-id | The ID of the site where the job is running. |
| job-id | The ID of the job to cancel. |
Request Body
None
Permissions
This method can only be called by server administrators and site administrators.
Response Code
200
Response Body
None
Version
Version 3.1 and later. For more information, see REST API and Resource Versions.
Errors
| HTTP status | error Code |
Condition | Details |
|---|---|---|---|
| 403 | 403032 | Update forbidden | A non-administrator user tried to cancel a job. |
| 403 | 403091 | Can not cancel job, because it's already complete. | The job ID provided is for a job that has already succeeded or failed. |
| 404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
| 404 | 405000 | Invalid request method | Request type was not PUT. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/1edc53ac-e247-4870-9fd3-6fad0ce5f84d/jobs/2474164d-8d37-4a4c-abc7-c2070fd25fd5" -X PUT -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Configure Identity Store
Configure a new local identity store to provision users.
Version: Available in API 3.19 (Tableau Server 2023.1) and later. Not available for Tableau Cloud. Version Overview
Permissions: This method can only be called by users with server administrator permissions. Permissions Overview
License: No additional license required.
Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux
POST {server}/api/-/authn-service/identity-stores
Create a Webhook
Creates a new webhook for a site.
URI
POST /api/3.6/sites/<site-id>/webhooks
Parameter Values
| site-id | The ID of the site in which you want to create the webhook. |
Request Body
<tsRequest>
<webhook
name="webhook-name"
isEnabled="webhook-enabled-flag"
event="api-event-name">
<webhook-source>
<webhook-source-api-event-name />
</webhook-source>
<webhook-destination>
<webhook-destination-http method="POST" url="url"/>
</webhook-destination>
</webhook>
</tsRequest>
Attribute Values
| webhook-name | This is required. A name for the webhook. |
| api-event-name | webhook-source-api-event-name |
You must specify one of these attribute values. The name of the Tableau event that triggers your webhook. The event name must be one of the supported events listed in the Trigger Events table. The event and webhook-source use different name values for the same event. Recommended: Use the event attribute of the webhook to specify the triggering API event for the webhook. The webhook-source element serves the same purpose but is being deprecated in future versions of Tableau webhooks. If both events and webhook-source are specified, their events specified must match. If either are specified, with the other being NULL, then the specified event becomes the webhook trigger, whether the element containing the event name is event or webhook-source. |
| url | Required. The destination URL for the webhook. The webhook destination URL must be https and have a valid certificate. |
| webhook-enabled-flag | (Optional) Boolean. If true (default), the newly created webhook is enabled. If false then the webhook will be disabled. |
Permissions
This method can only be called by server and site administrators.
Response Code
201
Response Body
<tsResponse>
<webhook
id="webhook-id"
name="webhook-name"
isEnabled="true-or-false"
statusChangeReason="status-change-reason"
event="api-event-name">
<webhook-source>
<webhook-source-api-event-name />
</webhook-source>
<webhook-destination>
<webhook-destination-http method="POST" url="url"/>
</webhook-destination>
<owner id="webhook_owner_luid" name="webhook_owner_name"/>
</webhook>
</tsResponse>
Response Headers
Location: /api/3.24/sites/site-id/webhooks/<new-webhook-id>
Create an Extract for a Data Source
Create an extract for a data source in a site. Optionally, encrypt the extract if the site and workbooks using it are configured to allow it.
URI
POST /api/api-version/sites/site-id/datasources/datasource-id/createExtract
POST /api/api-version/sites/site-id/datasources/datasource-id/createExtract?encrypt=encryption-flag
Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions. |
| site-id | The LUID of the site. |
| datasource-id | The LUID of the datasource. |
| encryption-flag | If true, then Tableau will attempt to encrypt the created extracts.
If false, or no encrypt parameter is appended to the URI, then the extract won't
be encrypted, unless encryption is enforced by site or workbook configuration. An error will be returned when
encrypt equals true and encryption is disabled in the site or workbook.
|
Request Body
None
Permissions
Extracts for data sources can be created by Tableau server or site administrators, and by users who own the data source or are an owner or leader of the project where the data source resides.
Response Code
200
Response Body
<tsResponse>
<job id="job-id" mode="Asynchronous" type="CreateExtract" createdAt="date-time">
<extractCreationJob>
<datasource id="datasource-id" name="datasource-name" />
</extractCreationJob>
</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. |
| 404 | 404000 | Site not found | The specified site doesn't correspond to an existing site. |
| 405 | 405000 | Invalid request method | Request type was not POST. |
| 409 | 409070 | Invalid request method | The data source cannot be extracted because it is file based or in another unsupported form. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/abcd7c6d-5e4f-3a2b-1c0d-9e8f7a6b1234/createExtract" -X POST -H "X-Tableau-Auth: oIcGYxkXSBCLLVm91mfITg|jCQSkWoIbUQVwTcH8WUTWD5nCoOf53LE"
Response body:
<tsResponse>
<job id="df410925-feae-481d-bf84-2f37bdf7ce69" mode="Asynchronous" type="CreateExtract" createdAt="2019-11-05T00:06:57Z">
<extractCreationJob>
<datasource id="e35ec79d-9526-44f1-9a67-7a8b63d265df" name="MY_DATASOURCE_NAME"/>
<jobLuid>df410925-feae-481d-bf84-2f37bdf7ce69</jobLuid>
</extractCreationJob>
</job>
</tsResponse> Create ask data lens - Retired in API 3.22
Retired in API 3.22 (Cloud February 2024 / Server 2024.2)
In February 2024, Tableau's Ask Data and Metrics features and their REST API methods will be retired in Tableau Cloud and Tableau Server version 2024.1. With advances in natural language technologies, we're developing an improved interface that will make it easier to ask questions of your data and stay on top of changes. For more information, see How Tableau GPT and Tableau Pulse are reimagining the data experience.
Create an ask data lens.
Version: Available in API 3.16 ( Tableau Cloud June 2022 / Server 2022.3) and later. Version Overview
Permissions: This method can be called by users who have Create permissions for lenses on the site. Permissions Overview
License: No additional license required.
Access Scope: 'tableau:lenses:create' Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux
POST {server}/api/-/askdata/lenses
Create Authentication Configuration
Create an instance of OpenID Connect (OIDC) authentication.
Version: Available in API 3.19 (Tableau Server 2023.1) and later. Not available for Tableau Cloud. Version Overview
Permissions: This method can only be called by users with server administrator permissions. Permissions Overview
License: No additional license required.
Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux
POST {server}/api/-/authn-service/auth-configurations
Create Cloud Extract Refresh Task
Creates a custom schedule for an extract refresh on Tableau Cloud.
For Tableau Server, see Add data source to server schedule and
Add workbook to server schedule.
Version: Available in API 3.20 (Tableau Cloud June 2023) and later. Not available for Tableau Server. Version Overview(Link opens in a new window)
License: No additional license required.
Permissions: Administrators and any user with the creator role can create a custom schedule for an extract refresh. Permissions Overview(Link opens in a new window)
JWT Access Scope:
tableau:tasks:create (this scope is included in the scope: tableau:tasks)
Access Scopes Overview:
Cloud(Link opens in a new window)
URI
POST /api/api-version/sites/site-luid/tasks/extractRefreshes
URI Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
|
| site-luid | The LUID for the site. |
Request Body
<tsRequest>
<extractRefresh type="FullRefresh">
<workbook id="54321fd-6365-44d5-925b-644e5281b605" />
</extractRefresh>
<schedule frequency="Daily">
<frequencyDetails start="18:30:00" end="23:30:00">
<intervals>
<interval hours="4"/>
<interval weekDay="Sunday"/>
<interval weekDay="Wednesday"/>
</intervals>
</frequencyDetails>
</schedule>
</tsRequest>
{
"extractRefresh": {
"type": "FullRefresh",
"workbook": {
"id": "54321fd-6365-44d5-925b-644e5281b605"
}
},
"schedule": {
"frequency": "Daily",
"frequencyDetails": {
"start": "18:30:00",
"end": "23:30:00",
"intervals": {
"interval": [
{ "hours": "4" },
{ "weekDay": "Sunday" },
{ "weekDay": "Wednesday" }
]
}
}
}
Request Attributes
All request attributes are required to create a custom schedule for an extract refresh.
extractRefresh type
|
enumeration: The type of extract refresh being scheduled. Valid values include:
|
workbook id or datasource id |
LUID: The LUID of the workbook or datasource that is the target of the custom schedule. |
schedule frequency
|
(Required to create subscription) enumeration: The scheduled frequency for triggering the task. Valid values include:
|
||||||||||
frequencyDetails start
|
(Required to create subscription) time: If the schedule frequency is Daily, Weekly, or Monthly, then start
is the time of day on which scheduled jobs should run. If the frequency is Hourly, then start is the beginning of the
time range during which jobs should be started. The valid format is HH:MM:SS.
|
||||||||||
frequencyDetails end
|
(Required to create subscription) time: If the schedule frequency is |
||||||||||
interval {interval type}
|
(Required to create subscription) string: Defines when and how often a scheduled job executes within the time parameters set in the start and end
values of the frequencyDetails of the schedule. The type and valid values for
an interval expression depend on the declared frequency of the schedule as follows:
|
cURL Request Example
curl --location --request POST "qa-near.tsi.lan/api/3.24/sites/a946d998-2ead-4894-bb50-1054a91dcab3/tasks/extractRefreshes" --header "Content-Type: application/xml" --data "<tsRequest> <extractRefresh type='FullRefresh'> <workbook id='0057ccac-872a-11e5-bb51-f763326b1350' /> </extractRefresh> <schedule frequency='Daily'> <frequencyDetails start='18:30:00' end='23:00:00'> <intervals> <interval hours='4'/> </intervals> <intervals> <interval weekDay='Sunday'/> </intervals> <intervals> <interval weekDay='Wednesday'/> </intervals> </frequencyDetails> </schedule> </tsRequest>"
Response Code
200
Response Body
<tsResponse>
<extractRefresh
id="13237fd-6365-44d5-925b-644e5281b605"
consecutiveFailedCount="0"
type="IncrementalRefresh" >
<datasource id="0057ccac-872a-11e5-bb51-f763326b1350" />
</extractRefresh>
<schedule id="cdfe8548-84c8-418e-9b33-2c0728b2398a"
createdAt="2023-04-06T23:43:12-0700"
updatedAt="2023-04-06T23:43:12-0700"
frequency="Daily"
nextRunAt="2023-04-06T23:43:12-0700">
<frequencyDetails start="18:30:00" end="23:30:00">
<intervals>
<interval hours="4"/>
<interval weekDay="Sunday"/>
<interval weekDay="Wednesday"/>
</intervals>
</frequencyDetails>
</schedule>
</tsResponse>{
"extractRefresh": {
"id": "13237fd-6365-44d5-925b-644e5281b605",
"consecutiveFailedCount": "0",
"type": "IncrementalRefresh",
"datasource": {
"id": "0057ccac-872a-11e5-bb51-f763326b1350"
}
},
"schedule": {
"id": "cdfe8548-84c8-418e-9b33-2c0728b2398a",
"createdAt": "2023-04-06T23:43:12-0700",
"updatedAt": "2023-04-06T23:43:12-0700",
"frequency": "Daily",
"nextRunAt": "2023-04-06T23:43:12-0700",
"frequencyDetails": {
"start": "18:30:00",
"end": "23:30:00",
"intervals": {
"interval": [
{ "hours": "4" },
{ "weekDay": "Sunday" },
{ "weekDay": "Wednesday" }
]
}
}
}
}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 | 401002 | Unauthorized Access | The authentication token provided in the request header was invalid or has expired. |
| 404 | 404026 | Task not found | The task for the extract refresh could not be found. |
| 409 | 409004 | invalid parameter value |
The request is malformed or contains an invalid or missing schedule or interval parameter value.
When the difference between start and end times are not increments of one hour,
this error will result.
|
For more information, see Handling Errors.
Create Cloud Flow Task
Creates a flow task on Tableau Cloud, and set its schedule.
Note: This method is unavailable if you do not have a Data Management license or Tableau Prep Conductor is disabled for your site.
Version: Available in API 3.22 (Tableau Cloud April 2024) and later. Not available for Tableau Server. Version Overview(Link opens in a new window)
License: Requires Tableau Data Management(Link opens in a new window).
Permissions: A user can create a cloud flow task if you are a site or server administrator, or they own the flow, or are the project leader for the project that contains the workbook. Permissions Overview(Link opens in a new window)
JWT Access Scope: Not available. Access Scopes Overview: Cloud(Link opens in a new window)
URI
POST /api/api-version/sites/site-luid/tasks/flows
URI Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
|
| site-luid | The LUID for the site. |
Request Body
<tsRequest>
<task>
<flowRun>
<flow id="dd3cd2e7-2ede-49c6-945f-e7b2a2f25541"/>
</flowRun>
</task>
<schedule frequency="Daily">
<frequencyDetails start="12:30:00" end="23:30:00">
<intervals>
<interval hours="4"/>
<interval weekDay="Monday"/>
<interval weekDay="Wednesday"/>
</intervals>
</frequencyDetails>
</schedule>
</tsRequest>
{
"task": {
"flowRun": {
"flow": {
"id": "dd3cd2e7-2ede-49c6-945f-e7b2a2f25541"
}
}
},
"schedule": {
"frequency": "Daily",
"frequencyDetails": {
"start": "12:30:00",
"end": "23:30:00",
"intervals": [
{
"hours": "4"
},
{
"weekDay": "Monday"
},
{
"weekDay": "Wednesday"
}
]
}
}
}Request Attributes
flow.id
|
(Required)The LUID of the flow the task is being scheduled for. |
schedule frequency
|
(Required to create subscription) enumeration: The scheduled frequency for triggering the task. Valid values include:
|
||||||||||
frequencyDetails start
|
(Required to create subscription) time: If the schedule frequency is Daily, Weekly, or Monthly, then start
is the time of day on which scheduled jobs should run. If the frequency is Hourly, then start is the beginning of the
time range during which jobs should be started. The valid format is HH:MM:SS.
|
||||||||||
frequencyDetails end
|
(Required to create subscription) time: If the schedule frequency is |
||||||||||
interval {interval type}
|
(Required to create subscription) string: Defines when and how often a scheduled job executes within the time parameters set in the start and end
values of the frequencyDetails of the schedule. The type and valid values for
an interval expression depend on the declared frequency of the schedule as follows:
|
cURL Request Example
curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/connections" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Response Code
200
Response Body
<tsResponse>
<task>
<flowRun id="4d49655a-0f3a-45cc-ba61-b108a763e83a"
priority="50"
consecutiveFailedCount="0"
type="RunFlowTask">
<schedule id="1060dcb7-fef7-4fb1-8d3b-d0f042932d1a"
name="SSS_e95a9d25-c616-4542-87b6-3725975bdfbd"
state="Active"
priority="50"
createdAt="2024-04-09T18:54:12Z"
updatedAt="2024-04-09T18:54:12Z"
type="Flow"
frequency="Daily"
nextRunAt="2024-04-10T19:30:00Z"/>
<flow id="dd3cd2e7-2ede-49c6-945f-e7b2a2f25541"
name="olympic 1">
<parameters>
<parameter id="4f22c514-5b56-4400-a48a-f69d9be217a9"
type="integer"
name="output_count"
description="This is a parameter of a flow."
value="2"
isRequired="true">
<domain xsi:type="flowParameterAnyDomainType"
domainType="all"/>
</parameter>
</parameters>
</flow>
<flowRunSpec flowId="dd3cd2e7-2ede-49c6-945f-e7b2a2f25541">
<flowOutputSteps>
<flowOutputStep id="485c8b5f-5647-466c-b549-e38410b7c7c8"
name="Output"/>
</flowOutputSteps>
<flowParameterSpecs/>
</flowRunSpec>
</flowRun>
</task>
</tsResponse>{
"task": {
"flowRun": {
"id": "4d49655a-0f3a-45cc-ba61-b108a763e83a",
"priority": "50",
"consecutiveFailedCount": "0",
"type": "RunFlowTask",
"schedule": {
"id": "1060dcb7-fef7-4fb1-8d3b-d0f042932d1a",
"name": "SSS_e95a9d25-c616-4542-87b6-3725975bdfbd",
"state": "Active",
"priority": "50",
"createdAt": "2024-04-09T18:54:12Z",
"updatedAt": "2024-04-09T18:54:12Z",
"type": "Flow",
"frequency": "Daily",
"nextRunAt": "2024-04-10T19:30:00Z"
},
"flow": {
"id": "dd3cd2e7-2ede-49c6-945f-e7b2a2f25541",
"name": "olympic 1",
"parameters": {
"parameter": {
"id": "4f22c514-5b56-4400-a48a-f69d9be217a9",
"type": "integer",
"name": "output_count",
"description": "This is a parameter of a flow.",
"value": "2",
"isRequired": "true",
"domain": {
"xsi_type": "flowParameterAnyDomainType",
"domainType": "all"
}
}
}
},
"flowRunSpec": {
"flowId": "dd3cd2e7-2ede-49c6-945f-e7b2a2f25541",
"flowOutputSteps": {
"flowOutputStep": {
"id": "485c8b5f-5647-466c-b549-e38410b7c7c8",
"name": "Output"
}
},
"flowParameterSpecs": []
}
}
}
}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 | 401002 | Unauthorized Access | The authentication token provided in the request header was invalid or has expired. |
For more information, see Handling Errors.
Create Connected App
Create a connected app.
A connected app can be used to securely authenticate your users to Tableau content embedded in a custom application or for REST API authorization (introduced to Tableau Cloud in June 2022 and Tableau Server 2023). By creating a connected app, you can establish a trusted relationship between Tableau and any custom application.
For more information about connected apps, see one of the following:
- For Tableau Server: Configure Tableau Connected Apps to Enable SSO for Embedded Content
- For Tableau Cloud: Configure Tableau Connected Apps with Direct Trust(Link opens in a new window)
URI
POST api/api-version/sites/site-id/connected-apps/direct-trust
Note: The connected-applications endpoint that performed this function was deprecated in API 3.17 (Tableau Cloud October 2022 / Tableau Server 2022.3), is no longer supported and may be retired in a future release.
Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions. |
| site-id | The unique ID of the site asset. |
Request Body
Tableau Cloud and Tableau Server using API 3.23 or later
<tsRequest>
<connectedApplication
name="name"
enabled="enabled"
domainSafelist="domainSafelist"
unrestrictedEmbedding="unrestrictedEmbedding">
<projectIds>
<projectId>project_id</projectId>
<projectId>project_id</projectId>
<projectId>project_id</projectId>
</projectIds>
<connectedApplication />
</tsRequest>Tableau Server (or Tableau Cloud) using API 3.21 or earlier
<tsRequest>
<connectedApplication
name="name"
enabled="enabled"
projectId="project_id"
domainSafelist="domainSafelist"
unrestrictedEmbedding="unrestrictedEmbedding" />
</tsRequest>Attribute Values
Any combination of attributes inside the <connectedApplication> element is valid, however name is required.
| name | Name of the connected app. |
| enabled | (Optional) Controls whether the connected app is enabled or not. Value can be "true" or "false". If the state is not specified, the connected app is set to "false" and not enabled by default. |
| project_id |
(Optional, embedding workflows only) The IDs of the projects that the connected app's access level is scoped to. To get a project's project ID, see Query Projects. You can specify one project, multiple projects, all projects on a site.
Note: The stand-alone projectId attribute will be retired in a future release so we recommend using projectIds attribute instead. |
| domainSafelist |
(Optional, embedding workflows only) A list of domains the connected app is allowed to be hosted. Specify one or more URLs, separated by spaces, using a format described in Domain allowlist rules(Link opens in a new window) in the Tableau Server Help or Domain allowlist rules(Link opens in a new window) in the Tableau Cloud Help. Important: We recommend using the domain allowlist as a security best practice to ensure Tableau content is only embedded in locations that you allow. For example: |
| unrestrictedEmbedding | (Optional, embedding workflows only) Controls whether the connected app can be hosted on all domains. If "true" value is specified, the connected app can be hosted on all domains. If "false" value is specified, the connected app can only be hosted on the domains specified in the <domainSafelist> attribute. |
Permissions
Tableau Server admins or Tableau Cloud site admins only.
Response Code
201
Response Body
Example response:
<tsResponse>
<connectedApplication>
<name>ConnectedApp_MyCo</name>
<enabled>true</enabled>
<clientId>ac95d175-c844-4779-9d58-415e01fe7dab</clientId>
<projectIds>
<projectId>1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e</projectId>
<projectId>1234de4e-5d6d-7c8c-9b0b-1a2a3f4f5e0e</projectId>
</projectIds>
<createdAt>2021-08-10T18:46:30Z</createdAt>
<unrestrictedEmbedding>true</unrestrictedEmbedding>
</connectedApplication>
</tsResponse>Note: When the scope of the connected app's access is set to all projects, the request does not return the projectId attribute.
Version
Version 3.14 and later. For more information, see REST API and Resource Versions.
The resource, POST /api/api-version/sites/site-id/connected-apps/direct-trust, was added in version 3.17. The original resource, POST /api/api-version/sites/site-id/connected-applications, was deprecated in API 3.17 and will be retired in a future release.
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. |
| 400 | 400143 | Generic connected app error | The connected app could not be deleted for some other reason than those specified in this table. |
| 403 | 403000 | Admin permissions required | A non-admin user called this method and doesn't have adequate permissions to perform the action. |
| 404 | 404000 | Resource not found | The site ID in the URI doesn't correspond to an existing site. |
| 404 | 404041 | Connected app not found | The requested connected app could not be found. |
Create Connected App Secret
Generate a secret for a connected app.
Secrets are tokens shared by Tableau and a custom application, and used to establish a trusted relationship.
A maximum of two secrets can be associated with a connected app. These secrets do not expire and remain valid until deleted. If a connected app has already reached its two secret maximum when another one is generated, an error is thrown.
URI
POST api/api-version/sites/site-id/connected-apps/direct-trust/client-id/secrets
Note: The connected-applications endpoint that performed this function was deprecated in API 3.17 (Tableau Cloud October 2022 / Tableau Server 2022.3), is no longer supported and may be retired in a future release.
Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions. |
| site-id | The unique ID of the site asset. |
| client-id | The unique ID of the connected app. |
Request Body
None
Permissions
Tableau Server admins or Tableau Cloud site admins only.
Response Code
201
Response Body
The request returns details about the generated secret, including the secret value <value>.
Example response:
<tsResponse>
<connectedApplicationSecret>
<value>TO7/wkW+45U001IBtyNbtyIMYQ/GBM0XlRXqsgYqPlY=</value>
<id>7ecc5c7c-d923-4ffd-917b-cab1bd89f03b</id>
<createdAt>2021-08-10T18:48:40Z</createdAt>
</connectedApplicationSecret>
</tsResponse>Version
Version 3.14 and later. For more information, see REST API and Resource Versions.
The resource, POST /api/api-version/sites/site-id/connected-apps/direct-trust/client-id/secrets, was added in version 3.17. The original resource, POST /api/api-version/sites/site-id/connected-applications/client-id/secrets, was deprecated in version 3.17 and will be retired in a future release.
Errors
| HTTP status | error Code |
Condition | Details |
|---|---|---|---|
| 400 | 400143 | Generic connected app error | The connected app could not be deleted for some other reason than those specified in this table. |
| 400 | 400144 | Secret limit exceeded |
The connected app has already reached its two secret maximum. |
| 403 | 403000 | Admin permissions required | A non-admin user called this method and doesn't have adequate permissions to perform the action. |
| 404 | 404000 | Resource not found | The site ID in the URI doesn't correspond to an existing site. |
| 404 | 404041 | Connected app not found | The requested connected app could not be found. |
| 404 | 404042 | Secret not found | The requested secret for the connected app could not be found. |
Create Data Driven Alert
Create a data driven alert (DDA) for a view with a single data axis.
Version: Available in API 3.20 (Tableau Cloud June 2023) and later. Not available for Tableau Server. Version Overview(Link opens in a new window)
License: No additional license required.
Permissions: Users with the Administrator, Creator, or Explorer role can add DDAs to views they have permissions to. Permissions Overview(Link opens in a new window)
JWT Access Scope:
tableau:data_driven_alerts:create
Access Scopes Overview:
Cloud(Link opens in a new window) |
Server-Windows(Link opens in a new window) |
Server-Linux(Link opens in a new window)
Available in API 3.20 and later Tableau Cloud June 2023). Not available for Tableau Server.
URI
POST /api/api-version/sites/site-luid/dataAlerts
URI Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
|
| site-luid | The LUID for the site. |
Request Body
<tsRequest>
<dataAlertCreateAlert
alertCondition="above"
alertThreshold="14000"
subject="Data Driven Alert for Forecast"
frequency="daily"
visibility="public"
device="desktop"
worksheetName="one_measure_no_dimension"
viewId="my-view-id"
<!-- OR customViewId="my-custom-view-id"> -->
/>
</tsRequest>
{
"dataAlertCreateAlert": {
"alertCondition": "above",
"alertThreshold": "14000",
"subject": "Data Driven Alert for Forecast",
"frequency": "daily",
"visibility": "public",
"device": "desktop",
"worksheetName": "one_measure_no_dimension",
"viewId": "my-view-id"
// can be "customViewId" instead
}
}Request Attributes
dataAlertCreateAlert alertCondition
|
(Required) Enumeration: The condition that triggers the DDA. Used in conjunction with the threshold to determine when to trigger an alert. For example, an alert can be triggered if on the condition that data is above or equal to a threshold of 1000 orders. The value can be:
|
dataAlertCreateAlert alertThreshold
|
(Required) Int: The data value where an alert should be triggered when that value drops below or rises above the alert threshold value. |
dataAlertCreateAlert subject
|
(Required) String: The name of the data driven alert. |
dataAlertCreateAlert frequency
|
(Required) Enumeration: The time period between attempts by Tableau to assess whether the alert threshold has been crossed. The value can be one of:
|
dataAlertCreateAlert visibility
|
(Required) Enumeration: Determines whether the alert can be seen by only its creator (private), or by any user with permissions to the worksheet where the alert resides (public) . The value can be one of:
|
dataAlertCreateAlert device
|
(Optional) Enumeration: The type of device the alert is formatted for.
If no
|
dataAlertCreateAlert worksheetName
|
(Required) String: The name of the worksheet that the DDA will be created on. For dashboards, this is the name of the underlying sheet that contains the data whose value can trigger the alert, not the name of the dashboard that presents that sheet. For custom views, the name of the original view that was used to form the custom view. |
dataAlertCreateAlert viewId
OR
|
(Required) LUID: The LUID of either the viewId or customViewId that contains the data that can trigger an alert. |
cURL Request Example
curl http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/datasources/1a1b1c1d-2e2f-2a2b-3c3d-3e3f4a4b4c4d/connections" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd"
Response Code
200
Response Body
<tsRequest>
<dataAlertCreateAlert
alertCondition="above"
alertThreshold="14000"
subject="Data Driven Alert for Forecast"
frequency="daily"
visibility="public"
device="desktop"
worksheetName="one_measure_no_dimension"
viewId="my-view-id"
<!-- OR customViewId="my-custom-view-id"> -->
/>
</tsRequest>{
"dataAlertCreateAlert": {
"alertCondition": "above",
"alertThreshold": "14000",
"subject": "Data Driven Alert for Forecast",
"frequency": "daily",
"visibility": "public",
"device": "desktop",
"worksheetName": "one_measure_no_dimension",
"viewId": "my-view-id"
// can be "customViewId" instead
}
}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 | 403165 | DDA creation failed | A data driven alert could not be created because there is a missing value in the request body. |
| 401 | 401002 | Unauthorized Access | The user does not have permissions to create a data driven alert. Causes may include: authentication token provided in the request header was invalid or has expired; the user does not have administrator, creator, or explorer permissions; the user does not have permissions to view the sheet. |
| 403 | 403164 | DDA not enabled | Data driven alerts are not enabled for the site, or the user visibility site setting is configured as
limited.
|
| 404 | 404011 | View not found | The view specified in the request could not be found. |
| 404 | 409004 | Request is malformed | A data driven alert could not be created because there is an unexpected value in the request body. |
For more information, see Handling Errors.
Create Extracts for Embedded Data Sources in a Workbook
Create extracts for all embedded data sources of a workbook. Optionally, encrypt the extracts if the site and workbook using them are configured to allow it.
When you create an extract for a data source in a workbook, the extract is available only to the workbook and may have
configuration specific to the workbook, such as hiding of unused fields.
You can create workbook extracts for both embedded and published data sources used by the workbook. When you create a
workbook data source for a published data source, then refreshing the workbook extract will retrieve any changes to data
from the published datasource, or from the published data source's extract if it is using one.
Note: This method will fail and result in an error if your Server Administrator has disabled the RunNow setting for the site. For more information, see Tableau Server Settings(Link opens in a new window).
URI
POST /api/api-version/sites/site-id/workbooks/workbook-id/createExtract
POST /api/api-version/sites/site-id/workbooks/workbook-id/createExtract?encrypt=encryption-flag
Path Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions. |
| site-id | The LUID of the site. |
| workbook-id | The LUID of the workbook. |
| encryption-flag | If true, then Tableau will attempt to encrypt the created extracts.
If false, or no encrypt parameter is appended to the URI, then the extract won't
be encrypted, unless encryption is enforced by site or workbook configuration. An error will be returned when
encrypt equals true and encryption is disabled in the site or workbook.
|
Request Body
<tsRequest>
<datasources includeAll="extract-all-datasources-flag">
<datasource id="datasource-id" />
</datasources>
</tsRequest>
Request Parameter Values
| datasource-id | LUID of the embedded data source to be extracted. |
| extract-all-datasources-flag | Boolean. If true, then all data sources in the workbook will have an extract created for them.
If false, then a data source must be supplied in the request.
|
Permissions
Extracts for data sources embedded in a workbook can be created by Tableau server or site administrators, and users who own the workbook, or are an owner or leader of the project where the workbook resides.
Response Code
200
Response Body
<tsResponse>
<job id="job-id" mode="Asynchronous" type="CreateExtract" createdAt="date-time">
<extractCreationJob>
<workbook id="workbook-id" name="workbook-name" />
</extractCreationJob>
</job>
</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. |
| 404 | 404000 | Site not found | The specified site doesn't correspond to an existing site. |
| 405 | 405000 | Invalid request method | Request type was not POST. |
| 409 | 409070 | Invalid request method | The data source cannot be extracted because it is file based or in another unsupported form. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/workbooks/abcd7c6d-5e4f-3a2b-1c0d-9e8f7a6b1234/createExtract" -X POST -H "X-Tableau-Auth: oIcGYxkXSBCLLVm91mfITg|jCQSkWoIbUQVwTcH8WUTWD5nCoOf53LE" -d "@create-extracts-for-workbook.xml"
Content of create-extracts-for-workbook.xml
<tsResponse>
<datasources includeAll="false" />
<datasource id="6b4cf715-c90b-49d6-be85-920a47bae433" />
</datasources>
</tsRequest>Response body:
<tsResponse>
<job id="df410925-feae-481d-bf84-2f37bdf7ce69" mode="Asynchronous" type="CreateExtract" createdAt="2019-11-05T00:06:57Z">
<extractCreationJob>
<workbook id="e35ec79d-9526-44f1-9a67-7a8b63d265df" name="MY_WORKBOOK_NAME"/>
<jobLuid>df410925-feae-481d-bf84-2f37bdf7ce69</jobLuid>
</extractCreationJob>
</job>
</tsResponse>Create Group
Creates a group on Tableau Server or Tableau Cloud site.
If Tableau Server is configured to use Active Directory for authentication, this method can create a group and then import users from an Active Directory group.
Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.
To add users to a group, call Add User To Group. To make changes to an existing group, call Update Group.
For Tableau Server, if you use the method to import users from an Active Directory, the import process can be performed immediately (synchronously) or as a background job (asynchronously).
Note: If Active Directory contains a large number of users, you should import them asynchronously; otherwise, the process can time out.
The Create Group response returns information in two ways: in the response header and in the response body. The ID of the new group is always returned as the value of the Location header. If you create a local group or import an Active Directory group (Tableau Server only) immediately, the response body contains the name and ID of the new group. If you import an Active Directory group (Tableau Server only) using a background process, the response body contains a <job> element that includes a job ID. You can use the job ID to check the status of the operation by calling Query Job.
URI
POST /api/api-version/sites/site-id/groups
POST /api/api-version/sites/site-id/groups?asJob=asJob-value
Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions. |
| site-id | The ID of the site to create the group in. |
| asJob-value |
A Boolean value that is used if you are importing from Active Directory. If you set this to false (the default), the import process runs as a synchronous process.
If the Active Directory group contains many
users, the process might time out before it finishes.
If you set this to true, the process runs asynchronously. In that case, Tableau Server starts a job to perform the import and returns the job ID in the Location header. You can check the status of the import job by calling Query Job. Note: This parameter has no effect if the server is configured to use local authentication. This attribute is available for Tableau Server only. |
Request Body
Creating a local group
<tsRequest>
<group name="new-tableau-server-group-name"
minimumSiteRole="minimum-site-role"
ephemeralUsersEnabled="on-demand-access"/>
</tsRequest>
When the request is to create a local group and minimumSiteRole is specified, users are granted a license using the grant license on-login mode by default.
Importing a group from Active Directory (Tableau Server only)
<tsRequest>
<group name="active-directory-group-name" >
<import source="ActiveDirectory"
domainName="active-directory-domain-name"
grantLicenseMode="license-mode"
siteRole="minimum-site-role"/>
</group>
</tsRequest>
When the request is to create a group with grantLicenseMode, a siteRole value should also be supplied.
When the request body contains an <import> element, a Tableau Server configured to authenticate via Active Directory will create the group and modify the set
of users in the group to be the same as those in Active Directory. The source attribute of the <import> element must be set to ActiveDirectory.
If Tableau Server or Tableau Cloud site is configured to use local authentication, including an <import> element has no effect.
Note: When a group is created by importing from Active Directory, Tableau Server
uses the value of the Active Directory sAMAccountName attribute as the user name.
Attribute Values
| new-tableau-server-group-name | The name for the new group. |
| active-directory-group-name |
The name of the Active Directory group to import. This attribute is available for Tableau Server only. |
| active-directory-domain-name |
The domain of the Active Directory group to import. This attribute is available for Tableau Server only. |
| minimum-site-role |
Required if an import element or grantLicenseMode attribute are present in the request. For Tableau Server, the site role assigned to users who are imported from Active Directory or granted a license automatically using the grant license on-sync or on-login mode. If the requested user name matches an existing user in the group, the user either retains their existing role or are granted the one specified in the request, based on the role that enables the most capabilities. This is true whether the group the user belongs to is imported from Active Directory (Tableau Server only) or local. Site roles that can be assigned, listed from the one enabling the least capabilities to the most, are as follows.
Note: You cannot use the REST API to set a user to be a Tableau Server administrator (ServerAdministrator site role). |
| license-mode |
The mode for automatically applying licenses for group members. When the mode is onLogin, a license is granted for each group member when they log in to a site. For local groups, the mode can be either onLogin or unset. If the attribute is omitted, the default mode is unset, which results in no licenses being granted automatically to group members. For groups that import an Active Directory domain, the mode can be either onSync or onLogin. The minimum role granted to users through grantLicenseMode is specified in the siteRole attribute. If that role has less permissions than an existing role assigned to the user, then the user's permissions remain unchanged. |
| on-demand-access |
Optional. A boolean value that is used to enable on-demand access for embedded Tableau content when the Tableau Cloud site is licensed with Embedded Analytics(Link opens in a new window) usage-based model. Set to true to enable the capability for the group or set to false to disable the capability for the group. For more information about on-demand access, see one of the following topics in the Tableau Cloud Help: On-demand access using connected apps with direct trust(Link opens in a new window) or On-demand access using connected apps with OAuth 2.0 trust(Link opens in a new window). This attribute is available for Tableau Cloud only starting from API version 3.21 (October 2023). |
Permissions
This method can only be called by Tableau Server administrators or Tableau Cloud site admins.
Required scope for JWT authorization
Introduced in Tableau Cloud June 2022 (API 3.16) and Tableau Server 2022.3 (API 3.17).
Authorize use of this method in your connected app by including this scope in its JSON Web Token (JWT). For more information, see Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Cloud Help or Access Scopes for Connected Apps(Link opens in a new window) in the Tableau Server Help.
tableau:groups:createResponse Code
201, for creating a local group and for importing immediately
202, for importing using a background process
Response Headers
Location: /api/3.24/sites/site-id/groups/new-group-id
Response Body
Creating a local group:
<tsResponse>
<group id="new-group-id"
name="group-name"
minimumSiteRole="minimum-site-role"
ephemeralUsersEnabled="true" />
<import domainName="local" siteRole="default-site-role" grantLicenseMode="license-mode" />
</group>
</tsResponse>
Creating a group and importing from Active Directory immediately (Tableau Server only):
<tsResponse>
<group id="new-group-id"
name="group-name">
<import domainName="active-directory-domain-name”
siteRole="default-site-role"
grantLicenseMode="onLogin" />
</group>
</tsResponse>
Importing as a background process:
<tsResponse>
<job id="job-id" mode="Asynchronous" type="GroupImport"
progress="0" createdAt="time-job-created" />
</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. |
| 400 | 400013 | Invalid site role |
The value of the minimumSiteRole or siteRole attribute must be Creator, Explorer, ExplorerCanPublish, SiteAdministratorCreator, SiteAdministratorExplorer, Unlicensed, or Viewer. |
| 400 | 400019 | Malformed import element | When the <import> element is present in the request body, the following attributes must be specified: source with the value ActiveDirectory; domainName; and siteRole If any of these is missing, the element is malformed. |
| 403 | 403011 | Active Directory is not configured | The <import> element is present, but Tableau Server is configured for local authentication. |
| 404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
| 404 | 404016 | Domain not found | The request body includes an <import> element, but the specified domain name doesn't exist in Active Directory. |
| 404 | 404017 | Active Directory group not found | The request body includes an <import> element, but no group exists in Active Directory that matches the specified group name. |
| 405 | 405000 | Invalid request method | Request type was not POST. |
| 409 | 409009 | Group name conflict | The group name in the request already belongs to the specified site. For the purpose of uniqueness checks, group names are case-insensitive. |
For more information, see Handling Errors.
Example: Local Group
curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups/" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @create-local-group.xml
Content of create-local-group.xml:
<tsRequest>
<group name="marketing-group" ephemeralUsersEnabled="true" />
</tsRequest>Response header:
Location: /api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups/1a2b3c4d5-e6f7-a8b9-c0d1-e2f3a4b5c6d
Response body:
<tsResponse version-and-namespace-settings>
<group id="1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d" name="marketing-group" ephemeralUsersEnabled="true"/>
</tsResponse>Example: Active Directory Group
curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups/" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @create-ad-group.xml
Content of create-ad-group.xml:
<tsRequest>
<group id="1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d" name="marketing-group">
<import domainName="MY-DOMAIN" siteRole="Viewer" grantLicenseMode="onLogin" />
</group>
</tsRequest>Response header:
Location: /api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groups/1a2b3c4d5-e6f7-a8b9-c0d1-e2f3a4b5c6d
Response body:
<tsResponse version-and-namespace-settings>
<group id="1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d" name="marketing-group">
<import domainName="MY-DOMAIN" siteRole="Viewer" grantLicenseMode="onLogin" />
</group>
</tsResponse>Create Group Set
Creates a group set with a specified name.
Note: You can't use this method to populate the group set with groups. After you create a group set and its ID is available, you can add a group to the group set by calling Add Group to Group Set.
Version: Available in API 3.22 (Tableau Cloud February 2024 / Server 2024.2) and later. Version Overview(Link opens in a new window)
License: No additional license required.
Permissions: This method can only be called by Tableau Server administrators or Tableau Cloud site admins. Permissions Overview(Link opens in a new window)
JWT Access Scope: tableau:groupsets:create Access Scopes Overview: Cloud(Link opens in a new window) | Server-Windows(Link opens in a new window) | Server-Linux(Link opens in a new window)
URI
POST /api/api-version/sites/site-id/groupsets
URI Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions. |
| site-id | The ID of the site to create the group in. |
Request Body
Request Attributes
name
|
(Required) Name of the new group set. |
cURL Request Example
curl "http://MY-SERVER/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/groupsets/" --header "Content-Type: application/xml" --header "X-Tableau-Auth: YqB9_MHoTHO26HGsFBFEBg|bQDOIH4MsqFGvUDYTrRYh633vrZHBt6d|a946d998-2ead-4894-bb50-1054a91dcab3" --data "<tsRequest> <groupSet name='marketing-group' /> </tsRequest>"
Response Code
201, for creating a group set.
Response Body
<tsRequest>
<groupSet id="4123e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6234"
name="marketing-group"
groupCount="0" />
</tsRequest>{
"groupSet": {
"id": "4123e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6234",
"name": "marketing-group",
"groupCount": "0"
}
}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 | 400013 | Invalid site role |
The value of the minimumSiteRole or siteRole attribute must be SiteAdministratorCreator or SiteAdministratorExplorer. |
| 404 | 404000 | Site not found | The site ID in the URI doesn't correspond to an existing site. |
| 405 | 405000 | Invalid request method | The request type wasn’t POST. |
| 409 | 409121 | Group set name conflict | The group set name in the request already belongs to another group set. For the purpose of uniqueness checks, group set names are case-insensitive. |
For more information, see Handling Errors.
Create Identity Pool
Create an identity pool.
Version: Available in API 3.19 (Tableau Server 2023.1) and later. Not available for Tableau Cloud. Version Overview
Permissions: This method can only be called by users with server administrator permissions. Permissions Overview
License: No additional license required.
Access Scope: Not available. Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux
POST {server}/api/-/authn-service/identity-pools
Create Label Category
Creates a data label category.
Note that category is one property of a label value (labelValue), which is itself a property of a label on an asset. Other properties of a labelValue include name and description. These properties determine label behavior and options that users see in label dialogs. For more information on data label objects and properties, see the Data Labels in the REST API(Link opens in a new window) topic.
A Data Management license is not required to create, update, or delete label categories, but one is required to create, update, delete, and see labels on assets.
URI
POST api/api-version/sites/site-luid/labelCategories
Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions. |
| site-luid | The unique LUID of the site asset. |
Request Body
<tsRequest>
<labelCategory name="label-category-name"
description="label-category-description" />
</tsRequest>Attribute Values
| label-category-name |
The label category name. Required. Must be 1-128 characters long. (In Tableau Server 2023.3 and earlier, must be 1-24 characters long.) |
| label-category-description |
The label category description. Required. Must be 1-500 characters in length. |
Permissions
- Only a site or server administrator can create, update, or delete label categories.
Response Code
200
Version
Introduced in Tableau Cloud October 2023 (API 3.21) / Server 2023.3 (API 3.21).
Response Body
<tsResponse>
<labelCategory name="label-category-name"
description="label-category-description"/>
</tsResponse>Errors
| HTTP status | error Code |
Condition | Details |
|---|---|---|---|
| 400 | 400189 | Generic create label categories error | An unknown error occurred. |
| 403 | 403004 | Operation on resource unauthorized | You must be an administrator to create, update, or delete label values. |
| 409 | 409004 | Invalid parameter |
|
Create metric
Creates a metric.
Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Versioning Overview Version Overview
Permissions: Any user can create a metric in a definition as long as the user has read or connect access to the data source used in the definition. Permissions Overview
License: No additional license required.
Access Scope: tableau:insight_metrics:create
Access Scopes Overview: Cloud Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux
POST {server}/api/-/pulse/metrics
Create metric definition
Creates a metric definition.
Version: Available in API 3.21 (Tableau Cloud December 2023) and later. Not available for Tableau Server. Versioning Overview Version Overview
Permissions: Any user can create a metric definition as long as the user has write and publish access to the data source used in the definition. Permissions Overview
License: No additional license required.
Access Scope: tableau:insight_definitions:create
Access Scopes Overview: Cloud Tableau Cloud | Tableau Server-Windows | Tableau Server-Linux
POST {server}/api/-/pulse/definitions
Create OpenID Connect Configuration
Create the Tableau Cloud site's OpenID Connect (OIDC) configuration.
After you've configured OIDC authentication, you can use the Tableau Cloud's UI to test the configuration(Link opens in a new window) and add users(Link opens in a new window).
For more information about OIDC authentication in Tableau Cloud, see OpenID Connect(Link opens in a new window) in the Tableau Cloud Help.
Version: Available in API 3.22 (Tableau Cloud February 2024) and later. Not available for Tableau Server.Version Overview(Link opens in a new window)
License: No additional license required.
Permissions: Tableau Cloud site admins only.
JWT Access Scope: Not available. Access Scopes Overview: Cloud(Link opens in a new window)
URI
PUT /api/api-version/sites/site-luid/site-oidc-configuration
URI Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions.
|
| site-luid | The LUID for the site. |
Request Body
<tsRequest>
<siteOIDCConfiguration
enabled="enabled"
clientId="clientId"
clientSecret="clientSecret"
authorizationEndpoint="authorizationEndpoint"
tokenEndpoint="tokenEndpoint"
userinfoEndpoint="userinfoEndpoint"
jwksUri="jwksUri"
endSessionEndpoint="endSessionEndpoint"
allowEmbeddedAuthentication="allowEmbeddedAuthentication"
prompt="prompt"
customScope="customScope"
clientAuthentication="clientAuthentication"
essentialAcrValues="essentialAcrValues"
voluntaryAcrValues="voluntaryAcrValues"
emailMapping="emailMapping"
firstNameMapping="firstNameMapping"
lastNameMapping="lastNameMapping"
fullNameMapping="fullNameMapping"
useFullName="useFullName" />
</tsRequest>
{
"siteOIDCConfiguration": {
"enabled": "enabled",
"clientId": "clientId",
"clientSecret": "clientSecret",
"authorizationEndpoint": "authorizationEndpoint",
"tokenEndpoint": "tokenEndpoint",
"userinfoEndpoint": "userinfoEndpoint",
"jwksUri": "jwksUri",
"endSessionEndpoint": "endSessionEndpoint",
"allowEmbeddedAuthentication": "allowEmbeddedAuthentication",
"prompt":"prompt",
"customScope":"customScope",
"clientAuthentication": "clientAuthentication",
"essentialAcrValues": "essentialAcrValues",
"voluntaryAcrValues": "voluntaryAcrValues",
"emailMapping": "emailMapping",
"firstNameMapping": "firstNameMapping",
"lastNameMapping": "lastNameMapping",
"fullNameMapping": "fullNameMapping",
"useFullName": "useFullName"
}
}Request Attributes
enabled
|
(Required) Controls whether the configuration is enabled or not. Value can be "true" or "false". For example "true". |
clientId
|
(Required) The client ID from your IdP. For example, "0oa111usf1gpUkVUt0h1". |
clientSecret
|
(Required) The client secret from your IdP. |
authorizationEndpoint
|
(Required) Use the authorization endpoint from your IdP. To find the value, enter the configuration URL in a browser and obtain the user information endpoint (authorization_endpoint) from the details that are returned. For example, "https://myidp.com/oauth2/v1/authorize". |
tokenEndpoint
|
(Required) Use the token endpoint from your IdP. To find the value, enter the configuration URL in a browser and obtain the token endpoint (token_endpoint) from the details that are returned. For example, "https://myidp.com/oauth2/v1/token". |
userinfoEndpoint
|
(Required) Use the user information endpoint from your IdP. To find the value, enter the configuration URL in a browser and obtain the user information endpoint (userinfo_endpoint) from the details that are returned. For example, "https://myidp.com/oauth2/v1/userinfo". |
jwkUri
|
(Required) Use the JWK set URI from your IdP. To find the value, enter the configuration URL in a browser and obtain the JWK set URI endpoint (jwks_uri) from the details that are returned. For example, "https://myidp.com/oauth2/v1/keys". |
endSessionEndpoint
|
(Optional) If single logout (SLO) is enabled for the site, which is done through Tableau Cloud site UI, you can specify the configuration URL or the end session endpoint from your IdP. For example, "https://myidp.com/oauth2/v1/logout". |
allowEmbeddedAuthentication
|
(Optional) Controls how users authenticate when accessing embedded views. Value can be "true" or "false". Default value is "false", which authenticates users in a separate pop-up window. When set to "true", users authenticate using an inline frame (IFrame), which is less secure. |
customScope
|
(Optional) Specifies a custom scope user-related value that you can use to query the IdP. For example, "openid, email, profile". |
prompt
|
(Optional) Specifies whether the user is prompted for re-authentication and consent. For example, "login, consent". |
clientAuthentication
|
(Optional) Token endpoint authentication method. Value can be "client_secret_basic" or "client_secret_post". Default value is "client_secret_basic". |
essentialAcrValues
|
(Optional) List of essential Authentication Context Reference Class values used for authentication. For example, "phr". |
voluntaryAcrValues
|
(Optional) List of voluntary Authentication Context Reference Class values used for authentication. |
emailMapping
|
(Optional) Claim for retrieving email from the OIDC token. Default value is "email". |
firstNameMapping
|
(Optional) Claim for retrieving first name from the OIDC token. Default value is "given_name". You can use this attribute to retrieve the user’s display name when useFullName attribute is set to "false". |
lastNameMapping
|
(Optional) Claim for retrieving last name from the OIDC token. Default value is "family_name". You can use this attribute to retrieve the user’s display name when useFullName attribute is set to "false". |
fullNameMapping
|
(Optional) Claim for retrieving name from the OIDC token. Default value is "name". You can use this attribute to retrieve the user’s display name when useFullName attribute is set to "true". |
useFullName
|
(Optional) Controls what is used as the display name. Value can be "true" or "false". Default value is "false", which uses first name (firstNameMapping attribute) and last name (lastNameMapping attribute) as the user display name. When set to "true", full name (fullNameMapping attribute) is used as the user display name. |
cURL Request Example
curl "https://us-west-2a.online.tableau.com/api/3.24/sites/9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/site-oidc-configuration" -X GET -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @create-update-oidc-config.xml
Content of create-update-oidc-config.xml:
<tsRequest>
<siteOIDCConfiguration
enabled="enabled"
clientId="clientId"
clientSecret="clientSecret"
authorizationEndpoint="authorizationEndpoint"
tokenEndpoint="tokenEndpoint"
userinfoEndpoint="userinfoEndpoint"
jwksUri="jwksUri"
endSessionEndpoint="endSessionEndpoint"
allowEmbeddedAuthentication="allowEmbeddedAuthentication"
prompt="prompt"
customScope="customScope"
clientAuthentication="clientAuthentication"
essentialAcrValues="essentialAcrValues"
voluntaryAcrValues="voluntaryAcrValues"
emailMapping="emailMapping"
firstNameMapping="firstNameMapping"
lastNameMapping="lastNameMapping"
fullNameMapping="fullNameMapping"
useFullName="useFullName" />
</tsRequestResponse Code
200
Response Body
<tsResponse>
<siteOIDCConfiguration
enabled="true"
testLoginUrl="https://sso.online.tableau.com/public/testLogin?alias=080bca2d-578b-49cc-b40d-3781b36b30ee&authSetting=OIDC"
allowEmbeddedAuthentication="false"
clientId="0oa111usf1gpUkVUt0h1"
clientSecret="<omit>"
authorizationEndpoint="https://myidp.com/oauth2/v1/authorize"
tokenEndpoint="https://myidp.com/oauth2/v1/token"
userinfoEndpoint="https://myidp.com/oauth2/v1/userinfo"
jwksUri="https://myidp.com/oauth2/v1/keys"
endSessionEndpoint="https://myidp.com/oauth2/v1/logout"
customScope="openid, email, profile"
prompt="login,consent"
clientAuthentication="client_secret_basic"
essentialAcrValues="phr"
emailMapping="email"
firstNameMapping="given_name"
lastNameMapping="family_name"
fullNameMapping="name"
useFullName="false" />
</tsResponse>{
"siteOIDCConfiguration": {
"enabled":"true",
"testLoginUrl":"https://sso.online.tableau.com/public/testLogin?alias=080bca2d-578b-49cc-b40d-3781b36b30ee&authSetting=OIDC",
"allowEmbeddedAuthentication":"false",
"clientId":"0oa111usf1gpUkVUt0h1",
"clientSecret":"<omit>",
"authorizationEndpoint":"https://myidp.com/oauth2/v1/authorize",
"tokenEndpoint":"https://myidp.com/oauth2/v1/token",
"userinfoEndpoint":"https://myidp.com/oauth2/v1/userinfo",
"jwksUri":"https://myidp.com/oauth2/v1/keys",
"endSessionEndpoint":"https://myidp.com/oauth2/v1/logout",
"customScope":"openid, email, profile",
"prompt":"login,consent",
"clientAuthentication":"client_secret_basic",
"essentialAcrValues":"phr",
"emailMapping":"email",
"firstNameMapping":"given_name",
"lastNameMapping":"family_name",
"fullNameMapping":"name",
"useFullName":"false"
}
}Notes:
-
The response hides the client secret and replaces it with
<omit>. -
You can use the
testloginURLto validate the OIDC configuration. When you enter the URL in a browser, details about the configuration displays.
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 | 401002 | Unauthorized Access | The authentication token provided in the request header was invalid or has expired. |
For more information, see Handling Errors.
Create or Update labelValue
Creates a label value with the specified name if it doesn't exist, or updates the existing label value if the label value name already exists.
Note: You can update an existing label value using either this method or the Update labelValue method. If you want to change the name on an existing label value, use the Update labelValue method.
Note that a label value (labelValue) is one property of a label. A label value has its own properties like name, category, and description that determine label behavior and options that users see in label dialogs. For more information on data label objects and properties, see the Data Labels in the REST API(Link opens in a new window) topic.
A Data Management license is not required to create, update, or delete label values, but one is required to create, update, delete, and see labels on assets.
URI
PUT api/api-version/sites/site-luid/labelValues
Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions. |
| site-luid | The unique LUID of the site asset. |
Request Body
<tsRequest>
<labelValue name="label-value-name"
category="label-value-category"
description="label-value-description" />
</tsRequest>Attribute Values
| label-value-name |
The label value name. Required. If you specify an existing label value name, this method will update the label value. If you specify a label value name that's different than existing label value names, this method will create the label value. Required. Must be 1-128 characters long. (In Tableau Server 2023.3 and earlier, must be 1-24 characters long.) |
| label-value-category |
The label value category. Required. If you're updating an existing label value, this must match the existing category for that label value. |
| label-value-description |
The label value description. Required, but does not need to be different than the existing description. Must be 1-500 characters in length. |
Permissions
- Only a site or server administrator can create, update, or delete label values.
Response Code
200
Version
Introduced in Tableau Cloud June 2023 (API 3.20) and Tableau Server 2023.3 (API 3.21).
Response Body
<tsResponse>
<labelValue name="label-value-name"
category="label-value-category"
description="label-value-description"
internal="true-or-false"
elevatedDefault="true-or-false"
builtIn="true-or-false">
<site id="site-luid"/>
</labelValue>
</tsResponse>Errors
| HTTP status | error Code |
Condition | Details |
|---|---|---|---|
| 401 | 4000173 | Generic create label values error | An unknown error occurred. |
| 403 | 403004 | Operation on resource unauthorized | You must be a site or server administrator to create or update label values. |
| 403 | 403157 | Bad request | You may see this error if you try to create or update a label in the certification category. |
| 409 | 409004 | Invalid parameter |
|
Create Project
Creates a project on the specified site. You can also create project hierarchies by creating a project under the specified parent project on the site. To make changes to an existing project, call Update Project.
Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.
Version: Available in API 1.0 and later. Version Overview(Link opens in a new window)
License: No additional license required.
Permissions: Only Tableau Administrators can update a project. Permissions Overview(Link opens in a new window)
JWT Access Scope:
tableau:projects:create
Access Scopes Overview:
Cloud(Link opens in a new window) |
Server-Windows(Link opens in a new window) |
Server-Linux(Link opens in a new window)
Available in API 3.16 (Tableau Cloud June 2022 / Server 2022.3) and later.
URI
POST /api/api-version/sites/site-id/projects
POST /api/api-version/sites/site-id/projects?publishSamples=publish-value
Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions. |
| site-id | The ID of the site to create the project in. |
| publish-value | (Optional) A Boolean value that specifies whether to publish the sample workbooks provided by Tableau to the project. When the publish-value is not specified in the request, or the publishSamples parameter is missing, no samples will be published. To publish the sample workbooks, set publishSamples parameter to true. This option is equivalent to the tabcmd command-line utility option, publishsamples. For more information, see tabcmd(Link opens in a new window). |
Request Body
<tsRequest>
<project
parentProjectId="afe6f0b8-cb10-11e7-9fd4-db8b61369aa5"
name="Update-Project-Name"
description="This is the new description after the project update"
contentPermissions="ManagedByOwner">
<owner id="abc12e4e-5d6d-7c8c-9b0b-1a2a3f4f5e90"/>
</project>
</tsRequest>
{
"project": {
"parentProjectId": "afe6f0b8-cb10-11e7-9fd4-db8b61369aa5",
"name": "Update-Project-Name",
"description": "This is the new description after the project update",
"contentPermissions": "ManagedByOwner",
"owner": {
"id": "abc12e4e-5d6d-7c8c-9b0b-1a2a3f4f5e90"
}
}
}Attribute Values
project name
|
(Required) The new name for the project. |
project description
|
(Optional) The new description for the project. |
project parentProjectId
|
(Optional) The new identifier of the parent project. Use this option to create or change project hierarchies. To create a project as a stand alone or at the top of a project hierarchy, omit the parentProjectId attribute. For information about how permissions are evaluated in project hierarchies, see Project Permissions States and Defaults. |
project contentPermissions
|
(Optional) This value controls user permissions in a project, however, if the project is nested within a project with more restrictive policies, it will inherit those permissions and these settings will have no effect. The functional permissions of a project, including those it inherits, are available in value of contentPermission in the response body from a request to create, update, or query a project.
The default is ManagedByOwner. For more information, see Lock Content Permissions(Link opens in a new window). |
owner id
|
The LUID of the user that owns the project. |
cURL Example
curl --request PUT "https://myServer/api/3.21/sites/1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e/projects/xz2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e3w" --header "Content-Type: application/xml" --header "X-Tableau-Auth;" --data "<tsRequest> <project parentProjectId='ab2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5ee0' name='new-name' description='new-description' contentPermissions='ManagedByOwner' /> </tsRequest>"
Response Code
201
Response Body
<tsResponse>
<project id="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e"
parentProjectId="afe6f0b8-cb10-11e7-9fd4-db8b61369aa5"
name="Update-Project-Name"
description="This is the new description after the project update"
contentPermissions="ManagedByOwner"
controllingPermissionsProjectId="1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e" >
<owner id="abc12e4e-5d6d-7c8c-9b0b-1a2a3f4f5e90"/>
</project>
</tsResponse>
{
"project": {
"id": "1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e",
"parentProjectId": "afe6f0b8-cb10-11e7-9fd4-db8b61369aa5",
"name": "Update-Project-Name",
"description": "This is the new description after the project update",
"contentPermissions": "ManagedByOwner",
"controllingPermissionsProjectId": "1f2f3e4e-5d6d-7c8c-9b0b-1a2a3f4f5e6e",
"owner": {
"id": "abc12e4e-5d6d-7c8c-9b0b-1a2a3f4f5e90"
}
}
}Errors
| HTTP status | error Code |
Condition | Details |
|---|---|---|---|
| 400 | 400000 | Bad request | The content of the request body is missing or incomplete, or contains malformed XML. |
| 400 | 400008 | Bad request | The request cannot set content permissions to LockedToProjectWithoutNested for a REST API version lower than 3.8. |
| 403 | 403008 | Insufficient storage on site | The samples could not be published because there is not enough storage space remaining on the server to accommodate the samples. |
| 404 | 404000 | Site not found |
The site ID in the URI doesn't correspond to an existing site. |
| 405 | 405000 | Invalid request method | Request type was not POST. |
| 409 | 409006 | Project name conflict | The project name in the request already belongs to the specified site. For the purpose of uniqueness checks, project names are case-insensitive. |
For more information, see Handling Errors.
Create Server Schedule
Creates a new server schedule on Tableau Server.
For Tableau Cloud, see Create Cloud Extract Refresh Task and
Create subscription.
Schedules are not specific to sites. For more information, see Creating a Flow Schedule(Link opens in a new window), Extracts and Refresh Schedules(Link opens in a new window) and Create or Modify a Schedule(Link opens in a new window) in the Tableau Server documentation. Scheduling flows requires Tableau Prep Conductor to be enabled on your Tableau Server. For more information, see Enable Tableau Prep Conductor(Link opens in a new window).
Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.
URI
POST /api/api-version/schedules
Parameter Values
| api-version | The version of the API to use, such as 3.24. For more information, see REST API and Resource Versions. |
Request Body
<tsRequest>
<schedule name="schedule-name"
priority="schedule-priority"
type="schedule-type"
frequency="schedule-frequency"
executionOrder="schedule-execution-order">
<frequencyDetails start="start-time" end="end-time">
<intervals>
<interval interval-expression />
</intervals>
</frequencyDetails>
</schedule>
</tsRequest>
Attribute Values
| schedule-name | The name to give to the schedule. This name identifies the schedule in the server environment when users select a schedule and manage schedule information. |
| schedule-priority | An integer value between 1 and 100 that determines the default priority of the schedule if multiple tasks are pending in the queue. Lower numbers have higher priority. |
| schedule-type | Flow to create a flow schedule, Extract to create an extract refresh schedule,
Subscription to create a subscription schedule, or DataAcceleration to create a
data acceleration schedule.
(Data acceleration is not available in Tableau Server 2022.1 (API 3.16) and later. See
View Acceleration(Link opens in a new window).) |
| schedule-execution-order | Parallel to allow jobs associated with this schedule to run at the same time, or Serial to require the jobs to run one after the other. |
| schedule-frequency |
This represents the granularity of the schedule.
The value you provide for schedule-frequency determines whether you must include an end-time value, and what is required in the contents of the <intervals> element. |
| start-time | The time of day on which scheduled jobs should run (or if the frequency is hourly, on which they should start being run), in the format HH:MM:SS (for example, 18:30:00). This value is required for all schedule frequencies. The entered time will be applied based on the time zone of your server. |
| end-time | If the schedule frequency is Hourly, the time of day on which scheduled jobs should stop being run, in the format HH:MM:SS (for example, 23:30:00). Hourly jobs will occur at the specified intervals between the start time and the end time. For other schedule frequencies, this value is not required; if the attribute is included, it is ignored. The entered time will be applied based on the time zone of your server. |
| interval-expression | A value that specifies the interval between jobs associated with the schedule. The value you specify here depends on the value specified in schedule-frequency.
The interval expression is only one of the following:
You can specify an interval in hours or minutes, but not both.
If the schedule frequency is
The interval expression is You can specify multiple <interval> elements to indicate that scheduled jobs should run on multiple days during the week.
The interval expression is Note: If you want to specify multiple days in the month, you can do this using the web interface. You cannot create or update such a monthly schedule using REST API. |
Permissions
This method can only be called by server administrators.
Response Code
201
Response Body
<tsResponse>
<schedule id="schedule-id"
name="schedule-name"
state="Active-or-Suspended"
priority="schedule-priority"
createdAt="datetime-created"
updatedAt="datetime-updated"
type="Extract-or-Subscription-or-Flow"
frequency="schedule-frequency"
nextRunAt="datetime-next-run"
executionOrder="Parallel-or-Serial">
<frequencyDetails frequency-expression >
<intervals>
<interval interval-expression />
</intervals>
</frequencyDetails>
</schedule>
</tsResponse>
Version
Version 2.3 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 | 400064 | Error creating schedule | An unspecified error occurred while trying to create the schedule. |
| 400 | 409004 | Bad request | The content of the request body is missing or incomplete. For hourly, daily, or monthly schedules, this often means that the content of the <intervals> element does not match the expected format. The <detail> element of the error provides detail about the expected format. |
| 405 | 405000 | Invalid request method | Request type was not POST. |
| 409 | 409021 | Schedule name conflict | The schedule name in the request already belongs to an existing schedule. |
For more information, see Handling Errors.
Example
curl "http://MY-SERVER/api/3.24/schedules/" -X POST -H "X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd" -d @create-schedule.xml
Content of create-schedule.xml for an hourly schedule
<tsRequest>
<schedule name="hourly-schedule-1"
priority="50"
type="Extract"
frequency="Hourly"
executionOrder="Parallel">
<frequencyDetails start="18:30:00" end="23:00:00">
<intervals>
<interval hours="2" />
</intervals>
</frequencyDetails>
</schedule>
</tsRequest>Response body
<tsResponse >
<schedule
id="4d652179-36bf-47e4-a9dc-e069227c72d0"
name="hourly-schedule-1"
state="Active"
priority="50"
createdAt="2016-05-07T01:51:19Z"
updatedAt="2016-05-07T01:51:19Z"
type="Extract"
frequency="Hourly"
nextRunAt="2016-05-07T03:30:00Z"
executionOrder="Parallel">
<frequencyDetails start="18:30:00" end="23:00:00">
<intervals>
<interval hours="2" />
</intervals>
</frequencyDetails>
</schedule>
</tsResponse>
Content of create-schedule.xml for a daily schedule
For a daily schedule, frequencyDetails is set to Daily. The start attribute is required. No intervals element is required. Daily schedules on any recurrence must have the same start and end minute. The hour can be different. However, if the daily schedule is set to only happen once a day, then it needs only a start time and not an end time.
<tsRequest>
<schedule
name="daily-schedule-1"
priority="50"
type="Subscription"
frequency="Daily"
executionOrder="Parallel">
<frequencyDetails start="02:15:00" />
</schedule>
</tsRequest>Response body
<tsResponse>
<schedule
id="4d652179-36bf-47e4-a9dc-e069227c72d0"
name="daily-schedule-1"
state="Active"
priority="50"
createdAt="2016-05-07T01:43:33Z"
updatedAt="2016-05-07T01:43:33Z"
type="Subscription"
frequency="Daily"
nextRunAt="2016-05-07T09:15:00Z"
executionOrder="Parallel">
<frequencyDetails start="02:15:00" />
</schedule>
</tsResponse>
Content of create-schedule.xml for a weekly schedule
For a weekly schedule, frequencyDetails is set to Weekly. A start attribute is required. The intervals element is required, and must include between 1 and 7 interval subelements that contain a weekDay attribute. Valid values for the weekDay attribute are Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, or Saturday.
<tsRequest>
<schedule name="weekly-schedule-1"
priority="50"
type="Subscription"
frequency="Weekly"
executionOrder="Serial">
<frequencyDetails start="18:30:00">
<intervals>
<interval weekDay="Sunday" />
<interval weekDay="Wednesday" />
</intervals>
</frequencyDetails>
</schedule>
</tsRequest>Response body
<tsResponse>
<schedule id="4d652179-36bf-47e4-a9dc-e069227c72d0"
name="weekly-schedule-1"
state="Active"
priority="50"
createdAt="2016-05-07T02:01:30Z"
updatedAt="2016-05-07T02:01:30Z"
type="Subscription"
frequency="Weekly"
nextRunAt="2016-05-09T01:30:00Z"
executionOrder="Serial">
<frequencyDetails start="18:30:00">
<intervals>
<interval weekDay="Sunday" />
<interval weekDay="Wednesday" />
</intervals>
</frequencyDetails>
</schedule>
</tsResponse>
Content of create-schedule.xml for a monthly schedule
For a monthly schedule, frequencyDetails is set to Monthly. A start attribute is required. The intervals element is required, and must include 1 interval subelement that contains a monthDay attribute. Valid values for the monthDay attribute are integers between 1 and 31 and the string LastDay.
<tsRequest>
<schedule name="monthly-schedule-1"
priority="50"
type="Subscription"
frequency="Monthly"
executionOrder="Parallel">
<frequencyDetails start="06:00:00">
<intervals>
<interval monthDay="15" />
</intervals>
</frequencyDetails>
</schedule>
</tsRequest>Response body
<tsResponse>
<schedule
id="4d652179-36bf-47e4-a9dc-e069227c72d0"
name="monthly-schedule-1"
state="Active"
priority="50"
createdAt="2016-05-07T02:08:25Z"
updatedAt="2016-05-07T02:08:25Z"
type="Subscription"
frequency="Monthly"
nextRunAt="2016-06-03T13:00:00Z"
executionOrder="Parallel">
<frequencyDetails start="06:00:00">
<intervals>
<interval monthDay="15" />
</intervals>
</frequencyDetails>
</schedule>
</tsResponse>
Create Site
Creates a site on Tableau Server. To make changes to an existing site, call Update Site. This method isn’t available for Tableau Cloud.
For more information, see Work with Sites(Link opens in a new window) and Add or Edit Sites(Link opens in a new window) in the Tableau Server documentation.
Note: After you create a resource, the server updates its search index. If you make a query immediately to see a new resource, the query results might not be up to date.
URI
POST /api/api-version/sites
Request Body
<tsRequest>
<site
name="site-name"
contentUrl="content-url"
adminMode="admin-mode"
storageQuota="limit-in-megabytes"
disableSubscriptions="disable-subscriptions"
editingFlowsEnabled="editing-flows-enabled-flag"
schedulingFlowsEnabled="scheduling-flows-enabled-flag"
allowSubscriptionAttachments="allow-subcription-attachments-flag"
guestAccessEnabled="guest-access-enabled-flag"
cacheWarmupEnabled="cache-warmup-enabled-flag [REMOVED IN API 3.19]"
commentingEnabled="commenting-enabled-flag"
revisionHistoryEnabled="enable-revision-history-flag"
revisionLimit="num-revision-limit"
subscribeOthersEnabled="subscribe-others-enabled-flag"
extractEncryptionMode="extractEncryptionMode"
requestAccessEnabled="request-access-enabled-flag"
runNowEnabled="run-now-enabled-flag"
userQuota="all-license-limit-total"
tierCreatorCapacity="creator-license-limit"
tierExplorerCapacity="explorer-license-limit"
tierViewerCapacity="viewer-license-limit"
dataAlertsEnabled="data-alerts-enabled-flag"
commentingMentionsEnabled="commenting-mentions-enabled-flag"
catalogObfuscationEnabled="catalog-obfuscation-enabled-flag"
flowAutoSaveEnabled="flow-auto-save-enabled-flag"
runNowEnabled="run-now-enabled-flag"
metricsContentTypeEnabled="metrics-content-type-enabled-flag"
notifySiteAdminsOnThrottle="notify-site-admins-on-throttle-flag"
authoringEnabled="authoring-enabled-flag"
customSubscriptionEmailEnabled="custom-subscription-email-enabled-flag"
customSubscriptionEmail="custom-subscription-email"
customSubscriptionFooterEnabled="custom-subscription-footer-enabled-flag"
customSubscriptionFooter="custom-subscription-footer"
askDataMode="ask-data-mode"
namedSharingEnabled="named-sharing-enabled-flag"
catalogingEnabled="cataloging-enabled-flag"
derivedPermissionsEnabled="derived-permissions-enabled-flag"
userVisibilityMode="user-visibility-mode"
useDefaultTimeZone="default-time-zone-flag"
timeZone="time-zone"
autoSuspendRefreshEnabled="auto-suspend-refresh-enabled-flag"
autoSuspendRefreshInactivityWindow="auto-suspend-refresh-inactivity-window"
explainDataEnabled="explainDataEnabled"
dqwSubscriptionsEnabled="dqw-subscriptions-enabled"
groupAssertionsEnabled="group-assertions-enabled-flag"
groupAssertionsSAMLEnabled="group-assertions-saml-enabled-flag"
groupAssertionsOIDCEnabled="