External Client API (PRE-RELEASE - confidential)

External Client API (PRE-RELEASE - confidential) (0.2.12)

Download OpenAPI specification:Download

This REST API provides a programmatic interface for reading and authoring the open Tableau Studio document. Clients authenticate with the bearer token published in the per-user discovery file.

External Client API Guide (PRE-RELEASE - confidential)

The External Client API Guide provides an overview of the External Client API and:

Get application info

Returns information about the running Tableau Studio process, including its version, edition, build, operating system, locale, and repository and log paths.

Authorizations:
credentialsToken

Responses

Response samples

Content type
application/json
{
  • "applicationVersion": "string",
  • "edition": "string",
  • "build": "string",
  • "os": "string",
  • "locale": "string",
  • "repositoryLocation": "string",
  • "logLocation": "string",
  • "isStartPageVisible": true,
  • "isDataSourcePageActive": true,
  • "isPresentationMode": true
}

Open a file

Opens a local file by path. A .twb/.twbx opens as a workbook; a datasource file (Excel, text, spatial, extract, .tds, and the like) attaches to the open workbook, creating one if none is open. An extension Tableau cannot open is rejected before dispatch. Note: opening a workbook when one is already open launches it in a NEW Studio window, and this API session stays bound to the workbook it started with -- GET /v0/workbook continues to report the original, not the newly opened one.

Authorizations:
credentialsToken
Request Body schema: application/json
required
filePath
required
string

The absolute path of the local file to open.

Responses

Request samples

Content type
application/json
{
  • "filePath": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "string",
  • "state": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "completedAt": "string",
  • "error": {
    },
  • "result": { },
  • "warnings": [
    ],
  • "blockingWindows": [
    ],
  • "progressWindows": [
    ]
}

Set start page visibility

Sets whether the Tableau Studio start page is visible and returns the resulting visibility. Repeated requests for the same visibility have no additional effect.

Authorizations:
credentialsToken
Request Body schema: application/json
required
isStartPageVisible
required
boolean

Determines whether the start page is visible (true) or not (false).

Responses

Request samples

Content type
application/json
{
  • "isStartPageVisible": true
}

Response samples

Content type
application/json
{
  • "isStartPageVisible": true
}

List dashboards

Lists the dashboards contained in the open workbook.

Authorizations:
credentialsToken

Responses

Response samples

Content type
application/json
{
  • "dashboards": [
    ]
}

Get a dashboard

Returns the metadata for a single dashboard in the open workbook identified by its id.

Authorizations:
credentialsToken
path Parameters
id
required
string

The resource's stable id as returned in its list or GET response, not its display name or caption.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "type": "string",
  • "hidden": true,
  • "isActiveSheet": true,
  • "index": 0,
  • "isAutoUpdatesPaused": true,
  • "containedSheets": [
    ]
}

Get a dashboard document

Returns a single dashboard from the open workbook serialized as a Tableau XML subtree.

Authorizations:
credentialsToken
path Parameters
id
required
string

The resource's stable id as returned in its list or GET response, not its display name or caption.

header Parameters
X-Tableau-Effective-Payload-Version
string

Tableau payload (file-format) version the client authored the document against.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "string",
  • "state": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "completedAt": "string",
  • "error": {
    },
  • "result": { },
  • "warnings": [
    ],
  • "blockingWindows": [
    ],
  • "progressWindows": [
    ]
}

Apply a dashboard document

Replaces a single dashboard with the submitted Tableau XML, leaving the workbook's other sheets intact. The payload is checked for well-formed XML only and is NOT validated against the schema; use POST /v0/workbook/document:validate for XSD validation. This apply is unconditional last-writer-wins: it performs no precondition/If-Match check and will overwrite a concurrent edit to the same sheet. A concurrent rename of the target sheet is rejected as a failed operation (Tableau error 0xC655862E).

Authorizations:
credentialsToken
path Parameters
id
required
string

The resource's stable id as returned in its list or GET response, not its display name or caption.

header Parameters
X-Tableau-Effective-Payload-Version
string

Tableau payload (file-format) version the client authored the document against.

Request Body schema:
required

The workbook document as Tableau XML.

string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "string",
  • "state": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "completedAt": "string",
  • "error": {
    },
  • "result": { },
  • "warnings": [
    ],
  • "blockingWindows": [
    ],
  • "progressWindows": [
    ]
}

Export a dashboard image

Renders a single dashboard (resolved by id) as an image, returned inline as base64 or written to a caller-supplied file path.

Authorizations:
credentialsToken
path Parameters
id
required
string

The resource's stable id as returned in its list or GET response, not its display name or caption.

query Parameters
filePath
string

Path to write the image to. Must be absolute and name a file; a directory, a trailing slash, or any '.'/'..' path segment is rejected with a 400. When set, the response projects this path instead of inline base64; when omitted, the image is returned as base64.

mimeType
string

Requested image MIME type (e.g. image/png, image/jpeg). The effective type is returned in the response.

Responses

Response samples

Content type
application/json
{
  • "imageBase64": "string",
  • "filePath": "string",
  • "effectiveMimeType": "string",
  • "width": 0,
  • "height": 0
}

Delete a dashboard

Deletes a single dashboard by id. Deleting the workbook's last visible sheet is a no-op.

Authorizations:
credentialsToken
path Parameters
id
required
string

The resource's stable id as returned in its list or GET response, not its display name or caption.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "string",
  • "state": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "completedAt": "string",
  • "error": {
    },
  • "result": { },
  • "warnings": [
    ],
  • "blockingWindows": [
    ],
  • "progressWindows": [
    ]
}

Pause dashboard auto-updates

Pauses automatic query execution for a dashboard so several edits can be batched before the next refresh.

Authorizations:
credentialsToken
path Parameters
id
required
string

The resource's stable id as returned in its list or GET response, not its display name or caption.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "string",
  • "state": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "completedAt": "string",
  • "error": {
    },
  • "result": { },
  • "warnings": [
    ],
  • "blockingWindows": [
    ],
  • "progressWindows": [
    ]
}

Rename a dashboard

Renames a dashboard identified by id.

Authorizations:
credentialsToken
path Parameters
id
required
string

The resource's stable id as returned in its list or GET response, not its display name or caption.

Request Body schema: application/json
required
name
required
string

The new name of the sheet.

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "string",
  • "state": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "completedAt": "string",
  • "error": {
    },
  • "result": { },
  • "warnings": [
    ],
  • "blockingWindows": [
    ],
  • "progressWindows": [
    ]
}

Resume dashboard auto-updates

Resumes automatic query execution for a dashboard.

Authorizations:
credentialsToken
path Parameters
id
required
string

The resource's stable id as returned in its list or GET response, not its display name or caption.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "string",
  • "state": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "completedAt": "string",
  • "error": {
    },
  • "result": { },
  • "warnings": [
    ],
  • "blockingWindows": [
    ],
  • "progressWindows": [
    ]
}

Add a blank dashboard

Creates a single blank dashboard with a generated name. Any request body is ignored.

Authorizations:
credentialsToken
query Parameters
index
integer

0-based tab position at which the new dashboard(s) are inserted, shifting the existing tab at that position (and beyond) to the right. index=0 inserts before the first tab. To append at the end (make it the last tab), omit the parameter or use a value >=n (where n is the current number of tabs). Negative values also append at the end.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "string",
  • "state": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "completedAt": "string",
  • "error": {
    },
  • "result": { },
  • "warnings": [
    ],
  • "blockingWindows": [
    ],
  • "progressWindows": [
    ]
}

Datasources

With Datasources operations, you can:

Refresh a datasource's data

Refreshes the live data for the datasource resolved by {id} (its internal name from GET /v0/workbook/datasources) the way the toolbar Refresh Data Source does: it lowers the query-cache timestamp and clears the mapped-image cache, then re-fetches the datasource from its source. This is NOT an extract refresh -- if the datasource is backed by an extract, the data stays fresh only through the extract's metadata date. A datasource with no data connection to refresh is a no-op SUCCEEDED Operation.

Authorizations:
credentialsToken
path Parameters
id
required
string

The resource's stable id as returned in its list or GET response, not its display name or caption.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "string",
  • "state": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "completedAt": "string",
  • "error": {
    },
  • "result": { },
  • "warnings": [
    ],
  • "blockingWindows": [
    ],
  • "progressWindows": [
    ]
}

Refresh a datasource extract

Kicks off an extract refresh on the datasource resolved by {id} (its internal name from GET /v0/workbook/datasources). By default the refresh is incremental when the extract supports it; send isFullRefresh=true to force a full refresh. A datasource that has no refreshable extract is a no-op SUCCEEDED Operation.

Authorizations:
credentialsToken
path Parameters
id
required
string

The resource's stable id as returned in its list or GET response, not its display name or caption.

Request Body schema: application/json
required
isFullRefresh
boolean

Force a full refresh instead of an incremental one. Defaults to false: incremental when the extract supports it, otherwise a full refresh.

Responses

Request samples

Content type
application/json
{
  • "isFullRefresh": true
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "string",
  • "state": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "completedAt": "string",
  • "error": {
    },
  • "result": { },
  • "warnings": [
    ],
  • "blockingWindows": [
    ],
  • "progressWindows": [
    ]
}

List operations

Lists in-flight and recently-completed async operations.

Authorizations:
credentialsToken
query Parameters
state
string

Return only operations in this state (an OperationState value); an unrecognized value matches nothing.

kind
string

Return only operations of this command kind.

Responses

Response samples

Content type
application/json
{
  • "operations": [
    ],
  • "blockingWindows": [
    ],
  • "progressWindows": [
    ]
}

Get an operation

Polls a single async operation by id until it reaches a terminal state.

Authorizations:
credentialsToken
path Parameters
id
required
string

The resource's stable id as returned in its list or GET response, not its display name or caption.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "string",
  • "state": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "completedAt": "string",
  • "error": {
    },
  • "result": { },
  • "warnings": [
    ],
  • "blockingWindows": [
    ],
  • "progressWindows": [
    ]
}

Get protected-resource metadata

Returns the RFC 9728 OAuth Protected Resource Metadata document, which advertises the authorization servers and bearer methods that clients use to authenticate against this loopback API.

Responses

Response samples

Content type
application/json
{
  • "authorization_servers": [
    ],
  • "bearer_methods_supported": [
    ]
}

Get the OpenAPI document

Returns the OpenAPI 3.1 document that formally describes every resource, operation, and schema exposed by this API.

Responses

Response samples

Content type
application/json
{ }

Get the API root

Returns the API and application version strings together with a link map that points to the available top-level resources.

Responses

Response samples

Content type
application/json
{
  • "apiVersion": "string",
  • "applicationVersion": "string",
  • "links": {
    }
}

Check API liveness

Returns a liveness probe result that confirms the External Client API is running and able to serve requests.

Responses

Response samples

Content type
application/json
{
  • "status": "string"
}

Get the connected site

Returns the Tableau site that the current user is signed in to, or a 404 response when no site is connected.

Authorizations:
credentialsToken

Responses

Response samples

Content type
application/json
{
  • "siteId": "string",
  • "authenticatedUserId": "string"
}

List published datasources

Lists the datasources that have been published to the connected Tableau site.

Authorizations:
credentialsToken

Responses

Response samples

Content type
application/json
{
  • "datasources": [
    ]
}

List published workbooks

Lists the workbooks that have been published to the connected Tableau site.

Authorizations:
credentialsToken

Responses

Response samples

Content type
application/json
{
  • "workbooks": [
    ]
}

List storyboards

Lists the storyboards contained in the open workbook.

Authorizations:
credentialsToken

Responses

Response samples

Content type
application/json
{
  • "storyboards": [
    ]
}

Get a storyboard

Returns the metadata for a single storyboard in the open workbook identified by its id.

Authorizations:
credentialsToken
path Parameters
id
required
string

The resource's stable id as returned in its list or GET response, not its display name or caption.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "type": "string",
  • "hidden": true,
  • "isActiveSheet": true,
  • "index": 0,
  • "storyPointCount": 0
}

Get a storyboard document

Returns a single storyboard from the open workbook serialized as a Tableau XML subtree.

Authorizations:
credentialsToken
path Parameters
id
required
string

The resource's stable id as returned in its list or GET response, not its display name or caption.

header Parameters
X-Tableau-Effective-Payload-Version
string

Tableau payload (file-format) version the client authored the document against.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "string",
  • "state": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "completedAt": "string",
  • "error": {
    },
  • "result": { },
  • "warnings": [
    ],
  • "blockingWindows": [
    ],
  • "progressWindows": [
    ]
}

Apply a storyboard document

Replaces a single storyboard with the submitted Tableau XML, leaving the workbook's other sheets intact. The payload is checked for well-formed XML only and is NOT validated against the schema; use POST /v0/workbook/document:validate for XSD validation. This apply is unconditional last-writer-wins: it performs no precondition/If-Match check and will overwrite a concurrent edit to the same sheet. A concurrent rename of the target sheet is rejected as a failed operation (Tableau error 0xC655862E).

Authorizations:
credentialsToken
path Parameters
id
required
string

The resource's stable id as returned in its list or GET response, not its display name or caption.

header Parameters
X-Tableau-Effective-Payload-Version
string

Tableau payload (file-format) version the client authored the document against.

Request Body schema:
required

The workbook document as Tableau XML.

string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "string",
  • "state": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "completedAt": "string",
  • "error": {
    },
  • "result": { },
  • "warnings": [
    ],
  • "blockingWindows": [
    ],
  • "progressWindows": [
    ]
}

Export a storyboard image

Renders a storyboard's active story point (resolved by id) as an image, returned inline as base64 or written to a caller-supplied file path.

Authorizations:
credentialsToken
path Parameters
id
required
string

The resource's stable id as returned in its list or GET response, not its display name or caption.

query Parameters
filePath
string

Path to write the image to. Must be absolute and name a file; a directory, a trailing slash, or any '.'/'..' path segment is rejected with a 400. When set, the response projects this path instead of inline base64; when omitted, the image is returned as base64.

mimeType
string

Requested image MIME type (e.g. image/png, image/jpeg). The effective type is returned in the response.

Responses

Response samples

Content type
application/json
{
  • "imageBase64": "string",
  • "filePath": "string",
  • "effectiveMimeType": "string",
  • "width": 0,
  • "height": 0
}

Delete a storyboard

Deletes a single storyboard by id. Deleting the workbook's last visible sheet is a no-op.

Authorizations:
credentialsToken
path Parameters
id
required
string

The resource's stable id as returned in its list or GET response, not its display name or caption.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "string",
  • "state": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "completedAt": "string",
  • "error": {
    },
  • "result": { },
  • "warnings": [
    ],
  • "blockingWindows": [
    ],
  • "progressWindows": [
    ]
}

Rename a storyboard

Renames a storyboard identified by id.

Authorizations:
credentialsToken
path Parameters
id
required
string

The resource's stable id as returned in its list or GET response, not its display name or caption.

Request Body schema: application/json
required
name
required
string

The new name of the sheet.

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "string",
  • "state": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "completedAt": "string",
  • "error": {
    },
  • "result": { },
  • "warnings": [
    ],
  • "blockingWindows": [
    ],
  • "progressWindows": [
    ]
}

Add a blank storyboard

Creates a single blank storyboard with a generated name. Any request body is ignored.

Authorizations:
credentialsToken
query Parameters
index
integer

0-based tab position at which the new storyboard(s) are inserted, shifting the existing tab at that position (and beyond) to the right. index=0 inserts before the first tab. To append at the end (make it the last tab), omit the parameter or use a value >=n (where n is the current number of tabs). Negative values also append at the end.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "string",
  • "state": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "completedAt": "string",
  • "error": {
    },
  • "result": { },
  • "warnings": [
    ],
  • "blockingWindows": [
    ],
  • "progressWindows": [
    ]
}

Get the open workbook

Returns the metadata and sheet inventory of the workbook currently open in Tableau Studio, or a 404 response when no workbook is open.

Authorizations:
credentialsToken

Responses

Response samples

Content type
application/json
{
  • "title": "string",
  • "location": "string",
  • "unsavedChanges": true,
  • "worksheets": [
    ],
  • "dashboards": [
    ],
  • "storyboards": [
    ]
}

List workbook datasources

Lists the datasources that the open workbook uses.

Authorizations:
credentialsToken

Responses

Response samples

Content type
application/json
{
  • "datasources": [
    ]
}

Get a workbook datasource

Returns metadata for a single datasource by its URL-encoded inventory id.

Authorizations:
credentialsToken
path Parameters
id
required
string

The resource's stable id as returned in its list or GET response, not its display name or caption.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "luid": "string",
  • "name": "string",
  • "caption": "string",
  • "type": "string",
  • "isExtract": true,
  • "hasDownloadFilePermission": true
}

Get a datasource document

Returns the datasource's local workbook representation as a Tableau XML subtree.

Authorizations:
credentialsToken
path Parameters
id
required
string

The resource's stable id as returned in its list or GET response, not its display name or caption.

header Parameters
X-Tableau-Effective-Payload-Version
string

Tableau payload (file-format) version the client authored the document against.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "string",
  • "state": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "completedAt": "string",
  • "error": {
    },
  • "result": { },
  • "warnings": [
    ],
  • "blockingWindows": [
    ],
  • "progressWindows": [
    ]
}

Apply a datasource document

Replaces one datasource's local workbook representation with the submitted Tableau XML, leaving all other datasources and sheets intact. A missing or empty body is rejected with 400 and a non-XML Content-Type with 415. Malformed or invalid workbook XML is rejected with 422. The payload must contain exactly one datasource whose internal name matches {id}; a mismatch is rejected with 409. The apply is unconditional last-writer-wins and does not publish changes to a server-side datasource.

Authorizations:
credentialsToken
path Parameters
id
required
string

The resource's stable id as returned in its list or GET response, not its display name or caption.

header Parameters
X-Tableau-Effective-Payload-Version
string

Tableau payload (file-format) version the client authored the document against.

Request Body schema:
required

The datasource's Tableau XML -- either the bare element returned by GET .../datasources/{id}/document, or that element inside a or envelope. The payload must contain exactly one datasource whose internal name matches {id}.

string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "string",
  • "state": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "completedAt": "string",
  • "error": {
    },
  • "result": { },
  • "warnings": [
    ],
  • "blockingWindows": [
    ],
  • "progressWindows": [
    ]
}

Get the workbook document

Returns the entire open workbook serialized as a Tableau XML document.

Authorizations:
credentialsToken
header Parameters
X-Tableau-Effective-Payload-Version
string

Tableau payload (file-format) version the client authored the document against.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "string",
  • "state": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "completedAt": "string",
  • "error": {
    },
  • "result": { },
  • "warnings": [
    ],
  • "blockingWindows": [
    ],
  • "progressWindows": [
    ]
}

Apply a workbook document

Replaces the open workbook with the submitted Tableau XML. The payload is checked for well-formed XML only and is NOT validated against the schema; use POST /v0/workbook/document:validate for XSD validation. This apply is unconditional last-writer-wins: it performs no precondition/If-Match check; it overwrites concurrent edits and (Overwrite policy) deletes sheets the payload omits.

Authorizations:
credentialsToken
header Parameters
X-Tableau-Effective-Payload-Version
string

Tableau payload (file-format) version the client authored the document against.

Request Body schema:
required

The workbook document as Tableau XML.

string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "string",
  • "state": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "completedAt": "string",
  • "error": {
    },
  • "result": { },
  • "warnings": [
    ],
  • "blockingWindows": [
    ],
  • "progressWindows": [
    ]
}

Validate a workbook document

Validates the submitted Tableau XML document against the schema and reports any issues without applying it to the open workbook.

Authorizations:
credentialsToken
header Parameters
X-Tableau-Effective-Payload-Version
string

Tableau payload (file-format) version the client authored the document against.

Request Body schema:
required

The workbook document as Tableau XML.

string

Responses

Response samples

Content type
application/json
{
  • "isValid": true,
  • "validationIssues": [
    ]
}

Export the workbook

Exports the open workbook to a non-native format, leaving the open document unchanged. Both filePath and format are required. format selects what to produce: "pdf" (a PDF of every sheet), "powerpoint" (a .pptx with one slide per sheet), "packaged-workbook" (a .twbx bundling the workbook and its data), or "prior-version" (a down-saved copy for an older Tableau release). filePath must end in the extension that format produces (.pdf, .pptx, .twbx, or .twb/.twbx respectively) or the request is rejected. For "prior-version", also supply targetVersion as the customer-facing release string (e.g. "2024.1"); an unrecognized version is rejected. The export always writes to the supplied filePath and never opens a dialog, so it is fully headless.

Authorizations:
credentialsToken
Request Body schema: application/json
required
filePath
required
string

Absolute path to write the export to. Its extension must match format: .pdf for pdf, .pptx for powerpoint, .twbx for packaged-workbook, and .twb or .twbx for prior-version.

format
required
string
Enum: "pdf" "powerpoint" "packaged-workbook" "prior-version"

The export format that selects what file to produce. Only the listed values are accepted; any other value is rejected with a 400.

targetVersion
string

Required when format is prior-version: the customer-facing Tableau release to down-save to (e.g. "2024.1"). Ignored for other formats.

Responses

Request samples

Content type
application/json
{
  • "filePath": "string",
  • "format": "pdf",
  • "targetVersion": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "string",
  • "state": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "completedAt": "string",
  • "error": {
    },
  • "result": { },
  • "warnings": [
    ],
  • "blockingWindows": [
    ],
  • "progressWindows": [
    ]
}

Go to a sheet

Makes the identified worksheet, dashboard, or storyboard the active sheet.

Authorizations:
credentialsToken
Request Body schema: application/json
required
id
required
string

The identifier of the sheet to activate.

Responses

Request samples

Content type
application/json
{
  • "id": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "string",
  • "state": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "completedAt": "string",
  • "error": {
    },
  • "result": { },
  • "warnings": [
    ],
  • "blockingWindows": [
    ],
  • "progressWindows": [
    ]
}

Publish the workbook

Publishes the open workbook to the connected Tableau site by opening the Publish Workbook dialog. Because the dialog is interactive, a terminal SUCCEEDED reports that the flow finished, not that a publish landed: dismissing or cancelling the dialog also resolves to SUCCEEDED. Returns 404 when not signed in to a site.

Authorizations:
credentialsToken

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "string",
  • "state": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "completedAt": "string",
  • "error": {
    },
  • "result": { },
  • "warnings": [
    ],
  • "blockingWindows": [
    ],
  • "progressWindows": [
    ]
}

Redo the last undone change

Reapplies the change most recently undone on the open workbook, equivalent to Edit > Redo.

Authorizations:
credentialsToken

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "string",
  • "state": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "completedAt": "string",
  • "error": {
    },
  • "result": { },
  • "warnings": [
    ],
  • "blockingWindows": [
    ],
  • "progressWindows": [
    ]
}

Save the workbook

Saves the open workbook. Supply a filePath to save a copy to that path, or omit it to save the workbook in place at the path it already has. filePath must end in .twb or .twbx: save writes workbook content verbatim without converting, so any other extension is rejected rather than writing a mislabeled file. The save is headless whenever there is a path to write to -- a supplied filePath, or the existing path of an already-saved workbook. It cannot be headless in one case: a workbook that has never been saved has no existing path, so omitting filePath leaves nowhere to write and the product opens its native Save As dialog, which blocks until a person responds. Supply filePath to keep that case headless too.

Authorizations:
credentialsToken
Request Body schema: application/json
required
filePath
string

Absolute path to save a copy to; must end in .twb or .twbx. Omit to save the workbook in place at its current path.

Responses

Request samples

Content type
application/json
{
  • "filePath": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "string",
  • "state": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "completedAt": "string",
  • "error": {
    },
  • "result": { },
  • "warnings": [
    ],
  • "blockingWindows": [
    ],
  • "progressWindows": [
    ]
}

Undo the last change

Reverses the most recent change to the open workbook, equivalent to Edit > Undo.

Authorizations:
credentialsToken

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "string",
  • "state": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "completedAt": "string",
  • "error": {
    },
  • "result": { },
  • "warnings": [
    ],
  • "blockingWindows": [
    ],
  • "progressWindows": [
    ]
}

List worksheets

Lists the worksheets contained in the open workbook.

Authorizations:
credentialsToken

Responses

Response samples

Content type
application/json
{
  • "worksheets": [
    ]
}

Get a worksheet

Returns the metadata for a single worksheet in the open workbook identified by its id.

Authorizations:
credentialsToken
path Parameters
id
required
string

The resource's stable id as returned in its list or GET response, not its display name or caption.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "type": "string",
  • "hidden": true,
  • "isActiveSheet": true,
  • "index": 0,
  • "isAutoUpdatesPaused": true,
  • "datasources": [
    ]
}

Get a worksheet document

Returns a single worksheet from the open workbook serialized as a Tableau XML subtree.

Authorizations:
credentialsToken
path Parameters
id
required
string

The resource's stable id as returned in its list or GET response, not its display name or caption.

header Parameters
X-Tableau-Effective-Payload-Version
string

Tableau payload (file-format) version the client authored the document against.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "string",
  • "state": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "completedAt": "string",
  • "error": {
    },
  • "result": { },
  • "warnings": [
    ],
  • "blockingWindows": [
    ],
  • "progressWindows": [
    ]
}

Apply a worksheet document

Replaces a single worksheet with the submitted Tableau XML, leaving the workbook's other sheets intact. The payload is checked for well-formed XML only and is NOT validated against the schema; use POST /v0/workbook/document:validate for XSD validation. This apply is unconditional last-writer-wins: it performs no precondition/If-Match check and will overwrite a concurrent edit to the same sheet. A concurrent rename of the target sheet is rejected as a failed operation (Tableau error 0xC655862E).

Authorizations:
credentialsToken
path Parameters
id
required
string

The resource's stable id as returned in its list or GET response, not its display name or caption.

header Parameters
X-Tableau-Effective-Payload-Version
string

Tableau payload (file-format) version the client authored the document against.

Request Body schema:
required

The workbook document as Tableau XML.

string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "string",
  • "state": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "completedAt": "string",
  • "error": {
    },
  • "result": { },
  • "warnings": [
    ],
  • "blockingWindows": [
    ],
  • "progressWindows": [
    ]
}

Export a worksheet image

Renders a single worksheet (resolved by id) as an image, returned inline as base64 or written to a caller-supplied file path.

Authorizations:
credentialsToken
path Parameters
id
required
string

The resource's stable id as returned in its list or GET response, not its display name or caption.

query Parameters
filePath
string

Path to write the image to. Must be absolute and name a file; a directory, a trailing slash, or any '.'/'..' path segment is rejected with a 400. When set, the response projects this path instead of inline base64; when omitted, the image is returned as base64.

mimeType
string

Requested image MIME type (e.g. image/png, image/jpeg). The effective type is returned in the response.

Responses

Response samples

Content type
application/json
{
  • "imageBase64": "string",
  • "filePath": "string",
  • "effectiveMimeType": "string",
  • "width": 0,
  • "height": 0
}

List worksheet logical tables

Lists the logical table ids and captions available for a worksheet's underlying data.

Authorizations:
credentialsToken
path Parameters
id
required
string

The resource's stable id as returned in its list or GET response, not its display name or caption.

Responses

Response samples

Content type
application/json
{
  • "tables": [
    ]
}

Get worksheet underlying data

Returns the underlying data for one logical table of a worksheet as JSON.

Authorizations:
credentialsToken
path Parameters
id
required
string

The resource's stable id as returned in its list or GET response, not its display name or caption.

logicalTableId
required
string

Logical table id from the worksheet's logicalTables list.

query Parameters
maxRows
integer

Maximum number of data rows to return.

ignoreAliases
boolean

Return underlying values instead of display aliases.

ignoreSelection
boolean

Return all data rather than only the current selection.

includeAllColumns
boolean

Include every column rather than only the referenced columns.

columnsToIncludeByFieldName
Array of strings

Restricts the returned columns. Each value is a base source-column name qualified by the datasource caption (e.g. "[Sample - Superstore].[Sales]"). A value that matches no column is silently ignored. Repeat the parameter to name several; values are not comma-split, so a name may contain a comma.

Responses

Response samples

Content type
application/json
{
  • "columns": [
    ],
  • "rows": [
    ]
}

Get worksheet summary data

Returns the summary, or logical table, data for a single worksheet as JSON, optionally limited by maximum row count, current selection, display aliases, and a set of included columns.

Authorizations:
credentialsToken
path Parameters
id
required
string

The resource's stable id as returned in its list or GET response, not its display name or caption.

query Parameters
maxRows
integer

Maximum number of data rows to return.

ignoreAliases
boolean

Determines whether underlying values are returned instead of display aliases (true) or not (false). The default is (false).

ignoreSelection
boolean

Determines whether all data is returned rather than only the current selection (true) or not (false). The default is (false).

columnsToIncludeByFieldName
Array of strings

Comma-separated field names to restrict the returned columns.

Responses

Response samples

Content type
application/json
{
  • "columns": [
    ],
  • "rows": [
    ]
}

Delete a worksheet

Deletes a single worksheet by id. Deleting the workbook's last visible sheet is a no-op.

Authorizations:
credentialsToken
path Parameters
id
required
string

The resource's stable id as returned in its list or GET response, not its display name or caption.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "string",
  • "state": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "completedAt": "string",
  • "error": {
    },
  • "result": { },
  • "warnings": [
    ],
  • "blockingWindows": [
    ],
  • "progressWindows": [
    ]
}

Pause worksheet auto-updates

Pauses automatic query execution for a worksheet so several edits can be batched before the next refresh.

Authorizations:
credentialsToken
path Parameters
id
required
string

The resource's stable id as returned in its list or GET response, not its display name or caption.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "string",
  • "state": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "completedAt": "string",
  • "error": {
    },
  • "result": { },
  • "warnings": [
    ],
  • "blockingWindows": [
    ],
  • "progressWindows": [
    ]
}

Rename a worksheet

Renames a worksheet identified by id.

Authorizations:
credentialsToken
path Parameters
id
required
string

The resource's stable id as returned in its list or GET response, not its display name or caption.

Request Body schema: application/json
required
name
required
string

The new name of the sheet.

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "string",
  • "state": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "completedAt": "string",
  • "error": {
    },
  • "result": { },
  • "warnings": [
    ],
  • "blockingWindows": [
    ],
  • "progressWindows": [
    ]
}

Resume worksheet auto-updates

Resumes automatic query execution for a worksheet.

Authorizations:
credentialsToken
path Parameters
id
required
string

The resource's stable id as returned in its list or GET response, not its display name or caption.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "string",
  • "state": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "completedAt": "string",
  • "error": {
    },
  • "result": { },
  • "warnings": [
    ],
  • "blockingWindows": [
    ],
  • "progressWindows": [
    ]
}

Apply Show Me to a worksheet

Applies a concrete Show Me visualization type to a worksheet using optional datasource and fully qualified selected-field context.

Authorizations:
credentialsToken
path Parameters
id
required
string

The resource's stable id as returned in its list or GET response, not its display name or caption.

Request Body schema: application/json
required
showMeType
required
string
Enum: "text" "heat" "spot-table" "bar-horiz" "bar-stack" "bar-side" "bar-measure" "o-line" "qi-line" "o-area" "qi-area" "circle" "circle-side" "gantt" "scatter" "scatter-matrix" "histogram" "maps" "filled-maps" "pies" "dual-bar-line" "dual-line" "bullet" "treemap" "bubble" "box-plot"

The serialized Show Me visualization type to apply.

dataSource
string

Optional internal datasource name used to resolve selected fields.

fieldsSelectedInSchemaViewer
Array of strings

Optional fully qualified encoded field names, each with at least a datasource and field component. An explicit empty array supplies an empty field selection; omission preserves ambient selection.

Responses

Request samples

Content type
application/json
{
  • "showMeType": "text",
  • "dataSource": "string",
  • "fieldsSelectedInSchemaViewer": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "string",
  • "state": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "completedAt": "string",
  • "error": {
    },
  • "result": { },
  • "warnings": [
    ],
  • "blockingWindows": [
    ],
  • "progressWindows": [
    ]
}

Sort a worksheet

Applies a sort by field, direction, and type to a worksheet without opening the sort dialog.

Authorizations:
credentialsToken
path Parameters
id
required
string

The resource's stable id as returned in its list or GET response, not its display name or caption.

Request Body schema: application/json
required
fieldName
required
string

The on-shelf field to sort, given as its fully-qualified column-instance name exactly as it appears in the worksheet document's / (e.g. "[Sample - Superstore].[none:Ship Mode:nk]"). The base column name (e.g. "[Sample - Superstore].[Ship Mode]") will not match any field on the view and the sort is silently ignored.

direction
string
Enum: "asc" "desc"

Sort direction; defaults to 'asc' when omitted. Only the listed values are accepted; any other value is rejected with a 400.

sortType
string
Enum: "data-source-order" "alpha"

Sort type; defaults to 'data-source-order' when omitted. Only the listed values are accepted; any other value is rejected with a 400.

clearSort
boolean

Determines whether any existing sort on the field is cleared (true) or not (false).

Responses

Request samples

Content type
application/json
{
  • "fieldName": "string",
  • "direction": "asc",
  • "sortType": "data-source-order",
  • "clearSort": true
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "string",
  • "state": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "completedAt": "string",
  • "error": {
    },
  • "result": { },
  • "warnings": [
    ],
  • "blockingWindows": [
    ],
  • "progressWindows": [
    ]
}

Validate a calculated-field formula

Validates a calculated-field formula against a worksheet's data model without adding or changing any field. On a worksheet with more than one data source, a formula that does not qualify its fields with a data source is validated against the worksheet's active data source.

Authorizations:
credentialsToken
path Parameters
id
required
string

The resource's stable id as returned in its list or GET response, not its display name or caption.

Request Body schema: application/json
required
formula
required
string

The calculated-field formula text to validate.

Responses

Request samples

Content type
application/json
{
  • "formula": "string"
}

Response samples

Content type
application/json
{
  • "isValid": true,
  • "errors": [
    ]
}

Add a blank worksheet

Creates a single blank worksheet with a generated name. Any request body is ignored.

Authorizations:
credentialsToken
query Parameters
index
integer

0-based tab position at which the new worksheet(s) are inserted, shifting the existing tab at that position (and beyond) to the right. index=0 inserts before the first tab. To append at the end (make it the last tab), omit the parameter or use a value >=n (where n is the current number of tabs). Negative values also append at the end.

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "kind": "string",
  • "state": "string",
  • "createdAt": "string",
  • "updatedAt": "string",
  • "completedAt": "string",
  • "error": {
    },
  • "result": { },
  • "warnings": [
    ],
  • "blockingWindows": [
    ],
  • "progressWindows": [
    ]
}