Publishing Methods


Using the publishing methods of the Tableau Server REST API you can:

  • Publish a small workbook or data source file to a site in a single call
  • Publish a larger workbook or data source file to a site in multiple calls

This functionality relates to the UI elements and concepts described at: Publishing Workbooks and Data Sources(Link opens in a new window).

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:create

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

Initiate File Upload

Initiates the upload process for a file. After the upload has been initiated, you call Append to File Upload to send individual blocks of the file to the server. When the complete file has been sent to the server, you call Publish Data Source, Publish Flow, or Publish Workbook to commit the upload.

Initiate File Upload returns an upload session ID that you pass to Append to File Upload or one of the publishing methods in order to identify the upload session.

The file size that is returned in the response is initialized to zero (0) megabytes, because no data has yet been loaded. Subsequent calls to Append to File Upload or the publishing APIs update this value.

For more information, see Publishing Resources.

URI

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

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.

Request Body

None

Permissions

Users who are not server administrators or site administrators can initiate a file upload 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:create

Response Code

201

Response Body

<tsResponse>
  <fileUpload uploadSessionId=new-upload-session-id
     fileSize=0 />
</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.
403 403015 Access to Favorites forbidden A non-administrator user attempted to initiate a file upload, but the caller doesn't have publishing rights on the site.
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.

For more information, see Handling Errors.

Publish Data Source

Publishes a data source on the specified site, or appends data to an existing data source. To make other changes to a published data source, call Update Data Source or Update Data Source Connection.

Version: Available in API 2.0 and later. Version overview

License: Available for Tableau Server and Tableau Cloud.

Permissions: You can publish a data source if you have implicit or explicit Publish permissions for the data source, or are a Tableau administrator. Note: The queryTaggingEnabled attribute is returned only for administrator users. Permissions Overview

JWT Access Scope: tableau:datasources: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.

This method is used in two ways. You can call it to publish a data source in a single request. To do that, you include the content of the data source file in the body of the request. The maximum size of a file that can be published in a single request is 64 MB. If you want to avoid having the publishing process time out, you can use the asJob parameter to make data source publication asynchronous.

Alternatively, you can publish a data source in multiple parts. To do that, you initiate a file upload by calling Initiate File Upload, send portions of the file to the server using Append to File Upload, and then commit the upload by calling Publish Data Source. In this case, Publish Data Source doesn't contain the file to publish.

Extracts with multiple table options
Starting in v2021.4, you can publish multi table Hyper extract files created using the Hyper API(Link opens in a new window). The data must include a single fact table(Link opens in a new window) containing the foreign keys that relate the tables to each other. The Hyper API infers the data object model, but does not perform any validation, such as referential integrity checking. If the Hyper API can’t infer the data object model of a Hyper extract, for instance, because there is more than one fact table, then attempting to publish the extract will fail. Prior to v2021.4, there was no way to append data to an extract with multiple tables using the REST API.

Data Sources stored locally
When you publish a data source from your local computer to the server, you must make sure that the server has all the components that are required in order for other users to see and interact with the data source. For example, if the data source is based on an Excel spreadsheet, you typically publish a packaged data source (.tdsx file) that contains all the components for that data source.

Working with Parquet files
- When publishing a Parquet file to a data source through a live-to-Hyper connection, the files are converted to Hyper files. You may want to publish a copy of your original Parquet file to retain that data in its native format.
- A data source with a live-to-Hyper connection to data in a Hyper file converted from Parquet can only have a single connection.
- When incrementally updating that data from that connection, using the Update Hyper in Data Source method, the Parquet file is not converted to Hyper.

For more information, see Publishing Resources.

URI

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

POST /api/api-version/sites/site-luid/datasources?overwrite=overwrite-flag&asJob=asJob-value

POST /api/api-version/sites/site-luid/datasources?append=append-flag

POST /api/api-version/sites/site-luid/datasources?uploadSessionId=upload-session-id&datasourceType=datasource-file-type&overwrite=overwrite-flag&append=append-flag

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 of the site to publish to.
overwrite-flag true to overwrite a data source that has the same name, or false to fail if the specified data source already exists. The default is false. If overwrite-flag is set to true but the data source doesn't already exist, the operation succeeds.

You can include both the overwrite and append parameters in a request, but they cannot both be true.
asJob-value A Boolean value that is used to publish data sources asynchronously. If you set this value to false (the default), the publishing process runs as a synchronous process. If a data source is very large, the process might time out before it finishes. If you set this value to true, the process runs asynchronously, and a job will start to perform the publishing process and return the job ID. You can check the status of the import job by calling Query Job.
append-flag true to append the data being published to an existing data source that has the same name. The default is false. If append-flag is set to true but the data source doesn't already exist, the operation fails.

In order to append data to a published data source on Tableau Server, both the source file and the published file must be an extract with the file extension .hyper or .tde. The schema of the source and the published extract must match.

If an extract was stored using the multiple tables option, you can't append data to it.

You can include both the overwrite and append parameters in a request, but they cannot both be true.
upload-session-luid If you are calling this method to commit a file that was uploaded in parts, this value contains the upload session LUID that was generated by a call to Initiate File Upload. If this value is not included, the server assumes that the body of the request contains the file to be published.
datasource-file-type hyper, tds, tdsx, or tde the kind of file that you are uploading. This value is required if you are calling Publish Data Source in order to commit a file that was previously uploaded using Append to File Upload. The value is not used if you upload a file in the body of the request.

Request Body

The content type in the header of requests to publish a data source must use the mixed multipart content type with a boundary string definition, in the form of: Content-Type: multipart/mixed; boundary=boundary-string.

Publishing a file in the request body 

--boundary-string
Content-Disposition: name="request_payload"
Content-Type: text/xml
<tsRequest>
	<datasource name="Sales"
	useRemoteQueryAgent="False"
	description="Sales Data Source">
		<connectionCredentials name="janedoe"
		  password="xxxxxx"
			embed="True" />
		<project id="ff2a8360-3c2b-4b05-a793-7607c602e1fb" />
  </datasource>
</tsRequest>
--boundary-string
Content-Disposition: name="tableau_datasource"; filename="Sales.TDSX"
Content-Type: application/octet-stream
	content-of-datasource-file
--boundary-string--

Committing a file previously uploaded 

--boundary-string
Content-Disposition: name="request_payload"
Content-Type: text/xml
<tsRequest>
	<datasource name="Sales" >
		<connectionCredentials name="janedoe" password="xxxxxx"
			embed="False" oAuth="True" />
		<project id="ff2a8360-3c2b-4b05-a793-7607c602e1fb" />
  </datasource>
</tsRequest>
--boundary-string--

Publishing a file in the request body 


Content-Length: 16301
Content-Type: multipart/form-data; boundary=----------------------my_boundary_string
----------------------my_boundary_string
Content-Disposition: form-data; name="part1.json"
Content-Type: application/json
{
  "the_JSON" : {
	"foo" :  "bar"
  }
}
----------------------my_boundary_string
Content-Disposition: form-data; name="datasource.tdsx"
Content-Type: application/pdf
  "datasource": {
	"name": "Sales",
	"useRemoteQueryAgent": "True",
	"description": "Sales Data Source",
	"connectionCredentials": {
	  "name": "janedoe",
	  "password": "xxxxxx",
	  "embed": "True"
	},
	"project": {
	  "id": "ff2a8360-3c2b-4b05-a793-7607c602e1fb"
	}
  }
}
----------------------my_boundary_string--

Committing a file previously uploaded 


Content-Length: 16301
Content-Type: multipart/form-data; boundary=----------------------my_boundary_string
Content-Disposition: form-data; name="part1.json"
Content-Type: application/json
{
  "the_JSON" : {
	"foo" :  "bar"
  }
}
----------------------my_boundary_string
Content-Disposition: form-data; name="datasource.tdsx"
Content-Type: application/pdf
  "datasource": {
	"name": "Sales",
	"connectionCredentials": {
	  "name": "janedoe",
	  "password": "xxxxxx",
	  "embed": "True",
	  "oAuth": "True"
	},
	"project": {
	  "id": "ff2a8360-3c2b-4b05-a793-7607c602e1fb"
	}
  }
}
----------------------my_boundary_string--

Request Attributes

boundary-string (Required) A string of characters that is guaranteed to be unique within the body of the request, and that is used to delimit sections of the request body. This value must be declared as a header that has this format:

Content-type: multipart/mixed; boundary=boundary-string
datasource name (Required) The name to assign to the data source when it is saved on the server.
datasource useRemoteQueryAgent (Optional) When true, this flag will allow your Tableau Cloud site to use Tableau Bridge clients(Link opens in a new window). Bridge allows you to maintain data sources with live connections to supported on-premises data sources.
datasource description (Optional) A description of the datasource.
connectionCredentials

The <connectionCredentials> element is required if the data source requires credentials. If the data source does not require credentials, Tableau will ignore this element if it is present. connectionCredentials attributes are:

username
(Required, depending on oAuth setting) The connection ceredentials username.

password
(Required, depending on oAuth setting) The connection credential password.

embed
(Optional) If true credentials are embedded in the datasource. Default is false.

oAuth
(Optional) If the data source connection is configured to use OAuth, set this to true to specify that the value of the name attribute in the connectionCredentials element is an OAuth username. In that case, no password is required and the value of the embed attribute specifies whether to embed the OAuth credential with the data source. For more information, see OAuth Connections(Link opens in a new window) in the Tableau Server documentation.

project The LUID of the project to assign the data source to. If the project is not specified, the data source will be published to the default project.
datasource-file-name The file name (including extension) of the data source file to upload. This attribute is used in the request body only if the request also includes the content of the data source file; it is not used if you are committing a file uploaded using previous requests.
content of datasource file The content of the data source file, if the request includes the file. The maximum size of a file that can be uploaded in one call is 64 MB.
askDataEnablement

This attribute is not available in API 3.12 and later (Tableau Cloud September 2021 / Server 2021.3).

cURL Example

curl "http://MY_SERVER/api/3.4/sites/ff2a8360-3c2b-4b05-a793-7607c602e1fb/datasources" -X POST -H "X-Tableau-Auth:6fSulU7ET8yjpHteQj56MQ|LrkEdTHcmPkWFcD8wOEy29hlVXm8iPo4" -H "Content-Type: multipart/mixed;" -F "request_payload=@publish-datasource.xml" -F "tableau_datasource=@data-source.tds"

Content of publish-datasource.xml: 

<tsRequest>
  <datasource name="datasource1" description="This is a data source named datasource1." >
    <project id="522dc5c5-e1da-47b9-8e07-f02929ff5ceb" />
  </datasource>
</tsRequest>

Response Code

201

Response Body

<tsResponse>
  <datasource
	id="75b71d2f-e8d3-42af-b654-d953659326ee"
	name="Sales"
	contentUrl="mySite"
	description="Sales Data Source"
	useRemoteQueryAgent="True"
	webpageUrl="https://my_server/#/datasources/222"
	type="excel-direct"
	createdAt="2016-02-12T23:36:09Z"
	updatedAt="2020-12-16T15:33:03Z"
	isCertified="False"
	certificationNote="This is a certification note."
	encryptExtracts="True">
	  <project
		id="56c86f04-b834-4a08-a561-86497bb4b2df"
		name="Visualization"/>
	  <owner id="20148c74-7818-4eb8-b2a1-9f3f5f582613"/>
	  <tags/>
  </datasource>
</tsResponse>

{
  "datasource": {
	"id": "75b71d2f-e8d3-42af-b654-d953659326ee",
	"name": "Sales",
	"contentUrl": "mySite",
	"description": "Sales Data Source",
	"useRemoteQueryAgent": "True",
	"webpageUrl": "https://my_server/#/datasources/222",
	"type": "excel-direct",
	"createdAt": "2016-02-12T23:36:09Z",
	"updatedAt": "2020-12-16T15:33:03Z",
	"isCertified": "False",
	"certificationNote": "This is a certification note.",
	"encryptExtracts": "True",
	"project": {
	  "id": "56c86f04-b834-4a08-a561-86497bb4b2df",
	  "name": "Visualization"
	},
	"owner": {
	  "id": "20148c74-7818-4eb8-b2a1-9f3f5f582613"
	},
	"tags": []
  }
}

The createdAt and updatedAt attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Response Headers

Location: /api/3.24/sites/site-id/datasources/id-from-server

Errors

HTTP status error Code Condition Details
400 400000 Bad request The request message is missing or incomplete, or contains malformed XML. Make sure that the Content-Length value is set.
400 400000 Missing data source There is no attachment in the request for the data source.
400 400008 Invalid overwrite value The overwrite parameter must be set to true or false.
400 400008 Invalid append value The append parameter must be set to true or false.
400 400008 Invalid embed value The request body contains a <connectionCredentials> element and it has an embed attribute whose value is not true or false.
400 400010 Invalid data source filename The name of the data source file did not end with the suffix .hyper, .tds, .tdsx, or .tde.
400 400010 Missing or invalid file type The request included an uploadSessionId parameter but no file type, or the file type was something other than hyper, tds, tdsx, or tde.
400 400010 Unexpected attachments The message had both a uploadSessionId parameter and an attachment, or the message contained more than one attachment.
400 400011 Publishing error The data source could not be published for some other reason than those specified earlier.
400 400019 Malformed request body The request message is missing or incomplete, or contains malformed XML. Make sure that the Content-Length value is set.
400 400055 Incompatible overwrite and append values The overwrite and append parameter cannot both be set to true.
400 400129 Invalid Ask Data enablement The enablement setting in the request body is not valid for the current server configuration.
403 403007 Insufficient publishing permission A non-administrator user attempted to publish a data source, but the caller doesn't have sufficient project permissions.
403 403007 Unlicensed publishing forbidden A non-administrator user who is unlicensed attempted to publish a data source. This is disallowed for all projects (including the default project).
403 403007 Overwrite forbidden A data source with the specified name already exists and the overwrite parameter was not set to true.
403 403007 Problem connecting to data source There was a problem connecting to a data source. This can be due to missing or invalid connection credentials or because the referenced data source is not available on the server.
403 403008 Insufficient storage quota The data source could not be published because there is not enough storage remaining on the server to accommodate its size.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404004 Data source not found The append parameter is true but the data source name specified in the request body does not correspond to an existing data source.
404 404005 Project not found The project ID in the request body doesn't correspond to an existing project on the site.
404 404015 File upload not found The file upload session ID in the request body doesn't correspond to an existing file upload on the site.
405 405000 Invalid request method Request type was not POST.

For more information, see Handling Errors.

Publish Flow

Publishes a flow on the specified site. To make other changes to a published flow, call Update Flow or Update Flow Connection.

You can do publish a flow in a single request or in multiple parts.

To publish a flow in a single request you include the content of the workbook file in the body of the request. The maximum size of a file that can be published in a single request is 64 MB.

To publish a flow in multiple parts, you initiate a file upload by calling Initiate File Upload(Link opens in a new window), send portions of the file to the server using Append to File Upload(Link opens in a new window), and then commit the upload by calling Publish Flow. In this case, Publish Flow doesn't contain the file to publish but the uploadSessionId and the flowType parameters are required.

URI

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

POST /api/api-version/sites/site-id/flows?overwrite=overwrite-flag

POST /api/api-version/sites/site-id/flows?overwrite=overwrite-flag&uploadSessionId=upload-session-id&flowType=flow-file-type

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 publish to.
overwrite-flag (Optional) true to overwrite a flow that has the same name, or false to fail if the specified flow already exists. The default is false. If overwrite-flag is set to true but the flow doesn't already exist, the operation succeeds.
upload-session-id If you are calling this method to commit a file that was uploaded in parts, this value contains the upload session ID that was generated by a call to Initiate File Upload. If this value is not included, the server assumes that the body of the request contains the file to be published.
flow-file-type tfl or tflx to indicate whether you have uploaded a flow file (tfl) or a packaged flow file (tflx). This value is only necessary and required if you upload a file in multiple parts. In the Publish Flow call after completing file upload, specify the file type.

Publishing a file in the Request Body 

 --boundary-stringContent-Disposition:
name="request_payload"
Content-Type: text/xml
<tsRequest>
	<flow name="flow-name" >
		<project id="project-id" />
	</flow>
	<connections>
      <connection id="abc"
        serverAddress="server-address"
        serverPort="port-number">
          <connectionCredentials
            name="connection-username"
            password="connection-password"
            embed="embed-flag"
            oAuth="oauth-flag" />
		</connection>
	</connections>
</tsRequest>

--boundary-string
Content-Disposition: name="tableau_flow"; filename="flow-file-name"
Content-Type: application/octet-stream
content-of-flow-file
--boundary-string--

Attribute Values

name The name to assign to the flow when it is saved on the server.
description The description of the flow.
server-address Specify the server address for an input connections.
port-number Specify the port number for input connections.
connection-username (Optional) If the flow input connections require credentials, the <connectionCredentials> elements are included and this attribute specifies the connection username. If the element is included but is not required, the server ignores the element and its attributes.
connection-password (Optional) If the flow input connections require credentials, the <connectionCredentials> elements are included and this attribute specifies the connection password. If the element is included but is not required, the server ignores the element and its attributes.
embed-flag (Optional) If the input connection requires credentials, the <connectionCredentials> element is included. Setting this attribute to Trueinstructs the server to save the credentials.
project-id The ID of the project to assign the flow to.
content-of-flow-file The file itself if you are including it in the request body.

Permissions

Users who are not server administrators or site administrators can publish a flow only if the flow belongs to a project that they have permissions to publish to, have a site role that allows publishing and have write permissions on the flow this is an overwrite.

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:flows:create

Response Code

201

Response Body

<tsResponse>
      <flow id="770a1cf8-6abe-4bc3-b0b8-59c4b15ce959"
            name="ShortTermRentalNola222"
            description=""
            webpageUrl="http://localhost/#/flows/3"
            fileType="tflx" createdAt="2018-11-20T19:28:58Z"
            updatedAt="2018-11-20T19:28:58Z">
           <project id="9077e04c-ece4-11e8-aa58-df538c72f42f"
            name="Default" />
           <owner id="5a39de9c-4eb0-47a7-88f7-2e78ddd58c6b" />
      </flow>
</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 Malformed request body The XML content in the MIME multipart request is not empty.
400 400089 Missing flow name Flow name is required and was not specified.
403 403007 Invalid permissions The caller does not have the necessary permissions to publish the flow. 
400 400090 Missing flow payload The flow information (the structure containing the flow description, flow project) was not included in the request body.
400 400086 Invalid flow attachment The name of the flow doesn't end in .tfl or .tflx.
400 400087 Generic flow publishing error The flow could not be published for some other reason than those specified earlier.
409 409041 Flow already found in destination The flow name should be unique, or the overwrite flag parameter should be set to true.
403 403008 Insufficient storage quota The flow could not be published because there is not enough storage remaining on the server to accommodate its size.
404 404000 Site not found The site ID in the URI doesn't correspond to an existing site.
404 404005 Project not found The project ID in the request body doesn't correspond to an existing project on the site.
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 POST.

For more information, see Handling Errors.

Publish Workbook

Publishes a workbook on the specified site. To make changes to a published workbook, call Update Workbook or Update Workbook Connection.

This method is used in two ways. You can call it to publish a workbook in a single request. To do that, you include the content of the workbook file in the body of the request. The maximum size of a file that can be published in a single request is 64 MB. If you want to avoid having the publishing process time out, you can use the asJob parameter to make workbook publication asynchronous.

Alternatively, you can publish a workbook in multiple parts. To do that, you initiate a file upload by calling Initiate File Upload, send portions of the file to the server using Append to File Upload, and then commit the upload by calling Publish Workbook. In this case, Publish Workbook doesn't contain the file to publish.

Hiding views in a published workbook
To exclude certain sheets (also known as views) when you publish a workbook, configure them in the request as hidden. You cannot publish a workbook if all sheets are hidden.

Extracts with multiple table options
If an extract was stored using the multiple tables option, you can't append data to it.

Workbooks that rely on external local resources
When you publish a workbook from your local computer to the server, the publish process will fail if the workbook relies on resources (such as an Excel file or other data file) that are on your local computer but are not available on the server. (Unlike the publish process that is used in Tableau Desktop, the REST API publish process cannot automatically include extracts or other resources that the workbook uses.) If you are publishing a workbook that gets its data from a source on your computer, save the workbook as a packaged workbook (.twbx file) and publish the package so that workbook has all the resources it needs on the server.

For more information, see Publishing Resources.

URI

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

POST /api/api-version/sites/site-id/workbooks?overwrite=overwrite-flag

POST /api/api-version/sites/site-id/workbooks?skipConnectionCheck=skip-connection-check-flag

POST /api/api-version/sites/site-id/workbooks?uploadSessionId=upload-session-id&workbookType=workbook-file-type&overwrite=bool&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 publish to.
overwrite-flag (Optional) true to overwrite a workbook that has the same name, or false to fail if the specified workbook already exists. The default is false. If overwrite-flag is set to true but the workbook doesn't already exist, the operation succeeds.
asJob-value (Optional, boolean) If false, the workbook publishing process runs as a synchronous process. If a workbook is very large, the process might time out before it finishes. If you set this value to true, the process runs asynchronously, and a job will start to perform the publishing process and return the job ID. You can check the status of the import job by calling Query Job. Default value is false.
skip-connection-check-flag (Optional, boolean) If true, then the Tableau server will not check if a non-published connection of a workbook is reachable. Publishing will succeed but unchecked connection issues may result in a non-functioning workbook. If you encounter this issue, follow Keep Data Fresh guidelines(Link opens in a new window). Default value is false.
upload-session-id If you are calling this method to commit a file that was uploaded in parts, this value contains the upload session ID that was generated by a call to Initiate File Upload. If this value is not included, the server assumes that the body of the request contains the file to be published.
workbook-file-type twb or twbx to indicate whether you have uploaded a workbook file (twb) or a packaged workbook file (twbx). This value is required if you are calling Publish Workbook in order to commit a file that was previously uploaded using Append to File Upload. The value is not used if you upload a file in the body of the request.

Request Body

The content type in the header of requests to publish a workbook must use the mixed multipart content type with a boundary string definition, in the form of: Content-Type: multipart/mixed; boundary=boundary-string.

Publishing a file in the request body 

--boundary-string
Content-Disposition: name="request_payload"
Content-Type: text/xml
<tsRequest>
  <workbook name="workbook-name" showTabs="show-tabs-flag" thumbnailsUserId="user-luid">
    <connections>
    <connection serverAddress="server-address" serverPort="port-number">
    <connectionCredentials name="connection-username" password="connection-password"
          embed="embed-flag" />
    </connection>
    </connections>
    <project id="project-id"/>
  </workbook>
</tsRequest>
--boundary-string
Content-Disposition: name="tableau_workbook"; filename="workbook-file-name"
Content-Type: application/octet-stream
content-of-workbook-file
--boundary-string--

Committing a file previously uploaded 

--boundary-string
Content-Disposition: name="request_payload"
Content-Type: text/xml
<tsRequest>
  <workbook name="workbook-name" showTabs="show-tabs-flag" thumbnailsUserId="user-luid" >
    <connections>
    <connection serverAddress="server-address" serverPort="port-number">
    <connectionCredentials name="connection-username" password="connection-password"
          embed="embed-flag" oAuth="oauth-flag" />
    </connection>
    </connections>
    <project id="project-id"/>
  </workbook>
</tsRequest>
--boundary-string--

Hiding a view when publishing a workbook 

--boundary-string
Content-Disposition: name="request_payload"
Content-Type: text/xml
<tsRequest>
  <workbook name="workbook-name" showTabs="show-tabs-flag" thumbnailsUserId="user-luid" >
    <connections>
      <connection serverAddress="server-address" serverPort="port-number">
        <connectionCredentials name="connection-username" password="connection-password"
           embed="embed-flag" oAuth="oauth-flag" />
	  </connection>
	</connections>
	<views>
      <view name="view-name" hidden="hide-view-flag" />
	</views>
	<project id="project-id"/>
  </workbook>
</tsRequest>
--boundary-string--

Attribute Values

boundary-string A string of characters that is guaranteed to be unique within the body of the request, and that is used to delimit sections of the request body. This value must be declared as a header that has this format:

Content-type: multipart/mixed; boundary=boundary-string
workbook-name The name to assign to the workbook when it is saved on the server.
show-tabs-flag (Optional) Specify true to have the published workbook show views in tabs; otherwise, false. The default is false.
user-luid (Optional) The LUID of the user to generate thumbnails as. You can get the user LUID by calling Get Users on Site.
server-address (Optional) Specify the server address for a data source connection if that data source does not use OAuth.
port-number (Optional) Specify the port number for a data source connection if that data source does not use OAuth.
connection-username

(Optional) If the workbook's data source connections require credentials, the <connectionCredentials> elements are included and this attribute specifies the connection username. If the element is included but is not required (for example, if the data source uses OAuth), the server ignores the element and its attributes.

Note: Even if credentials are embedded in a workbook, you must still provide credentials when connecting to a data source that requires credentials, unless that data source uses OAuth.
connection-password

(Optional) If the workbook's data source connections require credentials, the <connectionCredentials> elements are included and this attribute specifies the connection password. If the element is included but is not required (for example, if the data source uses OAuth), the server ignores the element and its attributes.

Note: Even if credentials are embedded in a workbook, you must still provide credentials when connecting to a data source that requires credentials, unless that data source uses OAuth.
embed-flag (Optional) If the workbook's data source connection requires credentials, the <connectionCredentials> element is included. Setting this attribute to true instructs the server to save the credentials for when the data source is used.
oauth-flag (Optional) If the workbook's data source connection is configured to use OAuth, set this to true to specify that the value of the name attribute in the <connectionCredentials> element is an OAuth username. In that case, no password is required and the value of the embed attribute specifies whether to embed the OAuth credential with the workbook, and the server address and port number are not required. For more information, see OAuth Connections(Link opens in a new window) in the Tableau Server documentation.
hide-view-flag Setting this flag to true will cause the named view to be hidden in the published workbook. The default value is false. You can specify any number of views to hide. If all views in a workbook are hidden the server will not perform a publish.
project-id The ID of the project to assign the workbook to. If the project is not specified, the workbook will be published to the default project.
workbook-file-name The file name (including extension) of the workbook file to upload. This attribute is used in the request body only if the request also includes the content of the workbook file; it is not used if you are committing a file uploaded using previous requests.
content-of-workbook-file The content of the workbook file, if the request includes the file. The maximum size of a file that can be uploaded in one call is 64 MB.
encryptExtracts (Optional) true to encrypt the extracts or false to not encrypt extracts. For more information, see Extract and Encryption Methods.

Permissions

Users who are not server administrators or site administrators can publish a workbook only if the workbook belongs to a project that they have permissions to publish to.

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:workbooks:create

Response Code

201

Response Body

<tsResponse>
  <workbook
    id="workbook-id"
	  name="workbook-name"
	  contentUrl="site-content-url"
	  webpageUrl="server-address"
	  showTabs="show-tabs-flag"
	  size="num-size"
	  createdAt="workbook-publish-date-time"
	  updatedAt="workbook-update-date-time"
	  encryptExtracts="encryptExtracts" >
 	    <project id="project-id" name="project-name"/>
	    <owner id="workbook-owner-id"/>
	    <tags/>
	    <views>
	      <view
	        id="view-id"
	     	name="view-name"
	        contentUrl="view-content-url"
	        createdAt="view-publish-date-time"
	        updatedAt="view-update-date-time" >
	          <tags/>
	 	  </view>
	  <materializedViewsEnablementConfig materializedViewsEnabled="materialized-views-enabled-flag"/>
  </workbook>
</tsResponse>

The datetime-created and datetime-updated attribute values are returned in UTC format (YYYY-MM-DDTHH:MM:SSZ).

Response Headers

Location: /api/3.24/sites/site-id/workbooks/workbook-id

Version

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

Errors

HTTP status error Code Condition Details
400 400000 Malformed request body The XML content in the MIME multipart request is not empty.
400 400000 Missing workbook There is no attachment in the request and no uploadSessionID parameter.
400 400000 Unexpected attachments The message had both an uploadSessionId parameter and an attachment, or the request body contained more than one attachment.
400 400008 Invalid embed value The request body contains a <connectionCredentials> element and it has an embed attribute whose value is not true or false.
400 400008 Invalid overwrite value The overwrite parameter must be true or false.
400 400011 Publishing error The workbook could not be published for some other reason than those specified earlier.
400 400020 Invalid workbook file name The name of the workbook doesn't end in .twb or .twbx.
400 400035 Missing or invalid file type The request included an uploadSessionId parameter but no file type, or the file type was something other than .twb or .twbx.
403 403007 Insufficient publishing permission A non-administrator user attempted to publish a workbook, but the caller doesn't have sufficient project permissions.
403 403007 Unlicensed publishing forbidden A non-administrator user attempted to publish a workbook. This is disallowed for all projects (including the default project).
403 403007 Overwrite forbidden A workbook with the specified name already exists and the overwrite parameter was not set to true.
403 403007 Problem connecting to data source There was a problem connecting to a data source used by the workbook. This can be due to missing or invalid connection credentials or because the referenced data source is not available on the server.
403 403008 Insufficient storage quota The workbook could not be published because there is not enough storage remaining on the server to accommodate its size.
403 403130 Publishing overwrite A workbook with the same name already exists.
403 403131 Concurrent update The workbook is already being published in another process.
403 403132 Failed connection check One or more data sources used by the workbook could not be reached.
404 404005 Project not found The project ID in the request body doesn't correspond to an existing project on the site.
404 404006 Workbook not found The user specified overwrite as true but no workbook with the specified name exists on the site.
404 404015 File upload not found The file upload session ID in the uploadSessionId parameter doesn't correspond to an existing file upload on the site.
405 405000 Invalid request method Request type was not POST.

For more information, see Handling Errors.

Example

curl "http://MY_SERVER/api/3.4/sites/ff2a8360-3c2b-4b05-a793-7607c602e1fb/workbooks" -X POST -H "X-Tableau-Auth:7T_33sOfS8Ks_0cht4tYxw|8tsTYQyyOZXfOgxZEHWQ4jUTCQ08GhRr" -H "Content-Type: multipart/mixed;" -F "request_payload=@publish-workbook.xml" -F "tableau_workbook=@MY_WORKBOOK.twbx"

Content of publish-workbook.xml (publish the Test1 workbook, hide the Test Sheet 1 view): 

<tsRequest>
	<workbook name="test1" showTabs="true" >
	<project id=""/>
	<views>
	<view name="Test Sheet 1" hidden="true" />
	</views>
	</workbook>
</tsRequest>

Example response:

<tsResponse>
	<workbook
		id="1e40f015-ac41-4377-8238-544f70d36150"
		name="test1" contentUrl="test1"
		webpageUrl="http://MY_SERVER/#/workbooks/3"
		showTabs="true"
		size="1"
		createdAt="2019-04-03T21:24:58Z"
		updatedAt="2019-04-03T21:25:02Z"
		encryptExtracts="false">
		  <project id="e6e94e18-349f-11e9-a794-13e5e0f21c22" name="Default"/>
		  <owner id="1473347e-b0c6-4f1f-bcac-7927ee1a690e"/>
	 	  <tags/>
		  <views>
			<view
			  id="0f0d33ac-027d-42a7-94bf-4f0b13e07652"
			  name="Sheet 1"
			  contentUrl="test1/sheets/Sheet1"
			  createdAt="2019-04-03T21:25:02Z"
		      updatedAt="2019-04-03T21:25:02Z">
			  <tags/>
			</view>
		 <materializedViewsEnablementConfig materializedViewsEnabled="false"/>
	</workbook>
</tsResponse>


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